Micro Focus Enterprise Test Server 10.0

Welcome to Enterprise Test Server

  • What is Enterprise Test Server?
  • Setup and Licensing

What's New

  • New Features in Enterprise Test Server 10.0
  • Significant Changes in Behavior or Usage

Getting Started

  • Assembler Support
  • Enterprise Server
  • Mainframe Support for Deployed Applications
  • SQL Option for DB2
  • Tools

Resources

  • OpenText Community Forums
  • OpenText Channel on YouTube
  • OpenText Support for Micro Focus Products
  • OpenText Product Updates
  • OpenText Knowledge Base
  • OpenText Training Store

Talk to Us

  • Contact OpenText Support for Micro Focus Products
  • Community Feedback


Welcome

Note: Check the Product Documentation section of the OpenText Support and Services Documentation Web site for Micro Focus products for any documentation updates.

Enterprise Test Server is a test execution environment that allows you to test mainframe applications on a low cost Windows platform. You can use variables or the tilde syntax to relieve the mainframe test bottleneck by allowing you to perform a substantial part of your application testing on Windows prior to moving the application back to the mainframe for final pre-production testing and deployment.

Enterprise Test Server supports IBM COBOL, High Level Assembler, CICS, IMS TM and DB, JCL, DB2, and z/OS file formats. It also supports common batch utilities such as SORT. This means that applications running under Enterprise Test Server behave just as they would on the mainframe, so you can perform a wide variety of pre-production testing activities on low-cost hardware rather than on the mainframe.

To configure Enterprise Test Server your development administrator will work with the development teams to set up the Enterprise Test Server environment on your central Windows test server, as follows:

  1. Micro Focus Enterprise Developer is used to recompile application source code for execution on Windows.
  2. Test data sets or databases are made available either locally or on the mainframe through remote access.
  3. Development and test teams are trained to ensure that they understand how to test applications within the Enterprise Test Server environment and to switch between the different test regions it supports.

Enterprise Test Server comes in the following product variants:

  • Enterprise Test Server, which is the standard Test Server product and is a mainframe Test Execution environment.
  • Enterprise Test Server Premium, which also provides Test Automator. Use Test Automator to automate testing by creating automated test suites you can play back against Enterprise Test Server or against the host.
  • Updating from an Earlier Release
  • Where do I start?
    Find the information you need in order to get started depending on which aspects of the product you need to get to grips with first.
  • Enterprise Test Server Tutorials Guide
  • Product Information
    Includes information about installing and licensing this product, any known issues, and about how to contact Micro Focus.
  • Managing Licenses
  • Setup and Licensing
    Includes information about setting up and licensing this product.
  • The Micro Focus Community
  • Help on Help
Parent topic: Micro Focus Enterprise Test Server 10.0


Updating from an Earlier Release

If you have used Enterprise Test Server before, check the links below for information on what new features are available with this release and whether there are any changes that could affect the behavior of existing applications.

  • New Features
  • Significant Changes in Behavior or Usage
Parent topic: Welcome


New Features

  • New Features in Enterprise Test Server 10.0
  • Features Added in Enterprise Test Server 9.0
  • Features Added in Enterprise Test Server 8.0
  • Features Added in Enterprise Test Server 7.0
  • Features Added in Enterprise Test Server 6.0
  • Features Added in Enterprise Test Server 5.0
Parent topic: Updating from an Earlier Release


New Features in Enterprise Test Server 10.0

Enhancements are available in the following areas:

  • Rocket COBOL and Rocket Enterprise Extensions for Visual Studio Code
  • Data Tools
  • Enterprise Server
  • Enterprise Server Common Web Administration (ESCWA)
  • Enterprise Server Security
  • IMS Support
  • Licensing Changes
  • Mainframe Access
  • Terminal Emulation
Parent topic: New Features

Rocket® COBOL Extension for Visual Studio Code and Rocket® Enterprise Extension for Visual Studio Code

Back to Top

The Micro Focus COBOL and Enterprise extensions for Visual Studio Code have been repackaged by Rocket Software on the Microsoft Visual Studio Marketplace.

  • The Rocket® COBOL Extension for Visual Studio Code (formerly Micro Focus COBOL Extension for Visual Studio Code) provides COBOL edit, compile and debug support for Visual COBOL and Enterprise Developer users in Visual Studio Code.
  • The Rocket® Enterprise Extension for Visual Studio Code (formerly Micro Focus Enterprise Extension for Visual Studio Code) provides PL/I edit, compile and debug support for Enterprise Developer users in Visual Studio Code. This extension installs the Rocket COBOL extension.
  • The Rocket® JVM COBOL Extension for Visual Studio Code (formerly Micro Focus JVM COBOL Extension for Visual Studio Code) provides support for debugging JVM COBOL code in Visual Studio Code.
  • The Learn COBOL extension for Visual Studio Code provides all training materials for the Micro Focus COBOL Fundamentals Training course.

New enhancements in this release are:

  • Support for accepting command-line arguments in COBOL notebooks.
  • New debug launch options - console and integrated Terminal support for platform specific values in the launch.json file.
  • Support is available for fine-tuning the colors of different parts of the code in the editor via Visual Studio Code's settings.json file. This requires a minimum release 10.0 of Enterprise Developer.
Note: These extensions are not included with the Enterprise Test Server installer. They are available from the Microsoft Visual Studio Marketplace website. All of the extensions are available on Windows and Linux.
Related information
Rocket COBOL extension for Visual Studio Code
Rocket COBOL Extension Documentation

Data Tools

Back to Top

This release includes the following enhancements in the Enterprise Developer and Enterprise Server products:

Attention: This feature is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.
  • A new REST-based file service API is now available. This enables you to access Micro Focus formatted data sets as follows - get dataset attributes, open or close datasets, get or set a dataset’s content, and to create datasets. The API commands can be used in customer scripts to access datasets with Micro Focus formats to automate application development processes.

Features of the new Data Tools include:

  • Open/save of Enterprise Server-cataloged datasets of the following Micro Focus formats: Fixed blocked, Variable blocked, and Indexed
  • Multi-line editing support
  • Insert, delete, update of lines or records
Related information
Data Tools

Enterprise Server

Back to Top

This release provides the following enhancements:

  • Remote File Access - it is now possible to remotely access files using a configured Remote File Access (RFA) MFCS Connector. You can access ordinary files, cataloged datasets, and spool output. This also enables remote editing of COBOL data files using the new Data Tools utility. This enables you to download and upload files, datasets, and spool output locally or remotely using the existing Enterprise Server Security configuration. Various security features make this solution a more secure alternative to more generic solutions such as FTP and SSH.
Related concepts
Remote File Access (RFA)

Enterprise Server Common Web Administration (ESCWA)

Back to Top

This release includes the following enhancements:

  • Catalog view has improved filtering options and now includes paging. A new Load on navigation check box enables you to filter based on the previously selected conditions.
  • A new Configuration Report page enables you to visualize potential security vulnerabilities in the ESCWA and MFDS configurations. Each domain and configuration attribute combination has its own help dialog.
  • Role-based security configuration. You can now configure a users view of ESCWA. If a user does not require specific roles then you can hide corresponding pages and API. You can configure the role-based access from the Role Options page. Click Security , expand ESCWA Configuration followed by the ESM, and then click Roles.
    Note: Role-based security is an ESCWA only feature that works on top of existing product security.
  • It is now possible to remove Locks, if necessary, to fix applications that are broken due to a lock that has not been removed. You can enable this feature from the Locks page. Click Native > Monitor > Locks, and then click Remove Locks. This functionality is controlled by the casstop resource entity in the OPERCMDS resource class.
    CAUTION:
    Incorrectly removing locks can result in system instability and corruption or loss of data.
  • Region verification - ESCWA can now verify the configuration of selected components for an enterprise server region. You can use this feature to identify potential start up or configuration issues for the selected region. The verification process uses the casverify utility to perform the verification action.
  • Improved CICS resource navigation. Active resources can now be filtered by group and large sets of filtered data can be paged.
  • The API return codes have been improved. Previously, when the region monitor and control APIs were called, they would return a HTTP 200 code, with the error specified in the JSON output. The return codes have been improved to give more information. You can configure the API to use the new or old behavior.
  • The ESCWA user interface is now more responsive and can be used with a greater variety of smaller Web browsers.
Related information
Catalog List
Configuration Report
Locks
Role-based Access
Verify

Enterprise Server Security

Back to Top

This release includes the following enhancements:

  • Enterprise Server security features provided by the VSAM External Security Manager (ESM) module are enabled by default. You will need to supply valid credentials when you interact with ESCWA, the Micro Focus Directory Server and regions in the browser based UI or in the IDE, use certain utilities from the command line, use TN3270 emulator to access regions, log into or with FileShare. See After Installing > Enterprise Server Security Features for details on how to configure this product.
  • TLS Certificate Checking Utility - a new executable in the product that can be used to help diagnose problems with TLS certificates. It can check the validity of certificates, verify certificate chains, check that certificates and private keys match and check that a certificate contains a SAN that matches a provided hostname/address. Improves TLS usability by diagnosing TLS certificate problems. See CertChecker Utility for more information.
  • The VSAM ESM Module, which provides file-based security for Enterprise Server is now a GA quality.
    • User authentication and resource authorization control can be enabled through a simple file-based security mechanism.
    • Security data can be imported from YAML or LDIF and exported to YAML for portability and ease of editing / scripting.
  • Additional optional security features are available for HTTP and MFBINP conversations, for the Web Services and J2EE, Web, and Remote File Access conversation types. Listeners can be configured to require user authentication and/or to restrict access to specific types of requests. See Enhanced Security for HTTP and MFBINP for more information.
Related information
Enterprise Server Security Considerations
VSAM ESM Module

IMS Support

Back to Top

This release provides the following new features:

  • APARM handling has been updated to use EBCDIC APARMs obtained from EBCDIC applications. In addition, the APARM positional parameter for DLI has been changed from 19 to 20 to be consistent with the IBM IMS documentation. The APARM positional parameter for BMP applications remains at 19.
  • The ES_IMS_APARM_DLI environment variable has been added to enable the APARM handing behavior of previous releases.
Related reference
ES_IMS_APARM_DLI

Licensing Changes

Back to Top

  • The SafeNet Sentinel licensing system that was available with previous releases of this product has been deprecated and is no longer available in release 10.0. This product also uses the Micro Focus AutoPass licensing technology which was introduced in release 8.0. Starting with release 10.0, AutoPass is the only licensing technology available in this product.

  • The SafeNet Sentinel licenses are no longer supported, and you need to use AutoPass licenses starting with release 10.0. Contact your account manager to replace your existing SafeNet Sentinel with AutoPass licenses.

Note: Installing 10.0 on a machine where there are other Micro Focus products or versions installed that use SafeNet Sentinel licensing might result in some compatibility issues. While the 10.0 installation process has been designed to address such issues, you should be aware of the following scenarios and if any action might be required to ensure licensing works as expected. See Advanced Installation Tasks > Licensing Coexistence when Upgrading to Release 10.0 in the Installation section.
Related concepts
Managing Licenses
Related information
Licensing Coexistence when Upgrading to Release 10.0

Mainframe Access

Back to Top

This release includes the following new features:

  • z/OSMF support - MFDAS and Syncmon now have access to mainframe-hosted PDS files using the z/OSMF interface. This enables you to list and download PDS files without having to install Mainframe Access Server.
Related information
Compare and Synchronization Monitor
Using z/OSMF

Terminal Emulation

Back to Top

This release includes the following enhancements:

  • Host Access for the Cloud shipped with this product is now version 3.0.0.2. The HACloud configuration file has changed is now the application-userprefs.properties file in %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hacloud (Windows) or $COBDIR/etc/hacloud (UNIX). If there is an existing hacloud.properties file in from an earlier Enterprise Developer release in %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer, this file is backed up the first time you start the HACloud session server. Micro Focus recommends that you migrate any non-default settings from the older configuration file over to the application-userprefs.properties file after the upgrade. See HACloud Configuration File for details.
  • For secured ESCWA scenarios, HACloud now retrieves credentials for the ESCWA connection from a default secret shipped with the product (in microfocus/common/readonly). You can override the default user credentials by supplying an escwacreds and/or an mfdscreds secret. If these secrets do not exist then the default supplied user will be used.
Related information
HACloud Configuration File
Authenticating HACloud for Work with ESCWA and the MFDS


Features Added in Enterprise Test Server 9.0

Enhancements are available in the following areas:

  • Learn Micro Focus™ Learn COBOL extension and Micro Focus™ COBOL Fundamentals Course
  • Micro Focus Enterprise Extension for Visual Studio Code
  • Micro Focus COBOL Extension for Visual Studio Code
  • Enterprise Server
  • Enterprise Server Common Web Administration (ESCWA)
  • Enterprise Server Security
  • IMS support
  • JCL Support
  • Terminal Emulation
  • Tracing
Parent topic: New Features

Learn Micro Focus™ COBOL Extension for Visual Studio Code and Micro Focus™ COBOL Fundamentals Course

Back to Top

Micro Focus has released a new video-based training course in COBOL, Micro Focus™ COBOL Fundamentals Course. The course teaches the fundamentals of the COBOL language, introduces the Micro Focus™ COBOL syntax, and usage of Micro Focus COBOL tools.

The course is ideal for developers familiar with C, Java, or .NET who want to learn COBOL. It doesn't matter what language you know, as long as you have experience of standard programming concepts, this course is for you.

A new Learn Micro Focus™ COBOL Extension for Visual Studio Code is available. The extension comes with the training materials for the COBOL training course. For information about the COBOL course, and the Learn Micro Focus™ COBOL Extension for Visual Studio Code, visit www.cobol.com.

Note: This extension is not included with the Enterprise Developer installer.
Related information
www.cobol.com

Micro Focus Enterprise Extension for Visual Studio Code

Back to Top

The following features are now available in the Micro Focus Enterprise Extension for Visual Studio Code when you use it with Enterprise Developer 9.0:

  • A PL/I Language Server is available. This enables the following advanced features in the PL/I editor - Find All References, Peek, Outline view, collapsible regions, Rename, Navigate To, background error reporting, variable highlights.
  • A new button, [image], Debug PL/I Program or Run PL/I Program in the top right corner of the editor, is present for the current PL/I program.
  • You can now specify the PL/I main file context for include files if an include copybooks is referenced in more than one program.
Note:
  • This extension is not included with the Enterprise Developer installer.
  • This extensions also installs the Micro Focus COBOL Extension for Visual Studio Code.
Related information
HTTPS://MARKETPLACE.VISUALSTUDIO.COM/ITEMS?ITEMNAME=MICRO-FOCUS-AMC.MFENTERPRISE
https://www.microfocus.com/documentation/vscode/enterprise/index.html

Micro Focus COBOL Extension for Visual Studio Code

Back to Top

The following features are now available in the Micro Focus COBOL Extension for Visual Studio Code when you use it with Enterprise Developer 9.0:

  • JVM COBOL debugging
  • COBOL notebooks where you can have text and executable blocks of COBOL code in the same file.
  • Colorization for COBOL directives files, cobol.dir.
  • A new button, [image], Debug COBOL Program or Run COBOL Program in the top right corner of the editor, present for the current COBOL program.
  • Configuration setting for custom tab stops.
  • A Micro Focus COBOL terminal in the TERMINAL pane.
  • You can now specify the COBOL main file context for copybooks if a copybooks is referenced in more than one program.
Note: This extension is not included with the Enterprise Developer installer.
Related information
HTTPS://MARKETPLACE.VISUALSTUDIO.COM/ITEMS?ITEMNAME=MICRO-FOCUS-AMC.MFCOBOL
https://www.microfocus.com/documentation/vscode/cobol/index.html

Enterprise Server

Back to Top

This release provides the following enhancements:

  • A new casverify command-line utility is available. This utility enables you to verify the configuration of a specified enterprise server region without attempting to start it, and also enables you to create immediate diagnostics information in JSON or human-readable output. Verification stages are modular, enabling you to specify which validation checks to run.
  • You can now list job steps to enable users to perform advanced restarts. Job steps can be output to JSON by specifying casout /%jnumber or output to a table by specifying casout /%tnumber. See casout for more information.
  • Enterprise Developer CICS now supports the MAPPINGDEV option of SEND MAP and RECEIVE MAP commands.
  • Application diagnostic reporting now enables you to collect JCL process failures. See Application Diagnostic Reporting for Enterprise Server for more information.
Related reference
casverify

Enterprise Server Common Web Administration (ESCWA)

Back to Top

Enhancements are available in the following areas:

  • Accessibility improvements - provide improved compliance with 508 and WCAG 2.1 standards.
  • API, version 2 extensions - includes updated versions of some of the existing API version 1 endpoints, and has been extended to contain more endpoints.
  • Merged Archived Spool - you can now configure an enterprise server region to view a merged archived spool in the UI. You can view multiple archived spools from a single region, and view old spool information for multiple jobs that have ran under a previous name
  • Page search facility - you can now search for a page that contains a specified search string. This enhancement is part of the WCAG 2.1 requirements for accessibility.
  • PAC clients - the ESCWA UI lists all TN3270 clients connected to a PAC. This enables you to administer and monitor clients across the entire PAC from a single PAC region.
  • TLS-enabled Redis connections. ESCWA now supports administering and monitoring PACs with a TLS Redis SOR.
Related information
Enterprise Server Common Web Administration

Enterprise Server Security

Back to Top

This release provides the following new features and enhancements:

  • Demo CA - the component has been completely redesigned and is now included as part of Enterprise Developer. Demo CA supports multiple installations, uses up-to-date cryptographic support, and generates modern version 3 certificates with SANS, PKIDs, AKIDs, etc. signed by an intermediate CA. Demo CA is now easier to use and has improved interoperability with third-party SSL/TLS systems.
    Note: Micro Focus strongly recommends that Demo CA is only used for SSL/TLS development and testing and is not intended for use in a production environment.
  • esfupdate support for the Vault Facility - the esfupdate utility now supports the use of the Vault Facility for credentials it needs to connect to MFDS.
  • OpenSSL 3.0 - OpenSSL has been updated to use the current Long Term Supported OpenSSL cryptographic library.
  • VSAM External Security Manager (EAP) - the VSAM ESM Module is a new option for Enterprise Server security which is simpler and more convenient than using LDAP-based security. The VSAM ESM Module provides a security manager for Enterprise Server which keeps security data in COBOL data (VSAM) files. It provides many of the features of the MLDAP ESM Module but does not require an LDAP server or other third-party solution. Security data can be imported from a YAML file, facilitating the securing of Enterprise Server and the modification of its security data.
    Attention: This feature is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.
Related information
Using the Demonstration Certificate Authority
To Update Security Manager Changes Using esfupdate
VSAM ESM Module

HCO for SQL Server

Back to Top

This release includes support for the following:

  • The Define Lists tool in the HCOSS UI has been enhanced to enable you to select a dependency mode to use when creating a transfer list. The available modes are:
    Default
    Automatically include all parent objects of the selected object.
    Family tree
    Automatically include all parent objects of the selected table.

    Automatically include the child objects of each parent object.

    Repeat until no more parents and children are found.

    No dependency handling
    Include the selected table only (do not include any parent or child objects).
  • The Transfer Data Tool now includes the start and end date and time for each table transfer.

IMS Support

Back to Top

This release includes the following new features for IMS:

  • A new environment variable, ES_IMS_DISPLAY_NEW, has been added to enable the new z/OS /DISPLAY timestamp output format.
  • APARM handling has been updated to use EBCDIC APARMs obtained from EBCDIC applications. In addition, the APARM positional parameter for DLI has been changed from 19 to 20 to be consistent with the IBM IMS documentation. The APARM positional parameter for BMP applications remains at 19.
  • The ES_IMS_APARM_DLI environment variable has been added to enable the APARM handing behavior of previous releases. See ES_IMS_APARM_DLI for details.
Related reference
IMS Environment Variables

JCL Support

Back to Top

  • In this release the security around running programs from JCL jobs has been enhanced to enable you to limit:
    • The location of the programs to load
    • Permission to run particular programs based on user ID

    This release writes several additional messages to the job log as a JCL job runs, including the location from which each program is loaded. For example:

    JCLCM0303I Program IDCAMS (MFJAMS) loaded from library
SYS1.LOADLIB

    When running one of your own programs, you might see messages such as:

    JCLCM0305I Failed to find program JCLREAD in private libraries
and SYS1.LNKLIB.
JCLCM0306I Number of SYS1.LNKLIB entries: 0.
JCLCM0303I Program JCLREAD loaded from library SYS2.LOADLIB.

    Combined, these three messages indicate that the program was not found in the main program search path (SYS1.LNKLIB) but has been loaded from the JES Program Path (SYS2.LOADLIB).

    For more information about increased JCL security checks including a configuration example, see JCL Enhanced Security Checks. For information about suppressing security check messages in the job log, see ES_JES_HIGHER_SECURITY_LEVEL.

  • The MF_SPLJNO_LOCK environment variable has been added. Using this variable, you can change the process by which the JES engine accesses the job number of a JCL submission to enable enqueuing, which can increase throughput, reduce latency, and reduce disk/file access. For details, see MF_SPLJNO_LOCK.
Related reference
MF_SPLJNO_LOCK

Terminal Emulation

Back to Top

This release provides the following new features.

  • Enterprise Developer and Enterprise Test Server now incorporate Host Access for the Cloud (HACloud) to provide 3270 emulation. HACloud is the leading Web-based emulator and requires no additional desktop installation. HACloud replaces the Rumba+ Desktop emulator previously supplied with Enterprise Developer. Customers that have Rumba+ Desktop entitlement can continue to use it within Rumba+ Desktop.
  • In this release, Host Access for the Cloud supports session configuration options, as well as creating and using macros.

Tracing

Back to Top

This release provides the following enhancements and new features:

  • Improvements have been made to the to the Common Communications Interface (CCI) tracing. CCI tracing can now be enabled using only the Consolidated Trace Facility (CTF) configuration, without needing to set trace options in CCI.INI or the environment as well. SSL/TLS trace points have been added to the CCI CTF trace, making it easier to control. It uses the same mechanism as other components such as the COBOL RTS. SSL/TLS tracing is now incorporated into CTF, placing all communications trace output in one place and adding timestamps and other useful information to these tracepoints. See Enabling CCI Tracing for more information.
Related information
Enabling CCI Tracing


Features Added in Enterprise Test Server 8.0

Enhancements are available in the following areas:

  • Micro Focus Enterprise Extension for Visual Studio Code
  • Data File Tools
  • Enterprise Server
  • Enterprise Server Common Web Administration
  • Enterprise Server Security
  • JCL Support
  • Micro Focus Database File Handler
  • Terminal Emulation
Parent topic: New Features

Micro Focus Enterprise Extension for Visual Studio Code

Back to Top

The Micro Focus Enterprise extension for Visual Studio Code provides the following enhancements:

  • The use of the Extension Enterprise extension with Enterprise Developer 8.0 provides PL/I editor, compiler and debug support. The PL/I debug support includes data breakpoints, conditions, and signals.
Note: The Micro Focus Enterprise extension is available from the Microsoft Visual Studio Marketplace - click here.

Data File Tools

Back to Top

The following enhancement has been made to the Data File Tools:
  • The Data File Editor now supports opening and editing KSDS VSAM files stored in an MFDBFH datastore.
Related information
Data File Tools

Enterprise Server

Back to Top

This release provides enhancements in the following areas:

  • EZ Sockets now supports up to 4096 sockets on Linux, up from 1024, and enhanced tracing.
    • EZ Sockets applications, including ones that use the CICS listener CSKL (EZACIC02), can have more simultaneous connections.
    • EZ Sockets tracing now has options for logging the recent history only when any error or one of a set of particular errors occurs. This makes it easier to use tracing to diagnose EZ Sockets issues.
  • Enterprise Server dataset management - dataset maximum retention period with the ability to alter and create reports:
    • ES_JES_ENFORCE_EXPIRE_DATE - helps determine whether or not to check the expiration date when deleting a catalogued dataset, and if expired, delete the dataset. If it hasn't expired and the PURGE option has not been specified, the dataset is not removed. The PURGE keyword is required to delete non-expired datasets. PURGE removes the underlying physical dataset file unless it is referenced by another catalog entry. SMS MANAGEMENTCLASS now supports maximum RETAIN days. See Using SMS MGMT Classes and the %SMS example command in the same topic.
    • ES_JES_LISTCAT_YMD - helps determine the date format used in the HISTORY report generated when the IDCAMS LISTCAT command specifies the ALL option.
    • The EXPDT entry in a DD statement must be a four-digit year (YYYY); otherwise 1900 is the default, which is in-line with the mainframe processing, and prevents unexpired datasets from being erroneously removed (as was the case with the previous default of 2000). The ALTER command now takes the TO and FOR options to enable specification of the retention period for the entry being altered. The maximum retention period might be limited by the management class. The IDCAMS LISTCAT command ALL parameter now generates a separate HISTORY report that shows the creation date time and job, the last changed date time and Job, and the expiration date.
  • HTTP compression - the Communications Server supports compressing large HTTP responses with gzip, and handles gzip-compressed HTTP requests. The Common Client supports gzip-compressed HTTP responses. Some large HTTP responses are compressed automatically if the client supports it. Large HTTP messages can be compressed, saving network bandwidth and improving performance.
  • Task-cleanup performance - the performance of post-processing for tasks in MFCS has been improved.
  • ICETOOL emulation - now supports the COUNT+n and COUNT-n syntax during trailer processing, where n is a numeric between 0-999. This adds to or subtracts from the COUNT value.
  • DSNRLI now implements one-phase commit optimization where appropriate.
  • Listing DEQ errors - a new caspac action, CasDEQs, enables you to list all errors that might have occurred on DEQs either at the end of a task or while a job or a transaction was executing.
  • Enterprise Server configuration - you can now change the recording directory of the dump, trace, HSF, and the console.log files of each region..
  • CICS API support - the CICS API GET CONTAINER option BYTEOFFSET is now supported.
  • Compression on ECI calls via CASBNCCL Client - when using the Micro Focus External Call Interface (ECI) over TCP/IP, the request and response data flows are now compressed using RLE.
Related concepts
Enterprise Server

Enterprise Server Common Web Administration (ESCWA)

Back to Top

This release includes the following enhancements:

  • Oracle Coherence is now available as a PAC Scale-Out repository as an alternative to Redis.
  • Reduced number of Redis instances required when a PAC incompatible upgrade is performed - it is now possible to have multiple PSORs in one REDIS instance. This allows for the REDIS instances provisioned in the PAC to be reused.
  • Enhanced PAC diagnostics via CTF - a new option on the ES Control page is now available to enable or disable CTF for a running region without the need to recycle the region.
  • ESCWA API, version 2 - includes updated versions of some of the existing API, version 1 endpoints, with improved JSON property names, more sensible URIs. The version 2 API is a single API standard across API endpoints. It includes a number of usability enhancements, has a better readability and discoverability, and includes an improved API documentation.
  • Enterprise Server Configuration Manager
    • A variety of configuration options are available in ESCWA on the General >Advanced page for a region.

      The property grid in ESCWA shows the full list of configurable properties, categorized by group, along with help text and some additional meta-information. Properties marked as dynamic in the property grid can also be updated in a running region.

    • A number of properties that were previously set with environment variables are now available in the ESCWA UI. The environment variables are still supported for backward compatibility.
  • Accessibility enhancements - the ESCWA UI includes a number of improvements in the areas of usability with screenreaders, color contrast, and text and icon sizing and alignment. This is to give it an improved compliance with the 508 and WCAG 2.1 standards.
Related information
Enterprise Server Common Web Administration

Enterprise Server Security

Back to Top

This release includes the following enhancements:

  • AWS Secrets Manager - support is available for using an AWS Secrets Manager, mfsecretsaws, as a remote vault.
  • Protection for sensitive data - some sensitive data is now protected in the memory. This helps reduce the risk of exposing sensitive data such as passwords in core dumps and similar scenarios.
  • An option to update short names - the ESF Update mechanism enables you to change between OS users ("long names") and ES userids ("short names") in running regions. This requires a non-default configuration setting.
  • Caching improvements - ESF caching now caches more types of requests. This helps improve the Enterprise Server latency and throughput when external security is configured with caching.
  • Support for Argon2 in password history - when Micro Focus passwords are used with the MLDAP ESM Module and password history is enabled, use Argon2 password verifiers in the history to avoid the potential exposure of passwords via weaker verifiers. This helps improve the security of the password-history mechanism.
  • The product Help includes a new section, Securing Enterprise Server, which provides guidance on improving the security of Enterprise Server installations and the applications they host. This includes information on security and how to reduce security exposure.
Related information
The mfsecretsaws Vault Provider
Securing Enterprise Server

IMS Support

Back to Top

This release provides the following enhancement:

  • The JES aliasing feature can be used with IMS DLI and BMP applications run from JCL.
  • APARM handling has been updated to use EBCDIC APARMs obtained from EBCDIC applications. In addition, the APARM positional parameter for DLI has been changed from 19 to 20 to be consistent with the IBM IMS documentation. The APARM positional parameter for BMP applications remains at 19.
  • The ES_IMS_APARM_DLI environment variable has been added to enable the APARM handing behavior of previous releases. See ES_IMS_APARM_DLI for details.

JCL Support

Back to Top

This release provides the following enhancement:

  • Support is available for the DSENQSHR JOB statement parameter with options of ALLOW, USEJC, and DISALLOW. You can configure the use of this parameter with the new ES_DSENQSHR environment variable for Enterprise Server.
  • The MF_SPLJNO_LOCK environment variable has been added. Using this variable, you can change the process by which the JES engine accesses the job number of a JCL submission to enable enqueuing, which can increase throughput, reduce latency, and reduce disk/file access. For details, see MF_SPLJNO_LOCK.
Related reference
ES_DSENQSHR
MF_SPLJNO_LOCK

The Micro Focus Database File Handler

Back to Top

The Micro Focus Database File Handler offers the following enhancements:

  • PostgreSQL and Microsoft SQL Server now support storing datastores, region databases, and cross-region databases in a single physical database, instead of storing them in separate databases.
  • Configurations that use a single physical database can now use a single database connection to access all MFDBFH resources stored within.
Related concepts
Database File Handling and Enterprise Server Region Database Management

Terminal Emulation

Back to Top

  • This release installs the Session Server component of Micro Focus Host Access for the Cloud (HACloud). HACloud provides browser-based HTML5 access to 3270 host applications on Windows and Linux for multiple connected users. HACloud is configured to work out-of-the-box with the default configuration for ESCWA and MFDS and might need to be configured before you start using it.
  • Patch Update 1 provides the following enhancement to the HACloud support:
    • On Windows, a new Windows service, Micro Focus HA Cloud, enables you to start the HACloud session server from the Windows Management Console. Before you can use the service, you need to deploy it with the hacloudserviceinstall script available from an Enterprise Developer command prompt.
Related information
Terminal Emulation with Micro Focus Host Access for the Cloud


Features Added in Enterprise Test Server 7.0

Enhancements are available in the following areas:

  • Micro Focus COBOL Extension for Visual Studio Code
  • Assembler Support
  • CICS Support
  • Code Set Support
  • Database Access - HCOSS Manage Connections Tool
  • Database Access - MBDT Utilities
  • Data File Tools
  • Enterprise Server
  • Enterprise Server Common Web Administration
  • Enterprise Server Security
  • IMS Support
  • Licensing Technologies
  • Mainframe Access
  • Micro Focus Database File Handler
Parent topic: New Features

Micro Focus COBOL Extension for Visual Studio Code

Back to Top

The new Micro Focus COBOL extension for Visual Studio Code is available on the Microsoft Visual Studio Marketplace. This provides edit, compile and debug support for Visual COBOL and Enterprise Developer users in Visual Studio Code.

Note: The new Micro Focus COBOL extension is not included with the Enterprise Developer installer.
Related information
https://www.microfocus.com/documentation/visual-cobol/vc70/VSCODE/index.html

Assembler Support

Back to Top

This release includes the following enhancements:

  • Support for Assembler data table generation on UNIX and Linux - a new command-line executable, MFMODGEN, is available on these operating systems to generate an Assembler data table (.MOD file) from an Assembler source file.

    This feature is the only Assembler functionality currently supported on UNIX systems. The rest of the Micro Focus Assembler functionality is supported for 32-bit Windows only.

CICS Support

Back to Top

CICS support in development has the following new features:

  • A 64-bit BMS Compiler on Windows and UNIX - the command-line utility, MFBMSCL, is now available in 64-bit format on Windows as part of Enterprise Developer and on UNIX as part of Micro Focus Enterprise Developer Unix Components.

Code Set Support

Back to Top

The following enhancements have been made to the integrated code set translation support:

  • Arabic support for Enterprise Server applications is available.

    If you are building Arabic support into Enterprise Server applications, your terminal emulator must support the Arabic EBCDIC 420 code page.

    Support is added by building your applications and configuring your enterprise server regions with the MFCODESET variable set to the supported country code (0420). Your product's in-built code set translation utility performs translations between the ASCII 1256 Arabic code page on your enterprise server region, and a terminal emulator that supports the Arabic EBCDIC 420 code page (for example, IBM's Personal Communications emulator).

    There are some considerations when working with a bi-directional language such as Arabic; these are discussed in Arabic support considerations.

Related information
Supported country codes

Database Access - HCOSS Manage Connections Tool

Back to Top

This release includes:

  • Enhanced usability features around connection error diagnosis and SQL Server connection/installed ODBC driver selections.
Attention: This feature is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

Database Access - MBDT Utilities

Back to Top

This release introduces:

  • The SQLTUL utility, which is equivalent to the z/OS DB2 DSNTIAUL program.
    Attention: This feature is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

Data File Tools

Back to Top

This release includes the following enhancements in the Data File Editor:

  • New Data Explorer for working with data sets - a new Data Explorer enables you to connect to either an ESCWA service or directly to an enterprise server region to access a catalog when working with data sets in the editor.
  • Multiple record selection- you can select multiple records and, where appropriate, can perform certain actions on more than one record at once.
  • Cut, copy, and paste functionality - traditional cut, copy, and paste functionality (including the standard Ctrl+X, Ctrl+C, and Ctrl+V shortcuts) is now available throughout the editor.
  • New filter creation - a new process for creating filters has been introduced. A filter consists of one or more sets of conditions, and the resulting filter can include or exclude those records selected. The previous filter process is still available, but has been marked as deprecated.
  • Remote filtering - functionality has gone into Fileshare Server which allows filtering to occur server side when opening data sets on remote enterprise server regions. The filter process results in only those filtered records being downloaded to the data file editor client.
  • Find/replace functionality - you can search records in a data file to identify specific strings, and then if required, replace them.
Related information
Data File Tools

Enterprise Server

Back to Top

This release includes the following enhancements:

  • Multiple Network Interface support - there is improved support for multiple network interfaces in some components, including better awareness of network interfaces and control over networking. This is a partial implementation and will be enhanced in future releases.
  • Extended IPv6 support - support is available in Micro Focus Directory Server (MFDS) and in the Micro Focus Communications Server (MFCS) listener for multiple IPv6 addresses.

    In release 6.0, you could only configure MFDS and MFCS listeners to listen on a single IPv6 address. In release 7.0, by default, MFDS and MFCS now listen on all configured IPv4 and IPv6 addresses, and can also be configured to listen on a combination of specific addresses.

  • HTTP improvements:
    • Additional security measures for HTTP, such as security-related headers.
    • Chunking support for large HTTP messages makes it possible to retrieve very large files from Enterprise Server regions.
    • Enhancements to CICS Web Interface and CICS Web Services.
  • Application Diagnostic Reporting for Enterprise Server - Application diagnostic reporting collects and packages a number of reports, trace, and log files into a single report file. See Application Diagnostic Reporting for Enterprise Server for more information.
  • Enterprise Server now supports automatic reconnection to the standby Queue manager in an Multi-Instance Queue Manager. See Reconnecting to an MQ Server in a Multi-instance Queue Manager and Enterprise Server XA Reconnect for more information.
  • The casmgr process has been optimized to improve the use of initiators when dispatching jobs across a PAC. In addition, improvements have been made to the way it manages the queue of jobs waiting to be dispatched.
  • Information has been added describing the best practice and the recommended approach you should adopt when performing a Patch Update to your PAC environment. See Performing a Product Upgrade to a PAC Environment for more information.
  • New operating modes , upgrade and quiesce, have been introduced for Performance and Availability Clusters (PACs). These operating modes can be used to facilitate the installation of product updates that introduce incompatibilities between PSOR data structures. You can check for incompatibilities using the new caspac utility option CheckCompat. An upgrade mode can be set when starting the first enterprise server region in a new PAC using the new casstart utility start-type option u. This upgrade mode will prevent participating enterprise server regions from processing batch workloads as part of its normal operation, and any EXEC CICS START requests will be rejected. See casstart and caspac in your product Help for more information.

    When enough enterprise server regions have been switched over to the new PAC, the old PAC can be set to operate in the quiesce mode. This prevents further batch workload and EXEC CICS START from being processed.

    The new PAC can now be switched to running mode so that batch workload and EXEC CICS START are enabled for processing again.

    Note: Before setting the new PAC mode to running, you must switch enough enterprise server regions to the new PAC to enable it to service the expected workload.

Enterprise Server Common Web Administration (ESCWA)

Back to Top

This release offers the following improvements:

  • MFDS User Interface functionality replacement - ESCWA now replaces the MFDS inside the IDE as the engine that provides access to and management of regions. ESCWA provides all the functionality that was previously available from MFDS. This release includes the following enhancements:
    • Delete all regions.
    • Session list.
    • Renew listening addresses.
  • ESMAC User Interface functionality replacement - the following ESMAC features have been implemented in ESCWA:
    • Resource Filtering. See CICS Resources for more information.
    • Millisecond support. See Threshold, Monitor, and Active PCT for more information.
    • Control the scope for all changes to timeouts, trace flags, and memory strategy when applied to regions in a PAC. See ES Control for more information.
    • Enable Application Diagnostic reporting. See ES Control and Application Diagnostic Reporting for Enterprise Server for more information.
    • Submission of local jobs from the JES Control page when CASRDO44_NEWSUB=OFF has been specified. See JES Control for more information.
    • View and reply to pending ACCEPT FROM CONSOLE statements. See Pending Replies for more information.
    • The messages after a JCL job has been submitted are now correctly JSON formatted. This page now works in ESCWA when MFJUXIT is enabled.
  • Import, export, and copy regions - you can now use the UI to export and import regions in various formats, including use JSON. You can:
    • Copy regions between Directory Servers
    • Import and export regions in JSON, XML or in the .dat legacy format. The legacy format can be converted to a modern format.
  • Mainframe Access (MFA) administration - ESCWA provides a modern Web UI and does not require you to use a separate terminal application. Features include:
    • Log in or off from MFA.
    • Change your MFA password.
    • View MFA server tasks.
    • Retrieve the XDBOUT log (Web UI).
    • Retrieve the JES spool files by DD Name (API).
    • Set the MFA and JES tracing level.
    • View the active MFA users.
    • Invalidate active user sessions.
    • View mainframe/MFA statistics.

    See Mainframe in the Enterprise Server Common Web Administration chapter for more information.

    The MFA API library has been exposed to enable you to test and use the requests that are provided. See MFA Interactive API Library for more information.

  • CICS resource support - the following resources are supported:
    • Resource Name List (RNL) CICS resource.
    • Thresholds CICS resource.
    • Extended Architecture Table (XAT) CICS resource.
  • Scale-Out and PAC administration - you can now:
    • Monitor Redis Sentinel and Cluster instances when used for Scale-Out Repositories.
    • Specify that all changes to timeouts, trace flags, and memory strategy can be applied to one of three options:
      • Only the local region.
      • All members of a PAC except the regions where local changes have been made.
      • All members of a PAC.

      You can configure this in ESCWA with the Apply Scope field on the ES CONTROL page. Alternatively, you can use the casutl utility with the /w option. See casutl for more information.

  • Multi-Network Interface Card support - ESCWA now enables you to configure Communications Servers and Listeners to listen on multiple IPv4 and IPv6 addresses. Previously, they were limited to listen on either all IPv4 addresses, or a single IPv4 or IPv6 address. Now a combination of any of the following can be used:
    • One or more specific IPv4 addresses.
    • One or more specific IPv6 addresses.
    • All IPv4 addresses.
    • All IPv6 addresses.
  • A new filter field resFilter has been added to the following ESCWA and ESMAC resource listing modules:
    • Every resource in By Type
    • Every resource in By Start L
    • Resource lists under Groups
    • Every active resource type except Locks

    This parameter will filter the list of resources displayed by ESCWA and ESMAC. In addition, a new environment variable ES_RDO_MAX_RESOURCES has been added that enables you to specify a limit to the number of records displayed. For JSON requests, the list being truncated is indicated by the addition of the JSON property "truncated": true.

Related information
Enterprise Server Common Web Administration

Enterprise Server Security

Back to Top

This release includes the following enhancements:

  • MLDAP ESM caching - the MLDAP ESM Module now implements LDAP search-result caching. This is controlled by the existing Security Manager cache settings, so that many installations will have this activated automatically. See the product Help for details.
  • Vault Hashicorp support - support is available for using a Hashicorp KV2 vault server as a local or remote vault.

IMS Support

Back to Top

This release includes the following enhancements:

  • An IMS Automated Operator Interface (AOI) - allows an application program to send IMS commands to, and receive responses from IMS Transaction Manager using the DL/I CMD and CGMS functions. This support includes:
    • Enterprise Developer and Enterprise Server support IMS DL/I functions CMD and GCMD across all language interfaces. These functions are used to send IMS commands and receive responses.
    • Commands can be sent from applications compiled either ASCII or EBCDIC.
    • Commands sent using AOI are limited to those supported in Enterprise Developer and Enterprise Server.
    • You can install an exit program that enables programming support for commands not directly supported by Enterprise Developer and Enterprise Server.
    • The IMSAO.CBL and IMSAO.JCL sample files, located in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples, are provided to demonstrate the use of AOI.
    • The AOEXIT.CBL program, located in the same place as the other AOI sample files, is an example of an installed exit routine for processing of AOI commands. Instructions for this interface are described in the program source.
  • The JES aliasing feature can be used with IMS DLI and BMP applications run from JCL.
  • APARM handling has been updated to use EBCDIC APARMs obtained from EBCDIC applications. In addition, the APARM positional parameter for DLI has been changed from 19 to 20 to be consistent with the IBM IMS documentation. The APARM positional parameter for BMP applications remains at 19.
  • The ES_IMS_APARM_DLI environment variable has been added to enable the APARM handing behavior of previous releases. See ES_IMS_APARM_DLI for details.

Licensing

Back to Top

AutoPass licensing technology

In this release, Micro Focus brings in the power of the in-house Micro Focus AutoPass licensing technology alongside Sentinel RMS. AutoPass has the following additional benefits compared to Sentinel RMS:

  • Usage logging which enables you to monitor the product usage. You need to install the AutoPass License Server in order to do this.
  • Ongoing support for all platforms that this product is available for.

Features include:

  • Installing this release installs both the Micro Focus AutoPass Daemon and the Sentinel RMS License Manager. Both of them are available in the Micro Focus License Administration tool.
  • You can have both AutoPass and Sentinel RMS licenses installed on the same machine. Optionally, you can switch off the licensing technology you do not use.
  • If you are an existing user of a Visual COBOL or an Enterprise Developer product, you only need an AutoPass license if you want to utilize usage logging or if you want to use your product on a platform on which Sentinel RMS is not supported.
  • If you are a new user of the Micro Focus COBOL products, you will normally be issued an AutoPass license.
  • Micro Focus will continue to provide Sentinel RMS in future releases of this product.
  • AutoPass licenses should be installed into the existing Micro Focus License Administration tool, and not in the AutoPass License Server.
Important: The SafeNet Sentinel licensing system that was available with previous releases of this product has been deprecated and is no longer available in release 10.0. This product uses the Micro Focus AutoPass licensing technology, first introduced in release 8.0, and AutoPass is now the only licensing technology available in this product.

The SafeNet Sentinel licenses are no longer supported, and you need to use AutoPass licenses starting with release 10.0. Contact OpenText Support for Micro Focus Products to replace your existing SafeNet Sentinel with AutoPass licenses.

Installing licenses at the command line

On Windows, Micro Focus License Administration is now also available as a command-line utility.

For more about AutoPass and usage logging, and about Micro Focus License Administration, see Managing Licenses.

Related concepts
Managing Licenses

Mainframe Access (MFA)

Back to Top

This release includes the following enhancements:

  • Improved file download and upload speeds - offers over seven times faster speeds for compressed files larger than 64K, and almost four times faster speeds for uncompressed files over 64K. This requires that you update both the Mainframe Access client and server, if you are using an older version of them.
  • Endevor transaction performance improvements - transactions with Endevor have been improved and are now around two times faster.
  • Support for MFDAS load and unload - load and unload-specific load library members are now available from the MFDAS command line. This enables you to interact remotely with Load libraries from the MFDAS command line.
  • SCLM export protection - you can now configure the MFA components to respect the SCLM managed flags. In this way, you can prevent outside source control changes to your managed datasets.

The Micro Focus Database File Handler

Back to Top

This release includes the following enhancements to the Micro Focus Database File Handler:

  • Oracle support: support has been added for use with Oracle databases (version 19c and later). Support is mostly equivalent to that of the existing databases, except that ODBC connectivity is not supported; connections must be made directly with the databases, using Oracle's OCI interface.
  • The dbfhview command line utility: a command line utility that generates database views from your Data File Editor structure files. These views allow you to view your data once it's stored in a datastore.
  • The mfdbcatc command line utility: a command line utility that helps you to relocate a disk-based catalog to a database. It can scan the current catalog, then generate a deployable response file that attempts to maintain the current structure of the catalog.
  • COBOL Run-Time System support for datastores: Library routines and variables that typically deal with files and folders on disk are now capable of also handling the SQL URLs required to reference file and folders in a datastore. Where appropriate, this is noted in the library routines documentation, and the topic 'The Datastore URL' gives full details of the SQL URL required.
  • Support has been added for Microsoft SQL Server and PostgreSQL users to host datastore, region and cross-region database resources in a single physical database. This support was already available for Db2 and Oracle users. See Using a Single Database for more details.
  • Datastores, regions, and cross-regions being hosted within the same physical database can now share connections. This greatly reduces the number of connections an MFDBFH application would require at any one time. See Sharing Database Connections for more details.


Features Added in Enterprise Test Server 6.0

Enhancements are available in the following areas:

  • Containers
  • Data File Tools
  • Enterprise Server
  • Enterprise Server Security
  • Enterprise Server Common Web Administration
  • File Handling
  • IMS Support
  • JCL Support
  • Micro Focus Database File Handler
  • Multi-Threaded Applications

Parent topic: New Features

Containers

Back to Top

Support has been added to enable you to work with containers from the IDE. In particular you can now create a Dockerfile for a COBOL project, and build, debug and run a COBOL project in a container, all from the IDE.

Related information
Using Enterprise Test Server with Containers

Data File Tools

Back to Top

The following enhancements have been made to the Data File Editor:

  • Double-byte character sets are now supported within the editor.
  • Insert mode is now available when editing a formatted record, except for numeric fields.
  • When editing DBCS data in EBCDIC files, the required Shift-out and Shift-in characters are automatically added when editing a formatted record and you are editing in Insert mode.
  • You can now load and unload structure files for an open data file.
  • A ruler at the top of the editing pane can be toggled on/off.
Related information
Data File Tools

Enterprise Server

Back to Top

The following enhancements are available:

  • Definition Import/Export Tool - a new utility, casesxml, has been added to enable you to import and export enterprise server definitions. Using casesxml you can do the following:
    • generate .xml files, in casesxml export format, that contain structured definitions of a region, a CICS resource definition file, and the catalog
    • import a casesxml export format .xml file to update the definitions of a region, a CICS resource definition file, and the catalog
  • IPv6 support (EAP) - This feature is in Early Adopter Program (EAP) release status. Some Enterprise Server components and features now support Internet Protocol version 6 (IPv6) network addressing and connectivity. Due to limitations with IPv4, IPv6 is becoming more common within corporate networks and on the public Internet. In some cases, the use of IPv6 can improve interoperability and simplify network configuration.
  • Administrative Commands - the add command in cascertreg now contains new options (-cwi setting, -dcas setting, -issuer, and -subject).
Related reference
casesxml
Related information
IPv6 Support

Enterprise Server Security

Back to Top

This release provides the following enhancements:

  • Micro Focus Secrets file storage permissions

    The Micro Focus Secrets Vault provides centralized storage for sensitive information such as passwords, with some protection against accidental disclosure or discovery by unauthorized users. Prior to this release, the only supported storage mechanism was a conventional file containing encrypted data. In this release, the permissions on the storage file and on the Secrets configuration file are set more restrictively to help protect the secrets.

  • Certificate wildcard support

    The X.509 digital certificates used to identify servers when making TLS (SSL) connections permit the use of fully-qualified domain names with wildcards for some parts of the name. This enables administrators to use a single certificate issued to, for example, *.mycorp.com for any number of servers with fully-qualified names like www.mycorp.com, server1.mycorp.com, and so on. These wildcard-bearing certificates are now supported by client programs using Micro Focus communication technology when validating a server's certificate.

  • Improved ACL wildcard support

    In the Access Control Lists used for resource access control with LDAP-based security in Enterprise Server, the ".**" wildcard sequence now behaves more similarly to mainframe RACF. A number of additional options for wildcard processing are also available.

  • PKIX compliance for TLS certificate validation

    The standard for using X.509 digital certificates to authenticate servers when making TLS (SSL) connections is known as PKIX, for Public Key Infrastructure (X.509). It is defined by a series of IETF RFC documents, currently RFC 5280 and others. In previous releases, the certificate validation performed by this product did not conform to PKIX in a number of ways, most notably in using DNS address-to-name resolution in an attempt to match a certificate to a host. With this release, clients using Micro Focus Common Client technology, such as COBOL web service proxy programs, CAS utility programs, and customer applications that use the CICS Web Services Interface feature, will by default, use stricter procedures for validating certificates which more closely conform to PKIX. This improves TLS security and interoperability.

  • Security improvements for XML parsing

    In this release the third-party components used for parsing XML data have been updated, or have had bug fixes integrated into the version used by Micro Focus, to address published security vulnerabilities. Also, XML external-entity support has been disabled except where it is required by a particular product feature; this prevents XML External Entity (XXE) attacks on customer systems by attackers who can trick a customer application into parsing a malicious XML document.

Related information
Vault Facility
Certificate and Key Formats

Enterprise Server Common Web Administration (ESCWA)

Back to Top

This release offers the following new features and improvements:

  • MFDS User Interface functionality replacement - ESCWA can now communicate with remote MFDS instances, and displays the equivalent pages of MFDS. Configuring regions, and their IMS, PL/I, MQ, and XA options, and security, is now available.
  • ESMAC User Interface functionality replacement - ESCWA can communicate with remote ESMAC instances, and can replicate functionality and display all the information provided by ESMAC.
  • Configurable User Interface access - you can now configure the ESCWA security manager to control user and group access to certain aspects of the user interface, such as, native, and security menu items.
  • Usability improvements
    • Starting and stopping regions from the navigation tree.
    • The native menu items are not displayed if the region features are not configured correctly.
    • Configuration of the display colors for MFDS hosts and regions to distinguish them with ease.
  • CICS resource support - the following resources are supported: ICEs, DocTemp, TCPIPService, URIMap, Bundle, Pipeline, and WebServices.
  • Scale-Out support - ESCWA has improved the way it displays a Scale-Out Repositories (SORs) association with its PAC and member regions.
  • Redis support - Redis is supported as a SOR when running this product in a PAC. Features include:
    • Redis cluster support
    • A Mfredis configuration file - enables you to configure reconnection when any network errors occurs. You can also use the file to configure Lua scripts tracing on servers.
    • Authentication support for the standalone Redis server.
Related information
Enterprise Server Common Web Administration

File Handling

Back to Top

Fileshare password files can now be stored in the Vault Facility, ensuring that sensitive user credentials are encrypted. Firstly, create the password file in the usual way, and then upload it, with a path of microfocus/fh, using the mfsecretsadmin utility.

To ensure the Fileshare server uses the file stored in the vault, start the server with the /uv option.

Related information
Vault Facility

IMS Support

Back to Top

Improvements are available in the following areas:

  • BMP inbound and outbound message processing - full support is available for BMP inbound and outbound message processing. Batch message processing programs (BMPs) can now access the IMS message queue for input and output, in addition to their batch-type processing and data-access capabilities.
  • Commands - the following commands are now supported: - /START TRAN ALL, /DISPLAY Q TRAN, and /DISPLAY STATUS TRAN.
  • DB Control SUSPEND / RESUME commands in an active system - IMS DB Control supports the SUSPEND command while transactions are active. DB Control will block any new units of work and allow active UOWs to complete during a quiesce. Once DB Control reaches a state with no outstanding UOWs it suspends. Note a long running BMP may prevent a system from suspending.

    This enables support for administrative tasks such as database and transaction log archiving. It also enables the creation of new transaction logs when roll forward recovery is enabled.

  • IMS BTS trace - IMS BTS trace is now visible from active SSTM and batch jobs. WIDTH and NOHEX options have been added for additional control of trace output format.

    This enables BTS output to be viewed when debugging a batch IMS application. Previously the job step had to complete before the trace was visible. This also enables you to view the trace output in an active SSTM job. Previously the MPR had to be stopped to make trace output visible.

  • User DB handler exit - database exit support has been added for GSAM databases. This provides programmatic control of the DB Catalog setting for a database instead of using the defined DB Catalog. Also, this exit can process DL/I calls completely, for example, to map DL/I calls into VSAM I/O requests. Previously, this exit was available only for full function databases.

    To assist you with writing an exit, a template file, USERDB.CBL, and an explanatory text file, USERDB.TXT, are available with your IMS classic samples.

  • JES Alias support - the JES aliasing feature can be used with IMS DLI and BMP applications run from JCL.
Related concepts
IMS Support Tasks

JCL Support

Back to Top

The following features have been added to the JCL support:

  • The sample printer exit in the product has been enhanced to retrieve extended information. The structure defined by idadoutp.cpy now contains two new entries (ws)-extended-output and (ws)-extended-data. The item (ws)-extended-output contains the version of the extended output data; currently, this should be set to 1. The item (ws)-extended-data is a pointer, that if null means there is no extended data; otherwise, it points to a new structure defined in outpext.cpy. That structure contains the extended output information for a given job. This is demonstrated in the provided sample - sampprnx.

The Micro Focus Database File Handler

Back to Top

Support for Db2 and Microsoft Azure databases has been added to the Micro Focus Database File Handler (MFDBFH). This support is equivalent to that of the existing databases.

The following features have been added for all databases:

  • I-O optimizations for sequential, line sequential, and ESDS/KSDS/RRDS files opened for output.
  • Using direct connection strings to make a database connection (as an alternative to using ODBC DSNs).
  • Creation of databases using script files.
  • Maintaining database configuration files with a command line utility, dbfhconfig.
  • Using the dbfhdeploy utility to delete data files from a datastore.
  • Database configuration files can now store confidential information in the Vault Facility.
  • CTF tracing of ODBC and Vault operations.
  • Recovering of locked processes or files can with the dbfhadmin utility.
  • The dbfhconfig and dbfhdeploy utilities are now capable of executing commands batched up in a response file.

Multi-Threaded Applications

Back to Top

This release includes the following improvements:

  • Thread local storage optimizations - the thread termination in applications with many threads has been optimized.


Features Added in Enterprise Test Server 5.0

Enterprise Test Server 5.0 provided enhancements in the following areas:

  • Amazon Web Services Quick Start for Enterprise Server
  • Enterprise Server and Scale Out Architecture
  • Enterprise Server Common Web Administration
  • CICS Support
  • Consolidated Trace Facility
  • Data File Tools
  • Database Access
  • Enterprise Server Security
  • JCL Support
  • Mainframe Access
  • Micro Focus Native Database File Handler
  • Platform Support
Parent topic: New Features

Amazon Web Services Quick Start for Enterprise Server

Back to Top

Micro Focus has worked with Amazon Web Services (AWS) to create an AWS Quick Start for Enterprise Test Server. The Quick Start includes AWS CloudFormation templates and a deployment guide with step-by-step instructions that enable you to deploy Enterprise Server into a new or existing virtual private cloud (VPC) on the AWS Cloud in about 1 hour and 15 minutes.

For full information see Enterprise Test Server on AWS.

Related information
http://www.microfocus.com/docs/links.asp?vc=mf-aws-es

Enterprise Server and Scale Out Architecture

Back to Top

Note: This feature is in Early Adopter Program (EAP) release status.

This release offers an enhanced and improved availability, and serviceability of Enterprise Server through the ability to administer and maintain a cross-system group of regions as a single system image with the new Performance and Availability Cluster (PAC).

In order for different Enterprise Server instances to be able to work together, they need to be able to share data. This is achieved through the use of a Scale Out Repository (SOR). All ES instances in a PAC will have a common SOR (PSOR) which is used to store CICS resources (limited to PCTs, PPTs, FCTs, DCTs and TSTs in this release) as well as internal system data to facilitate synchronisation between instances. Temporary Storage Queues and Transient Data Queues can also be shared between Enterprise Server instances by directing them to a SOR. Benefits of using PACs and SORs in this way include:

  • Reduced hardware costs - taking advantage of the PAC to scale-out rather than scaling-up for more efficient use of processor resources.
  • Easier maintenance - Dynamically adding or removing of regions to the PAC for system maintenance.
  • Increased availability - in the event of the failure of an Enterprise Server instance, the PAC can continue to operate with reduced capacity. Enterprise Server instances can reside on different machines, improving availability further.
  • Dynamic scaling - Enterprise Server instances can be added to, or removed from, the PAC depending on demand.
  • Better performance - throughput is no longer restricted by the resources on a single machine (scale-up).
  • Improved serviceability - you can now administer the PAC and any associated regions as a single image from a new contemporary web-based administration interface (ESCWA).
Related information
Scale-Out Performance and Availability Clusters

Enterprise Server Common Web Administration

Back to Top

Note: This feature is in Early Adopter Program (EAP) release status.

Enterprise Developer now includes a new Enterprise Server Common Web Administration interface (ESCWA). ESCWA is a web user interface and server for modern administration, monitoring and control of Enterprise Server. It offers improved usability that consolidates the different Enterprise Server user interfaces so that native and managed regions, and security stores can be managed in one place. Features include:

  • Administering directory servers across multiple hosts.
  • Monitoring and control of CICS and JES Enterprise Server instances.
  • Configuring and administering a security store, defined in an LDAP-compatible security manager such as Microsoft Active Directory or OpenLDAP.
  • Administering the Scale-Out features - enable you to specify logical groups of Enterprise Server instances, and configure and run Performance Availability Clusters (PACs) and their related Scale-Out Repositories (SORs).
  • Administering, monitoring and control of Enterprise Server for .NET regions and listeners.
  • The use of current web frameworks that have a greater focus on security.
  • (Included with 5.0 Patch Update 2 ) - support for Enterprise Server XA, MQ and PL/I configuration and monitoring. This includes support for XA resources, configuring MQ, Listeners and Writers, PL/I, MFCS console, Region Trace options, displaying the current ESMs on logon page and Local/loopback connections warning changes.

CICS Support

Back to Top

Note: This feature is in Early Adopter Program (EAP) release status.

This release includes the following enhancements:

  • CRCN CICS transaction - this new in-built CICS transaction monitors the state of XA connections for each resource manager (RM) entry defined in the system. If CRCN finds that connections have become unavailable, it will attempt to reconnect at regular intervals. (The frequency of the monitoring is controlled by the ES_XA_RECONNECT environment variable.) CRCN will emit messages to the console to warn of connections lost and regained.

Consolidated Trace Facility (CTF)

Back to Top

This release provides the following enhancements:

  • Dynamic CTF - it is now possible to configure the CTF dynamically from outside the process being traced.

    Using a new command line utility - cblctd - you can alter the tracing events of running applications that already have CTF tracing enabled. You can alter trace levels, add or remove components to or from the trace, and also configure the emitters in effect.

    Additionally, there is also a new component that you can trace - mf.mfdbfh enables you to trace activity of the Micro Focus Native Database File Handler.

Related reference
Dynamic CTF Syntax Options

Data File Tools

Back to Top

This release provides the following enhancements:

  • The Data File Editor now includes a Compare Files tool that enables you to compare the contents of two data files side-by-side.
  • Structure files, and the layouts within them, can now be created within the Data File Editor; you no longer need to use the Classic Data File Tools utility to manage your layouts.
  • When connecting to a VSAM dataset stored in an enterprise server region, you can store any passwords required for access, for the duration of your current session.
  • You can view archived JES spool jobs that have been merged into one spool file using the merging archived spool files process.
  • You can now quickly duplicate records in non-indexed files, using the Duplicate Record option.
Related tasks
Compare Two Data Files

Database Access

Back to Top

Enhancements are available in the following areas:

SQL Option for DB2

  • XML data type support - the following XML scalar functions are now supported - XMLATTRIBUTES, XMLCOMMENT (add), XMLCONCAT, XMLDOCUMENT, XMLELEMENT, XMLAGG(delete), XMLNAMESPACES, XMLPARSE, XMLPI, XMLSERIALIZE, XMLTEXT, XMLQUERY.
  • Initial XDB Server (add) support for z/OS DB2 V11 - includes support for archive tables and ALIAS on sequences (delete).
  • XDB Link support for z/OS DB2 V10/V11/V12 (add)

OpenESQL ADO.NET Connection Editor Toolbar

  • A new "i" (information) button is available that provides all the details of any installed .NET provider. Provides additional information mitigating resource definition and use within the ADO.NET Connection editor
  • Static XA switch modules "Reconnect" - At the beginning of a global transaction, the XA switch will attempt to reconnect temporarily broken connections to the database. If there is a temporary disconnect to the database, there is no need to manually re-enable the XA switch to run transactions.
Related information
SQL Option for DB2
ADO.NET Connection Editor

Enterprise Server Security

Back to Top

This release includes the following enhancements:

  • Security - security features can now be employed when developers and administrators install new COBOL services (web services and EJBs) into an enterprise server instance over the network. There are a number of authentication and authorization options that can be enabled. See Deployment Listeners and The .mfdeploy File.
  • Vault Facility - a new security feature has been added that enables some Enterprise Server components to keep certain sensitive information in a form of storage defined as a vault, accessible via a configurable vault provider. The default vault provider stores data in encrypted format on disk.
  • OpenSSL 1.1.1 - the OpenSSL security provider has been updated to OpenSSL version 1.1.1.

    This is the stable Long Term Support version of OpenSSL.

    • Added support for the ratified TLS protocol version 1.3. TLS 1.3 benefits include:
      • Much shorter initial connection negotiation sequence. This reduces the time taken to establish a link before starting to transmit data.
      • Using only the most secure ciphers and hash methods.
      • TLS 1.3 will be negotiated in preference to the older TLS protocols.
    • Added support for new Ciphers and Key Exchange groups in line with TLS 1.3 requirements.
    • The default security level for previously configured endpoints has been moved from Security Level 0 to Security Level 1. This removes the ability to accidentally make use of known-weak elements such as SSL3 and MD5. Similar changes to the default Security Level have recently happened to Java, Chrome, Firefox, and other systems providing secure connections.
  • Fileshare Security - the Fileshare Secure TCP/IP transport provider now supports the trusted use of X509 certificates bearing the name of the Fileshare service as the Common Name element of the certificate.

    In previous releases, a secure connection to a Fileshare server was made using a certificate that represented the network location upon which the Fileshare service was located. This method is still supported, but does not distinguish between the exact Fileshare server that is being connected to when more than one service can exist on a single host system. With this change, individual Fileshare services can identify themselves by using a unique certificate. While running on the same host and registered with the same network endpoint.

  • Support for Active Directory user groups and group name mapping - the Enterprise Server External Security Facility's MLDAP ESM Module can now use Active Directory user group objects for Enterprise Server user groups. Also, the module can now map long group names to the 8-character-maximum names required for mainframe emulation.
  • Selective auditing - administrators can audit only security activity of particular interest, reducing audit overhead and the volume of events. The Enterprise Server External Security Facility's MLDAP ESM Module can now enable ESF Audit events only for particular users, groups, and resources.
  • Improved interaction with LDAP client libraries resulting in fewer LDAP-related issues and easier diagnostics - the Enterprise Server External Security Facility's MLDAP ESM Module has improved interoperation with LDAP client libraries:
    • The client library vendor and version information is logged after the library is loaded
    • The module has better heuristics for loading the correct library supplied by the OS vendor, so the "provider" configuration option can generally be omitted
    • For OpenLDAP, the module sets its proprietary "connect timeout" option
  • SNI support (requires 5.0 Patch Update 1 or later) - support has been added in Patch Update 1 for the Server Name Identification (SNI) extension to TLS. This helps to avoid connectivity issues related to a growing number of Web services being hosted on SNI servers.
Related reference
The .mfdeploy file
Related information
Deployment Listeners
Selective Auditing
Vault Facility

JCL Support

Back to Top

This release includes the following enhancements:

  • Spool file housekeeping - you can now merge your archived spool files to a central location where they can be viewed using the Micro Focus Data File Editor. This copies the archived spool files and merges them into a new, combined archive. It does not change the original archive, so the audit trail remains untouched, but the combined archive allows viewing of all the jobs that have been merged. The merge process is carried out using a JCL job or by using a command line utility.
  • A new user exit MFJFAXIT - this user exit allows you to receive notifications when 'file open' events are processed by the JCL engine. A sample exit can be found in the src\enterpriseserver\exits sub-directory of your product install directory. You can enable this exit by using the MFJFAXIT environment variable, to point to the exit program.
Related concepts
Spool Housekeeping

Mainframe Access

Back to Top

This release provides enhancements in the following areas:

  • Browse dataset using IDCAMS dump - when using the MFDAS BROWSE command, it is now possible to view the output of the IDCAMS DUMP command on the specified dataset in hex and printable characters side-by-side.
  • Improved JES support for executing jobs and input datasets - it is now possible for MFA Server to interact with JES jobs that are in executing phase, and to list and download input datasets.
  • Retrieve binder information for load modules - when executing the MFDAS BINDER command, it is now possible to view the binder information from a load module.
  • TSO command server - MFA Server includes a new type of application server to support executing TSO commands as the current user. The address space is spawned as your user id and any valid TSO command can be executed.
  • UNIX sub-system (USS) support - MFA Server can now operate on files stored on a USS file system. The available functions are - edit, browse, rename, delete, and copy USS files and directories.

Micro Focus Native Database File Handler

Back to Top

The Micro Focus Database File Handler (MFDBFH) is a file handler that enables your native CICS and batch enterprise server applications to interact with data files and certain infrastructure files stored within a database.

VSAM files may experience logical and/or physical corruption in the event of a hardware failure. This is due to a single COBOL I-O operation consisting of multiple physical I-O operations. If all the physical I-O operations that make up the COBOL I-O operation are not performed, the file can be left without integrity. In previous releases you could guard against such occurrences with Fileshare and logging, but they required some manual intervention and came with performance cost.

In this release, configuration options have been added that allow the I-O operations to be routed to an RDBMS to take advantage of the availability and performance characteristics of the database. This can be achieved with no changes required to the application. The file will be routed to the SQL database simply by changing the filename prefix to sql://.

Features include:

  • CICS and batch Cobol file I-O can now be routed to an RDBMS with only simple configuration changes. No application changes are required.
  • Supports all Micro Focus file formats
  • Files can be routed to an RDBMS on a file by file basis.
  • Utilities are provided to enable data to be moved between disk files and RDBMS.
  • Support for PostgreSQL 10.x, Amazon Aurora PostgreSQL, Db21, and MS SQL Server (on Windows and Linux Intel)

Platform Support

Back to Top

Support is now available for the following additional or updated operating systems:

  • SUSE (Power) 11 SP3, 12
  • Red Hat (Power) 7.2, 7.3
  • Windows Server 2019

For a full list of supported platforms, check HTTPS://SUPPORTLINE.MICROFOCUS.COM/PRODAVAIL.ASPX.

1 Db2 support was introduced in the 5.0 Patch Update 2 release


Features Added in Enterprise Test Server 4.0

This release provides enhancements in the following areas:

  • Application Server JCA Support for Enterprise Server
  • Data File Tools
  • Docker
  • Enterprise Server
  • File Handler
  • HCO for DB2 LUW
  • IMS support
  • JCL support
  • Mainframe Access
  • OpenESQL
  • Platform support

Application Server JCA Support for Enterprise Server

Back to Top

This release includes the following enhancements:

  • COBOL Resource Adapters now support WebSphere 9.0 and WebLogic 12.2.1.
  • Tomcat 7.0 support for servlet generation with J2SEBeans.
  • NullSearch utility - for COBOL resource adapters, this new utility provides assistance in locating NULL fields in mappings passed to Enterprise Server. When a large number of arguments is provided in the parameters passed to Enterprise Server, it is difficult to locate NULL fields, which are not allowed. The NullSearch utility isolates NULL fields, so the Java application can be corrected.

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

Data File Tools

Back to Top

It is now possible to export any filtered results. When filtering a data file, you can use the results to create a new data file - click Search > Export Results when a filter is applied to save the filtered records to a new file. You can:

  • Save the filtered records to a new file.
  • Save the records that match the specified filter (such as customer information or orders).
  • Download a subset of the data from a remote file.
  • Save a small portion of the data for testing purposes.

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

Docker

Back to Top

This release provides support to enable you to run your COBOL and PL/I applications in Docker containers, taking advantage of the many benefits offered by the Docker platform such as portability, performance, agility, isolation, and scalability.

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

Enterprise Server

Back to Top

The following enhancements have been made to Enterprise Server:

  • Conversation filtering - the Enterprise Server Communications Process (MFCS) can now restrict access to listeners by client address. You can specify any permitted or forbidden addresses either by IP address, network mask, or domain name, and use wildcards. Filters can be applied to individual listeners, communications processes, or to entire regions. More specific filter rules override any general ones.
  • The Enterprise Server Security Facility now starts throttling Verify requests when it receives more than 100 requests per second.

    This can be used to limit the effectiveness of denial-of-service and brute force attacks. You can configure the value where throttling occurs. See Verify Request Throttling for more information.

  • (Technology Preview only) Support for adding, deleting, and modifying XA resources in a live Enterprise Server region.

    It is now possible to add, edit, or delete XA resources while an enterprise server instance is running. Any changes made come into effect after any in-flight transactions have completed. The ability to make these changes in a live environment comes under the control of the existing enterprise server permissions.

  • XA-compliant Resources (XARs) - this release provides enhanced CTF tracing that allows more flexible reporting of warnings and errors on the RM switch module level.
  • A new Communications Server resource class - enables you to control the access to the Enterprise Server Console Log and Communications Server Log when external security is in effect for an enterprise server region; see Resource Classes for Communications Server for more information.
  • Improved catalog availability - there is now an improved resilience to temporary communication issues with the catalog and error reporting enabling a region to stay active if a region has multiple catalogs defined and one of the catalogs is not available.
  • Enhanced SSL/TLS certificate support - for communications with TLS (formerly SSL), additional certificate and key file formats are supported. Servers may now be configured with both an RSA and an ECC key and certificate.
  • Enhanced SSL/TLS cipher configuration - for communications with TLS (formerly SSL), the permitted cipher suites and their preferred order can now be configured. The minimum size of Diffie-Hellman groups for DH key exchange can also be configured. The defaults have been made more secure.
  • The Historical Statistics Facility (HSF) now enables you to write user-defined data to the records produced within a .csv file. Use the ES_WRITE_CUSTOM_HSF or ESCSTHSF library routines within your COBOL programs to define the custom data, and use the ES_HSF_CFG environment variable to configure up to five custom fields in the generated record.
  • You can also use the ES_HSF_CFG environment variable to configure the number of CICSF, TSQ, and TDQ fields that are written to the record.

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

File Handler

Back to Top

This release provides the following enhancements:

  • The DFSORT and SYNCSORT emulations now support the NULLOFL parameter of the OUTFIL statement.
  • The ASCIISOSI configuration option is now available. It adds the required SOSI characters to the relevant EBCDIC DBCS character strings in order for them to be displayed or written out correctly.

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

HCO for DB2 LUW

Back to Top

This release includes the following new features:

  • Support for CHARSET EBCDIC COBOL stored procedures
  • Seamless integration with DB2 LUW SBCS databases, providing various EBCDIC collation sequences
  • 64-bit HCO command-line tools are now available across all supported platforms
  • HCO DCLGEN enhancements that provide more copybook generation options

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

IMS support

Back to Top

This release introduces the following new features:

  • The IMS Database Forward Recovery feature has been updated to provide point-in-time forward recovery that enables you to recover all database transactions completed up to a specified point in time, including date and time of day.
  • Support for export and import of IMS-configured enterprise server regions through Server Explorer.
  • Support for the same IMS user ID to be signed on to multiple LUs simultaneously by using the ES_IMS_SINGLE environment variable and optionally the ES_LTERM_PREFIX environment variable.
    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.

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

JCL support

Back to Top

This release introduces the following new features and enhancements:

  • Micro Focus FTP utility - you can now configure MFFTP to not process trailing blank spaces for a GET command, by setting the new control variable MFFTP_PROCESS_TRAILS_ONGET=FALSE and setting the LOCSTAT value TRAILINGBLANKS=FALSE.
  • A new API has been introduced - MVSSPLPB - that enables you to search all job information held in the JES spool control files. It is more comprehensive that the existing MVSCASPB API, and should instead be used for all new spool enquiries.
  • A number of new environment variables have been introduced that enable you to configure the JES startup behavior with regards to opening user catalog files. You can configure JES to open user catalog files only when they are required (and not during system startup), and you can configure JES to retry opening a catalog file that has failed to open. These changes increase the resilience of the JES system, as you can mitigate against JES startup failures if the user catalog files are not readily available whilst the region starts.
  • The public catalog API, MVSCATPB, has been enhanced to better report on file errors when opening catalog files. The following new functions have been added to mfpubcat.cpy: GCFS, GNFS, STNI, GCFE, and GNFE. See Functions for more information.

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

Mainframe Access

Back to Top

The installation process has been changed as follows:

  • A single installer for both Mainframe Access and the Mainframe Access z/Server support is provided.
  • There is now only one XML configuration file for Mainframe Access. There is also a new configuration utility that guides you through the configuration process.
  • Specify your own JES console character - it is now possible to configure the Mainframe Access installation to use a different JES console character instead of the default ("$"). To achieve this, use the new JES_CONCHAR configuration parameter.

Enhancements are available in the following areas:

OpenESQL

Back to Top

This release provides the following new features:

  • Support for SQL Server 2017.
  • The SQL(TRANSACTION) compiler directive has been enhanced to clearly define transaction boundaries.
  • A new SQL(NOWHERECURRENT) compiler directive that allows you to define updateable cursors that do not do positioned updates or deletes with PostgreSQL or MySQL.
  • Larger communication area (PID) that accommodates longer plan and program names.
  • SQL(OPTIMIZECURSORS) has been enhanced for consistent and better cursor performance across all OpenESQL backends.

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

Platform support

Back to Top

Note the following changes in platform support for this release:

  • Windows 8 and Windows Server 2012 are no longer supported for developing applications. They are still supported for deployment.

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

Parent topic: New Features
Related reference
Defining XA Resource Entries
Introduction to Containers
About Securing an Enterprise Server Installation
Filter the Data File
GUID-12554BDE-2B15-4E68-BC93-D19442C24379.ditamap


Features Added in Enterprise Test Server 3.0

This release provides enhancements in the following areas:

  • Application Server JCA support for Enterprise Server
  • CICS Web services
  • Data File Tools
  • Database access - HCOSS
  • Documentation
  • Enterprise Server
  • IMS support
  • Mainframe Access (MFA)

Application Server JCA support for Enterprise Server

In this release, EJBGEN has been updated to generate an EAR file as a part of the COBOL deployment process, which enables you to deploy EJBs to Java Application Server.

Back to Top

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

CICS Web Services

In this release, CICS Web services support includes the following additional features:

  • CICS JSON Web services for request/response and RESTful JSON. CICS Web Services support has been extended to allow JSON/REST requests to be used in both requestor and provider mode.
  • Use of container-based mappings

Back to Top

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

Data File Tools

This release provides the following enhancements to Data File Tools:

  • Opening files in shared mode - it is now possible to switch between read-only shared and edit modes. While a file is open in shared mode, others users can only open it in shared mode to ensure data consistency between users.
  • Enterprise Server-level of security when accessing files - there is an improved level of security when exchanging data between Data File Tools and the targeted enterprise server instance. Users must now provide a user ID, group and a password when they try to access and view datasets in enterprise server instances. These are used for authentication and authorization checks to provide the same access level as Enterprise Server.
  • Opening datasets using SSL - communication to a region is now possible using SSL. To enable the SSL communication, you need to provide a Java trust store which contains either a CA root certificate or a self-signed certificate of the region that it is communicating to. Java and the targeted region SSL configurations need to meet each other's standards in order for the communication to succeed.

    This feature enables you to secure the information exchange between Data File Tools and the targeted enterprise server.

  • Auditing of access and updates on datasets - Audit Manager now audits the access and updates on datasets via Data File Tools.
  • Support for existing .pro files - enables you to use your existing editor profiles.
  • Support for existing .str files - enables you to use your existing COBOL structure files.
  • Automatic timeout - if no internal operations or external actions (such as a mouse click) have been detected for 30 minutes, Data File Tools now displays a countdown message. If the user does not take any decision within the specified period, Data File Tools closes all opened files.

Back to Top

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

Database access - HCOSS

This release provides a new Offline Schema Extract feature – a batch solution that migrates a z/OS DB2 catalog to SQL Server without direct access to z/OS DB2.

Back to Top

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

Documentation

The following new sections have been added to the product help:

  • Where do I start? - located on the launch page of the product help, this section provides the information you need in order to get started depending on which aspects of the product you need to get to grips with first.
  • Configuring an SSL Client Connection to a Mainframe - includes instructions about how to configure client applications to connect to MFA and z/Server mainframe via AT-TLS in a zOS environment.

Back to Top

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

Enterprise Server

Improvements are available in the following areas:

EXEC CICS TRANSFORM:

  • Enterprise Server now supports the XMLTODATA and DATATOXML options of this API.

JCL spool

The JCL spool repository infrastructure has been redesigned to significantly improve its performance. The improvements include:

  • A more disk-efficient infrastructure, reducing the space required by the spool files by up to 75% in some cases.
  • Improved internal indexing, resulting in quicker generation of messages and sysout records during processing.
  • Improved navigation of spool queues: job status Complete replaces the Output, Out Hold, and Printed statuses, and completed jobs with any combination of sysout files can be displayed in a single list.
  • Increased range of job numbers, from five digits to seven digits.
    Important: These changes are automatically in place for new enterprise servers that you create. To enable these updates to existing enterprise servers, you must run a conversion utility before any JCL processing is permitted. Follow the To run the spool conversion utility process, detailed in Significant Changes in Behavior, for each existing JES-enabled enterprise server you have.

Long user IDs and passwords:

  • Enterprise Server now supports user IDs and passwords of up to 100 characters. It is possible to map IDs from long to short (or vice versa) to enable compatibility with programs that do not support long names.

Multi-factor sign-on:

  • Multi-factor authentication enables users to sign on to Enterprise Server CICS without entering a username and password. A secure user identifier, such as a certificate, is mapped to a username and is used to generate a passtoken. It is possible to use smartcards, biometrics, or other authentication systems to identify yourself to the system. The username and passtoken can then be used to log on to CICS in an automated way.

    The supported sign-on mechanisms are Express Logon Feature (ELF) and Automated Sign-On for Mainframe (ASM).

SHA-256 support in DemoCA:

  • By default, the Demonstration Certificate Authority (CA) now signs certificates with SHA-256. This ensures that the demonstration or evaluation certificates will be accepted by modern browsers and other software that has enhanced security requirements.

Syslog auditing:

  • Enterprise Server now supports auditing using syslog events, which can be consumed by a wide range of Security Information and Event Management (SIEM) products. This replaces the Audit Manager auditing solution. Syslog auditing provides a much more efficient auditing mechanism, with significantly less impact on overall speed.

Back to Top

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

IMS support

A new MFSGEN Compiler directive, CONTMVS, has been added to enable the compiler to parse MFS continuation lines (those continued without a terminating comma) by treating the line that follows as a comment line, just as is done on the mainframe.

Back to Top

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

Mainframe Access (MFA)

This release provides the following improvements:

  • Running MFA client in 64-bit processes - you can now call the MFA client modules from 64-bit applications and take advantage of the wider memory addressing available to those modules.
  • MFA client CTF tracing - MFDAS now supports CTF tracing. This provides better diagnostics of issues and helps increase turnaround on issues. CTF is common to a number of Micro Focus modules so cross-component logging can be turned on from a single place.
  • Endevor functions - the following functions are now available to Enterprise Sync and MFDAS: DELETE, DIRX, GENERATE, GETENQI, LIST, MOVE, SIGNIN and TRANSFER.

Back to Top

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

Parent topic: New Features
Related reference
Additional Software Requirements
Data Files


Features Added in Enterprise Test Server 2.3 Update 2

This release provides enhancements in the following areas:

  • COBOL language enhancements
  • Database access - DSNREXX
  • File handling
  • IMS support
  • Library routines

COBOL language enhancements

Back to Top

Numeric, edited and external floating point items can now specify USAGE NATIONAL when the NATIONAL"2" Compiler directive is in effect. Signed numeric items must be specified with the SIGN IS SEPARATE clause.

Database access - DSNREXX

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.

DSNREXX support is available for use with Enterprise Server using DB2 LUW and SQL Server. See DSNREXX Support for more information.

File handling

Back to Top

MFJSORT ICETOOL now supports the USING parameter in the SELECT operator.

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

IMS support

Back to Top

This release supports the PROMPT keyword in MFS source files.

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

Library routines

Back to Top

The following library routine contains new functionality:

  • CBL_GET_PROGRAM_INFO - a new function (function 10) has been added for native COBOL which returns the path and program name, or the program name only of a particular program.

Parent topic: New Features
Related concepts
DFSORT and ICETOOL Emulation


Features Added in Enterprise Test 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 (MBDT)
  • Database Access - OpenESQL
  • Database Access - SQL Option for DB2
  • File Handling

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

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

Database Access - SQL Option for DB2

Back to Top

This release provides the following new features:

  • Import/export of XML with SQLWizard/DSNUTILB(XUTLB)
  • New XDBSetup utility for TS/Citrix environments
  • Using Migrate to move XML tables from z/OS DB2 to XDB
  • Support for Temporal Tables

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.

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.

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

Parent topic: New Features
Related concepts
Data File Editor


Features Added in Enterprise Test Server 2.3

This release provides enhancements in the following areas:

  • Database access
  • Environment variables
  • File handling
  • Mainframe compatibility
  • 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.
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.
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
SQL Option for DB2
This release provides the following enhancements:
  • Initial support for XML data type in XDB Server, in addition to XDB Link
  • Better performance on table expressions and joins using literal strings
  • JDBC driver supports result set processing
  • SQL Wizard provides better LOB data type support
  • z/OS DB2 version 10:
    • Extended support for implicit casting
    • Greater timestamp precision for applications
    • Support for TIMESTAMP WITH TIME ZONE
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.

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 Rumba

Back to list

Micro Focus Rumba version 9.4 is now supplied with the Enterprise Developer 2.3 setup file. The license for Enterprise Developer will license all components of Rumba.

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
Configuration File Options
Micro Focus FTP Utility MFFTP
Spool Housekeeping


Features Added in Enterprise Test 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.
SQL Option for DB2
Support for the following has been added in this version:
  • DSNUTILB LOAD LOG=NO option
  • RID scalar function
  • XML data type via XDB Link to mainframe DB2
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.

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


Features Added in Enterprise Test Server 2.2 Update 1

This release provides enhancements in the following areas:

Micro Focus Heartbleed Update

This product includes OpenSSL version 3.0.8.

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.
    Note: For an OSVS dialect, numeric edited items are initialized to zeroes.
  • 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 Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products 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).

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.

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 Test Server 2.2

Consolidated Tracing Facility

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

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 OpenText Support for Micro Focus Products 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.

IMTK

EJB transactions
Enterprise Developer now supports EJB services that execute as a transaction.

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.

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.
SQL Option for DB2
Several updates have been made to the XDB tools:
  • Initial delivery of z/OS DB2 10 emulation engine:
    • A new XDB location version has been implemented
    • Support has been added for TIMESTAMP with TIME ZONE data type
  • Online analytical processing (OLAP) specifications support has been added for XDB V9 and V10 emulation
  • XDB Link has been updated to support the DRDA Version 5 architecture using SQL Application Manager DDM Level 10
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 Test Server 2.1 Update 1

Enterprise Server

The following new features and enhancements are available:

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

SQL Option for DB2

  • Background parsing support
  • Enhanced XDB engine LOB support
  • UTF-8 support for client-side expressions
  • Support for indices on expressions
Parent topic: New Features


Features Added in Enterprise Test 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
    EBCDIC SI/SO added on upload, removed on download
    -SOSI-K
    EBCDIC 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.

General Enhancements

Managed code enhancements

Delegates and Events

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

Service Interfaces Using the IMTK

Important: We highly recommend that you do the IMTK tutorials to get a feel for using these tools. See Tutorials: Interface Mapping Toolkit (IMTK) in the Enterprise Developer Tutorials Guide section under Native COBOL Tutorials.

The IMTK enables you to create an interface between a COBOL application running on an enterprise server instance as a service, such as a Web service or Java service, and a client, such as a Web service client or a JSP client. The interface you create is called a service interface.

You can create the following types of service interfaces for COBOL programs:

  • Web service
  • Java Interface

For service interfaces created from a new or existing COBOL application, you can expose as much or as little of the application functionality as you choose. Because COBOL applications often perform a wide variety of functions, the creation of a service interface enables you to limit your end users to access only the functions they need.

You can also use a WSDL or JSON file provided by a third party to generate both a service interface that supports the described Web service, and a skeleton COBOL program containing the data structures needed to support the Web service. You can then further enhance the COBOL program to contain the logic necessary to return the required output.

Attention: To deploy or generate a client for a Java Interface, you must install and configure the Java JDK and a Java application server. See the Application Server JCA support for Enterprise Server topic under Additional Software Requirements.

The process of creating a working service interface to run on Enterprise Server includes the following:

  • Creating and configuring an enterprise server instance to run the legacy application as a service
  • Creating a service interface in an Enterprise Developer project
  • Defining the details of the service interface using the Interface Mapper
  • Deploying the application and service interface to your enterprise server instance
  • Generating one or more clients to access the service running on the enterprise server instance
Parent topic: New Features


Significant Changes in Behavior or Usage

This section describes significant changes in behavior or usage in the current and past releases of Enterprise Test Server. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

Note: This list does not include the changes in behavior introduced by any of the Patch Update releases. Refer to the Patch Update readmes for information about such changes.
  • Changes in Behavior in This Release
  • Changes in Behavior in Release 9.0
  • Changes in Behavior in Release 8.0
  • Changes in Behavior in Release 7.0
  • Changes in Behavior in Release 6.0
  • Changes in Behavior in Release 5.0
  • Changes in Behavior in Release 4.0
  • Changes in Behavior in Release 3.0
  • Changes in Behavior in Release 2.3 Update 2
  • Changes in Behavior in Release 2.3 Update 1
  • Changes in Behavior in Release 2.3
  • Changes in Behavior in Release 2.2 Update 2
  • Changes in Behavior in Release 2.2 Update 1
  • Changes in Behavior in Release 2.2
  • Changes in Behavior in Release 2.1 Update 1
  • Changes in Behavior in Release 2.1
  • Changes in Behavior in Release 2.0

Changes in Behavior in This Release

Back to Top

  • AutoPass licensing and deprecation of SafeNet licenses
  • Enterprise Server Security Enabled by Default
  • Incorrect behavior for intrinsic function LENGTH and special register LENGTH OF when using NATIONAL fields

AutoPass licensing and deprecation of SafeNet Sentinel licenses

  • The SafeNet Sentinel licensing system that was available with previous releases of this product has been deprecated and is no longer available in release 10.0. This product also uses the Micro Focus AutoPass licensing technology which was introduced in release 8.0. Starting with release 10.0, AutoPass is the only licensing technology available in this product.

  • The SafeNet Sentinel licenses are no longer supported, and you need to use AutoPass licenses starting with release 10.0. Contact your account manager to replace your existing SafeNet Sentinel with AutoPass licenses.

    Note: Installing 10.0 on a machine where there are other Micro Focus products or versions installed that use SafeNet Sentinel licensing might result in some compatibility issues. While the 10.0 installation process has been designed to address such issues, you should be aware of the following scenarios and if any action might be required to ensure licensing works as expected. See Advanced Installation Tasks > Licensing Coexistence when Upgrading to Release 10.0 in the Installation section.

Enterprise Server security enabled by default

Enterprise Server security features provided by the VSAM External Security Manager (ESM) module are enabled by default. This includes support for authentication and authorization for users, user groups, and resources. On installation of the product, a password will be randomly generated for the SYSAD user. This password will be stored in the Vault Facility and can be retrieved using the following command:

mfsecretsadmin read microfocus/temp/admin
Note: Micro Focus strongly recommends that you promptly replace this password with one that conforms to your security policy. You can do this from the ESCWA logon page - click Change Password. Alternatively, you can use the esfadmin SETPASSWORD command and specifying the "vsam_esm" module file.

See the VSAM ESM Module chapter for more information on configuring the VSAM ESM Module. See Enterprise Server Security Considerations in After Installing for more details on the impact from this change.

Incorrect behavior for intrinsic function LENGTH and special register LENGTH OF when using NATIONAL fields

The intrinsic function LENGTH and special register LENGTH OF were not always returning the correct result for PIC N NATIONAL fields. These have been updated to the correct behavior, namely returning the number of characters for the former and number of bytes for the latter. If your legacy code has been relying on the previously incorrect behavior, results may now differ.

Changes in Behavior in Release 9.0

Back to Top

  • Licensing changes
  • LOCKDB replaces Enterprise Server Cluster Global Lock Manager (GLM)
  • Viewing active spool jobs

Licensing changes

  • The SafeNet Sentinel licensing system that was available with previous releases of this product has been deprecated and is no longer available in release 10.0. This product uses the Micro Focus AutoPass licensing technology, first introduced in release 8.0. Starting with release 10.0, AutoPass is now the only licensing technology available in this product.

  • The SafeNet Sentinel licenses are no longer supported, and you need to use AutoPass licenses starting with release 10.0. Contact OpenText Support for Micro Focus Products to replace your existing SafeNet Sentinel with AutoPass licenses.

LOCKDB replaces Enterprise Server Cluster Global Lock Manager (GLM)

The LOCKDB feature replaces the functionality of the Enterprise Server Cluster Global Lock Manager (GLM). See Enterprise Server LOCKDB for more information.

Default passing mode when passing pointers to a method

In previous releases, if a pointer was passed to a method without explicitly stating the passing mode (BY VALUE or BY REFERENCE), it was assumed to be passed BY REFERENCE. From this release, such items are assumed to be passed BY VALUE, making them consistent with other parameter types.

To pass a pointer BY REFERENCE, you must explicitly state reference in the method signature: for example:

method-id M1(reference ptr as pointer)
...

And ensure that the argument is also passed with the reference keyword; for example:

invoke M1(reference myptr)
...

Viewing active spool jobs

A new EXTFH configuration option, FLUSHSYSOUT, is now available to enable you to view the progress of active spool jobs. When set to ON (the default), the buffer is flushed after each record is written, enabling you to view the progress as it runs. Previously, a pre-defined buffer had to be completely written to before progress was displayed; this behavior was more performant, and so can be re-enabled by setting FLUSHSYSOUT=OFF

Changes in Behavior in Release 8.0

Back to Top

For an up-to-date list of these changes for release 8.0, see this product's Release Notes available from the Product Documentation section of the OpenText Support for Micro Focus Products website.

  • Validation during emulation of ICETOOL's SELECT operator

Validation during emulation of ICETOOL's SELECT operator

A validation check has been implemented to ensure that when making use of the DISCARD operand, the data set opened for output does not have an LRECL greater than the LRECL that ICETOOL is expecting. If it does, the job will fail.

This check may now cause jobs that previously ran successfully to now fail, but this behavior is now consistent with that of the mainframe.

Changes in Behavior in Release 7.0

Back to Top

For an up-to-date list of these changes for release 7.0, see this product's Release Notes available from the Product Documentation section of the OpenText Support for Micro Focus Products website.

  • Exceeding the maximum record length
  • ISO2002 support via the Compiler directive
  • Initializing variable-length groups when ODOSLIDE is in effect
  • .NET COBOL interoperating with other languages

Exceeding the maximum record length

The maximum record length supported by the File Handler is 62KB. If you create records that exceed this limit, a COBCH0649 error is generated on compilation. You can continue to use programs that utilise these large records, but you may experience adverse results in your file handling operations.

ISO2002 support via the Compiler directive

The ISO2002 directive now supports an option to provide different levels of ISO2002 features. ISO2002"1" provides the level of features supported in Server Express and Net Express, and ISO2002"2" provides those features, plus additional ones added since Visual COBOL. If you have used the ISO2002 directive in Server Express/Net Express, and are migrating to Enterprise Developer, use ISO2002"1" if your applications are affected by the change in behaviors provided with ISO2002"2".

Initializing variable-length groups when ODOSLIDE is in effect

The target of an INITIALIZE statement cannot be a variable-length group if the ODOSLIDE Compiler directive is set. This now results in a severe syntax error, whereas in previous releases this was incorrectly allowed to compile and produced unexpected run-time results.

.NET COBOL interoperating with other languages

.NET COBOL programs compiled with REENTRANT"2" now produce instance methods, whereas previously, compilation of these programs produced static methods. If your non-COBOL code relies on these methods being static, you will have to refactor your code to handle this, or recompile the .NET COBOL code with the ILSTATIC directive.

Note: The ILSTATIC directive will be deprecated in a future release of Enterprise Developer

Changes in Behavior in Release 6.0

Back to Top

For an up-to-date list of these changes for release 6.0, see this product's Release Notes available from the Product Documentation section of the OpenText Support for Micro Focus Products website.

iFileshare

iFileshare is no longer a strategic component of this product, and is no longer being enhanced. We recommend that if you currently rely on it, you migrate to a stand-alone FileShare server instead; see Using Fileshare with Enterprise Server.

Changes in Behavior in Release 5.0

Back to Top

For an up-to-date list of these changes for release 5.0, see this product's Release Notes available from the Product Documentation section of the OpenText Support for Micro Focus Products website.

  • Communications Facility syntax no longer supported
  • Monitoring Resource Manager Connections
  • Configuring SSL Security
  • JCL - Copying Empty Data Sets
  • JES Housekeeping
  • JES Security
  • JES Catalog Updates

Communications Facility syntax no longer supported

The Communications Facility (also referred to as the COMMS SECTION or COMMUNICATION SECTION) has long since been deprecated. Certain syntax relating to this was still accepted (but ignored) by the Compiler. That syntax is no longer permitted, and if encountered, the Compiler will now generate an error (COBCH1895 Communication Facility not supported); you must remove the section from your sources before recompiling.

Monitoring Resource Manager Connections

The processing associated with the ES_XA_RECONNECT environment variable has changed.

This processing has been replaced by a new CICS transaction (CRCN) monitoring and testing for disconnection and attempting reconnection at regular intervals.

ES_XA_RECONNECT is now used to specify this interval (in seconds) between connection tests carried out by the transaction.

If you currently have ES_XA_RECONNECT=TRUE, set it to an acceptable time for your installation (e.g. 5 seconds, 30 seconds, 60 seconds, etc…)

The ES_XA_???_NB_RETRIES variable is also no longer required with the new method of monitoring connections.

One or more RMs can be excluded from CRCN processing using environment variable ES_XA_EXCLUDE_MONITORING, i.e., ES_XA_EXCLUDE_MONITORING=RM1;RM2;RM3 excludes three resource managers, named RM1, RM2, and RM3.

See Monitoring Resource Managers for more information.

Configuring SSL Security

The validation of server certificates for TLS (also known as SSL) connections has been corrected. This is likely to cause connection failures in cases where previously connections were incorrectly allowed. For example, if Fileshare is secured with TLS, client applications must be configured to use the hostname of the Fileshare server as it appears in the server's certificate. If the Micro Focus Directory Server is secured with TLS, then MFDS clients, such as the casstart command-line utility, will need to connect to it using a hostname that appears in the certificate MFDS is using. Consult your Certification Authority administrator for more information.
Note: A certificate can contain multiple hostnames.

The default behavior for TLS certificate Common Name (CN) matching has changed for Enterprise Developer 5.0. It now requires a strict match on the CN value or any Subject Alternate Name (SAN). For example, 127.0.0.1 and localhost are no longer implicitly equivalent, nor are hostname and its IP address or fully-qualified domain name (FQDN) variants.

When starting a region from the Enterprise Server Administration Web interface, a resolved IP address is used for the casstart -m parameter value. A resolved IP address is also used even if a hostname is specified on a command line startup. To change this behavior and use a resolved hostname value (as determined by the machine TCP configuration, for example, hosts file entries.) set the environment variable MFDS_DNS_RESOLVE=Y. To use an unresolved string literal hostname, for example, a value explicitly passed in via the casstart -m command line parameter, set MFDS_DNS_RESOLVE=N.

JCL - Copying Empty Data Sets

As of Patch Update 5 of release 5.0, the incorrect changing of a VSAM data set file status from pristine to used when REPROing an empty data set has been corrected. When REPROing records into a data set, if the source data set is empty, the destination data set is not opened. The affect of this is that when OPENing INPUT a VSAM data set that was the destination of a REPRO of an empty data set, the file status is 35, rather than 00.

JES Housekeeping

When using the MVSSPLHK housekeeping process, the Spool Housekeeping history file (INDEXO) can now support 7-digit job numbering.

When you enable 7-digit job numbering, any existing data sets (specified by INDEXO) must be converted to a new format. A sample .jcl file (CONVERT.JCL) and a conversion utility (MFHKHCOV) are both supplied with this version of the product. Edit the .jcl file to reflect the name of your data sets and run it to convert the file. Once converted, the newly formatted data set supports both 5- and 7-digit job numbering. If you only use 5-digit job numbering, you do not need to run the conversion.

See the MVSSPLHK Spool Housekeeping Process section in the Help for more information.

JES Security

JCL security checks have been extended to verify that a user who submits a job has, at least, READ access to partitioned data sets whose members are used as catalogued procedures or INCLUDE files in the JCL file. Similarly, the user who runs the job must have, at least, READ access to JOBLIB and STEPLIB partitioned data sets mentioned in the job.

JES Catalog Updates

When using the public catalog API, MVSCATPB, changes to or deletion of a data set that is currently allocated to the job step are not permitted after the data set has been opened. If attempted, MVSCATPB will return a retcode of 78-RET-VALIDATE-ERROR (20) and a reason code of 78-dataset-in-use (19).

Also, when updating the DSORG of a data set using the REPL function, a check now verifies that the change is appropriate. If it is not, a return code of 78-RET-VALIDATE-ERROR (20) and a reason code of 78-MISMATCHED-DSORG (50) is produced.

Changes in Behavior in Release 4.0

Back to Top

For an up-to-date list of these changes for release 4.0, see this product's Release Notes available from the Product Documentation section of the OpenText Support for Micro Focus Products website.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • Enterprise Server security
  • Executables may require relinking or recompiling
  • HCO for SQL Server (HCOSS)
  • IMTK runtime configuration
  • Test Coverage results

Enterprise Server security

Web access to the Enterprise Server Console Log and Communications Server Log is now restricted when the enterprise server region is secured using external security. Users will be required to provide a valid username and password in order to view either log file.

Web access to the logs can be controlled using the standard ACL definitions under the new Communications Server resource class, with resources Enterprise Server Console Log and Communications Server Log. If these resources exist, users require 'read' access to be allowed to view the logs. If the resources do not exist, the default behavior is to allow 'read' access on entry of a valid username and password.

An example of the new resource class and resource definitions can be found in the es_default_ldap_msuser.ldf file, which is located in the bin sub-directory of your product directory.

Executables may require relinking or recompiling

Version 4.0 of your product is dependent on a later version of the Microsoft C run-time system than earlier Micro Focus products. This means that COBOL executables (.exe) built with an earlier version of your product might not be compatible with version 4.0 run-time products. If the behavior of your application changes with version 4.0, we strongly recommend that you relink the main executable with version 4.0. This will ensure that the COBOL run-time system fully handles any run-time error conditions that might occur.

A new executable that is fully compatible with version 4.0 can be produced without recompiling the application, as long as the original object code is available and it is relinked with version 4.0.

To allow your executables to benefit from the product's latest programming and performance enhancements, we recommend a full recompilation of your source code.

HCO for SQL Server (HCOSS)

When using the DIALECT=MAINFRAME setting, the OpenESQL STRICTPARSE SQL compiler directive option is now turned on by default for ODBC (DBMAN=ODBC). This ensures strict compliance with z/OS DB2 syntax.

If your applications require the OpenESQL preprocessor to behave as it did in an earlier release, compile using NOSTRICTPARSE.

IMTK runtime configuration

Due to changes made to the Configure Runtime Environment dialog box in this release, after you upgrade your system, you must reenter all previously set values on this dialog box before running a service.

Test Coverage results

Schema changes that affect the test coverage results generated from the tcutil utility mean that if you propagate the results to a third-party application (for example, an XSLT processor), and rely on the <copyFileCoverage> element, you need to alter your transformations to focus on <sourceFileCoverage> instead. The element was renamed to more appropriately reflect its contents, as tcutil now gives global coverage for all source files (not just copybooks).

Changes in Behavior in Release 3.0

Back to Top

For an up-to-date list of these changes for release 3.0, see this product's Release Notes available from the Product Documentation section of the OpenText Support for Micro Focus Products website.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • JES-enabled enterprise servers
  • Compiler Directives
  • JES security - the PHYSFILE resource class
  • OpenESQL
  • Reserved words

JES-enabled enterprise servers

Back to the list

Important: Existing JES-enabled Enterprise Server regions must perform this upgrade to continue using JES functionality. If you start a region without upgrading, the following message is displayed in the console log, and JES functionality is disabled:

JES000058E JES validation - Product requires new spool control files. Run spool conversion utility, splconv, to create them.

In this release, the infrastructure of the JES spool repository has been upgraded in order to improve performance. For each JES-enabled region, before you can submit any jobs to JES, you must run the spool conversion utility; any newly created regions will automatically be configured to use the new spool files.

The conversion process converts the information in the existing spool files to a set of new files required under the new system. There should be no loss of data in moving to the new system.

As well as significantly improved times when running housekeeping tasks, these changes have the additional benefits:

  • The new infrastructure is more disk-efficient, reducing the space required by the spool files by up to 75% in some cases.
  • Internal indexing is greatly improved, resulting in quicker generation of messages and SYSOUT records during processing.
  • Improved navigation of spool queues: job status Complete replaces the Output, Out Hold, and Printed statuses, and completed jobs with any combination of sysout files can be displayed in a single list.
  • Increased range of job numbers, from 5 digits to 6 or 7 digits; see details on the MF_MVSJOB environment variable.
    Important: After converting to the new JES spool infrastructure, we recommend that you do not employ the increased range of job numbers until you have thoroughly tested the new infrastructure. Reverting back to the previous JES spool files is possible, but requires that you remove all job entries using more than 5 digits, for which there is no easy process.

To run the spool conversion utility

  1. At the Enterprise Developer command prompt, set the following environment variables, as required:
    Variable | Description
    MFSYSCAT The location and name of the current JES catalog. This is mandatory.

    If multiple catalog files are being used (that is, one or more user catalogs are defined), this environment variable should point to the catalog where JES spool datasets are cataloged.

    MVSSPOOLDIR | The location of the current JES spool control files (for example: casspool.dat). This is only mandatory if the location is different to the location of the JES catalog.
    NEWSPOOLDIR | The location for the resulting JES spool control files (that is, the SPL* files if running the conversion, or the old-style spool files if running the regression). This is only mandatory if the location is to be different to the location of the existing spool files.
    MFSYSCAT_ERRS The number of catalog errors that will be tolerated during the conversion process before the conversion is terminated. This is optional, and defaults to 100.

    If the process is terminated, the following error is produced:

     *** Error: Error count exceeded - program terminating
  2. Type splconv, then press Enter.

    The conversion process runs, and details of the files and records converted are displayed to screen.

    Tip: It is common to see messages of the following type as the conversion runs:
    *** Error: Error raised on READ of MVSSPL
            File status is 23
            Processing record: Type=15 J#=,job no.> Seq#=<seq no.>

    Such a message is produced when a casspool sysout record is found, but no matching record is found in the MVSSPL01/02 file. The record type (15) indicates that this is an active spool record, which should only be present in casspool if a copy of the file were made while the associated ES region was in a started state, or the associated job had crashed.

    These messages can be safely ignored, but if more than 100 are generated, the default error limit will be exceeded, causing the conversion to terminate. If this situation occurs, set the error limit to a higher value, using the MFSYSCAT_ERRS environment value, and rerun the conversion process .

  3. If MVSSPOOLDIR and NEWSPOOLDIR were set to different locations prior to running the conversion, you must now set MVSSPOOLDIR to the value of NEWSPOOLDIR.
    Note: If you do not perform this step, you will receive the following error when you start your region, and JES fails to initialize:
    JES000058E JES validation - Product requires new spool control files. Run spool conversion utility, splconv, to create them.
  4. You can now start the region identified by the variables, and begin to submit jobs.

Reverting to the previous JES spool repository

If you plan to downgrade to an older version of your current product, any enterprise server region that has been converted or created with the current product will not be compatible. Before you can use them, they must be reverted to using the old JES spool repository.

Use this process if you are wanting to use a JES-enabled region in a previous version of the product:

  1. At the Enterprise Developer command prompt, set the environment variables listed in the To run the spool conversion utility process, as required.
  2. Set an additional variable, SPLREGR_TARGET, to PRE30.
  3. If the region has started to use 6- or 7-digit job numbers (an enhancement new to version 3.0 of the product), then before you run the regression, you must remove the jobs that are using these numbers, and ensure that the MF_MVSJOB environment variable (or the SPLJNO.dat file if the variable is not used) does not specify an upper limit greater than 5 digits.
    Note: If using the MF_MVSJOB environment variable, to revert to 5-digit job number support, set MF_MVSJOB=<low number>+<high number>, where high number is less than 0099999, and ensuring that the + sign is used to separate the low and high values.
  4. Type splregr, then press Enter.

    The regression process runs, and details of the files and records converted are displayed to screen.

    You can now use the region identified by the variables in previous versions of Enterprise Developer.

Exporting the spool files to Enterprise Server for .NET

If you plan to export a region to Enterprise Server for .NET, any enterprise server region that has been converted or created with the current product will not be compatible. Before you can use them, they must be reverted to using the old JES spool repository.

Use this process if you are exporting a JES-enabled region to Enterprise Server for .NET:

  1. At the Enterprise Developer command prompt, set the environment variables listed in the To run the spool conversion utility process, as required.
  2. Set an additional variable, SPLREGR_TARGET, to the appropriate value:
    DOTNET5
    Create spool files for use on Enterprise Server for .NET, using a maximum of 5 digits for job numbers.
    DOTNET7
    Create spool files for use on Enterprise Server for .NET, using a maximum of 7 digits for job numbers.
  3. Type splregr, then press Enter.

    The regression process runs, and details of the files and records converted are displayed to screen.

    You can now use the region identified by the variables in Enterprise Server for .NET.

Compiler Directives

The default for the FASTINIT directive has changed: FASTINIT is now the default when setting the MF dialect. The directive remains not set by default (that is, NOFASTINIT) for other dialects.

JES security - the PHYSFILE resource class

Back to the list

  • The PHYSFILE security setting is now checked when a dataset entry is inserted into the catalog, or when a dynamic PDS member is created. The check is made for all cataloged files, including spool files (for example, JESYSMSG and SYSOUT files). You should review any existing PHYSFILE rules to ensure they are correct, otherwise access may be denied where it was previously allowed; see Resource Classes for JES Security for more information.

    If the PHYSFILE class is created in the LDAP repository it is necessary to add appropriate rules to allow users that submit jobs to have 'write' access to the job log location, so that job submissions are successful.

    Note: If the files provided with release 3.0 have been used to populate the LDAP repository, the PHYSFILE resource class is created with no rules.

OpenESQL

Back to the list

The new OpenESQL OPTIMIZECURSORS SQL compiler directive option is turned on by default for both ADO.NET (DBMAN=ADO) and ODBC (DBMAN=ODBC). For ADO.NET, this reduces cursor memory consumption thereby providing optimal performance. This also ensures that, for ODBC, embedded SQL cursors that use WITH HOLD and FOR UPDATE clauses have the same data integrity across all databases.

If your applications require the OpenESQL preprocessor to use the behavior provided in an earlier release, compile them using OPTIMIZECURSORS=NO.

Reserved words

Back to the list

  • There have been a number of new reserved words added to the COBOL language; these are all in effect under MFLEVEL"19", which is the default level when running under the MF dialect. Any of the following words are now not allowed under default conditions, and you will need to remove/rename them, or specifically configure your environment to allow them:
    • ALLOCATE
    • FREE
    • JSON
    • END-JSON

    See Reserved Words Table at the end of this topic for more information.

Changes in Behavior in Release 2.3 Update 2

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • Enterprise Server
  • JCL Support
  • Micro Focus Directory Server
  • Monitoring and Management
  • Run-Time System

Enterprise Server

Back to the list

  • Previously, it was possible to install groups that should not have been installed. If a group name, as defined in the Startup List, did not exist in the list of Groups then the next Group in the alphabetical order would be loaded instead. Now, if a Group is not defined in the list of Groups, a warning that the Group could not be loaded is issued.

    2869848 (619107)

Micro Focus Directory Server

Back to the list

  • The "-n" option for the mfds command now supports hostnames as the network addresses in addition to IPv4 addresses.

    2816871 (1099564)

Monitoring and Management

Back to the list

  • Messages that are written to the console log by applications that perform "display upon console" now contain a standard message ID (CASMG0001I).

    2854207 (1103659)

JCL Support

Back to the list

  • A printer exit can now evaluate the spool copybook field lk-dest-source-is to find the source of the value in the spool DEST-NODE and DEST-USERID fields, to determine if it is from a SYSOUT 'DEST=' value or from a /*ROUTE PRINT value.

    2852302 (1103304)

Run-Time System

Back to the list

  • The command_line_linkage tunable has been deprecated; equivalent functionality can be achieved by using the COMMAND-LINE-LINKAGE Compiler directive instead.

    2838118 (1101539)

    Attention: As of release 4.0, this tunable is no longer deprecated.

Changes in Behavior in Release 2.3 Update 1

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • Communications Server
  • Enterprise Server
  • IBM Language Environment for OS/390 & VM Support
  • JCL Support
  • Run-Time System
  • SQL: OpenESQL
  • SQL Option for DB2

Communications Server

Back to the list

  • A new option, [Operation] synchronous=yes (or 1, or Yes, or y or Y) is now supported in the Fileshare listener configuration.

Enterprise Server

Back to the list

  • In situations where the crossregion option of the shareoptions parameter is either 1 or 2, both a CICS and a JCL job could have the same file open for IO. This has been fixed. In addition, the '-oo' (and the synonymous '-o ') option of the casfile command has been deprecated. If '-oo' is used, you will now receive a return code 4 (warning). Instead of '-oo', you need to use the '-ooi' option (open immediate). If -oo is used with a region configured for VSAM shareoption use, the '-ooi' option is now forced.

    2839272 (1101672)

  • When using an external security manager to secure a region, the EXEC CICS START TRANSID API now works as expected and honors the USERID option. Previously, the started transaction would run under the authority of the user that executed the EXEC CICS START API.

    2835112 (1101201)

IBM Language Environment for OS/390 & VM Support

Back to the list

  • When calling SETENV, SYSOUT(?) can be specified. This designates the file as a spool file but will not update its CLASS.

    2841220 (1101955)

JCL Support

Back to the list

  • The return code from a JCL printer exit will now be checked. If it is non-zero, the dataset that was sent to the printer exit will be moved to the OUT-HOLD queue rather than to the PRINTED queue. To release the dataset, click "Release" in the ESMAC view - this will also present the dataset again to the printer exit.

    2834206 (1101079)

  • Under Enterprise Server, flushing an active job previously resulted in all associated spool records for the job being deleted, but left the job running. A subsequent attempt to kill the running job using casout/seeout failed due to the job spool record no longer existing. This change causes the flush request to fail if the job is active. You must kill the active job first before attempting to flush it.
  • The catalog search facility has been enhanced to provide a quicker return when using wildcards in the dataset name selection.

    2698700 (1094266)

  • REXX can now be executed in VSE via IKJEFT01 and IRXJCL using in-stream data.

    2831984 (1100883)

Run-Time System

Back to the list

  • The Audit Manager contains a new TIMEOUT option. When a client sends an audit event using the ‘CBL_AUDIT_EVENT’ API, the event gets placed in the next available slot in a shared memory block. If shared memory is full (i.e. no slots are available), the event is re-tried until a slot becomes available.

    If no Audit Manager is running, no events are removed from shared memory, and no slots will ever become available. Therefore, use the new TIMEOUT option so that a client will only retry sending until the TIMEOUT duration is reached; after which, it will stop sending audit events. If Audit Manager is recycled, events will start to be sent again.

    To set the TIMEOUT for all Audit Manager clients, specify the following line in the Audit Manager configuration file:
    mfaudit.timeout = n
    Where n is the timeout value in milliseconds.

    To set the TIMEOUT for an individual Audit Manager client, use the ‘CBL_AUDIT_CONFIG_PROPERTY_SET’ API. It takes an integer property-value, which should be the timeout value in milliseconds.

    If TIMEOUT is set using both methods, the client property TIMEOUT takes precedence, unless this property is set to zero; in such cases, the TIMEOUT in the configuration file is used. If you use the ‘CBL_AUDIT_CONFIG_PROPERTY_GET’ API on the ‘TIMEOUT’ property, it only returns the TIMEOUT value for the client property; it does not return the value set in the configuration file.

    2838689 (1101685)

  • Several changes have been made to the implementation of IS DBCS, IS KANJI and IS JAPANESE class condition tests:
    • IS [NOT] DBCS

      When CHARSET"EBCDIC" is in effect, the IS DBCS test returns true when each character in the string is deemed to be a valid DBCS character. A valid character has its first byte in the range 0x41 through 0xFE, and the second byte in the range 0x41 through 0xFE, or the character is an EBCDIC space (0x4040). When CHARSET"ASCII" is in effect, the DBCS test uses an OS call to determine if the string contains only valid double-byte character, and returns true if valid.

    • IS [NOT] KANJI

      When CHARSET"EBCDIC" is in effect, the IS KANJI test returns true when each character in the string is deemed to be a valid Kanji character. A valid character has its first byte in the range 0x41 through 0x7F, and the second byte in the range 0x41 through 0xFE, or the character is an EBCDIC space (0x4040). When CHARSET"ASCII" is in effect, the IS KANJI test uses an OS call to determine if the string contains only valid Kanji character, and returns true if valid.

    • IS [NOT] JAPANESE

      When CHARSET"EBCDIC" is in effect, the IS JAPANESE test is not supported, and will generate a COBCH1806 Feature not supported in selected charset message on compilation.

      When CHARSET"ASCII" is in effect, the IS JAPANESE test returns true when the string contains only double-byte Japanese characters or single-byte Japanese Katakana characters, and returns true if valid. When NSYMBOL"NATIONAL" is in effect, these class tests are not supported, and will generate a COBCH0303 Operand has wrong data-type message on compilation.

    2812895 (1098401)

SQL: OpenESQL

Back to the list

  • The DB2 CONCAT function and operator now convert to SQL Server using the HCOSS-supplied dbo.CONCAT for character, numeric and datetime data. If you are using BINARY or VARBINARY data, you must apply the HCOSS-supplied dbo.CONCAT_BINARY function. HCOSS applications deployed with earlier versions of Enterprise Developer are affected, if they use string or binary concatenation. The mainframe dialect DB2 || operator and CONCAT function now call a new SQL Server scalar function dbo.CONCAT(). All existing programs with dialect=mainframe that use DB2 concatenation syntax should be recompiled. All existing SQL Server databases that are accessed by these programs must have dbo.CONCAT installed. To create the new function in your application’s SQL Server database, you can either:
    • Run a DSN bind against the customer database. Or:
    • Execute the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\InstallDigitsFunction.sql script.

    This is a one-time only change to the database.

    2843818 (1102248)

SQL Option for DB2

Back to the list

  • Spurious errors were sometimes returned while querying using an ALIAS.

    2830383 (1100609)

Changes in Behavior in Release 2.3

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

Where present, the numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • Assembler Support
  • CAS Security
  • CAS XA Switch modules
  • File Handling
  • J2EE Connector
  • JCL Support
  • Mainframe Access
  • MF Server Administrator (GUI)
  • SQL - HCO for SQL Server
  • Updated Run-Time System

Assembler Support

Back to the list

  • Previously, the Assembler run-time error SOC4 (Invalid 370 address abend) was mapped to the COBOL run-time error 200 (Internal logic error) which was misleading. It is now mapped to the COBOL run-time error 205 (COBRT205 Invalid mainframe pointer value (Fatal)). Note that, in most cases, you receive an Assembler SOC4 abend if the calling COBOL program was compiled without the AMODE(24) or the AMODE(31) Compiler directives.

    2806239 (1097738)

CAS Security

Back to the list

  • The Enterprise Server External Security Facility now includes MLDAP ESM Module 2.0, with a new algorithm for identifying the best-matching resource-access rule and ACE for resource-access security checks. This algorithm is faster and matches most customers' expectations. The new algorithm also provides an optional "username substitution" feature. It can be enabled by setting "rule substitutions" to "yes" in the [Operation] section in the Security Manager configuration text area. When this is enabled, the string "${user}" in a resource-rule name will be replaced with the name of the user that makes the request. For example, a DATASET rule named "USERS.${user}.**" would apply to datasets with the requesting user's name as the second qualifier. In rare cases, customers with complex, ambiguous resource-access security rules might see experience changes in behavior as a result of the new algorithm. The old algorithm is still supported and can be enabled by setting "version 1 authentication" to "yes" in the [Operation] section of the Security Manager configuration.

    2807531 (1097783)

CAS XA Switch modules

Back to the list

  • The XA switch modules now support dynamic registration.

    2682101 (1092325)

  • The XA switch modules now support batch-only operations when multiple XA Resource Managers have been defined.

    2664675 (1091082)

  • In Enterprise Developer 2.2 update 2, Micro Focus identified undefined run-time behavior when the following combination of directives was specified: SIGN"EBCDIC", CHARSET"ASCII", and one of the following: HOST-NUMMOVE, HOST-NUMCOMPARE or SIGN-FIXUP. Previously (Enterprise Developer 2.2 update 1 and earlier), if this combination was specified, the SIGN”EBCDIC” directive should have been ignored, to avoid a mixture of ASCII and EBCDIC characters; however, SIGN”EBCDIC” was still being honored, resulting in undefined run-time behavior. Therefore, this combination of directives is now invalid for Enterprise Developer 2.2 update 2 or later, and if specified, will be rejected at compile time.

    2786397 (1095265)

File Handling

Back to the list

  • Custom file handlers (using DYNREDIR) are now called for each part of a concatenated file.

    2795077 (1096322)

J2EE Connector

Back to the list

  • This release provides a new command-line argument to Java, mf.ssl.algorithm, which can be set to an appropriate algorithm.

    2799213 (1096684)

JCL Support

Back to the list

  • When allocating a dataset to a step using MVSCTLBP, the values returned for the dataset attributes are those defined in the catalog. If these are unset in the catalog, then the values defined in the MVSCTLBP call are returned.

    2816179 (1098882)

  • The program attributes for the SSTM job have been changed to default to a mainframe dialect, AMODE 31 program. These attributes will be used when constructing the MVS Control Blocks for the job, which means that the pointers to the sub-block areas will be in mainframe format rather than native format.

    2815695 (1098825)

  • Any OUTPUT statement information passed to the printer exit now includes the correct class of that statement.

    2814249 (1098636)

  • In ESMAC, when deleting the Spool, the physical spool files and the entries in casspool.dat are deleted.

    2812899 (1098412)

  • New functionality has been added to the printer exit interface that enables you to delete the printer spool file after a file has been printed. Set (ws)-prn-file-disp, which is defined in cascbprn.cpy, to 1 to delete the spool file after printing. Additionally, the environment variable ES_JESYSMSG_OUTPUT=Y now correctly routes spool files to the Output queue. Previously, ESMAC still showed the job on the HELD display, even when there were no spool files HELD.

    2812899 (1099966)

  • A new environment variable has been introduced - ES_JESYSMSG_RESTRICTED. JESYSMSG spool files are normally routed to HELD. This can be overridden by setting the environment variable ES_JESYSMSG_OUTPUT=Y, which causes all JESYSMSG spool files to be routed to OUTPUT. If ES_JESYSMSG_OUTPUT=Y is set but you require specific classes to be held, set the environment variable ES_JESYSMSG_RESTRICTED to a string containing the classes to be HELD.

    2812878 (1098417)

  • The IEBDG PICTURE value length must match the length specified. The value can now contain any characters including quotes as on the mainframe.

    2794881 (1096221)

  • Changes to the IDCAMS ALTER processing prohibit applying MGMTCLASS changes to GDGs and to a VSAM element other than a Cluster. Shareoption settings in a SMS DATACLASS are now applied to the VSAM elements correctly.

    2789939 (1095803)

Mainframe Access

Back to the list

Mainframe Access is now built using the IBM XL/C compiler rather than the SAS/C compiler that was used previously. This change requires you to update your production JCL procedures with reference to the supplied samples MFA, MFAS, and MFAAS. In each JCL procedure, change the STEPLIB DD statement and add a new one, CEEOPTS.

The web administration feature is no longer available in Enterprise Developer.

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.

MF Server Administrator (GUI)

Back to the list

  • Passwords that entered through either the MFDS or the ESMAC interface now use the same encoding.

    2792382 (1096011)

SQL: HCO for SQL Server

Back to the list

  • The return type for the HCOSS DB2 CHAR() function has changed from CHAR(255) to VARCHAR(255).

    2804069 (1097253)

Updated Run-Time System

Back to the list

  • Enterprise Test Server now provides an execution environment capable of running applications that were each built using different development products. A consequence of this is that if your application has a main COBOL executable (.exe) that was built with a version of Enterprise Developer prior to version 2.3, you should ensure that the executable is rebuilt and packaged with the new run-time system. This does not affect mainframe subsystem projects deployed to Enterprise Test Server. You can rebuild from the IDE or the command line.

    Other COBOL subprograms built with previous versions of Enterprise Developer are not required to be rebuilt.

Changes in Behavior in Release 2.2 Update 2

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • CICS Support
  • Compiler
  • Documentation
  • Enterprise Server
  • File Handling
  • Host Compatibility Option for SQL Server (HCOSS)
  • J2EE Connector
  • IMS Support
  • JCL Support

CICS Support

Back to the list

  • In CRTE mode, the transactions are now run using the correct userid if the user has signed on after running CRTE.

    2663890 (1091979)

Compiler

Back to the list

  • When using the HOSTRW directive with the mainframe dialect, Report Writer will now produce the full range of ASA control characters and will emulate mainframe print files.

    2697615 (1094527)

  • Fixed Binary (p<=7) is now an 8-bit, signed, 2's complement binary integer by default.

Documentation

Back to the list

  • The default setting for the MFALLOC_PCFILE environment variable has changed; the default is now set to Y, which means that when cataloguing a file that has a DCB attribute of DSORG=PS, a physical file is created for it if one does not exist. Previously, the default was set to N, which meant that a file was not created.

    2697571 (1094370)

Enterprise Server

Back to the list

  • The Enterprise Server External Security Facility now includes MLDAP ESM Module 2.0, with a new algorithm for identifying the best-matching resource-access rule and ACE for resource-access security checks. This algorithm is faster and matches most customers' expectations.

    The new algorithm also provides an optional "username substitution" feature. It can be enabled by setting "rule substitutions" to "yes" in the [Operation] section in the Security Manager configuration text area. When this is enabled, the string "${user}" in a resource-rule name will be replaced with the name of the user that makes the request. For example, a DATASET rule named "USERS.${user}.**" would apply to datasets with the requesting user's name as the second qualifier. In rare cases, customers with complex, ambiguous resource-access security rules might see experience changes in behavior as a result of the new algorithm. The old algorithm is still supported and can be enabled by setting "version 1 authentication" to "yes" in the [Operation] section of the Security Manager configuration.

    2807531 (1097783)

  • Starting with this release, IMSCONFG.DAT is no longer used for configuring enterprise servers. Instead, you need to use environment variables to control the following fields:
    Field Environment Variable
    LANG=PL/I PCB address lists ES_IMS_PLI_INDIRECT_PCBADDR=D|Y|N

    Where:

    D
    Dynamic (default) use indirect PCB address list when PSB language is PL/I and main program is PL/I.
    Y
    Always use indirect PCB address list if PSB language is PL/I.
    N
    Never use indirect PCB address list.
    IBM Platform ES_IMS_IBMPLATFORM=M|D

    Where:

    M
    MVS (default)
    D
    DOSVS Required by some DOS/VS customers.
    Secondary Index Sparse exit language ES_IMS_SPARSE_EXIT_LANG=C|A

    Where:

    C
    COBOL
    A
    Assembler
    Not set (default)
    Sparse exits disabled

File Handling

Back to the list

  • The ES_IMS_TLOG_FLUSH environment variable is now deprecated. To control TLOG flushing, use the following environment variable: ES_IMS_DB_TLOG_WRITETHRU=0|1
    0
    Forces the flushing of TLOG buffers to disk on COMMIT only (default)
    1
    Forces the flushing of TLOG buffers to disk on all database I/O
    To control database flushing, use the following environment variable: ES_IMS_DB_COMMIT_FLUSH=0|1
    0
    Forces the flushing of database buffers to disk on CLOSE only (default)
    1
    Forces the flushing of database buffers to disk on COMMIT only
    Depending on the number of database updates, the frequency of COMMITs, and other concurrent computer activities, use of these environment variables could cause significant performance degradation.

    2784949 (1095190)

  • The use of the environment setting MFJ_INPUTDS_ERROR=N has been extended so that an input file for a JCL step is now considered as optional and you no longer receive an error when the file is missing.

    2784622 (1095971)

Host Compatibility Option for SQL Server (HCOSS)

Back to the list

The mainframe dialect DB2 CHAR() function now calls a new SQL Server scalar function dbo.MFCHAR(). To create the new function in your application’s SQL Server database, you can either:

  • Run a DSN bind against the customer database.

    Or:

  • Execute the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\InstallDigitsFunction.sql script.

    Additionally:

  • The return type for the HCOSS DB2 CHAR() function has changed from CHAR(255) to VARCHAR(255).

2804069 (1097253)

J2EE Connector

Back to the list

  • The listSystem.properties file in package com.ibm.ctg.client was missing documentation for some sections.

IMS Support

Back to the list

  • The NODCX mfims dbdgen directive has been added to enable you to compile DBD source without executing data capture exit routines contained in the DBD source. Previously, data capture exit routines contained in the DBD source but that were not found during compilation were ignored. The new default behavior is to process all data capture exit routines unless NODCX has been specified.

    2579600 (1084675)

  • All existing IMS Global Physical Terminal edit routines (DFSGPIX0) in use must be recompiled with charset EBCDIC instead of charset ASCII.

    (606142)

JCL Support

Back to the list

  • Following the detection of an unrecoverable file status error on the casspool file, a message is displayed on the console and an ACCEPT statement is issued. This stops processing, allowing you to fix the underlying file problem, before continuing the job.

    2651654 (1090287)

  • You can now activate support for the VSAM Shareoption for batch jobs and for CICS files that use a catalog entry. For more details, see your product help.

    2660651 (1091290)

Changes in Behavior in Release 2.2 Update 1

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • COBSQL
  • Compiler
  • File Handler
  • JCL Support

COBSQL

Back to the list

  • COBSQL now displays appropriate COBOL syntax errors after encountering EXEC SQL statement errors.

    2673619 (1093197)

Compiler

Back to the list

  • In member reference in managed COBOL syntax, you may now only use parentheses when referencing methods. You can no longer specify parentheses when referencing fields or properties, as this will produce a syntax error. For example:
    set intLength to testString::Length()
    must change to:
    set intLength to testString::Length

File Handling

Back to the list

  • Random and Dynamic access of an empty VSAM file would open successfully. This has been changed to return a 3/5 file status to bring it into line with the mainframe.

    2692826 (1093604)

JCL Support

Back to the list

  • The final disposition processing of temporary datasets has been corrected to be in line with the mainframe processing, with a default value of PASS unless DELETE has been specified in the DD card. Previously, the default value was DELETE.

    2671175 (1091627)

  • When running batch programs, receiving an "Out of Space" error requires operator intervention to continue processing.

    2642115 (1089055)

  • You can now use MGMTCLAS to provide an EXPIRE AFTER number of days. This is used to calculate an expiry date for datasets allocated using the MGMTCLAS parameter.

    2664639 (1090992)

  • MFLEX*.DAT files were not being moved with spool files. Spool housekeeping now deletes LEX files when it deletes JESYSMSG. Also, to identify any remaining orphan LEX files, the MF_SPOOL_HK_LEX_SCAN environment variable sets spool housekeeping to scan the data directory for LEX files older than the max retain period.

    2659555 (1090759)

  • Spool housekeeping has been rewritten to provide a number of new features. These will be described in the product documentation.

    (592452)

  • The state of VSAM virgin files is now being correctly processed.

    2686149 (1093587)

  • A REPRO COUNT of zero is now processed as zero records to be included in the REPRO operation.

    2665006 (1091034)

Changes in Behavior in Release 2.2

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • Assembler Support
  • Common Communications Interface
  • File Handling
  • Interface Mapping Toolkit
  • IMS Support
  • JCL Support
  • MF Directory Server
  • MF Server Administrator (GUI)
  • Micro Focus Batch Scheduler Integration
  • Request Handler

Assembler Support

Back to the list

  • A "." (dot) specification is no longer ignored in the SYSIN environment variable or in the mf370ctl.cfg file when used to specify an output directory, and indicates the current directory. This is a change in behavior from Mainframe Express, where the "." (dot) character in the SYSIN environment variable or in the mf370ctl.cfg file is still ignored and assembler output files are placed in the directory specified by the SYSIN environment variable.
  • Assembler Build Output will now be sent to the location specified in the COBOL output path project setting. Previously, all Assembler build output went to the project directory.

Common Communications Interface

Back to the list

  • A new option, use_global_namespace, is available for the CCI.INI file in the Windows %SystemRoot% folder. If use_global_namespace is set, all the ccishared memory objects are created in a system-wide address space, and the applications hosted by different users, including system services, can communicate. To use this facility, edit the CCI.INI file and ensure use_global_namespace is set to "yes". [ccismem-base] # Allow interaction between users on a # single system. Using this option reduces security as # all users will have access to the same name space. use_global_namespace=yes If the value of this option is anything other than "yes", or if the option is missing, no change is made to the existing behavior.

    2195519 (1062800)

File Handling

Back to the list

  • When used with MFJSSTRICTSORT=ON, MFJSORT now errors (return code 16) if the input RECFM is different to a SORTOUT RECFM. It also errors if the input RECFM is different to an OUTFIL RECFM when FTOV or VTOF/CONVERT has not been specified.

    2643384 (1088993)

Interface Mapping Toolkit

Back to the list

  • For program-based Service Interfaces, if the program-id name in the COBOL source is in lowercase and is not surrounded by quotes, its corresponding entry-point name is now forced to uppercase when used in a Service Interface Operation. Previously, the case was preserved. As a result of this change, existing Service Interfaces will become invalidated if you refresh their program's annotations because of the new spelling of the entry-point name. To avoid this, you need to surround the program-id name in the COBOL source with quotes before you refresh the annotations.

IMS Support

Back to the list

  • The DBDCPY, MFSCPY, and PSBCPY environment variables are no longer required and have been deprecated. Use the IMSCPY environment variable to specify copybook locations.

JCL Support

Back to the list

  • The default for previous releases was to create a catalog entry with no physical file until data was actually written to the catalog. Now, a PC file is allocated for non-VSAM files by default. You can emulate the previous behavior if you set the environment variable MFALLOC_PCFILE to N.
  • Empty values for the USER or NOTIFY parameters on the JCL JOB card no longer cause an error when parsing the JCL.

    2646770 (1089380)

  • The disposition processing of PASSed datasets has been revised to be consistent with mainframe processing. Particularly, received datasets are removed at the end-of-step processing, unless they are to be passed on to another step in the job. Any passed datasets that were not received at the end of the job may be removed if they conform to the mainframe conditions for this.

    2610362 (1087601)

  • The value for the JCL DD UNIT=device parameter is now stored in the system catalog entry for the dataset.

    2619050 (1089095)

MF Directory Server

Back to the list

  • The mfds command line option for exporting registered Enterprise Server definitions to an XML file now supports the "*" option. This exports all registered servers rather than a specified server. Multiple server definitions are now exported into the target directory and saved into a file with the default name ALLSERVERS.xml. The import option now also supports the import of multiple server definitions from a single XML file.

    2641890 (1088838)

  • mdump now supports a new option, -e, to help you query the Security Manager configuration details. The possible values of the option are: "1" - shows security configuration that applies to any returned enterprise servers; "2" - shows security configuration for MFDS and the default Enterprise Server security configuration. This requires MFDS version 1.15.00 or higher; "3" - returns the properties of all configured external Security Managers.

    2487164 (1081693)

MF Server Administrator (GUI)

Back to the list

  • When adding a user to an external security manager, you can now include a password expiry time in the Advanced Configuration section of the Add New User wizard in Enterprise Server Administration. The field value is specified using generalized time format (YYYYMMDDHHMMSS.0Z), and can be used by the MLDAP ESM for calculating whether a user's password has expired and requires updating. This value may only be specified using this page when adding a user. You need to use an external directory services configuration tool to edit it.

    2562118 (1083203)

Micro Focus Batch Scheduler Integration

Back to the list

  • casout now correctly sets return-code to the job status for the sysout retrieval when the file is less than 65K. Also, MFBSI now considers return codes of 0, 7 or 8 to be successful for JESYSMSG retrieval where, previously, it only considered 0 as successful.

    2655482 (1090444)

Request Handler

Back to the list

  • A problem that caused BIS to create log files in a directory named C:\ProgramData\AcuCorp\BIS\LogFiles was fixed. BIS no longer creates log files unless specified and the BIS logging service is now disabled by default. To enable it, you need to use the following global environment variable: BIS_LOG=[ OFF | ON | <directory> ] Where the values are:
    • OFF - disables logging (the same as if BIS_LOG is not specified or is left blank)
    • ON - enables logging and directs the log files into the default location, which must not be read-only.
    • <directory> - enables logging and directs the log files into the specified directory. The user must ensure that the BIS request handler has write rights for this directory. The directory must be an absolute path or network path. If the specified directory does not exist, BIS will attempt to create it. The containing directory must exist.

    The BIS_LOG variable is only examined when the BIS application pool is started or recycled. After setting or changing BIS_LOG, IIS must be restarted in order for the variable to take effect.

Changes in Behavior in Release 2.1 Update 1

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • Enterprise Server
  • JCL Support
  • OpenESQL

Enterprise Server

Back to the list

  • HSF includes the following enhancements:
    • A new record type (JCLF) for JCL files.
    • A Job class has been added to the JCL JOBSTART records.
    • A condition code has been added to the JCL STEP records.
    • Statistics for up to 5 Transient Data Queues per CICS record has been added (same as for exisiting TSQ stats). The HSF files will now be created with the following 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,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

    2552658 (1082755)

JCL Support

Back to the list

  • Input files are no longer optional so you can receive errors if you catalog a file without creating the physical file. To help avoid failures of JES job steps because of a missing input file, you can use one or both of the following environment variables: 1) MFALLOC_PCFILE=Y - results in the creation of a catalog file if DSORG=PS is set in the DCB parameters. 2) MFJ_INPUTDS_ERROR=N - results in IEBDG, IEBGENER and IEBCOMPR utilities to treat missing input files as though they were present but empty files.

    (594968)

OpenESQL

Back to the list

  • SQLWARN4 flag was not being set when more than one row was returned for a singleton SELECT statement. The OpenESQL run-time now correctly sets SQLWARN flags when a singleton SELECT statement returns multiple rows.

    2593798 (1085945)

Changes in Behavior in Release 2.1

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • CICS Support
  • Run-Time System
  • Vision File System

CICS Support

Back to the list

  • If external security is configured (MLDAP) and the default ESMAC user is not allowed to login, the region does not startup.

    2550800 (1082337)

Run-Time System

Back to the list

  • When running a full-screen application inside a terminal emulator on Linux, the actual size of the terminal is read at startup and reread when the terminal is resized. This behavior is also supported on AIX, HP/UX, and Solaris. The Micro Focus vt220 terminfo entry now correctly describes a 24-line display. A vt220-25 terminfo entry is included for compatibility with the previous behavior.

    2579335 (1084817)

Vision File System

Back to the list

  • When you configure your application to return RM/COBOL file status codes, by setting COBFSTATCONV=rmstat, the codes returned are ANSI'85 codes.

    2553438 (1082469)

Changes in Behavior in Release 2.0

Back to Top

This section describes significant changes in behavior or usage. These changes could potentially affect the behavior of existing applications or impact the way the tools are used.

The numbers that follow each issue are the Support Incident Numbers followed by the Reported Problem Incident (RPI) number (in parentheses).

  • HCO for DB2 LUW
  • File Handling
  • Run-Time System

HCO for DB2 LUW

Back to the list

  • The DB2 ECM has been updated to resolve run-time errors returned when compiling against mainframe databases in 64-bit mode.

    2549058 (1082441)

File Handling

Back to the list

  • When reading a file cataloged as DISP=SHR the file handler now buffers the read for better performance.

    2518330 (1079491)

  • Using SKIP=nL in the SECTIONS section of SORT will now cause the following behavior: 1)Under a mainframe sort, (n/3 rounded up) blank lines (when n>0) will be skipped and the appropriate carriage control character will be placed in column 1 of each blank line. 2) For sequential file organizations, the same behavior will occur but no carriage-control characters will be printed. 3) For line sequential files, n blank lines will be skipped.

    2525670 (1080092)

Run-Time System

Back to the list

  • On Windows 7, building 64-bit native COBOL applications always rebuilt the entire project. This was caused by the Microsoft FileTracker tool, used by the COBOL projects to track dependencies, not working because of Windows 7 security updates. This product now includes a fix to work around this issue.
Parent topic: Updating from an Earlier Release


Where do I start?

Now that you have installed Enterprise Test Server, where you find the information you need in order to get started depends on which aspects of the product you need to get to grips with first.

The following sections direct you to key sources of information that will enable you to quickly get started with application development.

  • Want to deploy an application
Parent topic: Welcome


Want to deploy an application

Applications that you develop in Enterprise Developer require a variety of run-time system support files in order to be able to run. When running these applications from Enterprise Developer, these support files are accessed from Enterprise Developer itself, but if you need to deploy these applications to users that do not have Enterprise Developer installed you also need to deploy Enterprise Test Server to provide the required run-time system support files. When deploying Enterprise Test Server in this way you can choose to package it with your application's executable files or separately.

Exactly how you deploy an application depends on a number of factors such as the type of application (native or managed), the environment you are deploying to, and whether you want to provide a setup program. This topic of the Help helps to you determine exactly how best to deploy the applications that you have developed.

Where to start?

Once you have compiled your application, locate the application's executable files and any configuration files required during run time. How you deploy then depends on the type of application:

  • Start with a brief Overview of deploying applications.
  • Discover various ways you can ship the Micro Focus COBOL run-time system.
  • See Deploying native applications for considerations about how to create a setup program and how to set up your application and Enterprise Test Server.
  • See Deploying .NET COBOL Applications if you have .NET COBOL applications
  • See Deploying COBOL Applications to .NET if you have an application that targets the .NET.
  • See Deploying Stored Procedures to find out how to execute stored procedures on a remote machine.

What next?

There are a number of different examples from Micro Focus about applications you can deploy:

  • Check the Micro Focus YouTube channel for videos such as ones showing how to deploy Web Services or to Enterprise Server. For example:
    • HowTo IMTK - a series of videos about how to create and deploy Web Services
    • Implementing a COBOL program as a SOAP Web service
    • Implementing a COBOL program as a REST Web service
    • Accessing the IBM WebSphere MQ
Note: Some of the videos use Visual COBOL but the information equally applies to Enterprise Developer.

Also, check the Micro Focus Enterprise Developer YouTube videos that show how to develop applications that run on the mainframe.

Parent topic: Where do I start?


Enterprise Test Server Tutorials Guide

There are a number of tutorials that guide you through various aspects of application deployment using Enterprise Test Server.

The following tutorials are available:

Fileshare

Tutorial | Shows you how to
Fileshare Walkthrough | Configure Enterprise Test Server so that all I/O for applications running in your enterprise server go via a Fileshare server.

Security

Tutorial | Shows you how to
Tutorial: Configuring SSL Security in the Server | Configure SSL security.
Checking, Exporting and Importing Certificates | Look at the certificates already installed on your machine, regardless of the Micro Focus Security Pack.
Parent topic: Welcome


Product Information

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

  • Rocket Software End User License Agreement
  • Supported Operating Systems and Third-party Software
    Lists operating systems supported and tested with the Enterprise Developer and Enterprise Test Server software products, and third-party software supported by major features within these products.
  • Additional Software Requirements
  • Installation
  • Updates and Product Support
  • Backward Compatibility with Server Enterprise Edition or Studio Enterprise Edition Test Server
  • Known Issues and Restrictions
  • Contacting Micro Focus
Parent topic: Welcome


Rocket Software End User License Agreement

IMPORTANT: ROCKET SOFTWARE, INC. OR ITS AFFILIATE DESIGNATED IN THE ENTITY TABLE LOCATED AT www.rocketsoftware.com/company/legal/AMC-assigned-entity ("LICENSOR") PROVIDES LICENSED SOFTWARE TO LICENSEE (HEREINAFTER "CUSTOMER") UNDER THIS END USER LICENSE AGREEMENT (THE "AGREEMENT"). THIS AGREEMENT GOVERNS CUSTOMER'S INSTALLATION AND USE OF THE VERSION OF THE LICENSED SOFTWARE IDENTIFIED IN THE APPLICABLE PRODUCT ORDER, OR IF NOT ACQUIRED VIA A PRODUCT ORDER, CUSTOMER'S DOWNLOAD AND INSTALLATION OR USE OF THE LICENSED SOFTWARE CONSTITUTES ACCEPTANCE OF THIS AGREEMENT. PLEASE READ THIS AGREEMENT CAREFULLY, AS IT CONTAINS RESTRICTIONS ON CUSTOMER USE OF THE SOFTWARE. THIS AGREEMENT SUPERSEDES AND CONTROLS OVER ANY OTHER TERMS PROVIDED TO CUSTOMER REGARDING CUSTOMER'S USE OF THE LICENSED SOFTWARE, WHETHER WRITTEN OR ORAL, UNLESS A DIFFERENT WRITTEN AGREEMENT IS EXPRESSLY REFERENCED IN A PRODUCT ORDER OR EXECUTED BY LICENSOR AND CUSTOMER THAT SUPPLEMENTS OR SUPERSEDES ALL OR PORTIONS OF THIS AGREEMENT. ENTERING INTO THIS AGREEMENT DOES NOT CONSTITUTE A SALES TRANSACTION.

  1. DEFINITIONS. Capitalized terms in this Agreement are defined as follows:

    "Additional License Authorization" or "ALA" means the additional specific software license terms that govern the use of a given software product, including (but not limited to) the provisions of the Non-Production Licensing Guide. The ALA(s) for Licensed Software are found at https://www.rocketsoftware.com/company/trust/agreements by product name, or can be provided by Rocket Software at Customer's request.

    "Customer" or "Licensee" means the legal entity or individual that is identified in the applicable Product Order or who has rightfully received a license to the Licensed Product.

    "Documentation" means the user documentation Rocket Software makes available for Licensed Software.

    "Licensed Product" means Licensed Software and Documentation.

    "Licensed Software" means the executable version of the software listed in the Product Order or otherwise provided to or rightfully acquired by Customer. This Agreement will govern the use of any update to the Licensed Software that Customer receives pursuant to a separate support and maintenance agreement as described in the Support and Maintenance section below, unless such update contains, comes with, or is otherwise specifically governed by a different end user license agreement.

    "Open Source Software" means software or other material embedded in or made available with a Licensed Product where such software or other material is made available under an "open source license" as this term is commonly understood by members of the open source community, including, but not limited to, those licenses meeting all the criteria prescribed in the Open Source Definition provided by the Open Source Initiative (https://opensource.org/osd).

    "Product Order" means the combination of a Rocket Software Quote and a purchase order or purchase order alternative agreed to by the parties for the sale of a license(s) of one or more specific items of Licensed Software to Customer.

    "Rocket Software" or "Licensor" means the applicable Rocket Software entity listed on the Entity Table.

    "Rocket Software Quote" is a quote issued by Rocket Software or its authorized billing agent which contains the one or more specific items of Licensed Software, quantity, price and other pertinent license details.

    "Third Party Component" means any third party run time or other elements embedded in Licensed Software other than Open Source Software.

    "Third Party Software" means additional or accompanying third party software (other than Open Source Software or Third Party Components) that is specified in the Documentation or in a file accompanying Licensed Software.

    "Warranty Period" means the 90-day period starting from the date Licensed Software is delivered to Customer.

  2. PRODUCT ORDERS. The licensing of software products takes place under Product Orders which (unless stated otherwise in the Product Order) incorporate the terms of this Agreement. Any terms that conflict or are in addition to the terms of this Agreement or any applicable ALA ("Inconsistent Terms") in a purchase order or other document issued by Customer are rejected by Rocket Software and have no force and effect. If there is any Inconsistent Term(s) in a Product Order, such Inconsistent Term(s) shall not apply except where such Inconsistent Term(s) is contained in a Rocket Software Quote or a Product Order that is signed by both parties. Open Text Corporation("OpenText") and its affiliates are temporarily providing quoting and invoicing service for certain Rocket Software products and services and is acting as a billing agent for Rocket Software until further notice. Rocket Software will provide relevant billing and payment information as and when the transition to Rocket Software invoicing and billing systems occurs. Rocket Software is not otherwise affiliated or associated with Micro Focus or OpenText. "Micro Focus" and "OpenText" are registered trademarks of OpenText or its affiliates.
  3. LICENSING.
    1. License. Except as specifically permitted in the applicable ALA, or as described in the Evaluation Licenses section below, Rocket Software and its affiliates, respectively deliver and license to Customer the Licensed Products under a non-transferable, non-sublicensable, non-exclusive license to use Licensed Software and its Documentation as set out in this Agreement and/or the applicable ALA and solely for Customer's internal business operations and not for further distribution or commercialization.
    2. Evaluation Licenses. Except as specifically permitted in the applicable ALA, when Rocket Software and its affiliates, respectively deliver and license the Licensed Products solely for evaluation, Customer receives a non-transferable, non-sublicensable, non-exclusive license to use Licensed Products for internal evaluation and testing purposes only, and not for any development, production, distribution or commercial purpose ("Evaluation License"). The term of an Evaluation License will be 30 days starting from the date Licensed Product is delivered (i.e., made available for download or physically delivered) to Customer ("Evaluation Term"), unless Rocket Software authorizes a different period in writing. The Licensed Product is provided "as is" and there are no warranties or obligations for Rocket Software to provide support. The Evaluation License terminates at the end of the Evaluation Term, and Customer is required to return, or, if Rocket Software so directs, delete and destroy, all copies of such Licensed Product and provide Rocket Software with written confirmation of its compliance with this provision within 30 days of the end of the Evaluation Term. The Evaluation License for any prerelease or beta versions of Licensed Software ("Pre-Release Software") shall be for a term of 90 days unless Rocket Software authorizes a different period in writing. Customer agrees to promptly report to Rocket Software all problems (including errors, failures, nonconforming results, and unexpected performances) and any comments regarding the Pre-Release Software and to timely respond to all questionnaires submitted by Rocket Software regarding the results of Customer's testing of the Pre-Release Software. Rocket Software may choose not to release a final version of the Pre-Release Software or, even if released, to alter prices, features, specifications, capabilities, functions, release dates, general availability, or other characteristics of the Pre-Release Software.
  4. USE RESTRICTIONS.
    1. Except as specifically permitted in the applicable ALA or Documentation, Customer will not, directly or indirectly:
      1. Use Licensed Software for time-sharing, outsourcing, hosting, service bureau or like use, or permit access by, or use for the benefit of, any third party;
      2. Modify or create derivative works of Licensed Software;
      3. Reverse engineer, decrypt, disassemble or otherwise attempt to discover the source code of Licensed Software, except to the extent permitted by applicable law;
      4. Unbundle component parts of Licensed Software for separate use, where Licensed Software with multiple components is provided to Customer as a single product;
      5. Publish or disclose to third parties any evaluation or benchmarking of Licensed Software; or
      6. Alter, destroy, or remove any proprietary notices or labels on or embedded in Licensed Software.
    2. Customer may make a reasonable number of archival copies of Licensed Software and Documentation, and will reproduce all copyright and other proprietary rights notices appearing in or on Licensed Products, including notices of all third party suppliers, on all permitted copies.
  5. TERM. This Agreement and the license term for the Licensed Software granted herein is perpetual, unless a subscription/term license has been purchased by Customer (in which case the license term shall be set forth in the Product Order or ALA), and is subject to earlier termination as provided in the Termination section below. If Customer has purchased a subscription/term license, such license shall automatically terminate upon expiry of such subscription/term, unless earlier terminated in accordance with this Agreement.
  6. TERMINATION. Except as set forth herein, either party may terminate this Agreement, and/or any license granted, on written notice if the other party materially breaches the terms of this Agreement, or any applicable ALA or Product Order and does not cure the breach within 30 days of the date such party is notified of such breach. Rocket Software may terminate this Agreement, along with any or all licenses then in effect with Customer, immediately by giving Customer written notice of termination in the event that (i) Customer becomes insolvent, has a receiver appointed, or files for or has filed against it, liquidation, bankruptcy or analogous proceedings; or (ii) Customer infringes or misappropriates the intellectual property rights of Rocket Software. Termination shall be without prejudice to any other rights or remedies a party may have. In the event of any termination, Customer's license(s) to install, access or use the Licensed Software will immediately terminate, and Customer shall destroy and erase all copies of such Licensed Software in its possession or control and provide written certification to Rocket Software that it has complied with this provision. Early termination of this Agreement or any Product Order will not entitle Customer to any credit or refund or reimbursement of any previously paid fees.
  7. SUPPORT AND MAINTENANCE. Customer is not entitled to any updates to Licensed Software, unless Customer purchases (or may receive under a subscription/term license) maintenance and support services pursuant to Rocket Software's then current applicable standard maintenance and support agreement (which is found at https://www.rocketsoftware.com/company/trust/agreements or can be provided by Rocket Software at Customer's request).
  8. HARDWARE. In the event that Rocket Software provides Licensed Software embedded in an appliance, or provides hardware to Customer for use in conjunction with Licensed Software, additional hardware terms and conditions will apply. In all other instances, Customer will obtain and install any necessary hardware for proper installation and implementation of Licensed Software.
  9. PROFESSIONAL SERVICES. If Customer has Rocket Software or a Rocket Software affiliate perform any services with respect to Licensed Software (e.g., installation, implementation, maintenance, consulting or training), Rocket Software or its affiliate will provide those services at its then current standard terms and conditions and rates unless otherwise agreed in writing by the parties. Customer may agree to enter into a professional services engagement with Rocket Software or its affiliate through a separate agreement or statement of work.
  10. LIMITED WARRANTY. Rocket Software warrants for the Warranty Period that the Licensed Software substantially conforms in all material respects to the Documentation, and any media on which Rocket Software provides Licensed Software is free from defects in materials and workmanship under normal use.

    Customer's sole and exclusive remedy for breach of such warranty is (i) repair or replacement of the applicable Licensed Software or media free of charge so that it substantially conforms to Documentation or (ii) if Rocket Software reasonably determines such remedy is not economically or technically feasible, a refund of the license fee and any maintenance fee paid for the Licensed Software for the current year. The license to use such Licensed Software will immediately terminate when Customer receives the refund.

    The warranties described herein do not apply if the defects in Licensed Software or media result from: (i) failure to use Licensed Software in accordance with Documentation, this Agreement or the applicable ALA; (ii) malfunction of Customer's equipment or network; (iii) accident, neglect, or abuse; (iv) service by any unauthorized person; (v) other software used by Customer not provided by Rocket Software, or for which Licensed Software is not designed or licensed for such use; or (vi) any other cause occurring after initial delivery of Licensed Software or media to Customer, unless directly caused by Rocket Software. For purposes of this Agreement, Licensed Software is deemed delivered when it is first made available for download by, or physically delivered to, Customer.

    Rocket Software has no responsibility for any claims made outside the Warranty Period.

    The warranties described herein also apply to Third Party Components, but do not apply to (i) any free-of-charge Licensed Software or updates provided following the Warranty Period; or (ii) third party software that is not a Third Party Component.

  11. DISCLAIMER OF WARRANTY. Except for the limited warranties herein, Licensed Products are provided "as is" without warranty of any kind. To the extent permitted by law, all implied or statutory terms, conditions, representations, and warranties (including without limitation all terms, conditions, representations and warranties regarding merchantability, quality or fitness for a particular purpose, title or non-infringement, or that may arise out of course of dealing, usage or trade practice) are expressly disclaimed and excluded to the extent allowed by applicable law. The limited warranties in this Agreement are provided on the basis that Customer is procuring Licensed Products for the purposes of a business and not for household or consumer use. Rocket Software does not warrant that operation of Licensed Software will be uninterrupted or error-free. Customer has sole responsibility to select Licensed Software that works with other software, applications or systems to achieve intended results.
  12. LIMITATION OF LIABILITY.
    1. Liability Cap. In no event will any liability of one party to the other party arising out of or in connection with this Agreement exceed the total fees paid by Customer for the affected Licensed Software in the relevant Product Order(s) (including related maintenance and support). Nothing in this Section shall limit either party's liability for: willful misconduct or fraudulent misrepresentation; unauthorized use of intellectual property; breach of license; death or bodily injury caused by negligence; non-payment of amounts owed; or any liability which may not be excluded or limited by applicable law.
    2. Mutual Disclaimer of Consequential Damages. In no event will either party be liable for any indirect, special, incidental, consequential, punitive or similar damages; loss of profits, business, data or programs (including, but not limited to, the cost of recovery or replacement of such data or programs); loss, damage or any costs due to interruption, delay or inability to use Licensed Software, whether arising out of or in connection with this Agreement, even if informed of the possibility of such damages in advance.
    3. Scope. The limitations and disclaimers herein apply to all causes of action, including but not limited to, breach of contract, breach of warranty, negligence, strict liability, misrepresentation and other torts.
    4. Exclusive Remedy. The remedies in this Agreement are the parties' exclusive remedies and the limitations of the Liability Cap section and the Mutual Disclaimer of Consequential Damages section apply even if these remedies fail of their essential purpose. Customer may have other rights, including consumer rights, under the laws of the state or country where it is located.
    5. Free-of-Charge Software. If Rocket Software provides Customer with any Licensed Software free-of-charge or under an Evaluation License, to the extent permitted by law, Rocket Software and its affiliates will not be responsible for any loss or damage to Customer, its customers, or any third parties caused by that Licensed Software which is free-of-charge.
  13. OWNERSHIP. Rocket Software, Inc. and its affiliates and their suppliers own or have the right to use or further distribute all intellectual property rights in Licensed Products, and authorize Rocket Software to distribute Licensed Products under this Agreement. Customer's only rights in Licensed Products are the express licenses referenced in this Agreement or the applicable ALA.
  14. OPEN SOURCE SOFTWARE AND THIRD PARTY SOFTWARE. Open Source Software and Third Party Software are governed by the terms of their respective licenses and not the terms of this Agreement, notwithstanding anything to the contrary in any applicable ALA. Information about the Open Source Software may be found in a file accompanying the Licensed Software or in the Documentation or ALA.
  15. LICENSE FEES AND PAYMENT TERMS. Customer will pay the license fees set forth in the applicable Product Order for Licensed Software within 30 days of the date of invoice. Software license fees are non-refundable, except as provided herein, and will be paid without deduction or tax withholding. Software License fees are exclusive of any transportation charges, sales, use, value added, and other applicable taxes and duties, and all such amounts will be paid or reimbursed by Customer. Customer will be liable for all outstanding past due amounts, which will accrue interest (at the rate of 1.5% per month compounded or the maximum rate permitted by law if lower) and any collection costs for recovery of past due amounts.
  16. LICENSE VERIFICATION. Rocket Software has the right to verify Customer's compliance with licenses to the Licensed Software.

    Customer agrees to keep records sufficient to show Customer's compliance, including serial numbers; license keys; logs; records identifying machines on which Licensed Software is installed, accessed, or from which Licensed Software can be accessed; the number of different users accessing or authorized to access Licensed Software (if applicable); and licensing metrics, reports, and copies of Licensed Software. Rocket Software may require Customer to provide information about its deployment of Licensed Software, which may be in the form of a questionnaire. Customer will have a reasonable time to complete the questionnaire (or other form of request) and provide it to Rocket Software with an authorized Customer signatory certifying the accuracy of the information furnished. Upon 10 days prior written notice, Rocket Software or its designated representative may inspect Customer's records, systems and facilities, during Customer's normal business hours, to verify compliance with licenses to the Licensed Software. Customer agrees to cooperate with such verification. Information obtained will be used solely for compliance purposes and will otherwise be subject to the confidentiality provisions of this Agreement. If Customer has engaged in unlicensed installation, use of, or access to Licensed Software or infringed or misappropriated intellectual property rights in Licensed Software, or has otherwise breached this Agreement or an ALA (a "Non-Compliance"), without prejudice to Rocket Software' other rights or remedies, including, without limitation, injunctive relief, within thirty (30) days' notice of such Non-Compliance, Customer agrees to purchase sufficient licenses and or subscriptions and associated support and maintenance (12 months forward and any applicable back support and maintenance) to cure the Non-Compliance, by paying Rocket Software's current (as of the date of such additional purchase) list license fees and support and maintenance fees to Rocket Software, plus interest (compounded at 1.5% monthly or the maximum rate permitted by applicable law if lower) for such additional licenses from the commencement of the Non-Compliance until payment of the aforementioned fees, with interest payable even if an invoice was not issued at the time the Non-Compliance occurred. If Customer's Non-Compliance results in an underpayment of license fees of 5% or greater, Customer shall also reimburse Rocket Software for the reasonable cost of such audit in addition to other amounts due.

  17. PRIVACY. Customer is solely responsible for, and assumes all liability with respect to, its own collection, processing, storage, and transfer of any user data, including personally identifiable information, personal health and financial information, and other forms of personal information (collectively, "Personal Information"). Customer is solely responsible for notifying its users of proper use of such data. Customer is solely responsible for assessing the Licensed Product or any related product or service for compliance with any industry requirements applicable to Customer. Each party must comply with its respective obligations under all applicable laws, regulations, and industry standards regarding data collection and data privacy that apply to use of Licensed Software. Personal information or customer data that Customer provides to Rocket Software for the purpose of receiving products or services will be handled in accordance with the Rocket Software Global Data Protection and Privacy Notice (https://www.rocketsoftware.com/company/legal/privacy-policy) and the privacy and data security provisions in the applicable ALA.
  18. USE OF CUSTOMER INFORMATION. To the extent permitted by law, Customer expressly consents to the collection and use of information about Customer's purchase, installation and use of Licensed Software and the computer systems on which it is installed or accessed as necessary to fulfill the Product Order and provide the Licensed Product, for security and licensing purposes and to improve Rocket Software products and services.
  19. CUSTOMER FEEDBACK. Customer agrees that, should it provide Rocket Software with any feedback or suggestions regarding Licensed Products ("Feedback"), Rocket Software and its affiliates will be free to use all such Feedback, including (but not limited to) all intellectual property rights in and to such Feedback, in their discretion and for any purpose, without obligation of any kind to Customer.
  20. CONFIDENTIAL INFORMATION. Information exchanged under or in connection with this Agreement, including all information pertaining to Pre-Release Software, will be treated as confidential if identified as confidential at time of disclosure, or if the circumstances of disclosure reasonably indicate such information should be treated as confidential. Confidential information may only be used for the purpose of fulfilling obligations or exercising rights under or in connection with this Agreement, and shared with employees, affiliates, agents or contractors with a need to know such information to support that purpose, who are contractually bound to protect its confidentiality. Confidential information will be protected using a reasonable degree of care to prevent unauthorized use or disclosure for three years from date of receipt. These obligations do not cover information that (i) was known or becomes known to the receiving party without a duty of confidentiality; (ii) is independently developed by the receiving party; (iii) becomes publicly available without breach of this Agreement; (iv) is disclosed with the disclosing party's prior written consent; or (v) where disclosure is required by law, a court or government agency. Should the receiving party be required to reveal confidential information under subpoena, court order or other operation of law, the receiving party will provide reasonable prior notice to the disclosing party and request a protective order, if available.
  21. INDEMNIFICATION FOR INTELLECTUAL PROPERTY RIGHTS INFRINGEMENT. Rocket Software will defend and/or settle any claims against Customer that Licensed Products furnished under this Agreement infringe a third party's patent, copyright, or trade secret rights. existing under the laws of a country where Customer is using the Licensed Product ("IP Infringement Claim"), provided: (i) Customer promptly notifies Rocket Software in writing of the IP Infringement Claim; (ii) Rocket Software has sole control of the defense and all related settlement negotiations; and (iii) Customer reasonably cooperates with Rocket Software in the defense of the IP Infringement Claim.

    Rocket Software will pay all damages, costs, and expenses finally awarded (or agreed to by settlement) for any such IP Infringement Claim. Rocket Software will pay all reasonable out-of-pocket costs incurred by Customer for cooperation in the defense of the IP Infringement Claim. If, however, Customer wants separate legal representation, Customer will be responsible for the costs and fees of its separate counsel.

    Should any Licensed Products provided under this Agreement become or, in Rocket Software's opinion, likely become, the subject of an IP Infringement Claim, Rocket Software may replace or modify affected Licensed Product so as to make it non-infringing and materially equivalent, or procure for Customer the right to continue using it. If neither alternative is reasonably available, once Customer has returned or destroyed all copies of the affected Licensed Product, Rocket Software will refund to Customer the full amount paid for affected Licensed Product less straight line depreciation on a five-year basis from date of delivery.

    Rocket Software is not responsible for unauthorized use of Licensed Products, and has no obligations under this Section (Indemnification for Intellectual Property Rights Infringement), to the extent infringement results from (i) compliance with Customer's designs or instructions, (ii) a modification not authorized in writing by an authorized Rocket Software signatory, (iii) use or combination with software, equipment, or data not provided by Rocket Software, (iv) non-licensed use; or (v) Third Party Software or Open Source Software.

  22. MISCELLANEOUS.
    1. Assignment. Rocket Software may assign this Agreement and any Product Orders to an affiliate or a third party in connection with an asset sale or divestiture. Customer may not assign or transfer this Agreement (or any Product Orders) or any of its rights or duties hereunder, including (but not limited to) by operation of law, without Rocket Software's prior written consent, which will not be unreasonably withheld, and payment of any applicable assignment or transfer fee. Any transaction or series of related transactions resulting in a change in the ownership of more than 50% of the voting equity of Customer will be deemed an assignment for purposes of this provision. Any attempted assignment of this Agreement (or a Product Order) not in accordance with this section (Assignment) will be null and void.
    2. Governing Law and Jurisdiction. This Agreement and, subject to the Open Source Software and Third Party Software Section, licenses purchased under applicable Product Orders, as well as any claims or causes of action, whether in contract, tort or statute, based on, arising under or relating to this Agreement, will be governed and enforced as follows: If Customer's applicable place of business is located in North America, all matters arising out of or relating to this Agreement are governed by the laws of the state of Delaware, U.S.A. If Customer is located in the United Kingdom, Australia, Brazil, France, Germany, Italy, Japan, the Netherlands, New Zealand, Spain or Singapore, all matters arising out of or relating to this Agreement are governed by the laws of the country in which Licensee is located. In the rest of the world, the laws of England and Wales govern all matters arising out of or relating to this Agreement. The applicable law shall apply without regard to conflicts of law provisions, and without regard to the United Nations Convention on the International Sale of Goods. Any suit, action, or proceeding arising out of or relating to this Agreement shall be subject to the exclusive jurisdiction of the courts of the country determining the applicable law, except that the courts of the State of Delaware shall have exclusive jurisdiction in North America, and Rocket Software will be allowed to apply for injunctive relief in any jurisdiction. Each party agrees to be subject to the above-described jurisdiction and waives any right it may have to object to such venue, including objections based on personal jurisdiction or inconvenient forum. The prevailing party in any proceeding has the right to recover costs and reasonable attorneys' fees as awarded by the court or arbitrator.
    3. Export Control. Rocket Software and Customer will comply with their respective responsibilities as exporters and importers under laws and regulations applicable to the export, import or other transfer of the software, services and technology provided by Rocket Software under this Agreement, including the export, import and sanctions laws of the United States and other applicable jurisdictions. If Customer exports, imports, or otherwise transfers any Licensed Products provided under or in connection with this Agreement (or any technical data related thereto), Customer is responsible for obtaining any required authorizations. Customer will not use Licensed Products for any purpose prohibited by applicable export laws, including nuclear, chemical, missile or biological weapons-related end uses. With respect to any Pre-Release Software provided to Customer, Customer represents and warrants that(i)it is a non-governmental entity,(ii) the Pre-Release Software will only be used for internal testing and evaluation, and will not be rented, leased, sold, sublicensed, assigned, or otherwise transferred, and that it will not transfer or export any product, process, or service that is the direct product of the Pre-Release Software, and (iii) it will only use the Pre-Release Software in the United States or the countries listed in Title 15, U.S. CFR Supplement No. 3 to Part 740 - License Exception ENC Favorable Treatment Countries. Customer agrees to indemnify and hold Rocket Software harmless from and against any damages, claims, losses, fines, settlements, attorneys' fees, legal fees and court costs and other expenses related to any such activities or any claims in connection with any breach of this Section.
    4. Survival. Rights and obligations of the parties in the following Sections: Use Restrictions, Term, Termination, Disclaimer of Warranty, Limitation of Liability, Ownership, Open Source Software and Third Party Software, License Fees and Payment Terms, License Verification, Privacy, Use of Customer Information, Customer Feedback, Confidential Information, Indemnification for Intellectual Property Rights Infringement, and Miscellaneous will survive termination or expiration of this Agreement. Neither party will be liable for delays or non-performance beyond its reasonable control except for payment obligations.
    5. Notices. All notices permitted or required under this Agreement will be in writing and delivered personally, by courier, telecopy, first class mail, electronic mail, or similar transmission to the other party. Notices to Rocket Software shall be addressed to: Legal Department, Rocket Software via email to legal@rocketsoftware.com. Notices to Customer may be sent via electronic mail to any email address set forth in the Product Order or to its address listed on the applicable Product Order, or at such other address as may be supplied in writing. The date of delivery or the date of mailing will be the date of notice.
    6. Resellers. Rocket Software's obligations with respect to products or services supplied by Rocket Software and procured by Customer from an authorized Rocket Software reseller are limited to the terms and conditions in this Agreement and the Documentation included with the Rocket Software supplied products and services. With purchases from a reseller, the applicable pricing and payment terms are as set out in the separate agreement between Customer and the reseller, and any terms in this Agreement related to Rocket Software pricing and payments shall not apply. Rocket Software is not responsible for the acts or omissions of the reseller, or for any other products or services that it supplies to Customer.
    7. Entire Agreement. This Agreement and the applicable Product Order(s) and ALA(s) represent the entire understanding of the parties with respect to the subject matter of this Agreement and supersede any previous communications or agreements that may exist regarding the same subject matter.
    8. Order of Precedence. Subject to the Product Orders section, any conflicting terms and conditions will be resolved according to the following order of precedence: the applicable Product Order, the applicable ALA, and this Agreement.
    9. Amendment. No modification of this Agreement will be binding on the parties unless in writing signed by authorized representatives of Rocket Software and Customer.
    10. Waiver. No waiver of any right under or in connection with this Agreement will be effective unless in writing, signed by authorized representatives of both parties. No waiver of any past or present right arising from any breach or failure to perform will be deemed to be a waiver of any future right arising under or in connection with this Agreement.
    11. Publicity. For the term of this Agreement, Rocket Software may use Customer's name in press releases, product brochures, and other marketing materials to indicate they are Rocket's customer. Rocket will use Customer's trademarks, service marks, logos or branding, according to any branding guidelines which Customer makes available to Rocket Software. Licensee hereby agrees to serve as a reference for the Product(s) at times to be mutually agreed upon. Such references may, as mutually agreed upon, include activities such as (i) reference calls with or hosting of a site visit with mutually acceptable prospects; (ii) a published "News Release" announcing the successful partnership with Rocket no later than sixty (60) days from the date of this Agreement; (iii) mention of Licensee or Licensee logo on Rocket Software's website; (iv) the completion of a "Case Study;" or (v) sharing Licensee's "Success Story" which may include speaking at Rocket Software events. Both parties will agree to the content and timing of any announcement focused on their relationship prior to distribution.
    12. Severability. If any provision in this Agreement or the applicable ALA(s) or Product Order(s) is held invalid or unenforceable, that provision will be construed, limited, modified or, if necessary, severed, to the extent necessary, to eliminate its invalidity or unenforceability, and the other provisions will remain unaffected.
Parent topic: Product Information


Supported Operating Systems and Third-party Software

Lists operating systems supported and tested with the Enterprise Developer and Enterprise Test Server software products, and third-party software supported by major features within these products.
Attention: This topic provides a summary of operating systems and third-party software supported across the Visual COBOL / Enterprise Developer suite of products. Not all software and/or software versions listed here are supported by every product in the suite. See the Additional Software Requirements topic for details pertaining to this product.
  • Windows Operating Systems
  • Linux/UNIX Operating Systems
  • IBM Mainframe Operating Systems
  • Integrated Development Environments (IDEs)
  • .NET
  • Java JDK
  • Java Application Servers
  • Relational Database Management Systems (RDBMSs)
  • Database Client Software

Windows Operating Systems

Back to Top

All supported Windows operating system versions have been tested with all listed Enterprise Developer and Enterprise Test Server product releases. Each listed Windows operating system version and its subsequent updates are supported.

 | Micro Focus Product Release
Operating System | 7.0 | 8.0 | 9.0 | 10.0
Windows 8.1 | Check mark |  |  |
Windows 10 | Check mark | Check mark | Check mark | Check mark
Windows 11 | Check mark | Check mark | Check mark | Check mark
Windows Server 2012 R2 | Check mark |  |  |
Windows Server 2016 | Check mark | Check mark | Check mark |
Windows Server 2019 | Check mark | Check mark | Check mark |
Windows Server 2022 | Check mark | Check mark | Check mark | Check mark

Linux/UNIX Operating Systems

Back to Top

Micro Focus has tested the operating system base versions with corresponding Enterprise Developer and Enterprise Test Server product releases. Any of these release that supports a given operating system base release also supports any subsequent minor releases provided by the vendor.

Enterprise Developer Product Release
Operating System Base | Processor | 7.0 | 8.0 | 9.0 | 10.0
AIX 7.1.x (where x >=4) 1 | IBM Power System 2 | Check mark | Check mark
AIX 7.2 1 | IBM Power System 2 | Check mark | Check mark | Check mark | Check mark
AIX 7.3 | IBM Power System 2 | Check mark | Check mark | Check mark | Check mark
Amazon Linux 2 | Intel x64 | Check mark | Check mark | Check mark | Check mark
Amazon Linux 20238 | Intel x64 | Check mark
CentOS 7 1 | Intel x86-64 | Check mark | Check mark
CentOS 8 3 | Intel x86-64 | Check mark
Rocky Linux 8 | Check mark
Rocky Linux 9 | Check mark | Check mark
HP - UX 11.31 1 | Itanium | Check mark 5
Oracle Linux - Red Hat Compatible Kernel 6 | Intel x86-64
Oracle Linux - Red Hat Compatible Kernel 7 | Intel x86-64 | Check mark 1 | Check mark 1 | Check mark 1
Oracle Linux - Red Hat Compatible Kernel 8 | Intel x86-64 | Check mark | Check mark 1 | Check mark 1 | Check mark
Oracle Linux - Red Hat Compatible Kernel 9 | Intel x86-64 | Check mark 1 | Check mark 1 | Check mark
Oracle Linux - Unbreakable Enterprise Kernel 6 | Intel x86-64
Oracle Linux - Unbreakable Enterprise Kernel 7 | Intel x86-64 | Check mark 1 | Check mark 1 | Check mark 1
Oracle Linux - Unbreakable Enterprise Kernel 8 | Intel x86-64 | Check mark 1 | Check mark 1 | Check mark 1 | Check mark 1
Oracle Linux - Unbreakable Enterprise Kernel 9 | Intel x86-64 | Check mark 1 | Check mark 1 | Check mark 1
Red Hat Enterprise Linux 6 | Intel x86-64 1
Red Hat Enterprise Linux 6 | IBM Z System 1
Red Hat Enterprise Linux 7 | Intel x86-64 | Check mark | Check mark | Check mark
Red Hat Enterprise Linux 7 | IBM Z System 1
Red Hat Enterprise Linux 8 | Intel x86-64 | Check mark | Check mark | Check mark | Check mark
Red Hat Enterprise Linux 8.2 and later | IBM Z System 1,2 | Check mark | Check mark | Check mark | Check mark
Red Hat Enterprise Linux 9 | Intel x86-64 | Check mark 6 | Check mark | Check mark
Oracle Solaris 11 1,4, 7 | Intel x86-64 | Check mark | Check mark | Check mark
Oracle Solaris 11 1, 7 | SPARC | Check mark | Check mark | Check mark
SUSE Linux Enterprise Server 12 | Intel x64 | Check mark | Check mark | Check mark
SUSE Linux Enterprise Server 15 | Intel x64 | Check mark | Check mark | Check mark | Check mark
SUSE Linux Enterprise Server 12 | IBM Z System 1 | Check mark | Check mark | Check mark
SUSE Linux Enterprise Server 15 | IBM Z System 1 | Check mark | Check mark | Check mark | Check mark
SUSE Linux Enterprise Desktop 15 | Intel x64 | Check mark | Check mark | Check mark | Check mark
Ubuntu 18.04 1 | Intel x64 | Check mark | Check mark
Ubuntu 20.04 | Intel x64 | Check mark | Check mark | Check mark | Check mark
Ubuntu 22.04 | Intel x64 | Check mark | Check mark
1 Not supported by Eclipse.

2 64-bit-only

3 The end-of-life date for this platform is 31 December 2021. We recommend that you check CentOS 8 end-of-life notices before using this platform.

4 Not supported on Visual COBOL products

5 Supported in 7.0 until December 2025, in line with the vendor's lifecycle policy for this operating platform. Customers requiring additional coverage should discuss Extended Support + options with their Micro Focus account manager.

6 Supported starting with release 8.0 Patch Update 3.

7 Solaris OS will no longer be supported in releases 10.0 and later.

8 Not supported by the Eclipse-based products as some required packages are not supplied with the version of the OS.

Important: The following platforms only support a 64-bit version of this product - Amazon, SUSE, SUSE 390, Red Hat 390, and Ubuntu, and some product installers for Red Hat Linux. 64-bit versions of the product support compiling to and running 64-bit programs only.

IBM Mainframe Operating Systems

Back to Top

Operating System | Enterprise Developer Product Release
 | 7.0 | 8.0 | 9.0 | 10.0
z/OS 2.3 | Check mark | Check mark | Check mark | Check mark
z/OS 2.4 | Check mark | Check mark | Check mark | Check mark
z/OS 2.5 | Check mark | Check mark | Check mark | Check mark

Integrated Development Environments (IDEs)

Back to Top

 | Enterprise Developer Product Release
IDE | 7.0 | 8.0 | 9.0 | 10.0
Microsoft Visual Studio 2017 | Check mark | Check mark |  |
Microsoft Visual Studio 2019 | Check mark | Check mark |  |
Microsoft Visual Studio 2022 |  | Check mark | Check mark | Check mark
Eclipse v4.28 1 |  |  |  | Check mark
Eclipse v4.24 2 |  |  | Check mark |
Eclipse v4.20 2 |  | Check mark |  |
Eclipse v4.16 2 | Check mark |  |  |
Eclipse v4.7 |  |  |  |
Eclipse v4.8 |  |  |  |
Microsoft VS Code v1.x | Check mark | Check mark | Check mark | Check mark
1 Installed automatically with Eclipse-based products, and requires Java 17. 2 Installed automatically with Eclipse-based products, and requires Java 11.

.NET

Back to Top

 | Enterprise Developer Product Release
.NET version | 7.0 | 8.0 | 9.0 | 10.0
.NET Core 3.1 | Check mark |  |  |
.NET 6 |  | Check mark | Check mark |
.NET 8 |  |  |  | Check mark

Java JDK

Back to Top

 | Enterprise Developer Product Release
Java | 7.0 | 8.0 | 9.0 | 10.0
IBM JDK 1.74 | Check mark |  |  |
IBM JDK 1.84 | Check mark | Check mark | Check mark |
Oracle JDK 1.8 / 8 | Check mark | Check mark | Check mark |
Oracle JDK 11 6 | Check mark | Check mark | Check mark |
Oracle JDK 17 6 |  | Check mark 7 |  | Check mark
Oracle JDK 21 6 |  |  | Check mark 8 |
AdoptOpenJDK 8 | Check mark |  |  |
Adoptium's OpenJDK Temurin 8 2,5 |  | Check mark | Check mark |
Adoptium's OpenJDK Temurin 11 | Check mark 1,2,5 | Check mark 1,2,5 | Check mark 1,2,5 | Check mark 7
Adoptium's OpenJDK Temurin 17 | Check mark 1,2,5,8 | Check mark 1,2,5,8 | Check mark 1,2,5,8 | Check mark 1,2
Adoptium's OpenJDK Temurin 21 |  |  |  | Check mark 2,8
AdoptOpenJDK 11 OpenJ9 3,5 | Check mark |  |  |
1 Installed with Enterprise Developer products for Windows platforms. 2 Not supported on AIX platforms; use the IBM Semeru Runtime OpenJDK instead. 3 See the Adoptium Web site for more information about OpenJ9. 4 Supported on IBM platforms only. In 10.0 only supported for JCA. See Application Server JCA Support for Enterprise Server for details. 5 A minimum of Java 11 is required to install and run the Eclipse IDE. 6 Not supported for containerized deployments. 7 Supported for JCA only. See Application Server JCA Support for Enterprise Server for details. 8 Not supported for JCA. See Application Server JCA Support for Enterprise Server for details.
Important:
  • JDK versions earlier than IBM Semeru 17, Oracle JDK 17, Adoptium OpenJDK Temurin 17 will no longer be supported from the next major release of this product.
  • For details about JCA JDK support, see Application Server JCA Support for Enterprise Server.

Java Application Servers

Back to Top

Attention: This list represents the Java Application Servers and versions supported across Enterprise Developer software products, and does not provide details with regard to this specific product or its features. For this information, see the Additional Software Requirements topic.
Enterprise Developer Product Release
Java Application Servers | 7.0 | 8.0 | 9.0 | 10.0
Apache Tomcat 9.0 | Check mark
Apache Tomcat 10.0 | Check mark
Apache Tomcat 10.1 | Check mark | Check mark
IBM WebSphere 8.5.5 | Check mark | Check mark | Check mark | Check mark 3
IBM WebSphere 9.0 | Check mark | Check mark | Check mark | Check mark 3
IBM WebSphere Liberty y.0.0.x (where y >= 22) 1 | Check mark | Check mark | Check mark
IBM WebSphere Liberty y.0.0.x (where y >= 23) 1 | Check mark
JBoss EAP 7.4 2 | Check mark | Check mark | Check mark | Check mark
Oracle WebLogic 12.2.x | Check mark | Check mark | Check mark | Check mark 3
Oracle WebLogic 14.1.x | Check mark | Check mark | Check mark 3
1 Websphere Liberty is made available as a single stream continuous delivery software lifecycle. Micro Focus does not test all updates to Liberty but does periodically test the latest release of WebSphere Liberty against the latest available Enterprise Developer product release.

Micro Focus will make reasonable efforts to resolve product issues against supported releases of Liberty and in accordance with the Enterprise Developer product lifecycle policy. Micro Focus might require you to update to a newer release of Liberty to remedy a Support case.

2 Micro Focus will make reasonable efforts to resolve product issues against supported minor releases of JBOSS EAP 7.x and in accordance with the Micro Focus product lifecycle policy. Micro Focus might require you to update to a newer minor update release of JBOSS EAP 7.x to remedy a Support case.

3 Not supported for JVM COBOL; supported with JCA only.

Relational Database Management Systems (RDBMSs)

Back to Top

All RDBMS testing is done on both 32- and 64-bit platforms based on RDBMS client software availability.

Attention: This list represents RDBMSs and versions supported across Enterprise Developer software products, and does not provide details with regard to this specific product or its features. For this information, see the Additional Software Requirements topic.
 | Enterprise Developer Product Release
RDBMS | 7.0 | 8.0 | 9.0 | 10.0
Amazon Aurora for PostgreSQL 2.x (10.x) |  |  | Check mark |
Amazon Aurora for PostgreSQL 3.x (11.x) | Check mark |  | Check mark |
Amazon Aurora for PostgreSQL 4.x (12.x) |  |  | Check mark |
Amazon Aurora for PostgreSQL 12.x |  |  | Check mark |
Amazon Aurora for PostgreSQL 13.x |  |  | Check mark | Check mark
Amazon Aurora for PostgreSQL 14.x |  |  | Check mark | Check mark
Amazon Aurora for PostgreSQL 15.x |  |  |  | Check mark
Amazon RDS for PostgreSQL 12.x |  |  | Check mark |
Amazon RDS for PostgreSQL 13.x |  |  | Check mark | Check mark
Amazon RDS for PostgreSQL 14.x |  |  | Check mark | Check mark
Amazon RDS for PostgreSQL 15.x |  |  |  | Check mark
Oracle 19c (12.2.0.3) | Check mark | Check mark | Check mark | Check mark
Oracle 21c |  | Check mark | Check mark |
Microsoft SQL Server 2014 | Check mark | Check mark |  |
Microsoft SQL Server 2016 | Check mark | Check mark | Check mark | Check mark
Microsoft SQL Server 2017 | Check mark | Check mark | Check mark | Check mark
Microsoft SQL Server 2019 | Check mark | Check mark | Check mark | Check mark
Microsoft SQL Server 2022 |  |  | Check mark | Check mark
Microsoft Azure SQL Database | Check mark | Check mark | Check mark | Check mark
Microsoft Azure SQL Managed Instance | Check mark | Check mark | Check mark | Check mark
IBM DB2 LUW 10.5 | Check mark |  |  |
IBM DB2 LUW 11.1 | Check mark | Check mark | Check mark | Check mark
IBM DB2 LUW 11.5 | Check mark | Check mark | Check mark | Check mark
EDB PostgreSQL 10.x | Check mark |  |  |
EDB PostgreSQL 11.x | Check mark | Check mark |  |
EDB PostgreSQL 12.x | Check mark | Check mark | Check mark |
EDB PostgreSQL 13.x |  | Check mark | Check mark | Check mark
EDB PostgreSQL 14.x |  |  | Check mark | Check mark
EDB PostgreSQL 15.x |  |  |  | Check mark
GDG PostgreSQL 10.x | Check mark |  |  |
GDG PostgreSQL 11.x | Check mark | Check mark |  |
GDG PostgreSQL 12.x | Check mark | Check mark | Check mark |
GDG PostgreSQL 13.x | Check mark | Check mark | Check mark | Check mark
GDG PostgreSQL 14.x |  |  | Check mark | Check mark
GDG PostgreSQL 15.x |  |  |  | Check mark
MySQL 5.7 | Check mark |  |  |
MySQL 8.0 |  | Check mark | Check mark | Check mark

Database Client Software

Back to Top

Attention: This list represents database client software supported across Enterprise Developer software products, and in some cases, the components that use them. It does not provide details with regard to this specific product or its components. For this information, see the Additional Software Requirements topic.
Client | Release | Enterprise Developer Component(s)
.NET database providers | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of .NET are compatible. | OpenESQL
.NET Framework providers | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of ADO.NET are compatible. | OpenESQL HCOSS
ODBC | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of ADO.NET are compatible. | OpenESQL HCOSS Database Connectors
JDBC | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of ADO.NET are compatible. | OpenESQL
ADO.NET | Consult the RDBMS documentation specific to your installed RDBMS to determine which version(s) of ADO.NET are compatible. | OpenESQL HCOSS
IBM Data Server Runtime Client, which includes ODBC, JDBC, CLI, and .NET support | Consult the IBM documentation specific to your installed RDBMS to determine which version(s) of IBM Data Server Runtime Client are compatible. | OpenESQL DB2 ECM Database Connectors
IBM Data Server Client, which includes ODBC, JDBC CLI, and .NET support | Consult the IBM documentation specific to your installed RDBMS to determine which version(s) of IBM Data Server Client are compatible. | OpenESQL DB2 ECM Database Connectors
Oracle Client, Oracle Instant Client with Pro*COBOL, and OCI support | Consult the Oracle documentation specific to your installed RDBMS to determine which version(s) of Oracle Client or Oracle Instant Client are compatible. | OpenESQL COBSQL Database Connectors
IBM Informix ESQL/COBOL 1 | 7.3 or later | COBSQL
Microsoft OLE DB Provider for DB2 | Consult the SQL Server documentation specific to your installed RDBMS to determine which version(s) of Database Connectors Drivers are compatible. | HCOSS
Microsoft OLE DB Provider for SQL Server | Consult the SQL Server documentation specific to your installed RDBMS to determine which version(s) of Database Connectors Drivers are compatible. | HCOSS
Sybase Open Client Embedded SQL/COBOL 1 | 11.1 or later | COBSQL
1 Not tested.
Parent topic: Product Information
Related concepts
Additional Software Requirements


Additional Software Requirements

To ensure full functionality for some Enterprise Test Server features, you might be required to obtain and install additional third-party software. The following information specifies the third-party software required for each feature.

  • Application Server JCA Support for Enterprise Server
    Lists supported and tested JCA application servers for Enterprise Server .
  • Database Management Systems (DBMSs)
    Lists supported and tested DBMSs along with the Enterprise Test Server features that use them.
  • Enterprise Common Web Administration (ESCWA)
  • Interface Mapping Toolkit (IMTK)
    Lists the third-party software you need to install and configure before you can create certain types of service interfaces using the Interface Mapping Toolkit with Enterprise Developer.
  • JCL
    Lists supported and tested databases that can be used with the JCL Mainframe Batch Data Tools feature of Enterprise Test Server.
  • Legacy Enterprise Server Administration User Interface
  • MFFTP Utility
    Lists the third-party software you need to install and configure on the host system before you can use the Micro Focus FTP utility.
  • Performance Availability Clusters (PACs)
    Lists the prerequisite software required to use the Performance and Availability Cluster (PAC) feature with Enterprise Server.
Parent topic: Product Information
Related concepts
Supported Operating Systems and Third-party Software
HCO Tools
HCO for DB2 LUW
Deploying Native Applications


Application Server JCA Support for Enterprise Server

Lists supported and tested JCA application servers for Enterprise Server .
Testing
Third-party Java Application Servers
With regard to support for each third-party Java Application Server supported version, Micro Focus:
  • Provides support until end-of-service (EOS) dates provided by the JAS vendor
  • If your deployment requires support for a given JAS beyond the vendor’s EOS dates, check with Customer Support for availability of Extended Support Plus options
  • Encourages you to include third-party JAS consideration when planning an upgrade to your Micro Focus product
Planned support
Support for the following is planned for a future release:
  • JBoss EAP 8.0
Resolving reported issues
With regard to resolving reported issues with Micro Focus software while using a third-party Java Application Server, Micro Focus:
  • Attempts to resolve issues for supported JASs on tested or untested platforms
  • Investigates issues involving planned but not yet supported JASs and attempts to resolve non-architectural issues that also occur in latest supported JAS version
Availability
Operating System/Platform | JBoss EAP 7.4.x (where x>=3) | IBM WebSphere 8.5.5, 9.0, Liberty y.0.0.x (where y>=23) | Oracle WebLogic 12.2.1, 14.1.1 | Apache Tomcat 10.1
x86-64 running Windows | Check mark | Check mark | Check mark | Check mark
Current support
The following Java application server base versions and incremental releases are supported in this release of Enterprise Test Server :
Supported App Server base version | Tested App Server version | JDK (vendor) | Java EE | COBOL RA | CICS RAs and ECI
Apache Tomcat 10.1 1 10.0.5 11 (Adoptium)

17 (Adoptium)

IBM WebSphere 8.5.5 | 8.5.5.18 | 8 (IBM) | 72 | Check mark | Check mark
IBM WebSphere 9.0 | 9.0.5.6 | 8 (IBM) | 7 2 | Check mark | Check mark
IBM WebSphere Liberty y.0.0.x (where y>=23) 23.0.0.12 8 (IBM)

11 (IBM)

17 (IBM)

7 2 Check mark
JBoss EAP 7.4.x (where x>=3) 7.4.3 1.8 (Oracle)

1.8 (Adoptium)

11 (Oracle)

11 (Adoptium)

17 (Oracle)

17 (Adoptium)

7 2 Check mark Check mark
Oracle WebLogic 12.2.1 12.2.1.4 8 (Oracle)

8 (Adoptium)

7 2 Check mark
Oracle WebLogic 14.1.1 14.1.1.0 8 (Oracle)

11 (Oracle)

7 2 Check mark
1 Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs).

2 Java EE 7, including support for EJB 3.2 and Java Connector Architecture 1.7, is supported for the deployment of EJBs .

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

Parent topic: Additional Software Requirements


Database Management Systems (DBMSs)

Lists supported and tested DBMSs along with the Enterprise Test Server features that use them.

All RDBMS testing is done on both 32- and 64-bit platforms based on RDBMS client software availability.

With regard to support for each of these third-party RDBMS supported version, Micro Focus:

  • Provides support until the standard end-of-service (EOS) date provided by the RDBMS vendor
  • If your deployment requires support for a given RDBMS beyond the vendor's EOS dates, check with OpenText Support for Micro Focus Products for availability of Extended Support Plus options.
  • Encourages you to include third-party RDBMS consideration when planning an upgrade to your Enterprise Test Server

With regard to resolving reported issues with Micro Focus software while using a third-party RDBMS, Micro Focus :

  • Attempts to resolve issues for supported DBMSs on tested or untested platforms
  • Investigates issues involving planned but not yet supported RDBMSs, and attempts to resolve non-architectural issues that also occur in the latest supported RDBMS version

This release of Enterprise Test Server supports the following Database Management Systems:

  • COBSQL (Pro*COBOL)
  • DB2 ECM (non-mainframe) and HCO for DB2 LUW (mainframe)
  • HCO for SQL Server (HCOSS)
  • OpenESQL
  • SQL Option for DB2

COBSQL (Pro*COBOL)

Back to Top

Note: COBSQL (Pro*COBOL) is supported for native COBOL only.

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

Availability
Operating System/Platform | 32-bit | 64-bit
x86-64 running Windows | Check mark | Check mark
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. Oracle Instant Client fully supports all 1PC functionality with Pro*COBOL applications.
Restriction: The Oracle Instant Client does not support the 2PC functionality of the Oracle XA switch module. To use 2PC functionality with Pro*COBOL applications, you must install Oracle Client, not Instant Client.
Supported/tested version
For this release, COBSQL was tested with Oracle Pro*COBOL versions 19c and 21c.
Planned support
Support for the following is planned for a future release:
  • Oracle 23c

DB2 ECM (non-mainframe) and HCO for DB2 LUW (mainframe)

Back to Top

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

Note: DB2 is supported for native COBOL only.
Availability
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)
Supported/tested versions
For this release, HCO for DB2 LUW was tested with versions 11.1 and 11.5.

HCO for SQL Server (HCOSS)

Back to Top

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

Availability
Operating System/Platform | COBOL native 32-bit | COBOL native 64-bit | PL/I 32-bit | PL/I 64-bit
x86-64 running Windows | Check mark | Check mark | Check mark | Check mark
Database Migration
HCOSS Client Host node
  • SQL Server 2016 or later
  • Microsoft .NET Framework 4.7.2
  • Microsoft SQL Server Integration Services - available with the Microsoft SQL Server edition
    Note: Microsoft SQL Server Express edition might not support SSIS. See your Microsoft documentation for details.
  • Microsoft OLE DB Driver for SQL Server (MSOLEDBSQL)
    Note: Microsoft recommends MSOLEDBSQL only, as all other versions are deprecated or are no longer maintained. However, if MSOLEDBSQL is not installed, SQL Server Native Client (SNAC) is used if available.
  • Microsoft OLE DB Provider for DB2 version 5.0 or later
    Notes:
    • Be sure to configure the OLE DB Provider to connect to the mainframe. See your Microsoft documentation for details.
    • When using Microsoft OLE DB Provider for DB2 version 6.0, set the Extract Schema Cast STATEMENT column to VARCHAR during SysViews extract option.
SQL Server Target Host node
SQL Server 2016 or later
Mainframe DB2
IBM-supported z/OS DB2 versions only
Note: If you intend to develop applications on your local machine, but deploy applications to a SQL Server database on a remote machine, configure the remote machine using the requirements listed in the Deploying Native Applications > Deployment Machine section later in this topic.
Application Migration
ADO.NET applications
ADO.NET applications require SQL Server 2016 or later and SqlClient Data Provider in .NET Framework 4.x
Note: Microsoft recommends .NET Framework 4.5.2
Deploying Native Applications
Development Machine
Install SQL Server 2016 or later, along with its recommended Microsoft ODBC driver version.
Development SQL Server Machine
SQL Server 2016 or later.
Note: This can be the same machine as the development machine, but is not required to be.
Deployment Machine
  • Install Enterprise Test Server or Enterprise Test Server
  • Install SQL Server 2016 or later, along with its recommended Microsoft ODBC driver version.
If you want to bind your application from the deployment machine, install the following additional software:
  • Microsoft .NET 4 framework, or later
  • SQL Server 2016 or later System CLR Types
  • SQL Server 2016 or later Shared Management Objects
Deployment SQL Server Machine
SQL Server 2016 or later
Note: This can be the same machine as the deployment machine, but is not required to be.
Supported/tested versions
For this release, HCO for SQL Server was tested with SQL Server 2016, 2017, 2019, Azure DB, and Azure MI. Both SQL Server 2017 and 2019 were tested on Windows and Linux platforms.

OpenESQL

Back to Top

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

Availability
XA Switch Module
The ODBC One-phase Commit, SQL Server, and PostgreSQL switch modules are provided and available on the same platforms as are indicated in the Availability section above.
Native COBOL
  • 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 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 3.2.2 for EDB PostgreSQL
Supported/tested versions
For this release, OpenESQL was tested with:
  • Oracle 19c and 21c
  • DB2 LUW 11.1 and 11.5
  • SQL Server 2016, 2017, 2019, 2022, Azure DB, and Azure MI
  • Microsoft Azure SQL Database
  • Microsoft Azure SQL Managed Instance
  • PostgreSQL GDG community edition (early adopter program) and EDB PostgreSQL 13.x, 14.x, and 15.x
  • Amazon AWS Aurora and RDS for PostgreSQL 13.x, 14.x, and 15.x
  • MySQL 8.0
Note: Micro Focus provides compatibility for PostgreSQL and MySQL but does not directly contribute to or support either open source project. Any issues relating to the functionality of either DBMS should be addressed through an open source support vendor.

SQL Option for DB2

Back to Top

Availability
Operating System/Platform | 32-bit
x86-64 running Windows | Check mark
XA Switch Module
XDB XA switch modules are provided and are available for the Windows x86-64 32-bit platform.
Parent topic: Additional Software Requirements
Related tasks
To set HCOSS options
Related reference
Options
Related information
JCL


Enterprise Common Web Administration (ESCWA)

The Enterprise Server Common Web Administration interface has the following software requirements:

  • A Web browser (with a minimum required version):
    • Firefox (version 126)
    • Google Chrome (version 125)
    • Microsoft Edge (version 125)
    • Opera (version 110)
    Note: Internet Explorer (IE) is not supported.
  • ESCWA only supports MFDS version of 1.25.37 or later.
  • ESCWA is supported on Windows and UNIX platforms.
  • On UNIX platforms, you must ensure that the ESCWA log directory has write permissions. By default, the ESCWA log directory is located at $COBDIR/etc.
  • 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.
Parent topic: Additional Software Requirements


Interface Mapping Toolkit (IMTK)

Lists the third-party software you need to install and configure before you can create certain types of service interfaces using the Interface Mapping Toolkit with Enterprise Developer.

Java Application Server

Java EE 7, including support for EJB 3.2 and Java Connector Architecture 1.7, is supported for the deployment of EJBs generated using the Interface Mapping Toolkit.

Visual C++

.NET client generation for Service Interfaces requires Visual C++, which is an optional feature of Visual Studio 2015 and later. To ensure that Visual C++ is installed with Visual Studio, you must do a custom installation of Visual Studio, and specifically choose the Visual C++ option.

Parent topic: Additional Software Requirements


JCL

Lists supported and tested databases that can be used with the JCL Mainframe Batch Data Tools feature of Enterprise Test Server.

Mainframe Batch Database Tools (MBDT)

Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | Check mark | Check mark
OpenESQL
The MBDT toolset consists of OpenESQL applications, and are native code using ODBC. See the OpenESQL section in the Database Management Systems (DBMSs) topic for further details.
Testing
For this version, MBDT was tested with:
  • DB2 LUW 11.1 and 11.5
  • Oracle 19c and 21c
  • On Windows platforms - SQL Server 2016 and later
  • GDG and EDB PostgreSQL 12.x, 13.x, and 14.x
  • Amazon RDS and AWS Aurora for PostgreSQL 12.x, 13.x, and 14.x
Parent topic: Additional Software Requirements
Related information
Database Management Systems (DBMSs)


Legacy Enterprise Server Administration User Interface

Note: Micro Focus recommends you adopt the Enterprise Server Common Web Administration (ESCWA) interface. ESCWA is a modern and feature-rich interface that combines functionality from Enterprise Server Administration, ESMAC, and the ESF LDAP Security Administration interfaces.
  • A Web browser is required for Enterprise Server Administration in Enterprise Test 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.
Parent topic: Additional Software Requirements


MFFTP Utility

To use the MFFTP utility, you must have an FTP client on the host system - for example, WS_FTP Pro.

Parent topic: Additional Software Requirements


Performance Availability Clusters (PACs)

Lists the prerequisite software required to use the Performance and Availability Cluster (PAC) feature with Enterprise Server.

Supported Operating Systems

The following platforms are supported:

  • Windows
  • x86-64 running Red Hat Linux 7, 8, or 9
  • x86-64 running on SUSE 12

Operating System Dependencies

On Linux platforms, the scale-out features require the latest version of the libuuid library.

To install on SUSE, at the command prompt, type the following:

zypper search libuuid

Follow the prompts and only install the non-development packages.

To install on Red Hat, at the command prompt, type the following:

yum search libuuid

Follow the prompts to install the packages.

RDBMS Support

The PAC requires a supported RDBMS to manage the following databases:

  • Region database (mandatory)
  • Cross-region database (mandatory)
  • Datastore database(s) (optional)
A datastore database should be used to manage VSAM files using the Micro Focus Database File Handler support.
Windows
Database | ODBC Driver
Microsoft SQL Server 2008 (including Express editions) R2 and later | ODBC 13.1 for SQL Server
PostgreSQL 10.x (incl. Amazon Aurora Postgres) and later | psqlodbc 11
DB2 10.5 and later | n/a
Oracle 19c | n/a
Note: These are databases supported for database hosted VSAM files. See Additional Software Requirements on Windows and Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components for more information on CICS SQL supported databases.
UNIX
Database | ODBC Driver
Microsoft SQL Server 2017 (including Express editions) and later ODBC 13.1 for SQL Server
Note: SQL Server 2017 installs versions 13 and 17 (x64 only)
PostgreSQL 10.x and later | psqlodbc 11
DB2 10.5 and later | n/a
Oracle 19c | n/a
Note: The Micro Focus Native Database File Handler is only supported on x86-64 running Red Hat Linux 7.3 or 7.4 or x86-64 running on SUSE v12 SP2 as these are also the minimum requirements for Microsoft SQL Server 2017.

In addition, there are minimum requirements for the following components:

Component | Version
Driver manager (MSSQL and PostgreSQL installations only) | unixODBC 2.3.2
Current Limitations
  • The order in which duplicate keys are returned is not guaranteed for indexed files. For files stored on disk, duplicate keys are always returned in the order they were written in.
  • The supported key types are currently limited to alphanumeric, binary, and numeric.
  • PostgreSQL does not support EBCDIC collating sequences. See Configure Datastores for Db2 for more information.
  • MFDBFH does not support COBOL programs compiled with NOFCD3.

NoSQL Support for Scale-Out Repository

Enterprise Server must use a NoSQL database as a Scale-Out Repository (SOR), a requirement to maintain PAC integrity. Enterprise Server supports the following NoSQL databases:

Redis
An open source in-memory data structure store.
Redis Cluster
A distributed implementation of Redis with performance, scalability, and availability as part of its design. See Configuring Redis Cluster for more information about configuring Redis cluster.
Redis Sentinel
Provides Redis high availability.
Oracle Coherence
An in-memory data grid solution.
Parent topic: Additional Software Requirements
Related concepts
Scale-Out Performance and Availability Clusters


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 the Software Downloads section of the Micro Focus Software Licenses and Downloads Web site.
Parent topic: Before Installing


System Requirements

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


Hardware Requirements

The disk space requirements are approximately:

Enterprise Test Server
1 GB
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


Operating Systems Supported

For a list of supported operating systems, see Supported Operating Systems and Third-party Software in your product documentation.

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


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. It will also install the Micro Focus Database Engine.
  • This product includes OpenSSL version 3.0.8.

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 Management System if you install this on a separate machine as a license server.

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

License Manager requirements

  • For local servers, you do not need to install the Micro Focus License Administration tool separately, as the setup file installs a new Enterprise Developer client and a new licensing server on the same machine.
  • If you have any network license servers, you must update them before you update the client machines.
  • If you are upgrading from Enterprise Developer release 2.2 or earlier, uninstall the license manager before installing the product.
You can download the new version of the license server software by following these steps:
  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter.
  2. Select your account and click Downloads.
  3. Select a product and a product version from your orders.
  4. In the list of software downloads, locate the License Manager.
  5. Click Download to download an archive with the installers.
  6. Run the installer suitable for your Operating System to install License Manager on your machine.
Parent topic: System Requirements
Related information
Hardware Requirements
Operating Systems Supported
Installing
Installing as an Upgrade


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 Test 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
Related information
Installing as an Upgrade


Product Co-Existence

  • Enterprise Developer and Enterprise Test Server (or Enterprise Test Server) cannot coexist on the same machine.
  • Enterprise Test 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 Test Server installed on your machine, check Installing as an Upgrade first.

These are the steps to install this product:

  1. Run the ets_100.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, 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 OpenText Support for Micro Focus Products 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 Test Server but you can install it if you wish.
Parent topic: Basic Installation
Related information
Software Requirements


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
  • Licensing Coexistence when Upgrading to Release 10.0
  • Enterprise Test Server Installation Options
  • Installing Mainframe Access Server
Parent topic: Installation


Installing as an Upgrade

Before installing, check Installation Restrictions and Requirements.

  • This release cannot be installed as an upgrade to an earlier release of Enterprise Test Server. You must uninstall the previous version before you install this release.
Parent topic: Advanced Installation Tasks
Related information
Installation Restrictions and Requirements
Software Requirements


Licensing Coexistence when Upgrading to Release 10.0

With release 10.0 of the Enterprise Developer product suite, the SafeNet Sentinel licensing technology has been deprecated. This can result in some compatibility issues if you install 10.0 on a machine where there are other Micro Focus products or versions installed that use SafeNet Sentinel licensing. While the 10.0 installation process has been designed to address such issues, you should be aware of the following scenarios and if any action might be required to ensure licensing works as expected:

Scenarios

Your installed products use SafeNet Sentinel Licenses (Windows and UNIX)
Warning: Installing 10.0 deprecates SafeNet Sentinel licensing on the machine.
If you use SafeNet Sentinel licenses for any other Micro Focus products, such as Enterprise Analyser or Relativity, you need to contact your account manager to obtain AutoPass licenses for these products. See the Troubleshooting section further in this topic, Action 7 for how to obtain a list of your installed licenses.
Your older products use AutoPass licenses (Windows and UNIX)
Existing AutoPass licenses are compatible with the 10.0 products.
Upgrading to 10.0 (UNIX)
After installing 10.0 on a machine with a previous version of licensing installed, the lserv daemon is retained (and might be running) but is not required. See Troubleshooting > Action 2 for details.
Downgrading from 10.0 (Windows and UNIX)
In order to revert to a previous version of the product (for example, if 10.0 is installed but no longer required), the 10.0 product and licensing must be uninstalled. See Troubleshooting > Action 1 for details.
Installing a product or Patch Update of an older product release (UNIX)
Use the "skip license installation" command line arguments.
  • See Troubleshooting > Action 3 for details.
  • Else, see Troubleshooting > Action 4 to reset mfcesd.
  • SystemD may be overwritten - see Troubleshooting > Action 6.
Installing a product or Patch Update of an older product release (AIX only)
If after 10.0 is installed a customer installs a Patch Update for an older release, the lserv entry is moved back to /etc/inittab.
  • See Troubleshooting > Action 3 about how to avoid this.
  • To correct the /etc/inittab entry, see Troubleshooting > Action 5.
  • Alternatively, re-run the 10.0 license install. See Troubleshooting > Action 6.

Troubleshooting

Action 1
To reset licensing from the 10.0 installation to an older product configuration, you need to perform the following:
Windows
Uninstall the product and the License Manager from "Uninstall a Program" in the Windows Control Panel.
UNIX
Execute the following commands:
sudo $COBDIR/bin/Uninstall_[Product Name]_10.0.sh.
sudo /opt/microfocus/licensing/bin/UnInstallMFLicenseServer.sh
Action 2
(UNIX) To disable the lserv daemon on a machine, execute the following commands:
cd /var/microfocuslicensing/bin
sudo ./stopmfcesd.sh
sudo systemctl stop MFSafeNet
sudo systemctl disable MFSafeNet
Action 3
When installing an older release or Patch Update, use -skipsafenet -skipautopass to the install command. This will skip the licensing installation for that release.
Action 4
To restart mfcesd from the correct location, execute the following commands:
cd /var/microfocuslicensing/bin
sudo ./stopmfcesd.sh
cd /opt/microfocus/licensing/bin
sudo ./startmfcesd.sh
Action 5
To reset the inittab on AIX 7.3/7.4:
  1. Edit the /etc/inittab file.
  2. Delete the line:
    mFls:2345:wait:sh /var/microfocuslicensing/bin/startlserv.sh 2>&1
Action 6
To reinstall the 10.0 licensing and reset any issues from installing a previous version, execute the following:
cd [10.0-COBDIR-location]/licensing
sudo MFLicenseServerInstall.sh force
Action 7
In order to get a list of the installed licenses:
Windows
  1. From a COBOL command environment, execute mfsupportinfo.
  2. View the Micro Focus Licensing section.
UNIX
  1. In a terminal, run cobsetenv to set the product environment.
  2. Run mfsupport.
  3. See mfpoll.txt for the licenses details.
Parent topic: Advanced Installation Tasks
Related concepts
Overview


Enterprise Test Server Installation Options

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

TheEnterprise Test Server executable can take a number of parameters, enabling you to specify a number of different types of installation:

  • Standard Installation
    • Format:
    • <Enterprise_Server_exe>
    • Summary:
    • Full installation including License Manager and Enterprise Test Server. During installation you can specify options including the location to which the components are installed.
  • Non-interactive Installation
    • Format:
    • <Enterprise_Server_exe> /passive
    • Summary:
    • Full installation, but the components are installed non-interactively using default options and directories.
  • Silent Installation
    • Format:
    • start /wait <Enterprise_Server_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:
    • start /wait <Enterprise_Server_exe> /q InstallFolder=d:\cobolrts
    • Summary:
    • Full installation, but the components are installed non-interactively with no user interface, and Enterprise Test Server is installed to d:\cobolrts.

To see what parameters you can use, execute the following from the command line: <Enterprise_Server_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
Parent topic: Deploying the Micro Focus Run-Time System


Installing Mainframe Access Server

Introduction

The installation process for Mainframe Access Server (MFA) uses a single FTP operation to transfer all of the mainframe software into a partitioned data set that you pre-allocate. When this transfer is complete, the remaining installation activities are all done on the mainframe. You customize and submit the pre-built FRESTORE job to restore the product data sets from the uploaded files and then continue with customization steps to create an operational Mainframe Access Server.

Requirements

  • IBM Communications Server
  • Two APPLIDs, two TCP/IP ports
  • Availability of APF security authorization support personnel
  • Access to a network share with acceptable space for source and data, as well as the ability to access the IP address and ports used to access MFA
  • The following installation-specific variable information:
    Variable | Description
    drive
    userid | TSO user-ID for FTP to your mainframe
    pswd | TSO password for the FTP user-ID
    your.mainframe.name | TCP/IP host name or IP address of your mainframe
    prodhlq | A NEW high level qualifier that will be assigned for all Host Connectivity data sets when the new Mainframe Access product is installed. These are NOT existing product data sets, but rather brand new files that you will be creating for this base version.
    Important: The installation of a new version of MFA creates new product run-time data sets before the upgrade is applied. Any existing Host Connectivity 3.01 libraries remain intact, and can be used for fallback. If you prefer to retain your former production library names and re-use your existing prodhlq, rename your old libraries beforehand.

    Make a note of the maintenance level of your current Mainframe Access Server. Messages MFM0001I and MFM0014I on the syslog and XDBOUT sysout data set show the maintenance level at startup. You may need to know what level you are upgrading from when you complete post-installation customizations for this upgrade.

Install Mainframe Access Server

In the instructions that follow, the information that you must provide is shown as one of the variable names from the table of information in the previous section. For example, if your high-level qualifier (prodhlq) value is MY.MFA, then substitute MY.MFA for prodhlq.

Follow these steps to load Mainframe Access Server:
  1. Download the installation file from the link in your Electronic Product Delivery email and extract its contents to a directory on the PC.
  2. On the mainframe, allocate a new partitioned data set named prodhlq.UPLOAD to receive the uploaded files. Use the following data set characteristics for this upload library:
    DSORG=PO                   <=== PDS (partitioned data set)
RECFM=FB                   <=== record format fixed and blocked
LRECL=80                   <=== 80 character record size
BLKSIZE=3120               <=== 3120 character block size
SPACE=(3120,(3500,500,50)) <=== allocate blocks (BLKS) size 3120
                                3500 primary blocks
                                500 secondary blocks
                                50 directory blocks
  3. On the PC, issue the following FTP commands. The actual text of the FTP prompts and responses that you see may differ slightly from those shown in this example.
    1. Start FTP:
      C:\>ftp your.mainframe.name
Connected to your.mainframe.name.
220-FTPD1 IBM FTP CS/390 VxRy at YOUR.MAINFRAME.NAME, hh:mm:ss
220 Connection will close if idle for more than 5 minutes.
User (your.mainframe.name:(none)): userid
331 Send password please.
Password: pswd
230 userid is logged on. Working directory is "userid.".
    2. Change the working directory on the mainframe to be the upload library that you allocated:
      ftp> cd 'prodhlq.UPLOAD'
250 The working directory "hlq.UPLOAD" is a partitioned data set.
    3. Set file transfer type to binary:
      ftp> binary
200 Representation type is Image
    4. Set FTP prompting off to transfer all files without interruption:
      ftp> prompt
Interactive mode Off.
    5. Transfer all files from the extracted \Upload directory to members in the prodhlq.UPLOAD library:
      ftp> mput drive:\upload\f*
200 Port request OK.
125 Storing data set prodhlq.UPLOAD(Fxxxxxxx)
250 Transfer completed successfully.
ftp: xxxx bytes sent in x.xx seconds (xxx.xx Kbytes/sec)
.
.
.
    6. When mput has transferred all files the ftp> prompt appears. End the FTP connection:
      ftp> quit
221 Quit command received. Goodbye.
    7. On the mainframe, verify that all files transferred successfully and that for each Fxxxxxxx file in the \Upload directory there is a corresponding member in the prodhlq.UPLOAD data set. There should be five members, F1 through to F4 and FRESTORE.
  4. On the mainframe, edit member FRESTORE in the upload library, prodhlq.UPLOAD. Follow the instructions in that member to customize the JCL and then submit that job to restore the product libraries from the uploaded files and populate your new product runtime libraries.
  5. Start Mainframe Access Server.

After installation

Since the program libraries can change between versions, it is necessary to either create new procedures, or back up the old procedures, and at least modify the DSNQUAL=prodhlq within your MFA sample started task procedures as provided by Micro Focus. The prodhlq.LOADLIB must be authorized.

If you are upgrading Mainframe Access from a version of Enterprise Developer prior to 2.3 you will need to modify your production JCL procedures with reference to the supplied samples MFA, MFAS, and MFAAS. The modification is necessary because at Enterprise Developer 2.3 Mainframe Access changed to being built using the IBM XL/C compiler rather than the SAS/C compiler, so for each JCL procedure you need to change the STEPLIB DD statement and add a new one, CEEOPTS.

Verify successful maintenance application by checking the Mainframe Access Server startup message:

MFM0001I: Mainframe Access V4.00 (BASE ) is active

The "(BASE )" indicates the product maintenance level. Also check for "V4.00" in the Mainframe Access Data Connect server startup message:

MFA303I MFA/DATACONNECT V4.00 - BASE COPYRIGHT (C) 1987-2012 MICRO FOCUS...

When you are satisfied with the new version installation you may delete the UPLOAD data set from your system.

New parameters and members in the CNTL samples data set

The following updated members are found in the CNTL data set.

MFA | sample MFA started task
MFAS | *new* sample MFAS started task for Data Connect
MFAAS | sample MFAAS application server started task
MFAVTAM | sample MFA VTAM definitions
PARMS | sample PARMS for MFA started task
PARMSAS | sample PARMSAS for MFAAS started task
SERVERS | sample SERVERS configuration for MFA
UPQUICK | configuration notes

If you are migrating from Host Connectivity 3.01 WebSync 10 or earlier, you may want to retain your existing CNTL members from your current version as an installation test. You can simply copy the existing MFA started task JCL and change the STEPLIB to reference the new product libraries. You will however need to modify the MFAS started task JCL since the module names for Data Connect have been changed to allow co-residence within the same authorized library as MFA.

Review the Change Log in each of the new members. Read the documentation for any new parameters in the Readme and in the updated Mainframe Access Administrator's Guide. Add these new parameters and other changes to your working copies. If necessary, customize the new parameters for your installation.

Once you are satisfied with the operation of Mainframe Access, you can consolidate the configuration settings into the new high-level qualified CNTL members.

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 OpenText Support and Services Documentation Web site for Micro Focus products for any documentation updates.

Also, note the following:

  • Enterprise Server Security Considerations
  • Repairing
  • Uninstalling
Parent topic: Installation


Enterprise Server Security Considerations

Starting with this release, the Enterprise Server security functionality provided by the VSAM External Security Manager (VSAM ESM) module is enabled by default out of the box. This means you now need to supply valid credentials when you interact with:

  • Enterprise Server Common Web Administration (ESCWA)
  • The Micro Focus Directory Server (MFDS)
  • enterprise server regions via:
    • ESCWA
    • Certain command-line utilities (such as casstart)
    • TN3270 emulator access
    • The Server Explorer window in the new Data Tools available in 10.0
    • IMTK deployment

For more information about the default VSAM Security Manager, see VSAM ESM Module.

Parent topic: After Installing
Related concepts
Default Enterprise Server Security Configuration
Related reference
Default Enterprise Server Security Configuration
Getting Started with Default Enterprise Server Security
VSAM ESM Module

Upgrading an Existing Security Configuration

If security is already configured for a domain (Data Tools, MFDS, or the default Enterprise Server security), the installation process does not change this configuration. If data already exists in either the old or new VSAM ESM default data directory, it will not be altered. However, Micro Focus recommends backing up the following before reinstalling or updating the product - the Data Tools and MFDS configuration files (commonwebadmin.json and mfdsacfg.xml), the MFDS repository data, and the VSAM ESM Module security data. By default, the MFDS repository data and the VSAM ESM Module data are located under %ProgramData%\Micro Focus (Windows) or $COBDIR/etc (UNIX).

Default Generated Password for SYSAD

The installation generates a random password for the system administrator account, SYSAD. To retrieve this password, execute the following from an Enterprise Developer command prompt or Enterprise Server command prompt (Windows) or from a terminal that has the COBOL environment set (UNIX):

mfsecretsadmin read microfocus/temp/admin

The password value stored in this vault location is not used by the default Security Manager (VSAM ESM) to validate input credentials. Its purpose is to enable users to initially discover their randomly generated password. Additionally, Server Explorer uses this location to pre-populate the Micro Focus Servers connection and the credentials dialog box at region start-up. Once entered, you can optionally save the credentials in IDE-specific storage. Micro Focus recommends that once the credentials are safely known or changed that you remove this value from the vault (using mfsecretsadmin delete microfocus/temp/admin).

Related reference
Getting Started with Default Enterprise Server Security

Change the Default Password for SYSAD

Micro Focus recommends that you promptly replace this password with one that conforms to your security policy. You can do this from the ESCWA logon page - click Change Password. Alternatively, you can use the esfadmin SETPASSWORD command.and specifying the "vsam_esm" module file.

Authentication in the Browser-Based ESCWA

You need to provide credentials to access ESCWA. After the installation, the ESCWA logon page shows information on how to obtain the default admin (SYSAD) generated password. You can disable this message in the ESCWA Security Settings dialog ("Show Default Security Warning on Log On").

For local installations, the default Directory Server will automatically be authenticated with the ESCWA credentials. Otherwise, you might need to provide its own credentials. You may use the same credentials as the ones for ESCWA.

Note the default 5-minute (300 second) session time out setting for inactivity in ESCWA. If required, you can change this from the ESCWA Security Settings dialog ("Session Inactivity Timeout").

Authentication Inside the Data Tools Utility

The Server Explorer window in Data Tools, requires credentials for the Micro Focus Servers node to connect to the default local ESCWA and the MFDS. Additionally, you need to provide credentials to start any regions. By default, the credentials will be pre-populated in the dialog using the values stored in the microfocus/temp/admin vault location. These credentials can optionally be stored by the IDE so they do not need to be manually input again.

Note: If you delete the SYSAD user or change the password generated for it by the installer in the default VSAM Security Manager, you need to provide new sufficiently authorized credentials for the Server Explorer connection.

Authentication for HACloud

HACloud will initially use the default generated "readonly" credentials specified in the microfocus/common/readonly vault location. If ESCWA and/or the Micro Focus Directory Server are subsequently configured with non-default credentials, you need to manually configure HACloud to use these. See Authenticating HACloud for Work with ESCWA and MFDS.

Related reference
Authenticating HACloud for Work with ESCWA and the MFDS

Fileshare

If you want to view or delete Fileshare instances in ESCWA, you now need to log on using authorized credentials (such as the default SYSAD user).

Related reference
Fileshare Guide

Command-Line Utilities

There are multiple command line utilities that control and access enterprise server region. These use Enterprise Server credentials specified as parameters - for example, casstart /z.

See Administration and Configuration Commands for individual commands to determine how to specify authorized credentials.

Related reference
Administration and Configuration Commands

Samples and Tutorials

There are a variety of samples and tutorials supplied with the product. Many of these assume that security is not enabled, so to work through these unaltered default security will first need to be disabled. See To Disable the Default Enterprise Server Security Configuration. If security is not disabled, you will need to it take into account when you:

  • Use ESCWA
  • Start a region
  • Run a cas command line utility
  • Run a transaction using TN3270. You need to sign in via CESN.
  • Submit a JCL job
Related reference
To Disable the Default Enterprise Server Security Configuration
To Recreate the Default Enterprise Server Security Configuration

Micro Focus Common Client

The mf-client.dat file which is used by the Micro Focus Common Client (MFCC), is configured out-of-the box to use the default generated "readonly" credentials from the microfocus/common/readonly vault location. This means that access to the Micro Focus Directory Server using the default security configuration works automatically for read-only access.

MFCC is used by COBOL web service proxy programs, the Interface Mapping Toolkit service-deployment mechanism, Fileshare clients (when configured appropriately), various utilities such as cassub (depending on the operating mode), the CICS Web Interface and CICS Web Services, and product components such as MFCS and ESCWA. See Micro Focus Common Client.

Related reference
Micro Focus Common Client


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.

Important: Before performing a repair of the installation, Micro Focus recommends that you create backups of any configuration files of the product that you might have changed.

To repair your installation:

  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.

During the uninstall process, only those files added during the installation (to the installation and Samples directories) are removed.

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 Enterprise Test Server, Enterprise Server for .NET, and Micro Focus License Administration. Uninstalling only Enterprise Test 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


Updates and Product Support

When you have installed, you need to apply the latest updates if there are any. .

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

  1. Click Register on the Software Licenses and Downloads page.
  2. Enter your details. You will need your product serial numbers, which you can find in the subject line and body of either your Electronic Delivery Receipt email or Micro Focus Software Activation Information email that you received from Micro Focus when you activated or got a license key.

To log in:

  1. Enter your User Name and Password on the Software Licenses and Downloads page.

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

  2. Click Login.

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

  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
  2. Select your account and click Entitlements.
  3. Search for the product by using any of the available search parameters.
  4. Click Show all entitlements.
  5. Click Get Software in the Action column for the product you want to download or update.

    In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

  6. Click Download on the relevant row.

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


Backward Compatibility with Server Enterprise Edition or Studio Enterprise Edition Test Server

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


Known Issues and Restrictions

The following known errors and restrictions apply to Enterprise Test Server:

  • Application-Managed Services (Known Issues)
  • Audit Manager (Known Issues)
  • Containers (Known Issues)
  • Data Tools (Known Issues)
  • Documentation (Known Issues)
  • Enterprise Server (Known Issues)
  • FaultFinder (Known Issues)
  • File Handler (Known Issues)
  • HCO for SQL Server (Known Issues)
  • Mainframe Subsystem Support (Known Issues)
  • JCL Support (Known Issues)
  • Network File Access (Known Issues)
  • OpenESQL (Known Issues)
  • Security Considerations (Known Issues)
  • Security Management (Known Issues)
  • SQL Option for DB2 (Known Issues)
Parent topic: Product Information


Application-Managed Services (Known Issues)

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 Issues and Restrictions
Related concepts
Using XA-compliant Resources (XARs)


Audit Manager (Known Issues and Restrictions)

Audit Manager (Known Issues)

The Security Audit Manager is now deprecated.

The Enterprise Server security auditing mechanism supports sending audit events using the syslog protocol to a syslog server or a Security Information and Event Management (SIEM) system. See Enterprise Server Auditing for more information.

.
Parent topic: Known Issues and Restrictions


Containers (Known Issues)

You should be aware of the following limitations when using Enterprise Server with containers:

General

  • Java is supported from version 17 onwards.
  • It is not possible to containerize COBOL applications using lightweight operating systems such as CoreOS Container Linux, SUSE MicroOS and Alpine Linux.
  • It is not possible to run COBOL applications in containers on Linux on PowerPC or S/390 chipsets.
  • Using the Micro Focus Support Scan Utility, MFSupportInfo, in a container is not supported on Windows.
  • The microsoft/windowsservercore image only supports the English language so you cannot use any other languages in images based on that image.

    The base images for Enterprise Test Server that are created by the Docker demonstrations are based on the microsoft/dotnet-framework image (which is based on the microsoft/windowsservercore image), so this restriction applies to any images created using the Docker demonstrations.

Operating Systems

Enterprise Server is supported for use with Docker on the following Intel 64-bit operating systems:

  • Windows 10 (Pro or Enterprise editions) with Hyper-V enabled
  • Windows Server 2016
Note: Docker cannot be used on a PC that has VirtualBox or VMware installed.

Use with Enterprise Developer Products

  • It is not possible to containerize a COBOL application that runs under Enterprise Server for .NET.
  • If a region is hosted within a container which does not or cannot expose its internal network addresses, the Micro Focus Enterprise Server Common Web Administration interface will be unable to connect to the started region's ESMAC/monitor configuration unless the MFDS_EXTERNAL_ADDR environment variable is set within the container to an externally contactable address.
Parent topic: Known Issues and Restrictions
Related reference
https://www.microfocus.com/docs/links.asp?vc=docker_trblshoot
https://www.microfocus.com/docs/links.asp?vc=github_dockerwin_issues
Related information
Introduction to Containers


Data Tools (Known Issues)

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

The Data Tools product currently has the following known limitations:

  • There is no support for opening and editing local files. Any files opened and modified by the file service must be accessed from a data set on a remote server that is configured in advance.
  • You cannot create new data files using file service.
  • There is no Filter functionality.
  • There is no Search/Replace functionality.
  • There is no Save As option available. Any changes you make must be saved to overwrite the existing file.
  • There is no support for line sequential files.
  • There is no support for relative files.
Parent topic: Known Issues and Restrictions


Documentation (Known Issues)

Feedback link

  • Each help topic in the documentation for Enterprise Test 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 Issues and Restrictions


Enterprise Server (Known Issues)

HTTP 403 page
ESMAC contains defence mechanism against cross-site request forgery attacks. As a result, a 403 page is displayed in the browser if an incorrect authentication token is sent in a request to ESMAC that performs a protected operation, such as submitting a job or updating a resource definition.

If you receive a 403 page when using ESMAC, try clearing your session cookies as there might be a stale cookie value left behind which is triggering the page. If the page continues to appear, contact OpenText Support for Micro Focus Products for assistance.

Using more than one region in the same browser session
ESMAC contains defence mechanism against cross-site request forgery attacks. As a result of this, it is currently not possible to log in into two different regions within the same browser session. This is because cookies are used as part of the authentication process, and each region needs its own version of the authentication cookies to keep the ESMAC session valid.

You can work around this issue in one of the following ways:

  • Open each new ESMAC session in a separate private or incognito browser window for each region you want to access concurrently alongside any other running regions.
  • Alternatively, use ESCWA to manage your regions.
Upgrading Enterprise Server

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

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

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

Debugging Assembler modules with Enterprise Server
The MFASM debugger is unable to open a window for debugging on any enterprise server region started via ESWCA, as Microsoft has permanently disabled access to the user desktop from any application started in the background and owned by "SYSTEM".
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 Test 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.

Remote File Access
Remote File Access in this release might not operate correctly when uploading files if the client uses all three of: a multipart content-type (such as "multipart/form-data"), the "chunked" transfer-encoding, and the "gzip" transfer encoding. This issue can be avoided by not using gzip compression when using a multipart content-type.
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 run time 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 run time 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 Issues and Restrictions
Related concepts
Enterprise Server


FaultFinder (Known Issues)

The FaultFinder tool has been removed from the current version of Enterprise Test 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 Issues and Restrictions
Related reference
cobconfig_error_report


File Handler Known Issues and Restrictions

File Handler (Known Issues)

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 Issues and Restrictions
Related concepts
IDXNAMETYPE


HCO for SQL Server (HCOSS) Known Issues and Restrictions

HCO for SQL Server (Known Issues)

  • 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 run-time system 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 Issues and Restrictions
Related concepts
HCO for SQL Server (HCOSS)


Mainframe Subsystem Support (MSS) Known Issues and Restrictions

Mainframe Subsystem Support (Known Issues)

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.

Mainframe utilities

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 Enterprise Server Common Web Administration (ESCWA); it cannot be invoked, for example, from a batch job.

Parent topic: Known Issues and Restrictions
Related concepts
CICS Transaction Gateway


JCL Support Known Issues and Restrictions

JCL Support (Known Issues)

JCL jobs:

The number of duplicate DD statements for a DD name is limited to 999 per job step.

JCL utilities:

  • You cannot restart jobs that have been hard-killed, as they no longer possess the job information required for a restart.

  • If you have used the spool archiving utility, MVSSPLHK, to perform a FULL archive prior to Enterprise Developer 3.0 HF4, the archive may have failed to write records to the archive catalog. It may be missing the required information to display spool files, and a 'File not Found' error will be reported on the ESMAC page when clicking on a spool file entry. If that is the case, a utility to correct the errors, and insert the correct catalog records is available through your OpenText Support for Micro Focus Products engineer.

    Archive files created using Enterprise Developer 3.0 HF4 and later are working correctly.

Parent topic: Known Issues and Restrictions
Related concepts
MVSSPLHK Spool Housekeeping Process


Network File Access (Known Issues)

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 Issues and Restrictions
Related concepts
Enterprise Server Execution Control Under Windows


OpenESQL (Known Issues)

Linking

If you use CHARSET(EBCDIC) when compiling COBOL code that contains SQL host variables that are of the display numeric type defined as XXXXXX, you must link to the oesqlebc library to prevent link errors.

You can either set up the link from the IDE and recompile, or run the required commands from a command prompt after compiling.

From the IDE, before compiling or recompiling:

From a command prompt, after compiling:

  1. Start an Enterprise Developer command prompt. If you need instructions, see To start an Enterprise Developer command prompt.
  2. At the command prompt, switch to the directory that contains your COBOL code.
  3. Enter the following commands consecutively:
    set lib=installDir\lib;%lib%
cbllink myapp.obj oesqlebc.lib
    Where installDir is the path to your Enterprise Developer installation (by default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer, and myapp is the name of your COBOL object file.

MySQL

  • Supported for ODBC only.
  • OpenESQL does not support scrollable cursors.
  • OpenESQL uses the MySQL _rowid field to support the use of positioned updates and deletes in cursors. The _rowid field is available in MySQL only when a table is defined with a unique constraint or primary key on an integer column.
    Note: When a table is not defined with a unique constraint or primary key on an integer column, you must replace EXEC SQL UPDATE/DELETE WHERE CURRENT OF statements with corresponding searched EXEC SQL UPDATE/DELETE statements.
  • When a row in MySQL is updated but the row contents do not change, MySQL might return an affected row count of 0 (zero) instead of 1 as is generally returned by other DBMSs. To work around this, consider modifying the MySQL ODBC driver Configuration Options as follows:
    1. Invoke the MySQL/Connector/ODBC Data Source Configuration.
    2. Click Cursors/Results.
    3. Check Return matched rows instead of affected rows
  • The following restrictions apply when using MySQL 5.7 with the ODBC 5.3 driver:
    • Unqualified SELECT * statements must not have any other items in the projection list
    • ODBC escape sequences are not recognized
    • MySQL does not permit deferred constraint checking for an SQL statement, or for SQL statements within a transaction boundary
    • SQL TYPE BLOB host variables are restricted to 3M bytes in length

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 Issues and Restrictions
Related concepts
OpenESQL


Security Considerations Known Issues and Restrictions

Security Considerations (Known Issues)

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

Parent topic: Known Issues and Restrictions
Related concepts
Enterprise Server Security


Security Management (Known Issues)

  • 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 Issues and Restrictions
Related concepts
Enterprise Server Security
ESF Passtokens
MLDAP ESM Module


SQL Option for DB2 Known Issues and Restrictions

SQL Option for DB2 (Known Issues)

  • You must have administrator privileges and you must enable server security before you can delete a user from the XDB Server. Otherwise, XDB Server returns the error "X124 Illegal operation on system object".
Parent topic: Known Issues and Restrictions


Contacting Micro Focus

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

  • Further Information and OpenText Support for Micro Focus Products
  • Information We Need
  • Contact information
Parent topic: Product Information


Further Information and OpenText Support for Micro Focus Products

Additional technical information or advice is available from several sources.

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

  • Product Updates on Software Licenses and Downloads, where you can download fixes and documentation updates.
    1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
    2. Select your account and click Entitlements.
    3. Search for the product by using any of the available search parameters.
    4. Click Show all entitlements.
    5. Click Get Software in the Action column for the product you want to download or update.

      In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

    6. Click Download on the relevant row.
  • The Examples and Utilities section of the OpenText Support for Micro Focus Products Web site, including demos and additional product documentation. Go to https://supportline.microfocus.com/examplesandutilities/index.aspx.
  • The Support Resources section of the OpenText Support for Micro Focus Products Web site, that includes troubleshooting guides and information about how to raise an incident. Go to https://supportline.microfocus.com/supportresources.aspx

To connect, enter https://www.microfocus.com/en-us/home/ in your browser to go to the Micro Focus home page, then click Support & Services > Support. Type or select the product you require from the product selection dropdown, and then click Support Portal.

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 for Micro Focus products, https://www.microfocus.com/support-and-services/contact-support/. 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 Micro Focus product..
  • Micro Focus webinars: https://www.microfocus.com/en-us/resource-center/webinar.
Parent topic: Contacting Micro Focus
Related information
OpenText Support for Micro Focus Products
Examples and Utilities
Support Resources
OpenText Community
White Papers
Webinars
Micro Focus YouTube Channel


Information We Need

If your purpose in contacting Micro Focus is to raise a support issue with OpenText Support for Micro Focus Products, you should collect some basic information before you contact us, and be ready to share it when you do. See Preparing to Raise a Support Case for complete information.

Parent topic: Contacting Micro Focus
Related concepts
Preparing to Raise a Support Case


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.

To connect to the product support pages, enter https://www.microfocus.com/en-us/home/ in your browser to go to the Micro Focus home page, then click Support & Services > Support. Type or select the product you require from the product selection dropdown, and then click Support Login.

If you are a customer of OpenText Support for Micro Focus Products, please see the Customer Support Handbook that includes information about downloading and licensing your product, contacting Customer Support, and about reporting an incident. You can download it from our Web site at https://support.microfocus.com/programs/guide.html. Support from Micro Focus may be available only to customers who have maintenance agreements.

You can download fixes and documentation updates:

  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
  2. Select your account and click Entitlements.
  3. Search for the product by using any of the available search parameters.
  4. Click Show all entitlements.
  5. Click Get Software in the Action column for the product you want to download or update.

    In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

  6. Click Download on the relevant row.
Parent topic: Contacting Micro Focus
Related information
Micro Focus Web Site
Micro Focus SupportLine
Welcome to Customer Care


Managing Licenses

  • Overview
  • Enterprise Test Server Editions and Managing Licenses
  • To start Micro Focus License Administration
  • Configuring Micro Focus License Administration
  • Installing licenses
  • Installing licenses silently
  • Viewing installed licenses
  • Uninstalling licenses
  • Installing License Manager
  • Trial licenses
  • Subscription licenses
  • Usage Logging
Parent topic: Welcome


Overview

You manage your product licensing by using the Micro Focus License Administration tool.

On Windows, you can use both a GUI interface and a command-line version of the Micro Focus License Administration tool. On UNIX, only a command-line version is available.

When you install your Micro Focus product, the Micro Focus AutoPass Daemon 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.

Important: The SafeNet Sentinel licensing system that was available with previous releases of this product has been deprecated and is no longer available in release 10.0. This product uses the Micro Focus AutoPass licensing technology, first introduced in release 8.0, and AutoPass is now the only licensing technology available in this product.

The SafeNet Sentinel licenses are no longer supported, and you need to use AutoPass licenses starting with release 10.0. Contact OpenText Support for Micro Focus Products to replace your existing SafeNet Sentinel with AutoPass licenses.

Network license server

If your site has multiple licenses and you want to use a network 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

Uninstalling a Micro Focus product that uses the Micro Focus AutoPass Daemon does not remove the license(s) that you have activated for that product, nor does it uninstall the daemon and the license server. We recommend that before you uninstall the Micro Focus product, you uninstall the licenses for it.

Note: Installing 10.0 on a machine where there are other Micro Focus products or versions installed that use SafeNet Sentinel licensing might result in some compatibility issues. While the 10.0 installation process has been designed to address such issues, you should be aware of the following scenarios and if any action might be required to ensure licensing works as expected. See Advanced Installation Tasks > Licensing Coexistence when Upgrading to Release 10.0 in the Installation section.
Parent topic: Managing Licenses
Related concepts
Licensing Coexistence when Upgrading to Release 10.0


Enterprise Test Server Editions and Managing Licenses

Enterprise Test Server comes in the following product variants:

  • Enterprise Test Server, which is the standard Test Server product and is a mainframe Test Execution environment.
  • Enterprise Test Server Premium, which also provides Test Automator. Use Test Automator to automate testing by creating automated test suites you can play back against Enterprise Test Server or against the host.

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: Managing Licenses


To start Micro Focus License Administration

To start the GUI Micro Focus License Administration

Windows 10
From your Windows desktop, click Start > Micro Focus License Manager > License Administration.
Windows 11
Click the Start button in the Task Bar. Use the search field in the Start menu to find and start License Administration.

To start the command-line Micro Focus License Administration tool

  1. At a command prompt, navigate to:
    C:\Program Files (x86)\Micro Focus\Licensing
  2. Type cesadmintool.bat, and press Enter.

Configuring licensing for older products

If you use release 10.0 and previous releases on the same machine on UNIX, you need to the set the environment variable MFCES_INIT_LOCATION to /opt/microfocus/licensing/bin/ces.ini in order for licensing to work for the older products. Also, see Advanced Installation Tasks > Licensing Coexistence when Upgrading to Release 10.0 in the Installation section.

Parent topic: Managing Licenses


Configuring Micro Focus License Administration

CAUTION:
Before you make any changes to the configuration options, you need to consult with OpenText Support for Micro Focus Products.

To use the GUI Micro Focus License Administration

  1. Start Micro Focus License Administration.
  2. Click Options > Autopass Configuration.
  3. Change the Host or Port for the AutoPass server, and click Save.

To use the command-line Micro Focus License Administration tool

  1. Start the command-line Micro Focus License Administration tool.
  2. Select Advanced Configuration Options by entering 3.
  3. Enter the number of the option you want to change, and press Enter.
  4. Follow the instructions for the specific option.
Parent topic: Managing Licenses


Installing licenses

You need a license file (with an .xml extension for AutoPass licenses). You need to install AutoPass licenses into the existing Micro Focus License Administration tool, and not in the AutoPass License Server.

  • Applying your license file
  • Configuring your machine to use a central license server
Parent topic: Managing Licenses


Applying your license file

To use the GUI Micro Focus License Administration

  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 .xml).
    • Drag and drop the license file from Windows Explorer to the License file field.
  4. Click Install Licenses.

To use the command-line Micro Focus License Administration tool

  1. Start the command-line Micro Focus License Administration tool.
  2. Select the Manual License Installation option by entering 4.
  3. Enter the name and location of the license file.
Parent topic: Installing licenses


Configuring your machine to use a central license server

This topic describes how to configure your machine to use a central license server. You might have already done this when you installed your product.

You need the IP address or server name for the central license server you want to use.
Important: We recommend that Advanced Configuration options other than those referenced here are modified only under guidance from OpenText Support for Micro Focus Products.
  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.

To use the command-line Micro Focus License Administration tool

  1. Start the command-line Micro Focus License Administration tool.
  2. Select the Advanced Configuration Options option by entering 3.
  3. Select the License server option by inputting the corresponding list number and clicking Enter.
  4. Enter the IP address or server name of the central license server and click Enter.
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 don't have access to the Internet but have a file from Micro Focus, FileName, that contains the license string:

    For 32-bit Windows environments:

    start /wait "" "C:\Program Files (x86)\Micro Focus\Licensing\cesadmintool" -term install -f FileName

    For 64-bit Windows environments:

    start /wait "" "C:\Program Files (x86)\Micro Focus\Licensing\cesadmintool" -term install -f FileName

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

Parent topic: Managing Licenses
Related information
License Manager


Viewing installed licenses

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

If you are unsure of what your license entitlement is or if you wish to purchase additional licenses, contact your sales representative or OpenText Support for Micro Focus Products.

To use the command-line Micro Focus License Administration tool

  1. Start the command-line Micro Focus License Administration tool.
  2. Select the Check License Status option by entering 2.
  3. You can see more information for some licenses, such as type and number of licenses, the date a license was generated and the platform it is for. To do this, return to the License Administration main menu and selecting the Get License Details option by entering 8. This lists the license information - choose the requisite license by entering the corresponding number.

If you are unsure of what your license entitlement is or if you wish to purchase additional licenses, contact your sales representative or OpenText Support for Micro Focus Products.

Parent topic: Managing Licenses


Uninstalling licenses

Licenses you can uninstall have a Remove link in the Uninstall column.

  • Removing licenses
Parent topic: Managing Licenses


Removing licenses

You can remove a license that was installed using a .xml file as follows:

To use the GUI Micro Focus License Administration

  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.

To use the command-line Micro Focus License Administration tool

  1. Start the command-line Micro Focus License Administration tool.
  2. Select the Uninstall Licenses option by entering 5.
  3. Select the license to remove and click Enter.
Parent topic: Uninstalling licenses


Installing License Manager

The License Manager infrastructure is installed by default on each machine when a product is installed. The product installer invokes the License Manager installer silently.

  • Installing a local license server
  • Installing a standalone network license server
  • Installing License Manager without AutoPass
  • Setting up network licensing with COBOL server
Parent topic: Managing Licenses


Installing a local license server

The License Manager infrastructure is installed by default on each machine when a product is installed. The product installer invokes the License Manager installer silently. This enables a product to ask for a license locally by default.

Any License Manager can also be used as a network license server.

These are the instructions to download and install License Manager without a product installation:

  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter.
  2. Select your account and click Downloads.
  3. Select a product and a product version from your orders.
  4. In the list of software downloads, locate the License Manager.
  5. Click Download to download an archive with the installers.
  6. Run the installer suitable for your Operating System to install License Manager on your machine.
Parent topic: Installing License Manager


Installing a standalone network license server

A separate installer is available so that License Manager can be installed on a machine without needing to install a product.

Note: License Manager only supports 64-bit Windows.
  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
  2. Select your account and click Entitlements.
  3. Search for the product by using any of the available search parameters.
  4. Click Show all entitlements.
  5. Click Get Software in the Action column for the product you want to download or update.

    In the File Type column, you see entries for "Software" for any GA products, and "Patch" for any patch updates.

  6. Click Download on the relevant row.
  7. From the Downloads section, select the product name and version you are using.
  8. In the list of software downloads, locate the License Manager.
  9. Click Download to download an archive with the installers.
  10. Run the installer suitable for your Operating System to install License Manager on your machine.

  • Installing on Windows
Parent topic: Installing License Manager


Installing on Windows

  • Standard installation
  • Silent installation
Parent topic: Installing a standalone network license server


Standard installation

  1. Run the License Manager installer to install the licensing infrastructure.
  2. During the installation, on the Product Features screen, you can optionally disable the AutoPass, if you do not need it. Also note that:
    • With 64-bit only products, License Manager only installs AutoPass licensing.
  3. Start the Licensing System Administration tool. To do this, select:

    Start > All Programs > Micro Focus License Manager > License Management System

    The Micro Focus License Administration window appears.

    You can now manage licenses on the machine.

Parent topic: Installing on Windows


Silent installation

Type:

start /wait msiexec /qn /i lmsetup64.msi

Parent topic: Installing on Windows


Installing License Manager without AutoPass

If you are using a network license server, you might not want to install License Manager on each client machine with AutoPass.

The following procedures install a basic infrastructure (the licensing daemon and relevant configuration files) without the Micro Focus AutoPass Daemon infrastructure.

CAUTION:
This means that there is no local license server and, therefore, you cannot manage licenses on the local machine, only on the network license server.
  • Installation
  • Silent installation
Parent topic: Installing License Manager


Installation

Use the following command if you want to skip inclusion of AutoPass during License Manager installation:

msiexec /i <license-manager-installer> SKIPAUTOPASS=1

Parent topic: Installing License Manager without AutoPass


Silent installation

Use the following command if you want the installation to use a non-standard License Manager server setup silently:

start /wait msiexec /qn /i <license-manager-installer> NOSAFENET=<ip-addess>|NONET

where <license-manager-installer> is lmsetupx64.msi, <ip-addess> is the address of a remote server where the License Manager resides, or where NONET indicates that no server is required (for example, with a Docker image).

Parent topic: Installing License Manager without AutoPass


Setting up network licensing with COBOL server

A scenario for setting up network licensing with COBOL Server 2.1 to run native (non-.NET) applications can be found at:

https://community.microfocus.com/cobol/visualcobol/w/wikiid-120/4087/set-up-networked-licensing-with-cobol-server-2-1-to-run-native-non-net-applications

Parent topic: Installing License Manager


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 OpenText Support for Micro Focus Products.

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


Subscription licenses

Micro Focus offers subscription-based licensing of products.

Expired subscription

Important: You will still be able to access and use your Micro Focus product after your subscription has ended.

Once the subscription has expired, users will receive the message Unlicensed program, please contact your system administrator or Micro Focus support when starting the product, and at the start of every session thereafter. You can continue to access and use the product after automatic expiration of your license, however, you must contact Micro Focus to renew your subscription as soon as you receive this message.

Parent topic: Managing Licenses


Usage Logging

AutoPass usage logging

This product supports license usage logging with the help of the AutoPass License Server. See License Usage Logging with AutoPass License Server.

Usage logging with the License Administration tool

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

  • License Usage Logging with AutoPass License Server
Parent topic: Managing Licenses


License Usage Logging with AutoPass License Server

AutoPass License Server (APLS) is a Micro Focus web-based solution for managing Micro Focus Software product licenses. If your Micro Focus development or run-time product is licensed using an AutoPass license, you can take advantage of the license usage logging feature available within APLS.

This usage logging feature captures license usage statistics within the development or run-time product, and then periodically sends them, encrypted, to an AutoPass License Server. Once uploaded, an authorized user can run reports from the server, showing high-level license usage over a period of time. There are a number of pre-defined reports available that are based on the types of licenses available; for example, concurrent user reports, machine core reports, etc... Those reports can also be customized to suit your organizational needs. Additionally, you can create your own reports, either from scratch or by basing them on the existing reports.

The usage statistics used in a report are defined as instances where a feature requiring a product license is consumed. For development products, this would be things such as checker/compilation or run-time processes; for deployment products, this would be a run-time process. Usage is monitored over the time frame of one hour: for example, multiple compilations by a single user, on the same product/machine within an hour would generate one instance, resulting in one record entry in a generated report. Statistics are also captured for Docker containers, using the same principles.

Such reporting can demonstrate if your current license quota is in line with your needs, and helps avoid your organization from contravening any licensing agreements, or it can simply be used for auditing purposes.

  • Prerequisites for Integration with an AutoPass License Server
  • Integrating with an AutoPass License Server
  • Configuring AutoPass License Server for Custom Reports
  • Working with Custom Reports
Parent topic: Usage Logging


Prerequisites for Integration with an AutoPass License Server

The following pre-requisites are required in order to configure your product to generate license usage statistics.

Micro Focus COBOL development and run-time products

Each product for which you are required to collect license usage statistics must be licensed with an AutoPass license. If your product is still using a SafeNet license, you must replace it as the Sentinel SafeNet technology is not available as of release 10.0. In order to acquire AutoPass licenses, contact your Micro Focus Account Manager.

AutoPass License Server

Important: The integration only pertains to the Custom Report functionality within AutoPass License Server; other features of the server are not yet supported when integrated with Micro Focus products.

Custom Report is the functionality that utilizes the license usage statistics. This is only supported in AutoPass License Server (APLS) version 12 or later. If the APLS is already established, the administrator of the server should supply you with the server details (host name and port), so that you can configure your .ini file; see Integrating with an AutoPass License Server.

If you are setting up a new APLS, you can download the product from https://marketplace.microfocus.com/itom. It can run on Windows and Linux platforms.

APLS comes with full help for installation and setup, and is therefore not covered in this documentation.

Restriction: APLS does not support the use of Internet Explorer 11; use Microsoft Edge or an alternative browser in order to access the product.

An additional consideration is the choice of database with which to link to a supported server - see the next section.

PosgtreSQL

APLS works with a number of database types, but currently PostgreSQL is the only database type compatible with the custom report functionality. It uses PostgreSQL to store the usage data uploaded from your Micro Focus COBOL products licensed with AutoPass.

Micro Focus recommends your APLS uses PostgreSQL 13.2, as this is the version tested against.

Parent topic: License Usage Logging with AutoPass License Server
Related information
Integrating with an AutoPass License Server
Configuring AutoPass License Server for Custom Reports
Working with Custom Reports


Integrating with an AutoPass License Server

In order to generate license usage statistics for this product, it must be licensed using an AutoPass license, and then configured to send the information to an AutoPass License Server.

  1. Open the AutoPassDaemonConfig.ini file. This file is located:
    C:\Program Files (x86)\Micro Focus\Licensing\AutoPass

    In its default state, this file contains a number of parameters without values.

  2. Update the following mandatory parameters:
    Option | Description
    autopass.daemon.ls.host | The host name of the AutoPass License Server
    autopass.daemon.ls.port | The port number of the server. (The default port number is 5814.)
    autopass.daemon.ls.protocol | Set to HTTPS
    autopass.daemon.allow.usage.persistence | Set to true - this enables the link between your product and the AutoPass License Server
  3. Save and exit the file.
  4. Restart the following services:
    • Micro Focus CES Daemon
    • Micro Focus AutoPass Daemon
    Usage records are generated immediately, and periodically (once an hour) sent, encrypted, to the specified AutoPass License Server.

The process for configuring license usage statistics in an AutoPass licensed container is the same as described here, but additionally, once your autopassdaemonconfig.ini file is configured, it must be added into your container image in the same location as described above: this can be copied in during your application deployment image build process or mounted at run time.

Note: The sending of reports is not visible to an end user; if an administrator informs you that records are not being received by the intended APLS, you should contact OpenText Support for Micro Focus Products, who can enable logging to help troubleshoot any problems.
Parent topic: License Usage Logging with AutoPass License Server
Related information
Prerequisites for Integration with an AutoPass License Server
Configuring AutoPass License Server for Custom Reports
Working with Custom Reports


Configuring AutoPass License Server for Custom Reports

If you already have an AutoPass License Server, it needs to be linked to a PostgreSQL 13.2 database. If it currently links to any other type of database, the required Custom Report option, within the USAGE & REPORT section, is not available.
Note: These instructions cover functionality within AutoPass License Server; always refer to the in-product APLS help by clicking The Help icon for the most comprehensive instructions.

To view which database a AutoPass License Server currently links to, point to The Configuration icon and select Database Configuration.

To set up or change the linked database:

  1. Click The Configuration icon.

    The SYSTEM configuration pane is displayed by default.

  2. On the Config pane, click DATABASE.

    The Database Connection Attributes are displayed.

  3. Complete the fields using the following table as a guide:
    Field | Value
    DataBase Type | PostgreSQL
    DataBase URL/DataBase Host | Either the URL or host name of the PostgreSQL instance
    DataBase Port | Port number of above instance
    DataBase Name | Name of database that the data will be stored
    DataBase User | User with sufficient permissions to write to the database
    DataBase Password | Password for specified user
  4. Click Test Connection.

    If the connection is successful, a message is displayed.

  5. Click Save.
  6. Either restart the machine, or restart the AutoPass License Server service. The first time the server receives some license usage statistics from a Micro Focus product, the Custom Report option appears in the USAGE & REPORT section.
Parent topic: License Usage Logging with AutoPass License Server
Related information
Prerequisites for Integration with an AutoPass License Server
Integrating with an AutoPass License Server
Working with Custom Reports


Working with Custom Reports

The Custom Report feature of the USAGE & REPORT section contains the group of reports that use the license usage data collected from your Micro Focus products.

These reports are only available to authorized users, and only if your AutoPass License Server is linked to a PostgreSQL 13.2 database.

The license usage statistics are grouped by Micro Focus product and version. Within each group there are a number of pre-defined reports that equate to each of the license types that are available from Micro Focus, and an additional report that captures all data. If these reports do not suit your needs, you can clone and edit them, or you can create new reports from scratch.

You can manipulate the results of these reports by applying filters, allowing you to focus on usage over a particular time scale, for a particular machine or user, etc... After which, you can export the generated report as a .csv file, or exported directly to Excel, where you can manipulate the data further.
Note: Exported date data is in epoch format, so you may need to convert it to a more readable date once in your spreadsheet.

For a more comprehensive description of creating and exporting reports, refer to the documentation available from the APLS, by clicking The Help icon.

  • Create a Custom Report
  • Run a Custom Report
Parent topic: License Usage Logging with AutoPass License Server
Related information
Prerequisites for Integration with an AutoPass License Server
Integrating with an AutoPass License Server
Configuring AutoPass License Server for Custom Reports


Create a Custom Report

If none of the pre-defined reports meet your needs, you can create a custom report, defining the fields for the report, and the order in which they appear.

For a more comprehensive description of custom reports and the fields they may contain, refer to the documentation available from the APLS, by clicking The Help icon.

  1. Click The Menu icon and select Custom Report from the USAGE & REPORT section.
  2. Click Select Product and select the product on which to run a report.
    Tip: At this point, if there was a report similar to your needs, you could edit that report and save it with a new name to create a new report; alternatively, continue to create a new report from scratch.
  3. Click Create Usage Report.

    The Create Usage Report form is displayed.

  4. Complete the Report Name and Report Description fields.
  5. In the Add Report Field section, select a field, and a data type and aggregator for that field, and then click Add.
  6. Repeat the last step at least twice more; a report must have a minimum of 3 fields.

    The Report Field Settings section contains the selected fields.

  7. In the Report Field Settings section, you can drag the fields to change their order in the report, or edit ( The Edit field icon) or delete ( The Delete field icon) them.
  8. In the Report Filter Settings section, if required, define one or more filters to focus on the required records: define the filter details and click Add Filter.
  9. Click Create to create the custom report.

Once you have created the report, there are a number of actions, as well as running it, that you can perform, such as cloning, editing, deleting and exporting it. Again, refer to the APLS documentation for more details.

Parent topic: Working with Custom Reports


Run a Custom Report

For a more comprehensive description of the data shown in the custom reports and how to run and export them, refer to the documentation available from the APLS, by clicking The Help icon.

  1. Click The Menu icon and select Custom Report from the USAGE & REPORT section.
  2. Click Select Product and select the product on which to run a report.
  3. Click Select Report and select the report to run.

    The report runs automatically and the results are displayed.

  4. At this point, you can perform a number of steps, such as:
    • Edit the report - click Edit Report, update the report fields and click Update.
    • Clone the report - click Edit Report, update the report name and fields and click Save As.
    • Filter the report results - click Add Filter and select a field to filter the results on.
    • Export the results - click Export to Excel icon (Export to Excel) or Export to CSV icon (Export to CSV).
    • Focus on a subset of results - use expand icon and collapse icon on the column heading and within the rows to expand and collapse information.
Parent topic: Working with Custom Reports


The Micro Focus Community

In addition to this product documentation, visit the OpenText Community Forum 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


Help on Help

The latest up-to-date Help is available on the OpenText Support and Services Documentation Web site for Micro Focus products.

Release Notes

The Release Notes accompany major releases and updates. They are available from the Software Licenses and Downloads (SLD) site and your EPD email. On Windows, a link to the release notes is available from the startup screen during installation.
  1. Log into the Software Licenses and Downloads (SLD) site at https://sld.microfocus.com/mysoftware/download/downloadCenter .
  2. Select your account and click Downloads.
  3. Search for the product by using any of the available search parameters.

    All available downloads are displayed.

  4. Click Download in the Action column on the row for the product whose Release Notes you want to download.

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:

  • Patch Update readmes contain information about issues that are resolved in a Patch Update, changes in behavior that could potentially affect existing applications, and any specific Patch Update 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 Patch Update readme.

Parent topic: Welcome


Deploying Applications

Describes the concepts and tasks involved in deploying COBOL and Mainframe Subsystem applications using Enterprise Test Server.
  • Overview of Deploying Your Applications
  • Deploying the Micro Focus Run-Time System
  • Deploying Native Applications
  • Deploying COBOL Applications to the .NET Environment
  • Deploying COBOL Applications to .NET
  • Deploying IMS Applications
    Describes the features available to deploy an IMS application to and run a production IMS application on Enterprise Test Server.
  • Deploying Stored Procedures
  • Deploying ES.NET Mainframe Subsystem Applications
  • Code set translation
Parent topic: Micro Focus Enterprise Test Server 10.0


Overview of Deploying Your Applications

Applications developed using a COBOL development system require a COBOL run-time server to provide the necessary run-time system and support.

Enterprise Test Server is your COBOL run-time server. It is supplied as part of Enterprise Developer, which is your COBOL development system. Enterprise Test 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 Test Server with your application, if it is a modular application. We recommend that you ship the whole of Enterprise Test Server to avoid compatibility issues and other problems.
  • Ensure that the application you have developed has the proper Enterprise Test 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 license, 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.

Enterprise Test Server Variants and Deploying Applications

To configure Enterprise Test Server your development administrator will work with the development teams to set up the Enterprise Test Server environment on your central Windows test server, as follows:

  1. Micro Focus Enterprise Developer is used to recompile application source code for execution on Windows.
  2. Test data sets or databases are made available either locally or on the mainframe through remote access.
  3. Development and test teams are trained to ensure that they understand how to test applications within the Enterprise Test Server environment and to switch between the different test regions it supports.

Enterprise Test Server comes in the following product variants:

  • Enterprise Test Server, which is the standard Test Server product and is a mainframe Test Execution environment.
  • Enterprise Test Server Premium, which also provides Test Automator. Use Test Automator to automate testing by creating automated test suites you can play back against Enterprise Test Server or against the host.
Parent topic: Deploying Applications
Related concepts
Deploying the Micro Focus Run-Time System
Deploying ES.NET Mainframe Subsystem Applications
Related information
Deploying COBOL Applications to the .NET Environment


Deploying the Micro Focus Run-Time System

Applications developed using Enterprise Developer require a COBOL run-time server, Enterprise Test Server, to provide the necessary run-time system and support.

Micro Focus recommends that you install the full Enterprise Test Server with your applications. It is also possible to install only selected files, which is available to preserve backward compatibility.

To install the full Enterprise Test Server (recommended):

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

    You can also install Enterprise Test Server silently - see Enterprise Test Server Installation Options.

    If you use a Windows install package to deliver your application, you can include the Enterprise Test Server with this. See Enterprise Test Server Deployment Toolkit.

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

  1. Determine the files to ship.
  2. Extract the files in the Enterprise Test Server install file. To do this, run the executable file ets_100.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.
  • Enterprise Test Server Installation Options
  • Enterprise Test Server Deployment Toolkit
    The Enterprise Test Server Deployment Toolkit includes a number of components that enable you to integrate Enterprise Test Server into a Windows installer package.
  • Shipping Selected Files from Enterprise Test Server
  • Run-time Launch Configuration Files
Parent topic: Deploying Applications
Related concepts
Overview of Deploying Your Applications
Deploying ES.NET Mainframe Subsystem Applications
Related information
Deploying COBOL Applications to the .NET Environment


Enterprise Test Server Deployment Toolkit

The Enterprise Test Server Deployment Toolkit includes a number of components that enable you to integrate Enterprise Test Server into a Windows installer package.
  • Introduction to the Enterprise Test Server Deployment Toolkit
  • Merge Modules and Installer Packages
    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: Deploying the Micro Focus Run-Time System


Introduction to the Enterprise Test Server Deployment Toolkit

Note: This document is intended for administrators and installation developers.

It assumes that you are familiar with the specific packaging software you are going to use, such as InstallShield or WiX. For information about how to create the installer, refer to the documentation of your packaging software.

The Enterprise Test Server Deployment Toolkit gives you more flexibility when deciding how to deploy your COBOL-based applications that depend on Enterprise Test Server. It contains a number of merge modules and install package files which enable you to integrate Enterprise Test Server in a Windows installer package that you can then use to distribute your applications to your end users.

The files making up the Deployment Toolkit are contained in the file es_243_deployment_sdk.zip which you can download from the Electronic Delivery Receipt email which you are sent when you purchase a license for Enterprise Test Server, or from the Micro Focus Software Activation Information email which you are sent when you activate or get a license key.

The Deployment Tookit includes a number of merge modules (.msm files) and installer package (.msi) files for either 32-bit or 64-bit systems. You can include the .msm files in your application's installer if it is an .msi installer. You can use the .msi files in your application's installer if it is a wrapper or a bundle .msi-style installer.

License Manager is only provided as installer packages (.msi) and must be supplied separately where you are using the Enterprise Test Server merge modules.

Parent topic: Enterprise Test Server Deployment Toolkit
Related information
Writing Your Own Setup Program


Merge Modules and Installer Packages

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 Test Server components. It also includes merge modules and executable (.exe) files to install Visual C++ libraries that Enterprise Test Server requires to be able to run applications developed using the Microsoft Visual C++ Runtime and Microsoft Visual Studio 2017 or later.

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

For 32-bit Windows systems the files are:

  • enterpriseserver_243x86.msm - the Enterprise Test Server merge module
  • enterpriseserver_243x86.msi - the Enterprise Test Server installer package
  • Microsoft_VC141_CRT_x86.msm - the C/C++ run-time distributables for the Microsoft Visual C++ Runtime
  • vcredist_x86.exe - the C/C++ run-time distributables for Microsoft Visual Studio 2017 or later

For 64-bit Windows systems the files are:

  • enterpriseserver_243x64.msm - the Enterprise Test Server merge module
  • enterpriseserver_243x64.msi - the Enterprise Test Server installer package
  • Microsoft_VC141_CRT_x64.msm - the C/C++ run-time distributables the Microsoft Visual C++ Runtime
  • vcredist_x64.exe - the C/C++ run-time distributables for Microsoft Visual Studio 2017 or later
Note: If your application is being installed onto a system that does not already include the Visual C++ libraries that are required to run applications developed using the Microsoft Visual C++ Runtime and Microsoft Visual Studio 2017 or later, your installer must include one of vcredist_x86.exe, vcredist_x64.exe, Microsoft_VC110_CRT_x86.msm or Microsoft_VC141_CRT_x64.msm as appropriate.

For example:

  • If your application's installer consists of a group of .msi files, add the Enterprise Test Server installer package file (either enterpriseserver_243x86.msi or enterpriseserver_243x64.msi) to the group.

See the MSDN for more information about the Windows Installer and merge modules.

Parent topic: Enterprise Test Server Deployment Toolkit


License Manager

The Deployment Toolkit includes a couple of merge module files (.msi) to enable you to install the Micro Focus License Manager to work alongside Enterprise Test 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.

Use the /i parameter to install License Manager:

start /wait msiexec /i lmsetupx86.msi

Use the /qn parameter to install License Manager silently:

start /wait msiexec /qn /i lmsetupx86.msi

You can use the -term parameter to silently install the license using your license file. See Installing licenses silently for details.

Parent topic: Enterprise Test Server Deployment Toolkit
Related concepts
Installing licenses silently


Shipping Selected Files from Enterprise Test Server

Note: The following applies to native COBOL only.
CAUTION:
Micro Focus recommends that you ship the whole of Enterprise Test Server with your application. However to provide backward compatibility, you can still select and ship specific files.

The Enterprise Test 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
  • .int and .gnt support files to ship
  • Native OO COBOL Files to Ship
  • Run-time System Files to Ship
Parent topic: Deploying the Micro Focus Run-Time System


.int and .gnt support files to ship

CAUTION:

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

If your application contains .int and .gnt files, you need to supply the following files:

  • The trigger program that starts your application.
  • The run-time file that enables the run-time system to run .int files. This file is cblints.dll for single-threaded programs, and cblintm.dll.
  • The file for making calls to the Win32 API from intermediate and generated code: cob32api.dll.

In addition, you need the same range of files as any other application:

  • The files that comprise your application, which in this case are .int and .gnt files.
  • Any linked programs called by the application.
  • The file for the shared run-time system: cblrtss.dll, for single-threaded applications, or cblrtsm.dll
  • Any run-time support modules called by the application.
Parent topic: Shipping Selected Files from Enterprise Test Server


Native OO COBOL Files to Ship

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

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

If your application uses native OO COBOL 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 Test 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 Test 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: | 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
Enhanced ACCEPT/DISPLAY syntax (ADIS) | adis.dll | adis.dll
File handling or enhanced ACCEPT/DISPLAY syntax (ADIS) or 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:
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
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.lib (when using the DB2 ECM compiler)
  • mfsqlsmf.dll

Micro Focus run trigger program:

  • trigger (console application)
  • trigger (GUI application)
  • single-threaded trigger
  • single-threaded trigger (Windows)

  • run.exe, and runm.exe
  • runw.exe, and runmw.exe
  • runs.exe
  • runsw.exe
  • run.cfg
  • shell.dll
Note: run.cfg must be placed in a sub-directory named etc; it is an internal file, and must not be edited manually.
Microsoft Transaction Server
  • objectcontext.dll
ODBC
  • drivers obtained separately, and
  • odbcrw32.dll
OUTDD directive or DBCS CODESET support
  • cblutil.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, OpenESQL, and ODBC
  • csqlsupp.dll (Cobsql)
  • odbcrw32.dll or odbcrw64.dll (OpenESQL)
  • oesqlebc.dll (OpenESQL with EBCDIC data)
  • ODBC drivers obtained separately
  • mfsqlsmf.dll
  • antlr4-runtime32.dll (OpenESQL)
  • antlr4-runtime64.dll (OpenESQL)
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 Test 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.

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

Priority of settings

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 Test Server installation.

Loading the launch configuration

If the main program of the application is a COBOL one, the application launch configuration file is loaded automatically.

However, if the main program is not written in COBOL, you must load the application launch configuration file. To do this, you need to add a call to the Micro Focus routine coblaunchconfig() before any COBOL code is executed in the application.

  • Run-time Launch Configuration File Options
  • Examples of a Run-time Launch Configuration File
Parent topic: Deploying the Micro Focus Run-Time System


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

SETENV var-name=var-value | Sets the environment variable var-name, with the value var-value.
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 location:

  • C:\Program Files (x86)\Micro Focus\Licensing
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 Test 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 Test 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 Test 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 Test Server using the binary files located in the rt-files sub-directory of the application's working directory.

set BINPATH=\rt-files

The following example amends the current PATH. This particular example is a specific workaround when deploying applications that require the character Dialog System (DSCHAR) - in order that the character version of the Dialog System is picked up in preference to the default GUI version of the Dialog System (DSGUI), you need to amend the PATH to the location of DSCHAR.

SETENV PATH=C:\InstallDir\DShar\bin;%PATH%

Where InstallDir is product installation folder.

Parent topic: Run-time Launch Configuration Files
Related reference
Run-time Launch Configuration File Options


Deploying Native Applications

  • Writing Your Own Setup Program
  • To set up an application with a shared Enterprise Test Server
  • To set up an application with its own Enterprise Test Server
  • To run a native COBOL application from a network server
    You need to configure the licensing for Enterprise Test Server when running native COBOL applications from a network server.
Parent topic: Deploying Applications
Related concepts
Deploying Native Applications


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.

Applications that run in an enterprise server region

If your application runs in an enterprise server region, setting it up requires that the application is deployed to the region, but there are no other major considerations.

Applications that do not require a region

If your application uses a COBOL run-time system but does not run in an enterprise server region, when providing your own setup program for it, first you need to decide how your end users will install the 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 the COBOL run-time system in this case 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 licensing files for the COBOL run-time system (Enterprise Test Server).

    You need to create an installation procedure that:

    1. Installs the Enterprise Test 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 Test 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 Test 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 COBOL run-time system (Enterprise Test 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 Test 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 Test Server (or the selected run-time files). Your installation procedure also needs to set up licensing.

Parent topic: Deploying Native Applications
Related information
Introduction to the Enterprise Test Server Deployment Toolkit


To set up an application with a shared Enterprise Test Server

Note: The following applies to native COBOL only.
  1. Install Enterprise Test Server.
  2. Install your application executable files in a separate directory from Enterprise Test 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 Test 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 Test Server, using the following command:

    path = app-server-dir;%PATH%

    where r:\app-server-dir is the directory where Enterprise Test 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 Applications


To set up an application with its own Enterprise Test Server

Note: The following applies to native COBOL only.
  1. Install Enterprise Test Server.
  2. Install your application executable files in the same directory as Enterprise Test Server, or if installing the application executable files in a different directory, ensure the Enterprise Test 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 Applications


To run a native COBOL application from a network server

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

The following instructions are based on 64-bit Windows environments where:

  • any 32-bit software is installed in C:\Program Files (x86).
  • Windows stores the 32-bit system files in C:\Windows\SysWOW64.
  • Windows stores the 64-bit system files in C:\Windows\System32.

In 32-bit Windows environments, these locations are as follows:

  • any software is installed in C:\Program Files.
  • Windows stores the system files in C:\Windows\System32.

Your native COBOL program must be compiled in Enterprise Developer with the dynamic link setting enabled. You do this as follows:

In Visual Studio:

  1. In Visual Studio, load the project for your application.
  2. Click Project > MyProject Properties.
  3. Click the COBOL Link tab in the properties and then click Dynamic.
  4. Save your changes and rebuild the solution.

In Eclipse:

  1. In Eclipse, open the project for your application.
  2. Click Project > Properties.
  3. Click Micro Focus > Build Configurations > Link.
  4. Click Dynamic and then click OK.
  5. Ensure your project recompiles.

To enable a COBOL application to be launched from the client machine, you need to configure the environment at both the server and the client sides as follows:

Server Side

The following instructions show how to install the entire Enterprise Test Server and configure it so that your application uses its run-time system modules.

Important: You must remove any individual copies of run-time system modules (for example, cblrtsm.dll) that might have been copied into your application’s working directory. This is to avoid issues with running the application such as "245 no valid licenses found" as the run-time system is not loading from the expected location, or where the copied run-time modules are from other versions of the product versions. Removing such modules ensures that any run-time system modules are only loaded from the Enterprise Test Server instance which you have installed following the instructions in this topic.

Perform the following steps on the server:

  1. Ensure Enterprise Test Server is installed.
  2. Start Micro Focus License Administration.

    See To start Micro Focus License Administration for details.

  3. Install the license:
    • Click Options > Advanced Configuration.
    • Click Change on the row for License server field, specify the IP address or the name of the server, and click Save.
    • Close both the Advanced Configuration and the Micro Focus Licensing System Administration dialog boxes.
  4. Copy the following files to the %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin folder:
    • C:\Program Files (x86)\Micro Focus\Licensing\mfcesd.exe
    • C:\Program Files (x86)\Micro Focus\Licensing\mfcesdchk.exe
    • C:\ProgramData\Micro Focus\ces.ini
      Note: By default, the C:\ProgramData folder is hidden. See the Windows help for information about how to make it visible.
    • Create a network shared folder, such as MicroFocusSrv from %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server and only give it read-only access for users.
    • If your COBOL application is deployed on the server:
      1. Use a text editor to create a run-time launch file, progname.exe.mfcfg, where progname is the same name as the name of the executable, progname.exe.
        Tip: If there are multiple .exe files, you can instead create one mfdefault.exe.mfcfg file, to be used for all .exe files. When running .int and .gnt files with run.exe, we recommend you do create mfdefault.exe.mfcfg.
      2. Include the following two lines in the launch file:
        SET SERVERPATH=\\ServerName\MicroFocusSrv
SET CESDYNAMIC=ces.ini

        where:

        • ServerName is the server's name or IP address
      3. Add the run-time launch configuration file in the same folder as the application's .exe file.

Client Side

Perform the following steps on the client machine:

  1. Add the bin subfolder within the Enterprise Test Server shared folder you created on the server, MicroFocusSrv, and the application folder to the PATH environment variable as follows:
    • For COBOL applications compiled as 64-bit:
      PATH=\\ServerName\MicroFocusSrv\bin64;\\ServerName\MicroFocusSrv\bin;<AppFolder>;%PATH%
    • For COBOL applications compiled as 32-bit:
      PATH=\\ServerName\MicroFocusSrv\bin;<AppFolder>;%PATH%

    where:

    • ServerName is the server's name or IP address
    • <AppFolder> is the application folder
  2. If your COBOL application is deployed on the client machine:
    1. Use a text editor to create a run-time launch file, progname.exe.mfcfg, where progname is the same name as the name of the executable, progname.exe.
      Tip: If there are multiple .exe files, you can instead create one mfdefault.exe.mfcfg file, to be used for all .exe files. When running .int and .gnt files with run.exe, we recommend you do create mfdefault.exe.mfcfg.
    2. Include the following two lines in the launch file:
      SET SERVERPATH=\\ServerName\MicroFocusSrv
SET CESDYNAMIC=ces.ini

      where:

      • ServerName is the server's name or IP address
    3. Add the run-time launch configuration file in the same folder as the application's .exe file.
  3. Run the application.
Parent topic: Deploying Native Applications
Related tasks
To start Micro Focus License Administration


Deploying COBOL Applications to the .NET Environment

.NET COBOL applications require Enterprise Test Server to enable them to run. Enterprise Test Server provides support for .NET 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 Test Server. This installs both the native COBOL and the .NET COBOL support. The installation process adds the .NET COBOL code support files to the Global Assembly Cache (GAC), and installs some files into the Enterprise Test Server directory.

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

  • Deploying to the .NET Environment
  • 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 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 Test Server locally on each workstation.
Parent topic: Deploying Applications
Related concepts
Overview of Deploying Your Applications
Deploying the Micro Focus Run-Time System
Deploying ES.NET Mainframe Subsystem Applications


Deploying to the .NET Environment

Note: The following applies to .NET COBOL only.

There are broadly two ways of deploying COBOL Windows-based applications to the .NET environment. You can either use a traditional setup program or you can copy the files manually. In both cases you need the prerequisite software such as Enterprise Test Server and the .NET Framework installed on the target machine.

You package the application in a setup.exe file and distribute that file to users, who run it to install the application. To package the application you can use tools such as the WiX Toolset (either as a standalone application or an add-in for Visual Studio) or Microsoft's InstallShield Limited Edition. Refer to respective product's help for more details.

If you are deploying your COBOL application without a setup program, 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


To deploy a Windows application to the .NET environment

You can either use a setup file to deliver your application to customers or copy the application files directly.

When creating a setup file, you can use tool such as the WiX Toolset (either as a standalone application or an add-in for Visual Studio) or Microsoft's InstallShield Limited Edition to package. For example, here's how you would use InstallShield Limited Edition:

  1. Install Microsoft's Visual Studio and InstallShield Limited Edition. See the MSDN for more details.
  2. In Visual Studio, click File > New > Project.
  3. In the Create a new project dialog box, type setup in the search field, select a setup project and click Next.
  4. Uncheck Place solution and project in the same directory and click Create.

    This creates a solution and a project from the available templates in the specified location and opens them in Solution Explorer in Visual Studio.

  5. Select the InstallShield project type and click Create to create the project.
  6. Follow the instructions in the project in order to create the project. See the Visual Studio Help for details.

If you are deploying your application without a setup file:

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


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 COBOL Applications to the .NET Environment


To run a .NET COBOL application from a network server

You can deploy a .NET 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 Test Server locally on each workstation.

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

  • Enterprise Test Server is installed and licensed on the server.
  • The workstations that are accessing the server on the network have the necessary permissions. The workstations must have the Microsoft .NET Framework 4.5.2 or later and the Microsoft Visual C++ 2017 Redistributable Runtime installed.

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 Test Server on the server include:
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin contains the native run-time files for 32-bit machines
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin64 contains the native run-time files for 64-bit machines
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\redist\v4.0 contains the .NET Framework version 4.0 of run-time assemblies
  • %ProgramFiles(x86)%\Micro Focus\Enterprise Test 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 Test Server installation location into your application folder, or copy your application files into the appropriate redist\* folder in the Enterprise Test 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 Test 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.

    Note: Support for .NET Framework versions 3.0 and 3.5, and for the CLR v2 has been deprecated. The option 2 of the ILCLR directive has also been deprecated.

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


Deploying COBOL Applications to .NET

  • Introduction to Deploying COBOL Applications to .NET
  • To deploy a COBOL application to .NET
Parent topic: Deploying Applications


Introduction to Deploying COBOL Applications to .NET

.NET is an open-source development platform that supports multiple operating systems. As such, a COBOL application that has been published for use with .NET can be deployed to any operating system that .NET supports.

The information in this section of the documentation describes how to deploy and run a COBOL application that has already been developed and published to target .NET.

Note: To develop and publish a COBOL application for .NET you must use Enterprise Developer with Visual Studio 2022 version 17.0.4 or later.
Parent topic: Deploying COBOL Applications to .NET
Related reference
Microsoft: .NET Documentation
Related information
To deploy a COBOL application to .NET


To deploy a COBOL application to .NET

You can use a number of methods to deploy the files that were produced when an application was published. Examples of the methods you could use include:

  • Running one or more operating system commands to copy the required files and folders to the target machine.
  • Using a software installation package.
  • Zipping the published files into an archive, copying the archive to the target machine then extracting its contents.

Once the published files for an application have been deployed, how your users run the application varies depending on the type of deployment:

  • For a framework-dependent deployment the command to use is:
    dotnet application-name.dll
  • For a self-contained deployment on Linux the command is:
    application-name
    For a self-contained deployment on Windows the command is:
    application-name.exe
Parent topic: Deploying COBOL Applications to .NET
Related information
Introduction to Deploying COBOL Applications to .NET


Deploying IMS Applications

An IMS application developed in Enterprise Developer can be deployed to Enterprise Test Server and run there in production.

To become familiar with the process of creating and configuring an enterprise server instance to support your IMS application, we recommend that you follow the procedures presented in either of the following sets of topics available in your Enterprise Developer documentation:

IMS: Tutorial
The IMS tutorial takes you through:
  • Creating an Enterprise Developer project
  • Adding IMS application and database files to the project
  • Building the application from the Enterprise Developer IDE
  • Using the Enterprise Test Server IMS template from the Enterprise Developer IDE to create and configure an enterprise server instance to run the application
  • Running the application on the enterprise server
IMS Installation Verification
The IMS Installation Verification topics take you through:
  • Preparing and compiling an IMS application using command-line tools
  • Using Enterprise Test Server to create and configure an enterprise server instance to run the application
  • Verifying CICS installation
  • Running the application on the enterprise server
  • Creating and Configuring an Enterprise Server Region for IMS
    Describes the creation and configuration of an enterprise server region that runs an IMS application.
  • IMS Database Administration
    BTS Trace, IMS Database Locking and IMS Database Recovery.
  • WebSphere MQ Support
    Describes Enterprise Test Server support for communicating with WebSphere MQ to receive and process requests, and to return output back to WebSphere MQ.
Parent topic: Deploying Applications


Creating and Configuring an Enterprise Server Region for IMS

To run IMS applications, you must create an enterprise server region that is MSS-enabled and appropriately configured to run an IMS application. You can do this from Enterprise Server Administration.

Creating and configuring an enterprise server region from Enterprise Server Administration

When you create an enterprise server region 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 region, specify:
  • A name for the enterprise server region
  • 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 Test 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)
  • Configuring IMS Multiple Sign-on Support
    Describes support for multiple sign-ons by a single user across multiple LUs.
  • IMS-enabled Enterprise Server Administration using ESMAC (deprecated)
  • Defining IMS Resources
  • Defining IMS Transactions
  • Configuring the IMS Message Queue
  • Configuring IMS Printers
  • Calculating Shared Memory Area Requirements
Parent topic: Deploying IMS Applications
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 MSS-enabled enterprise server for IMS applications from Enterprise Test 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. 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 Region 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 Test 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
Parent topic: Creating and Configuring an Enterprise Server Region 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 Test 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 Region for IMS
Related information
ES_OTMA_TIMEOUT


Configuring IMS Multiple Sign-on Support

Multiple sign-on support is implemented using the ES_IMS_SINGLE and ES_IMS_LTERM_PREFIX Enterprise Server environment variables.

Parent topic: Creating and Configuring an Enterprise Server Region for IMS


IMS-enabled Enterprise Server Administration using ESMAC (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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 Region for IMS
Related concepts
Defining IMS Resources
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)
To create a resource group
To modify a resource


Defining IMS Resources

Enterprise Test 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 Region for IMS
Related concepts
IMS-enabled Enterprise Server Administration using ESMAC (deprecated)
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)
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 Test 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 Test 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 Region 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 Region 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. Use the following environment variable:

Initializes performance settings for the IMS message queue, and enables dynamic performance tuning. 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.
Syntax
ES_TMC_AGGREGATE={[,N|,D]|nnn,Y}
Parameters
,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 ESCWA. 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.
Notes: To avoid unpredictable results when using this setting, Micro Focus recommends that you also set the static options as follows on ESCWA. Select enterprise server region you require, click IMS > Configuration and then click the TM tab:
  • Set the Cold start list to Everything.
  • Check Persist.

See Server Instance Properties: MSS IMS TM General for more information.

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.

Typically, when the message queue resides on a higher performance I/O subsystem such as one using SSDs, a smaller value, for example 1 or 2, produces the best results. A value of 10 or higher seldom improves performance.

Default
ES_TMC_AGGREGATE=,N

Dynamic changes using ESMAC

You can adjust and apply IMS message queue performance settings dynamically from the System Overview and Control section on the ESCWA IMS Control page. In ESCWA, select the enterprise server region you require. Click IMS > Control and then click the TM tab. 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
Server Instance Properties: MSS IMS TM General
IMS Control


Configuring IMS Printers

Enterprise Test 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 Test Server. Group IMSGRP contains resource definitions that are specific to Enterprise Test 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 Test 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 Test 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 Test Server security system as a user ID. The printer operates under Enterprise Test Server with the security authorization assigned to this user ID.
  • When attached to Enterprise Test Server, this client name appears as the printer's Net Name on the Enterprise Test Server ESMAC Clients page.
  • If this client name/Net Name is not defined to Enterprise Test Server with a specific TERM definition, it is assigned the characteristics of the Enterprise Test 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 Test Server definitions are used if they match the names specified in the TN3270 client.
Parent topic: Creating and Configuring an Enterprise Server Region 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 (deprecated)


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 Region 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: Deploying IMS Applications
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
JESLOG | Include trace output in the job log
STATS | Include call statistics
TIMES | Include call timings for performance measurement
CONSOLE | Include trace output in the Enterprise Server console and in the job logs
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
STAYOPEN | When used with SSTM, BTS trace will keep trace output file open between transactions for efficiency.

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 Utility (IMSDBU)
Accessible from JCL and the command line. 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
Related information
ES_IMS_LOCALDLI (deprecated)


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 (deprecated)
Parent topic: IMS Database Locking
Related information
ES_IMS_IRLM


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)


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

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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


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 Test 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 Test 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 Test 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 Test 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 Test 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. When a database has a secondary index, you must also have a backup of every secondary index file. 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 Test Server. Once enabled, Enterprise Test 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 Test 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, the most recent database updates performed just before a hardware or a system failure, or database updates performed up until a specified point in time.

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'
  • Optionally, to specify a point in time at which to recover a database, add the PITR parameter. For example:
    //RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
//PITR=17123123595959

    For details on using the PITR parameter, see the Recover function topic in your Enterprise Developer documentation.

  • 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
Related concepts
TLOG Files


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_COMMIT_FLUSH
  • ES_IMS_DB_TLOG_WRITETHRU
  • ES_IMS_TLOG_COMPRESS
  • ES_IMS_TLOG_MAXSIZE
  • ES_IMS_TLOG_PATH
  • ES_IMS_TLOG_THRESHOLD

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 Test Server generates and renames TLOG files using this naming convention:

serverName-YYMMDDhhmmssmm.TLOG

Where serverName is the name of the server on which the database is stored, and YYMMDDhhmmssmm represents two digits for each: year, month, day, hour, minute, second, and millisecond.

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

TLOG File Contents

You can view the contents of a TLOG file using the cobfhtlog utility as follows:

  1. Start an Enterprise Server command prompt. If you need instructions, see To start an Enterprise Server command prompt.
  2. Change to the directory specified as your ES_IMS_TLOG_PATH environment variable.
  3. Enter:
    cobfhtlog filename
    Where filename is the name of a TLOG file.

The contents of the file are written to the screen. The following example represents a snippet of the contents of a TLOG file:

rollfwd data
    data len: 00019
    data    : 100000006 00000006
    …..
commit prep
     session: 0000000002
    sequence no: 00000000000000000006
    date time: 17081415252517
     …..
commit begun
     session: 0000000002
 sequence no: 00000000000000000007
     date time: 17081415252523
      …..
commit comp
     session: 0000000002
 sequence no: 00000000000000000008
     date time: 17081415252523
Note: In the above example, the date time value for commit comp represents a point in time you can use with the Recovery Utility and Recovery function PITR parameter. See Recovery function and Recovery Utility for details.
Parent topic: IMS Database Recovery
Related concepts
Automatic Backward Recovery Process
Recovery Utility


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 Test 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 Test 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 Test 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 Test 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 Test Server warm/cold start

The following applies to warm and cold starts of the Enterprise Test 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 Test Server:

  • Basic and Symbolic Checkpoint Calls
  • IMSLGR Files
  • Avoiding Dataset Contention
Parent topic: IMS Database Administration


Basic and Symbolic Checkpoint Calls

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

When restarting a BMP using a symbolic checkpoint, the log file is searched to find a match not only on the provided checkpoint ID but also on the name of the application program being restarted. This is consistent with mainframe behavior; however, when restarting a program with a checkpoint ID of LAST, the mainframe enforces on JOB name, PSB name, and program name, Enterprise Server IMS only enforces a match on program name.

Notes:
  • An input GSAM file position RBA is saved on a checkpoint call and restored on a restart call.
  • An XRST call does not reposition any databases, nor does it restore any PCB information.
  • 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 Test Server supports both the MQ-IMS Bridge and IMS trigger monitoring.

Prerequisites

In addition to Enterprise Test Server, you must have WebSphere MQ client or server installed on your PC. To see supported WebSphere MQ versions, see the Middleware section in Supported Operating Systems and Third-party Software.

  • MQ-IMS Bridge
    Describes the MQ-IMS Bridge feature used to communicate with WebSphere MQ and process requests on Enterprise Test Server.
  • IMS Trigger Monitoring
    Describes Enterprise Test Server support for IMS Trigger Monitoring.
Parent topic: Deploying IMS Applications
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 Test Server and WebSphere MQ are established by enabling MQ listener support and defining and enabling one or more MQ listeners in Enterprise Test Server.

An MQ listener is an Enterprise Test 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 Test Server dynamically creates a listener for each associated input queue that receives inbound messages.

An MQ writer is an Enterprise Test Server component that sends messages back to a WebSphere MQ output queue. You do not define MQ writers. Enterprise Test 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 Test Server to process MQ messages.
  • Enterprise Test Server Configuration
    Describes the Enterprise Test Server configuration requirements necessary to enable communication with WebSphere MQ.
  • MQ Listeners and Writers in ESMAC (deprecated)
    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 Test 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 Test 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 Test Server to listen to an initiation queue rather than an input queue, Enterprise Test 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 Test 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 Test Server Configuration

To use Enterprise Test 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 (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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 Test 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
Related information
ES_MQ_LIB


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


Deploying Stored Procedures

You can deploy an application that runs DB2 Stored Procedures

If your application executes COBOL DB2 Stored Procedures, their execution is done on the same machine as your database instance. In Enterprise Server version 8.0 and earlier, when the database server machine was remote to the installation of Enterprise Server, successful execution of stored procedures required that you install the full Enterprise Server product on the database server machine. Starting with version 9.0, you can install the Enterprise Server for Stored Procedures product on your remote server instead of the full Enterprise Server product. ESSP is a scaled-back version of Enterprise Server consisting of the Micro Focus run-time only components required to execute stored procedures on the database server machine. For details about installing Enterprise Server for Stored Procedures, see Micro Focus Enterprise Server for Stored Procedures 9.0 Release Notes.

Parent topic: Deploying Applications


Deploying ES.NET Mainframe Subsystem Applications

Enterprise Server for .NET is the execution environment for emulated mainframe CICS and JCL applications running as .NET code. You can use it on a single system, across multiple machines, or in the Microsoft Azure cloud infrastructure.

You use Enterprise Developer for Visual Studio to create a project for the application and then you deploy the artifacts to Enterprise Server for .NET.

Enterprise Server for .NET must be installed and licensed on the machine on which you are going to deploy your applications or in Microsoft Azure.

You can deploy files to a local or a network file system. The locations of these and of any database hosted files are configured in the region's start-up file.

You deploy the artifacts to either a region, a cross-region or to a datastore database. Micro Focus recommends the cross-region or a datastore database scenarios as this does not affect region start-up performance.

  • To deploy programs and CICS MOD files to a cross-region database, use the following MMC UI view - Shared Database Deployment Locations > Application Programs /Maps > Cross-region.
  • To deploy data files in addition to programs and CICS MOD files to a datastore database, use the following MMC UI view - Shared Database Deployment Locations > Application Data Files.
  • Alternatively, the seedeploy command-line utility is available for deploying artifacts to both the cross-region and datastore databases.

Deploying to Azure:

You can deploy your ES.NET Mainframe Subsystem Applications to Azure. First you need to deploy Enterprise Server for .NET. Then, you can use the same tooling (seedeploy or MMC UI) to deploy the application's files to either a database location or to the Azure Cloud Drives.

For more details, see the documentation for Enterprise Server for .NET available from the Enterprise Developer documentation section of the Website.

Parent topic: Deploying Applications
Related concepts
Overview of Deploying Your Applications
Deploying the Micro Focus Run-Time System
Related information
Deploying COBOL Applications to the .NET Environment


Code set translation

For applications that are required to translate between ASCII and EBCDIC characters, there is inbuilt support for a number of languages. Code set support is further extended by the ability to utilize translation tables distributed by IBM; these tables provide access to many more languages and character sets.

The environment variable MFCODESET determines the code sets to be translated. By setting this variable to the appropriate country code or CCSID(s) as detailed in Supported country codes, the required translations are made for certain functionality within the product. For example, any program compiled under the CHARSET"EBCDIC" directive uses the value of this variable; programs that call the _CODESET library routine also rely on this variable.

If the code set you require is not part of the built-in support (that is, not listed in Supported country codes), you can install one of the code set tables distributed by IBM; for more information, see Installing CCSID translation tables. Once installed, the support explained above is extended to the newly installed code sets.

If an application needs to convert from one CCSID to another, you can perform that directly using the CBL_CCSID_CONVERT library routine, which will convert from one installed CCSID table to another.

If the available code sets still do not match your needs, you can create custom translations between EBCDIC and ASCII using the Codecomp utility.

Note: Certain deployed applications do not require a full Enterprise Test Server product to be available (for example, .NET COBOL applications, and native self-contained applications); if these rely on the inbuilt DBCS translation support (that is, ASCII/EBCDIC translations for code sets 81, 82, 86, 886, and 941), they must be deployed with the appropriate code set mapping files, and then you must use the MFCODESET_DBCSDIR environment variable to locate those files at run time. The required mapping files are located in the etc/codeset sub-directory of the Enterprise Developer installation directory. (You only need to deploy the .E2A and .A2E files appropriate to the code set(s) you require.)
  • Supported country codes
    Enterprise Developer has built-in country support for EBCDIC <-> ASCII character set translations.
  • To install a supported country code for deployed applications
    Some deployed applications require additional steps in order to translate DBCS code sets.
  • Installing CCSID translation tables
    Enterprise Developer has built-in support for a number of code sets, but if you require a different code set, you can install a number of additional CCSID translation tables, distributed by IBM, to increase the number of supported code sets.
  • The code set translation environment variable
    Set the MFCODESET variable in your environment to control the code sets being translated.
  • Enabling code set support for Enterprise Server
    Use the following instructions to configure your EBCDIC Enterprise Server projects to use one of the supported code sets.
Parent topic: Deploying Applications
Related information
MFCODESET
MFCODESET_DBCSDIR


Supported country codes

Enterprise Developer has built-in country support for EBCDIC <-> ASCII character set translations.

When you use the _CODESET library routine to convert a string between EBCDIC and ASCII, the MFCODESET environment variable manages and selects the appropriate EBCDIC <-> ASCII translation for your applications, based on its specified value or default behavior.

The table below shows the possible MFCODESET values (also known as country codes), and their corresponding EBCDIC Coded Character Set Identifiers (CCSIDs) and languages.

Originally, this table reflected the country codes established by the International Telecommunication Union (ITU), but it has since been expanded to include Chinese, Japanese, and Korean (CJK) extensions.

Support is provided for the following character set translations:

  • EBCDIC <-> ASCII
  • EBCDIC <-> ASCII with Euro support for single-byte character sets

For Euro enablement (€), prefix your MFCODESET value with "E".

Country Code (MFCODESET) | EBCDIC CCSIDs | Language
AUTOMATIC AUTO |  | Operating system default - sets country code based on CBL_GET_OS_INFO
DEFAULT |  | Set to 0437 (US English) on Windows, or 0081 (Japanese Katakana Extended) on Japanese Windows.
0031 | 37, 1140 | Dutch
0033 | 297, 1147 | French
0034 | 284, 1145 | Spanish
0039 | 280, 1144 | Italian
0043 | 273, 1141 | German (Austrian)
0044 | 285, 1146 | UK English
0045 | 277, 1142 | Danish
0046 | 278, 1143 | Swedish
0047 | 277, 1142 | Norwegian
0049 | 273, 1141 | German
0066 | 838 | Thai Extended
0081† | 930 (290, 300) | * Japanese Katakana Extended
0082 | 933 (833, 834) | *Korean
0086 | 13676 (836, 837) | *Simplified Chinese
0351 | 37, 1140 | Portuguese
0358 | 278, 1143 | Finnish
0420 | 420 | Arabic See Arabic Support Considerations below.
0437 | 37, 1140 | US English
0500 | 500, 1148 | International (Latin 1)
0886 | 937 (37, 835) | *Traditional Chinese
0930 † | 930 (290, 300) | *Japanese Katakana Extended
0939 † | 939 (1027, 300) | *Japanese Latin Extended
9122 † | 9122 (290, 300) | *Japanese Katakana

Character sets marked with an asterisk (*) are capable of mixed single-byte and double-byte character translation. EBCDIC CCSIDs in these rows indicate the mixed-byte CCSID first, followed by the single-byte, then double-byte Code Page Global Identifiers (CPGIDs) in parenthesis.

MFCODESETs marked with a dagger (†) are based on the Japanese International Standard (JIS) X 0208 1978 revision. Additional translation tables are available based on the Japanese International Standard (JIS) X 0208 1990 revision (and are taken from IBM's translation tables CCSID 300 - 941); to use these tables instead of the default ones, set the MFCODESET_DBCS environment variable to 941.

Other EBCDIC CCSIDs in parentheses reflect a 'non-Euro, Euro' pair for appropriate country codes.

If you set an invalid country code, the DEFAULT country code setting is used.

For database applications using a DBMS server on Windows, use the table above.

  • Arabic support considerations
Parent topic: Code set translation
Parent topic: HCO for DB2 LUW
Related concepts
Installing CCSID translation tables
Related tasks
To install a supported country code for deployed applications
Related information
MFCODESET


Arabic support considerations

Terminal Emulation

Your TN3270 terminal emulator must be able to support the Arabic EBCDIC 420 code page in order to connect to your enterprise server region that has Arabic support enabled. Micro Focus has tested this support with IBM's Personal Communications emulator (PCOMM); visit the following external link to the IBM documentation for details on how to configure a PCOMM session for Arabic input - Configuring Sessions.

Ligature special cases

Support of Arabic code sets can require special consideration when the 'Lam Alef ' character combinations are used, when the terminal emulator is set in its Arabic right-to-left input mode.

Entry of those two characters results in a conversion to a ligature represented by a one-byte EBCDIC code point followed by an EBCDIC space (0x40). When using PCOMM, on entering this combination, the cursor should be automatically positioned one space to the left in order to account for the additional space. It is possible to move the cursor back to the right, to remove this space, but removing it can cause problems when converting to ASCII. If the space is removed, the translation results in the 0x1A ASCII substitution character being used. (However, when converting back to EBCDIC in this situation, the correct ligature code and EBCDIC space is restored.)

If your emulator does not add the additional space automatically, you must ensure it is added manually; otherwise, as above, you will encounter problems with translation.

The following table describes those Lam Alef character combinations that must retain the additional space for correct translation to occur:
Visual EBCDIC 420 | Logical ASCII 1256 | Description
B8 40 | E1 C7 | Lam isolated form + Alef isolated form
B2 40 | E1 C2 | Lam isolated form + Alef with Madda above isolated form
B4 40 | E1 C3 | Lam isolated form + Alef with Hanza above isolated form
B9 40 | E1 C7 | Lam isolated form + Alef Final form
B3 40 | E1 C2 | Lam isolated form + Alef with Madda Final form
B5 40 | E1 C3 | Lam isolated form + Alef with Hanza Final form
Parent topic: Supported country codes


To install a supported country code for deployed applications

Most deployment applications will perform ASCII <-> EBCDIC translations of the supported country codes without further interaction; however, translation of the DBCS supported code sets (namely, MFCODESETs 81, 82, 86, 886, and 941) for applications that do not require a full Enterprise Server product to be available (for example, .NET COBOL applications, and native self-contained applications), you are required to deploy the appropriate mapping files with the application, and then use an environment variable to locate them at run time.
  1. Deploy the appropriate .E2A and .A2E mapping files along with the application. The required files can be found in the etc/codeset sub-directory of a full development or deployment product installation directory.
  2. Set the MFCODESET_DBCSDIR environment variable to the location of these files.
  3. Set the MFCODESET environment variable to the required code set for translation; see The code set translation environment variable for details.
Parent topic: Code set translation
Related tasks
The code set translation environment variable
Related information
Supported country codes
MFCODESET_DBCSDIR


Installing CCSID translation tables

Enterprise Developer has built-in support for a number of code sets, as listed in Supported country codes, but if you require a different code set, you can install a number of additional CCSID translation tables, distributed by IBM, to increase the number of supported code sets.

  • To install a CCSID translation table
  • To install a CCSID translation table for deployed applications
Parent topic: Code set translation
Related information
Supported country codes
TX_MQ_CONVERT


To install a CCSID translation table

Use these instructions when installing a translation table into a development environment. For details on installing a translation table for a deployed application, see To install a CCSID translation table for deployed applications.

Prerequisites:
  • During Enterprise Developer installation, the IBM-37, IBM-437, and 002501B5 tables are installed in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ccsid. If you require other translation tables, download the full package of IBM CCSID translation tables file from cdctables.zip and extract it to the ccsid directory.
  • To complete this task, you must have administrator privileges to the Enterprise Developer installation directory.
  1. If you require a table other than one of the pre-installed ones:
    1. Use the tabindex.txt file (located in the intro.zip file of the extracted package) to identify the package number and filename for each CCSID translation table you need to install.
    2. Within the ccsid directory, create a sub-directory for each table you want to install, using the name of the CCSID translation table filename, specified in the tabindex.txt file, as the directory name.
    3. For each CCSID that you want to install, open its corresponding Packagen.zip file (as specified in tabindex.txt) and extract the files from the appropriate CCSID .zip file to the corresponding directory you created in the previous step.
  2. Set the MFCODESET environment variable to the required code set for translation; see The code set translation environment variable for details.

Example

To install a CCSID translation table to convert Spanish to USA English, create a sub-directory under ccsid named 011C01B5, and then extract the contents of package4.zip\011C01B5.zip to the 011C01B5 sub-directory.

Parent topic: Installing CCSID translation tables
Related tasks
To install a CCSID translation table for deployed applications
The code set translation environment variable


To install a CCSID translation table for deployed applications

Use these instructions when installing a translation table for a deployed application.

  1. In a Web browser, download the IBM CCSID translation tables file from cdctables.zip and extract it to a location within the user application.
    Tip: The IBM-37, IBM-437, and 002501B5 tables are pre-installed in the \etc\ccsid sub-directory of the product installation directory; if you require any of these tables, you can copy them from the stated location to your user application, without the need to download the .zip file.
  2. Set the COBCCSIDDIR environment variable to the location of this directory.

    This directory will serve as the translation table base directory.

  3. Use the tabindex.txt file (located in the intro.zip file) to identify the package number and filename for each CCSID translation table you need to install.
  4. Within the translation table base directory, create a sub-directory for each table you want to install, using the name of the CCSID translation table filename, specified in the tabindex.txt file, as the directory name.
  5. For each CCSID that you want to install, open its corresponding Packagen.zip file (as specified in tabindex.txt) and extract the files from the appropriate CCSID .zip file to the corresponding directory you created in the previous step.
  6. Set the MFCODESET environment variable to the required code set for translation; see The code set translation environment variable for details.

Example

To install a CCSID translation table to convert Spanish to USA English, create a sub-directory under the translation table base directory, named 011C01B5, and then extract the contents of package4.zip\011C01B5.zip to the 011C01B5 sub-directory.

Parent topic: Installing CCSID translation tables
Related tasks
To install a CCSID translation table
The code set translation environment variable


The code set translation environment variable

Set the MFCODESET variable in your environment to control the code sets being translated.

To use your product's inbuilt translation module for EBCDIC applications, you must use the MFCODESET environment variable to specify the EBCDIC code set you require.

This variable can be set on the command line or within the IDE, and must take the following form:

  • To translate between the ASCII character set and the EBCDIC character set for a specific country code, at the command prompt, enter:
    set MFCODESET=nnnn

    where nnnn is either a supported 4-digit country code or the code set number as detailed in Supported country codes, or the code set number of a customized translation module.

    Note: If you set an invalid country code, the DEFAULT country code setting is used.
  • To translate between a specified ASCII character set and a specified EBCDIC character set, at the command prompt, enter:
    set MFCODESET=xxxxyyyy

    where xxxx is a 4-character hexadecimal string representing the EBCDIC CCSID, and yyyy is a 4-character hexadecimal string representing the ASCII CCSID. If the specified CCSID translation table is not currently installed, refer to To install a CCSID translation table.

Example:

To run a program under the CHARSET"EBCDIC" Compiler directive, and have it translate its output between your current ASCII character set and UK English EBCDIC:
set MFCODESET=0285
To run a program under the CHARSET"EBCDIC" Compiler directive, and have it translate its output between the MS-WIN LATIN-1 code set (CCSID 1252) and the COM EUROPE EBCDIC code set (CCSID 37):
set MFCODESET=002504E4
Parent topic: Code set translation
Related information
Installing CCSID translation tables


Enabling code set support for Enterprise Server

The table within Supported country codes shows the in-built support for various EBCDIC code sets. Use the following instructions to configure your IDE to build your EBCDIC projects with the required code set support, and to configure your enterprise server regions to support the code set translations.

  1. Configure the enterprise server region to use a particular EBCDIC code set:
    1. Click Edit to the left of the appropriate server.
    2. Select Server > Properties > General.
    3. In the Configuration Information section, ensure there is a heading entitled [ES Environment], and then within it, type MFCODESET=xxxx[yyyy]. For xxxx[yyyy], refer to The code set translation environment variable.
    4. Click OK.
  2. Start or restart the server.

    When the server is running, you can connect your terminals emulator to the server, and as long as it supports the corresponding EBCDIC CSSID, you can run the application with your chosen code set support.

Parent topic: Code set translation
Related tasks
The code set translation environment variable


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.
  • 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 Test Server 10.0
Related information
Enterprise Server (Known Issues)


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
  • Enterprise Server Common Web Administration
  • Planning your Configuration
  • Configuring the Server Instance Environment
  • Scale-Out Performance and Availability Clusters
  • SSL Support for CICS Web Interface Servers
  • User Certificate Registration for CICS Web Interface Servers and DCAS
  • IPv6 Support
  • 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
  • Remote File Access (RFA)
  • User Exits for Request Handlers
  • Enterprise Server LOCKDB
  • Enterprise Server Clustering (deprecated)
  • Legacy Enterprise Server Administration User Interface
    Micro Focus recommends you adopt the Enterprise Server Common Web Administration (ESCWA) interface. ESCWA is a modern and feature-rich interface that combines functionality from Enterprise Server Administration, ESMAC, and the ESF LDAP Security Administration interfaces.
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
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. An enterprise server instance provides 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

A default Enterprise Server installation consists of a number of interacting components. These include Enterprise Server Common Web Administration, a Micro Focus Directory Server, and a number of example 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 Enterprise Server Common Web Administration (ESCWA) operating on the Micro Focus Directory Server. From this user interface, you can configure installation-wide settings. From the ESCWA user interface, you can also access and administer each enterprise server instance potentially operating on distributed hardware and in a scale-out configuration.

Diagram of Enterprise Server Architecture - Communicating detween ESCWA, multiple Directory Servers (MFDS) and enterprise server instances.
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
Diagram of 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:

  • Servers
  • Services
  • Request handlers
  • Implementation packages
  • Communications processes
  • Listeners
  • JES initiators
  • JES printers
  • IMS Message Processing Regions (MPR)
  • MQ Listeners
  • XA resources
  • External Security Managers (ESM)

When you deploy a COBOL application as a service using the Interface Mapping Toolkit, much of the operating information maintained on the Micro Focus Directory Server is created automatically. An administrator can edit this information to respond to changing requirements.

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 Communications Interface (CCI), using the Directory Server as a naming server instead of registering with a CCITCP2 process. CCI servers are supported for backward compatibility:

  • Enterprise Server Processes
  • Service Execution Process (SEP)
  • Request Handlers
  • Implementation Packages
  • Communications Processes
  • Listeners
  • JES Initiators
  • JES Printers
  • IMS Message Processing Regions (MPR)
  • MQ Listeners
  • XA Resources
  • External Security Managers (ESM)
Parent topic: Overview and Architecture


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
CASTRC - Region Trace Control (TRC)
CASTRC writes trace to disk when auxiliary tracing is active and generates HSF data. There is one process per region. It is started by CASCD.

Responsibilities:

  • Auxiliary trace hardening - to casauxta.rec and casauxtb.rec
  • Creation of historical statistic information
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: 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.

    The request handler uses the mapping information created by the Interface Mapping Toolkit to map the request parameters into the call interface of the COBOL application.

  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: The Micro Focus Directory Server


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.

Request handlers are provided 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: The Micro Focus Directory Server


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 enables a client request to be mapped onto a COBOL program interface.

Parent topic: The Micro Focus Directory Server


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: The Micro Focus Directory Server


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 Transport Layer Security (TLS) - 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.
    Note: Do not use the http-echo conversation type in production. It is intended only for connection testing. Older versions of the http-echo module are vulnerable to web cross-site scripting (XSS) attacks, which are a serious security exposure.
Parent topic: The Micro Focus Directory Server


JES Initiators

A JES initiator manages jobs from the input queues and enables multiple jobs to run asynchronously without conflicts. You can add and start JES initiators. See JES Configuration and JES Control for more information.

Parent topic: The Micro Focus Directory Server


JES Printers

Print jobs can be sent to local or remote Job Entry Subsystem (JES) printers. JES printers and jobs can be configured, managed, and monitored. See JES Configuration and Directory Server Statistics for more information.

Parent topic: The Micro Focus Directory Server


IMS Message Processing Regions (MPR)

The IMS Message Processing Region (MPR) control applications that process messages that are provided as input to IMS TM, such as input from terminals or programs. You can specify, control, and monitor IMS MPRs. See IMS Configuration and IMS Control for more information.

Parent topic: The Micro Focus Directory Server


MQ Listeners

An MQ Listener is a process that listens for connections to the queue manager. You can specify and edit MQ listeners. See MQ Listeners for more information.

Parent topic: The Micro Focus Directory Server


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: The Micro Focus Directory Server
Related information
Resource Management
Resource Managers


External Security Managers (ESM)

Access to Enterprise Server administrative features, MSS applications, and application resources are controlled by security managers. Sometimes referred to as an External Security Manager (ESM). Through the use of security managers, you can implement controls to verify users and their actions against permissions established in the operating system or in an LDAP repository.

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 Server. See About Security Managers and About Securing an Enterprise Server Installation for more information.

Parent topic: The Micro Focus Directory Server


Enterprise Server Common Web Administration

The Enterprise Server Common Web Administration (ESCWA) tool is a modern and feature-rich interface that enables you to:

  • Configure a custom dashboard to display and monitor servers, their status, and performance.
  • Monitor and control Enterprise Server instances.
  • Administer Directory Servers, across multiple hosts, which provides the ability to stop, start and configure their Enterprise Server instances.
  • Enable administration and monitoring of scale-out enterprise server instances for improved performance of systems under load. See Scale-Out Performance and Availability Clusters for more information.
  • Import and export enterprise server regions in XML, JSON, and legacy formats.
  • Provides an HTTP and JSON-based API to automate Enterprise Server deployment and monitoring.
  • Configure and administer a security manager, defined in an LDAP-compatible security manager such as Microsoft Active Directory, AD LDS or OpenLDAP. You can create, modify and delete users, groups, resource classes, and resource entities. Easily sort and filter users, groups, classes, and resource entities.
  • Administer, monitor, and control Enterprise Server (ES) for .NET regions and listeners.
  • Administer and monitor enterprise server instances running within a Kubernetes cluster.
  • Administer the MFA product on a Mainframe. This feature is in Early Adopter Program (EAP) release status.

Limitations

ESCWA has the following limitations:

  • The security manager does not support nested groups within the interface. If required, you can administer nested groups from the esfadmin command-line utility.
  • ESCWA is not supported on HP-UX.
Note: The CASESM Security Manager was part of the legacy security model used in the Net Express or Server Express 5.0 and earlier products. As part of this, the legacy ESMAC user interface pages had Security Keys as configurable options. In ESCWA, these can only be accessed by the Client Web API and are not available in the ESCWA user interface pages that are equivalent to the corresponding ESMAC pages.
  • Prerequisites
    This topic outlines the requirements when using Enterprise Server Common Web Administration (ESCWA) interface.
  • To Start ESCWA
    This chapter details how you can start and configure ESCWA, including enabling it to operate using Transport Layer Security (TLS).
  • The Enterprise Server Common Web Administration User Interface
  • Dashboard
    The dashboard is your home screen, it is the first view of ESCWA once you have logged in. You can configure your dashboard to display the information that best helps you monitor and administer your servers.
  • Native
    These are the Enterprise Servers and Directory Servers which run directly on the processors of the platform you have installed them on.
  • Mainframe
    This page lists Mainframe Access servers and their key configuration properties.
  • Auditing
    This topic outlines two methods for auditing activity using the Enterprise Server Common Web Administration (ESCWA) interface.
  • Security
    This chapter covers various aspects of security configuration for ESCWA. It includes External Security Facility (ESF), component administration, security manager's properties, restricting access to components, and configuring Transport Layer Security (TLS).
  • ESCWA Client Web API
    Micro Focus has provided the HTTP and JSON Application Programming Interface (API) used by the ESCWA client. This is to enable you to write your own custom scripts to support and automate your organization's specific Enterprise Server administration requirements.
Parent topic: Enterprise Server configuration and administration
Related reference
Configuring External Security Facility (ESF) from the Command Line
Related information
Enterprise Server Common Web Administration


Prerequisites

The Enterprise Server Common Web Administration interface has the following software requirements:

  • A Web browser (with a minimum required version):
    • Firefox (version 126)
    • Google Chrome (version 125)
    • Microsoft Edge (version 125)
    • Opera (version 110)
    Note: Internet Explorer (IE) is not supported.
  • ESCWA only supports MFDS version of 1.25.37 or later.
  • ESCWA is supported on Windows and UNIX platforms.
  • On UNIX platforms, you must ensure that the ESCWA log directory has write permissions. By default, the ESCWA log directory is located at $COBDIR/etc.
  • 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.
Parent topic: Enterprise Server Common Web Administration


To Start ESCWA

This chapter details how you can start and configure ESCWA, including enabling it to operate using Transport Layer Security (TLS).
Note: Enterprise Server Security is enabled by default. See Default Enterprise Server Security Configuration for more information.

On Windows, by default, the Micro Focus Enterprise Server Common Web Administration service is set to automatic startup type. This means that the service will start when the host machine starts.

In addition, ESCWA can only initially be contacted using the loopback address (localhost 127.0.0.1). You can access the application by using the following URL in your Web browser: http://localhost:10086.

Note: On the first occasion you access the Web interface, the following warning message is displayed:
  • The ESCWA server is not TLS-enabled. Communications across the network will not be encrypted. Micro Focus recommends that you enable TLS settings as soon as possible.

To restrict access to ESCWA you need to enable a security manager. See Specifying an External Security Manager for more information.

You can access ESCWA from a Web browser on a remote host by turning off the loopback mode.

Note: Micro Focus recommends that you restrict access and enable TLS before turning off loopback mode.

You can turn off loopback mode using one of the following three methods:

  1. Modify the ESCWA application configuration file:
    1. Edit the commonwebadmin.json file, and change the value of the MfRequestedEndpoint property to tcp:*:10086.

      The application configuration file is located in C:\ProgramData\Micro Focus\Enterprise Developer\ESCWA.

      Note: The commonwebadmin.json file is not overwritten when installing a new version of Enterprise Developer. Previous versions of ESCWA used port 10004, therefore, you might need to modify the configuration file.
  2. Add a parameter to the service before starting it.

    On Windows:

    1. Run services.msc to open the Windows Service Manager.
    2. In the Services list, right-click Micro Focus Enterprise Server Common Web Administration.
    3. Click Properties.

      This opens the Micro Focus Enterprise Server Common Web Administration Properties dialog box.

    4. In the Start parameters field, type --BasicConfig.MfRequestedEndpoint="tcp:*:10086" --write=true.
    5. Click OK.
    6. Click Start.
  3. Modify the requested endpoint from within ESCWA:
    1. In a browser, type the following into the search bar localhost:10086.
    2. Click [image].

      This opens the Enterprise Server Administration Configuration dialog box.

    3. Click Server Settings to expand the available configuration options.
    4. In the Hostname or IP Address field, type *
    5. In the Port field, type 10086
      Note: You must restart the ESCWA service if you modify these fields.
    6. Click Apply.
Note: You can substitute the IP and port values of tcp:*:10086 (protocol:ip_or_domain:port) with the IP or domain and port you require. The --write=true parameter enables configuration changes to be written to the config file.
  • ESCWA Command Line Options
  • Enterprise Server Administration Configuration
  • Configuring TLS for the ESCWA Client
Parent topic: Enterprise Server Common Web Administration
Related reference
Specifying an External Security Manager
Default Enterprise Server Security Configuration


ESCWA Command Line Options

Syntax:

escwa.exe [OPTION]...

Options

Options with arguments can be supplied as 'OPTION=ARG' or 'OPTION ARG':

-c , --config=<file>
Configuration file to use instead of commonwebadmin.json.
-h, --help
Displays the parameter list.
-s, --service
If and only if you are running ESCWA as a service, set this option. Mandatory for running ESCWA as a service.
Note: This option is for Windows only.
-V, --version
Displays the version of ESCWA being used.
-w, --write[=<bool>]
Write configuration changes made in ESCWA to the configuration file.

If neither --config or --<ConfigNode> are set and this is unsupplied, this is implicitly true.

If either --config or --<ConfigNode> are set and this is unsupplied, this is implicitly false. 'TRUE', 'true', 'YES', 'yes' and '1' are all interpreted as true; all other arguments are interpreted as false.

The default value is true.

-u, --vault[=<bool>]
Enable or disable use of the secrets vault. If 'true', the value of BasicConfig.VaultSpecification is used if valid. 'TRUE', 'true', 'YES', 'yes' and '1' are all interpreted as true; all other arguments are interpreted as false.

The default value is true.

-p, --shutdown [<user> [<password>]]
Shut down a running ESCWA instance. If multiple ESCWA instances are running specify which one by the configuration file location. If ESCWA is restricted then a user must be specified with execute permissions on the control resource in the Common Web Administration class. ESCWA cannot be shut down by this command if it is running as a Windows service.
--<ConfigNode>[<.<ConfigNode>>...]=<value>
Override the specified node in the configuration file with the specified value. The configuration file is JSON and the format of the option reflects that structure: it is a period ('.') separated list of nodes in the configuration file, with the first node being one of the root nodes, and each subsequent node being a child of the node preceding it. For example --TraceConfig.TraceEnabled corresponds to the setting TraceEnabled in the root node TraceConfig.

Elements in an array can be accessed using an integer as the node. JSON arrays are 0-indexed. For example --MfdsList.1.MfdsHost corresponds to the setting MfdsHost in the 2nd item of the array MfdsList, which is also a root node.

The final specified node does not need to be a leaf node of the file; entire JSON objects and arrays can be overridden. Elements can be appended to an array using '+' as a child node. For example --MfdsList.+ will append a supplied element to MfdsList.

Arguments can be numbers, strings, boolean, JSON arrays, or JSON objects depending on the specified setting. For boolean, 'TRUE', 'true', 'YES', 'yes' and '1' are all interpreted as true; all other values are interpreted as false. If overriding a JSON object or array, the specified JSON object or array must be correct and complete JSON, structurally identical to the original (arrays may have a differing number of items, including 0. For example --MfdsList=[]), and escaped with respect to the command line. Items not enclosed in quotes do not need to be escaped. Escaping requirements will vary according to platform. For example:

--TraceConfig="{\"TraceEnabled\":false,\"TraceLevel\":0,\"TraceFileName\":\"\/home\/user\/trace file\", ... }"

Optional configuration blocks (for example K8sConfig) can be added by passing in an appropriate and valid JSON object as the argument, or removed by passing in 'null' as the argument. See commonwebadmin.json file for possible settings and their values.

Parent topic: To Start ESCWA


Enterprise Server Administration Configuration

You can configure the properties for the following categories:

Note: Micro Focus recommends that you secure your Enterprise Server Common Web Administration installation by restricting access and enabling TLS.

You can disable the logon screen animation. To do this, click the user ( [image]) icon on the top right of the menu bar and then switch off Animate Logon.

  • Server Settings
    Enables you to configure the protocol, endpoint, and TLS settings for the server running the Enterprise Server Common Web Administration service.
  • Security Settings
    Enables you to configure session activity, enable single sign on, configure HSTS and input a vault specification for storing secrets.
  • Tracing and Logging Settings
    Enables you to configure the Consolidated Tracing Facility (CTF), its verbosity and the options it applies to.
Parent topic: To Start ESCWA


Server Settings

Enables you to configure the protocol, endpoint, and TLS settings for the server running the Enterprise Server Common Web Administration service.
Protocol
Protocol used to connect to endpoint.
Hostname or IP Address
The hostname or IP address used by the listener to accept incoming client requests. The IP address can be either IPv4 or IPv6.
Note: You must restart the ESCWA service if you modify this field.

Specifying 0.0.0.0 binds on all available IPv4 addresses. Specifying :: binds on all available IPv6 addresses. Specifying * binds on all available IPv4 and IPv6 addresses.

Port
This must be a valid port or an asterisk * which indicates that the address is dynamically assigned for the listener when it starts.
Enable TLS
Indicates whether or not the ESCWA server has Transport Layer Security (TLS). This will secure communications between the client and ESCWA.
Certificate File
Location, on disk, of the certificate. If multiple certificates are used, separate the paths with a semicolon ';'.
Keyfile
Location, on disk, of the keyfile. If multiple keyfiles are used, separate the paths with a semicolon ';'
Keyfile Password
The password for the keyfile is specified here. If multiple keyfiles are used, separate the passwords with four colons '::::'.

Advanced

Certificate Password
If the certificate is locked with a password, specify it here. If multiple certificates are used, separate them with two colons '::'.
Client Authentication
Accept all clients
Allow all clients to communicate with the server without being checked for an SSL certificate.
Request client certificate, and verify if present
Requests the client for a certificate, and to verify the returned certificate. If the client does not return a certificate, communication continues between the client and server. If a certificate is returned and it fails to verify, communication stops.
Note: If you select this, you must specify the CA root certificates file.
Require client certificate, and verify
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.
Note: If you select this, you must specify the CA root certificates file.
Client CA Root Certificates File
If you require clients to have certificates, this file must contain the trusted root certificates.
Note: Enterprise Developer supports DER, CER, PKCS #7, PKCS #8, PKCS #12 and PEM certificate file formats and PKCS #8, PKCS #12 and PEM for key file formats.
Honor Server Cipher List
By default, the TLS honor server cipher list is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
Note: If the TLS protocols and Cipher suites list are not specified then it uses the default. See Configuring a TLS Protocols List and Configuring a Cipher Suites List for more information.
Protocols
The list of TLS protocols to be used, in order of precedence. Each specified protocol is preceded by one of the following operators:
!
Exclude. Permanently exclude the protocol and ignore any subsequent attempt to add the protocol back in.
+
Add. Add the protocol to the existing collection.
-
Delete. Delete the protocol from the existing collection.
For example, to only use TLS1.1 and TLS1.2, type -ALL+TLS1.1+TLS1.2
Note: The Protocols field now supports TLS1.3.

You must use @SECLEVEL=0 for TLS 1.1 and earlier. See Security Levels for more information.

Cipher Suites
Specifies the priority of cipher suites to be used. The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:
!
Exclude. Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add. Add the cipher suite to the end of the collection.
-
Delete. Delete the cipher suite from the existing collection.
By default, the following cipher suite list is used:
kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
To determine the cipher suites supported by your version of OpenSSL, type the following from a command prompt:
openssl ciphers -v 'ALL:COMPLEMENTOFALL'
TLS1.3 Cipher Suites
The list of cipher suites to be used with TLS1.3 separated by a colon ':'. For example:
TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
Diffie-Hellman Minimum Group Size
Specifies the size in bits of the modulus length of the Diffie-Hellman group:
  • Default
  • 512 bit
  • 1024 bit
  • 2048 bit
  • 4096 bit
Note: Micro Focus recommends a minimum modulus size of 2048 bits.
Key Exchange Cipher Groups
The key exchange cipher groups to be used, separated by semicolons ';'. For example:
secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1
TLS1.3 Middlebox Compatibility
Enable workaround for TLS1.3 on networks with incompatible middleboxes, for example, routers and firewalls. Disabling this can improve performance on compatible networks but might result in dropped connections otherwise.
.NET Admin Host
The endpoint that ESCWA will communicate with for ES for .NET. This should point to a ES for .NET Admin Server. This administers, monitors, and controls managed regions.
External Communications Response Timeout
Specify, in seconds, how long ESCWA will wait for an external communications response before timing out. This timeout is used to communicate with the Communications Process, Web Services, J2EE Listener, ES for .NET, and MFA. Actual timeout might be a few seconds longer than specified.
Default Locale
Use this to specify the default locale of the ESCWA interface. If set to Browser Determined the user's browser locale will be used.

See Security Levels for more information.

Parent topic: Enterprise Server Administration Configuration
Related reference
Configuring a TLS Protocols List
Configuring a Cipher Suites List


Security Settings

Enables you to configure session activity, enable single sign on, configure HSTS and input a vault specification for storing secrets.
Session Inactivity Timeout
If a registered session makes no requests for longer than the timeout, the user will be required to login again.
Session Limit
The maximum number of open sessions that can be registered with ESCWA.
Single Sign-On Behavior
This specifies the single sign-on behavior:
Disabled
Disables all single sign-on behavior including live enterprise server region.
Only Secure and Loopback
Single sign-on will be enabled for secured and localhost resources.
Allow Insecure (All)
Single sign-on will be enabled globally.
Password Change Enabled
Check this to enable users to change their password when they log on to ESCWA.
Show Default Security Warning on Log On
Check this to display information about default security when logging onto ESCWA.

Encryption

Enable HSTS
HSTS is a security enhancement that prevents ESCWA from being accessed over unencrypted connections. ESCWA must be TLS enabled for this setting to be available. Once enabled, any other sites on this host will not be available unless they are accessible via HTTPS. The setting only stops applying when the user has not accessed the site for the duration specified in HSTS Max Age field. Only once HSTS has timed out for all users can HSTS and TLS be safely disabled. You can set the HSTS Max Age field to 0 to speed up this process.
Note: If enabled, the root certificate must be installed in the user's browser or they will not be able to access ESCWA.
HSTS Max Age
Duration in second for Enable HSTS timeout. See Enable HSTS for more information.
Vault Encryption Specification
By default, all passwords using ESCWA will be encrypted. The secrets.cfg file contains the specifications for these encryptions. A blank string in this field indicates the use of the default specification, otherwise you can name a specification to use. See Vault Facility for more information.

Active Sessions

Click Active Sessions to open the Active Sessions dialog box. This displays a table listing all the current active sessions along with the following session information:

  • User
  • Last Active
  • Logon Time
  • Client IP(s)

You can logoff users by clicking [image] Logoff icon on the row containing the required user.

Click Refresh to refresh the display with the current active sessions.

Parent topic: Enterprise Server Administration Configuration
Related reference
Vault Facility


Tracing and Logging Settings

Enables you to configure the Consolidated Tracing Facility (CTF), its verbosity and the options it applies to.
Enable Tracing
Create a Consolidated Tracing Facility (CTF) trace file which will provide low level technical logging for debugging issues.
Use Binary Format
The trace file will be created as a compressed binary file, which can be viewed using the CTF Viewer.
Trace Level
The level of trace output to generate:
  • Debug
  • Info
  • Warning
  • Error
  • Fatal
File Name
The CTF trace file will be created with the location and name provided. If only a file name is provided, it will be created in the default mftrace folder location C:\ProgramData\Micro Focus\Enterprise Developer\product_version\mftrace\logs.

Enable Tracing for:

Configuration
Enable tracing for when changes are made to the configuration file of ESCWA.
JSON Parsing and Serialization
Enable tracing for ESCWA's use of JSON objects.
Communications
Enable tracing for network communications between ESCWA and other components.
Session
Enable tracing for user sessions in ESCWA.
ESF
Enable tracing for the External Security Facility (ESF) usage in ESCWA.
Vault
Enable tracing for the Secrets Vault in use by ESCWA.
Audit
Enable tracing for auditing in ESCWA.
Log Directory
The directory to which the server log (log.html) will be saved. The specified directory must already exist. By default, this is located in C:\ProgramData\Micro Focus\Enterprise Developer\ESCWA\log.html.
Show Log
Click this to display the Micro Focus ES Communications Process Message Log.
Log Max File Size
The maximum size of the server log (log.html) that will be saved. Once the specified size has been reached a new file will be started. If set to 0 the file will grow without bound. The default file size is 1024kB.
Log File Count
The number of old server logs (log.html) that will be saved. Once reached the oldest file will be deleted and reused. The default log file count is 5.
Log User Authorization
Check this to log when users fail to authorize. This log information will be added to the server log (log.html).
Note: When enabled, this can log significant amounts of information.
Enable Auditing
Enable Auditing for ESCWA. ESCWA will collect information on security related events and preserve them for later review. Enterprise Server Auditing must be setup for this to take effect.
Note: See Enterprise Server Auditing for more information.
Audit Request Bodies
Check this to enable auditing of request bodies. See Audit Event Codes for more information.
Note: Enable Auditing must be checked for this option to take effect. This option significantly increases the amount of data that ESCWA will emit.
Parent topic: Enterprise Server Administration Configuration
Related reference
Enterprise Server Auditing


Configuring TLS for the ESCWA Client

To configure TLS security for the ESCWA client:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Click Server Settings to expand the available configuration options.
    Note: The following warning is displayed This endpoint is accessible over the network and is not TLS enabled.
  3. Click TLS Settings.

    This expands the TLS Settings group.

  4. Check Enable TLS.
  5. In the Certificate File field, type the absolute path to your certificate file.
  6. In the Keyfile field, type the absolute path to your private keyfile.
  7. In the Keyfile Password field, type your private keyfile password.
  8. Click Advanced.

    This expands the options available.

  9. In the Certificate Password field, type your certificate password.
  10. Click Apply.

    This logs you out of the ESCWA interface.

  11. Log back in, and then click TLS Settings.
  12. Click Advanced.
  13. In the Client Authentication field, select Accept all clients.
  14. Check Honor Server Cipher List.
  15. In the Protocols field, type the TLS protocol string. For example, to only enable TLS 1.2 and 1.3 type -ALL+TLS1.2+TLS1.3. See Server Settings for more information.
    Note: This supports TLS1.3.
  16. In the Cipher Suites field, type the Cipher Suites string. For example, to only enable best-in-class cipher suites for TLS 1.2 type ALL:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:DHE-DSS-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256

    See Server Settings for more information.

  17. Click Apply.
  18. Click Back.
  19. Logout and restart the Micro Focus Enterprise Server Common Web Administration service.
  20. Now access ESCWA using a URL which includes https and an IP address or hostname which matches the Common Name (CN) or Subject Alternative Name (SAN) on your server certificate.

    Your browser must trust the Certificate Authority (CA) used to sign the certificate being added in the above steps.

    Note: The FireFox browser does not use the Windows certificate store. This means that you need to add the root CA certificate to your FireFox store.

You now need to configure Micro Focus Directory Server (MFDS) to use TLS. You need to modify the CARootCerts.pem located in your Enterprise Developer bin directory. By default, this is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin

Parent topic: To Start ESCWA


The Enterprise Server Common Web Administration User Interface

When you access the Enterprise Server Common Web Administration (ESCWA) user interface, the Dashboard page is displayed. What you can see depends on your access permissions, set by your login ID.

Menus
The ESCWA main menu appears in a menu bar at the top of the page. The menu options are grouped under headings, such as Security. The main menu options can be configured to only be displayed for an appropriate user permission level.
Configuration
Click the configuration ( [image]) icon at the top right of the page to configure ESCWA's server, security, trace and logging settings. See Enterprise Server Administration Configuration for more information.
Dashboard
The dashboard is your home screen, it is the first view of ESCWA once you have logged in. You can configure your dashboard to display the information that best helps you monitor and administer your servers. See Dashboard for more information.
Refreshing a page or node
Many pages and tree nodes, such as those displayed in the navigation pane, contain a refresh ( [image]) icon. Click this to refresh the page information or node's status. This can be used to update the status if you have performed an action that might have occurred outside of the ESCWA interface.
Search
Click the search ( [image]) icon at the top right of the page. This opens the Search dialog box. Start typing a search string to find the page where it is featured. A list of possible search result candidates will be displayed, grouped under its associated page heading. If the page that you selected is associated with more than one object, a list of relevant objects will be displayed. Selecting an object will take you to the appropriate page.
Parent topic: Enterprise Server Common Web Administration


Dashboard

The dashboard is your home screen, it is the first view of ESCWA once you have logged in. You can configure your dashboard to display the information that best helps you monitor and administer your servers.

Click Reload Default to reset the default dashboard, for all users, to the Enterprise Test Server default configuration.

Click Update Default to display two options to modify the default dashboard displayed:

Set Current Dashboard as Default
Click this to display a confirmation dialog asking if you want to set the current dashboard configuration as the default for all users.
Reset the Default Dashboard
Click this to display a confirmation dialog asking if, since customizing your dashboard you now want to reset the dashboard configuration to the default currently set for all users.
Note: The default dashboard is displayed to all users that have not created their own dashboard.

You can customize the widgets that are displayed, their content, dimensions, and placement. You can add multiple instances of each widget type, each with their own configuration.

Welcome
Can display customized content. For example, a welcome message that provides specific information or links within your organization. To add custom content, modify the en.md file. By default, the file is located at %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\webui\escommonwebadmin\assets\welcome (Windows) or $COBDIR/etc/webui/escommonwebadmin/assets/welcome (UNIX). This is the only widget that is displayed by default.
Directory Server List
Displays a list of all the directory servers. By default, their name, host, and port number are listed. You can modify the columns displayed and the order the servers are sorted in.
Native Region List
Displays a list of regions associated with a specified directory server. By default, their CN, status, bitism, and whether the region is MSS-enabled. You can modify the columns displayed and the order the regions are sorted in.
Native Region Status
Displays the status for a specified region. You can stop or start the region from the widget. Click on the status to take you to the region list for the appropriate directory server.
Native Region Monitor Graph
Plots the latency, task rate, and task time on a graph. You can configure it to sample every minute or every 15 minutes.
Note: To enable monitoring for a region it will require a started Web Services Listener.
Native Region Console
Displays the auxiliary, backup, or current console logs for a specific region, console.bak, and console.log respectively. By default, you can display time stamp, process ID, message ID, and message in formatted columns. To display the unformatted console text, click Raw View when configuring the widget.
Native Region Listeners List
Displays information for listeners associated with a specific region. By default, it displays the listener name, address, status, status log, conversation type, and description. You can modify the columns displayed and the order the columns are sorted in.
Native Region Communications Log
Displays the messages from the region's communications log.
Managed Region List
Displays either CICS or JES managed regions.
Active XA Resources
Displays a list of all the active extended architecture (XA) resources for a specified enterprise server region. The table lists their names and status. You can modify the columns displayed and the order the resources are sorted in. Clicking on the resource action column will take you to the full extended architecture table entry.
Parent topic: Enterprise Server Common Web Administration


Native

These are the Enterprise Servers and Directory Servers which run directly on the processors of the platform you have installed them on.
  • Groups
    Groups enable you to create and modify groups of native regions and to configure Performance and Availability Clusters (PACs).
  • Directory Servers
    This page lists directory servers and their key configuration properties.
  • Scale-Out Repositories
    You can view, add, edit, and delete Scale-Out Repositories (SORs).
Parent topic: Enterprise Server Common Web Administration


Groups

Groups enable you to create and modify groups of native regions and to configure Performance and Availability Clusters (PACs).
  • Logical
    You can view, create, and modify groups of native regions.
  • Performance and Availability Clusters
    Enables you to configure and monitor Performance and Availability Clusters (PACs).
Parent topic: Native


Logical

You can view, create, and modify groups of native regions.
  • Region Group List
    You can create and modify groups of native regions. You can use this to visualize and support regions that might have shared characteristics or functions but are distributed across directory servers.
Parent topic: Groups


Region Group List

You can create and modify groups of native regions. You can use this to visualize and support regions that might have shared characteristics or functions but are distributed across directory servers.

To create a new group:

  1. Click * New.

    This opens the New Group dialog box.

  2. In the Group Name field, type the name of the group you want to create.
  3. Optionally, in the Description field, type a group description. This will be displayed in the region group list.
  4. Click Save.

You can edit or delete a region group by clicking the appropriate icon at the far right of a directory server row.

  • Group Member List
    The Group Member List enables you to check the status and manage your native region members.
Parent topic: Logical


Group Member List

The Group Member List enables you to check the status and manage your native region members.

You can add, remove, and apply actions to the regions.

To add new regions:

  1. Click +Add.

    This opens the Add New Group Members dialog box.

  2. Click the directory server, and then check the regions you require.
  3. Click Add.

To perform an action on one or more regions, check the regions required in the list. You can then remove the regions or perform a group action on them. Click Actions and then select the Start or Stop option. If you wish to stagger the start or stop action, then you can set the interval in seconds between each action.

You can edit or remove a region by clicking the appropriate icon at the far right of the group member list row.

Note: You can select all regions by clicking the checkbox in the table header.
Parent topic: Region Group List


Performance and Availability Clusters

Enables you to configure and monitor Performance and Availability Clusters (PACs).

This page enables you to create a new Performance and Availability Cluster (PAC) and to list existing PACs. A cluster can be used to specify where resources, queues, and files will be stored and accessed within a group of scale-out regions.

See Scale-Out Performance and Availability Clusters for more information.

To create a new PAC, click * New. This take you to the New Performance and Availability Cluster page.

Important: Before you start working with PACs you need to specify a Scale-Out Repository (SOR) for use in your PAC. See Scale-Out Repositories for more information.
  • Configuring PACs and SORs
    You can configure a number of enterprise server instances to act as a PAC.
Parent topic: Groups
Related reference
Scale-Out Performance and Availability Clusters


Configuring PACs and SORs

You can configure a number of enterprise server instances to act as a PAC.

See Scale-Out Performance and Availability Clusters for more information. The PAC acts as a single logical entity that supports scale-out growth.

Configuring a PSOR for use with a PAC

Firstly, you need to specify a Scale-out Repository (SOR) which will store the system and configuration data that will be shared between all the enterprise server region that are part of the PAC:

  1. In the menu bar, click Native.
  2. In the navigation pane, click SORs.
  3. Click +Add.

    This opens the Scale-Out Repository Configuration dialog box.

  4. In the Name field, type the name of your PSOR. For example, type MyPSOR.
  5. In the Type list, select the SOR type. Redis and Oracle Coherence are supported as SORs. See Scale-Out Performance and Availability Clusters for more information.

    The default is Redis.

  6. Optionally, in the Description field, type a description for your PSOR.
  7. Depending on the type of SOR selected:
    • If Redis is selected, in the Connection Path(s) field, type the host name and port number to connect to. In the form host:port. For example, if you are running Redis locally on the default port, type localhost:6379.
      Note: If you are using Redis Sentinel or Cluster, you can specify the connection details for multiple nodes. Click + to add an additional node name and port number.
    • If Coherence is selected, in the Connection String field, type the connection string which takes the form [userid@][configfile][,property=[value]]…

      See PAC and SOR Environment Variables for more information.

  8. Click Save.
Important: Only one PSOR can be associated with a given PAC. A PSOR can be specified with multiple Redis Sentinel or Cluster connections. This configuration can help support high availability. You can specify multiple connections in the Connection Path(s) field.

Configuring a PAC

You now need to specify a PAC:

  1. In the menu bar, click Native.
  2. In the navigation pane, click Groups > PACs.
  3. Click * New.
  4. In the Name field, type the name of your PAC. For example, type MyPAC.
    Note: The PAC Name is limited to no more than 8 characters long.
  5. Optionally, in the Description field, type a description for your PAC.
  6. The PAC SOR field lists all the available SORs that could be used. Click MyPSOR, which you configured in the steps above.
  7. Click Save.

You have now specified a PAC and its PSOR and you can now add regions to the PAC.

Sending TSQs and TDQs to a SOR

You can optionally send TSQs and TDQs to a PSOR that has already been specified or you can create a new SOR to store this information:

  1. In the menu bar, click Native.
  2. In the navigation pane, click Groups > PACs.
  3. Click [image] Edit in the row containing the PAC you want to edit.
  4. Click * New next to the SOR Models heading.

    This opens the SOR Model dialog box.

  5. In the Resource field, select the resource type you want to store in the SOR.
  6. In the Prefix field, type a prefix that will match the instances that you want to be stored in the SOR. You can use the following wildcard characters:
    • * Matches any string of characters.
    • + Matches any one character.
    Note: This field will have the remaining characters padded with the + wildcard. For example, if you type T for a TD Queue resource, then the remaining characters will be padded with the +.
  7. In the SOR field, select the name of the SOR you want to associate the model with.
  8. Check Shared if you require the SOR model to be shared between PACs.
  9. Click Save to save the model in the SOR Models list.

Adding an enterprise server instance to a PAC

To add an enterprise server instance to your PAC:

  1. In the menu bar, click Native.
  2. In the navigation pane, click Groups > PACs.
  3. In the navigation pane, click on the name of the PAC you want to add enterprise server instances to.
  4. Click Install.

    This opens the Install PAC Definition to Regions dialog box.

  5. In the left pane, click the directory server that hosts the enterprise server instance you want to add.
    Note: Micro Focus recommends a minimum of three regions to a PAC and that each region should be located on Directory Servers hosted on separate hardware. This will help reduce single points of failure.
  6. In the right pane, check the enterprise server instances you want to add to your PAC.
  7. Click Add.

    This adds the enterprise server instances to the PAC field in the General Properties for the region.

Once you have added an enterprise server instance to a PAC you will be able to see its scale-out configuration information under its region's General Properties.

Note: If the configuration of a PAC changes, including the configuration of any of its SORs or SOR Models, then you will need to reinstall the PAC to ensure that all enterprise server instances within that PAC are synchronized.
Parent topic: Performance and Availability Clusters
Related reference
Scale-Out Performance and Availability Clusters


Directory Servers

This page lists directory servers and their key configuration properties.

To add a new directory server:

  1. Click Add.

    This opens the Directory Server dialog box.

  2. In the Name field, type the name of your directory server.
  3. In the Host field, type the name of the host or IP address. If you are connecting via TLS, type one of the Subject Alternate Name (SAN), or Common Name of the certificate that the server is using.
  4. Optionally, in the Port field, you can modify the default port number.
  5. Optionally, in the Description field, type a short description.
    Note: The description is displayed in the directory servers list.
  6. Click Save.

You can edit or remove directory servers by clicking the appropriate icon at the far right of a directory server row.

The status of each directory server is displayed when you hover over the Server server icon on the far left of the directory server row.

  • Native Directory Server Navigation Bar
    Outlines how you can assign a color to each directory server to assist identification and grouping of its regions and servers.
  • Regions & Servers
    Regions & Servers are listed under their parent directory server.
  • Properties
    You can configure settings, connection properties, and view statistics and status information for your Directory Servers.
  • Security
    You can configure security managers and security settings for Directory Servers.
  • 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.
Parent topic: Native


Native Directory Server Navigation Bar

From here you can view the region and server list for a directory server, access the directory server's security configurations and its journal. You can also access the directory server's configuration, connection, and statistics properties. This includes assigning the directory server a distinct color, which is inherited by its regions and servers. Assigning a color to a directory server can assist with the identification and grouping of its regions and servers.

To assign a color to a directory server:

  1. Click Properties > Appearance.
  2. Click one of the preselected colors in the displayed palette. Or alternatively, you can specify the exact HEX or RGBA color code that you require.
  3. Click Save.
Parent topic: Directory Servers


Regions & Servers

Regions & Servers are listed under their parent directory server.
  • Regions
    Regions are listed under their parent Directory Server.
  • Servers
    Servers are listed under their parent directory server.
Parent topic: Directory Servers


Regions

Regions are listed under their parent Directory Server.

To add a new region, click * New and specify its details in the New Region dialog box. You can edit or delete regions by clicking the appropriate icon at the far right of the region row. To start or stop a region, click the Start/Stop icon, this takes you to the Control page.

Note: A warning will be displayed if you try to create a region with a working mode that is different from the bitism of the parent Directory Server. The region might not work on some platforms if they do not have the corresponding product binaries.

Click Export to export the definition of a single or multiple regions and specified characteristics, such as security configuration, from ESCWA into a single JSON or XML definition file. You can transfer the output file to other machines and import the region(s) into other instances of Enterprise Server or ESCWA.

Click Import to import a single or multiple regions stored in a JSON, XML, or legacy definition file which has been exported from another instance of Enterprise Server into ESCWA.

Click Copy to copy one or more regions and specified characteristics, such as security configuration, to a new region on the same Directory Server.

Click Reconnect to refresh the network endpoint addresses for the started regions.
Note: The Directory Server might not be contactable while this occurs.

Click on the value for the Security column to take you to the region's External Security Manager (ESM) configuration.

  • Native Region Navigation Bar
    This provides information on how to enable native region menu options.
  • To export a region from ESCWA
    You can export the definition of a single or multiple regions from ESCWA into a specified file format, JSON or XML.
  • To import a region into ESCWA
    You can import a region definition into ESCWA if it is contained in a compatible file type, JSON, XML or Legacy (.dat).
  • To copy a region in ESCWA
    To copy the definition of a single or multiple regions from a Directory Server in ESCWA
  • General
    This menu provides pages that enable you configure general properties, listeners, control regions, and services.
  • Monitor
    This menu provides pages to view live properties, monitor, and view logs.
  • Logs
    You can obtain more log information from the Console, Communications Process Log, Trace, and Dumps.
  • CICS
    This menu provides pages that enable you to manage CICS configuration and resources.
  • JES
    This menu provides pages that enable you to configure, control, and monitor the Job Entry Subsystem (JES).
  • IMS
    This menu provides pages that enable you to configure, control, and view IMS transactions.
  • MQ
    This menu provides pages that enable you to configure MQ listeners, writers, and startup MQ listeners.
  • Character encoding support for enterprise server region
Parent topic: Regions & Servers


Native Region Navigation Bar

Check MSS Enabled on your region's General Properties page to display the CICS menu item. Check JES Enabled, IMS Enabled, or MQ Enabled to display the corresponding menu item.

When the menus are visible, you will always be able to access the configuration options under each of the menu items.

When regions are started, additional options can appear under each of the menus. These are specific to active region configuration, monitoring, and control.

Note: These additional menu options will not appear if their respective feature (MSS, JES, IMS, or MQ) is not correctly configured. The region will start but the menu will have a red triangle next to it warning that the feature is not working as a result of misconfiguration.

Additionally, when a region is TranClass enabled and started, the Monitor > TranClass option will appear along with the TranClass resource type under CICS > Resources.

Parent topic: Regions


To export a region from ESCWA

You can export the definition of a single or multiple regions from ESCWA into a specified file format, JSON or XML.

You can then transfer the file to other machines and import the region definition file into other instances of Enterprise Server or ESCWA.

To export a single or multiple regions:

  1. On the Choose Export Type page, check the export file type required and then click Next.
  2. On the Select Region page, check the region or regions that you want to export and then click Next.
  3. On the Security Options page, check the security options that you want to export.
    Note: Their corresponding security managers will be included in the exported file.
  4. Click Next.
  5. On the Review and Download page, you can review the regions and components that you have selected to export.
    • If you need to change any of the selected options, click Back and modify your selection.
    • If the selected options meet your requirements, click Download.
  6. Click Finish to export the definition file to your browser's download directory.
Parent topic: Regions


To import a region into ESCWA

You can import a region definition into ESCWA if it is contained in a compatible file type, JSON, XML or Legacy (.dat).

To import a region from a definition file:

  1. On the Choose Import Type page, click the import file type required and then click Next.
    • If you select the JSON or XML file type:
      1. On the Upload File page, click inside the dashed rectangle and then browse to the file location. Alternatively, drag and drop the file inside the dashed rectangle.
      2. If the definition file is accepted, click Next.
      3. On the Select Regions page, check Import next to the regions you want to import and choose from the following import options:
        New Name
        You must type a new region name for the regions being imported.
        64-Bit Working Mode
        Check this to import the region in 64-bit working mode. Otherwise, the region will be imported as a 32-bit working mode.
        Clear TLS from Endpoints
        Check this to ensure that all imported listeners will be configured to start without TLS.
        Clear Hostnames from Endpoints
        Check this to ensure that all imported listeners will be configured to have hostname *.
        Clear Ports from Endpoints
        Check this to ensure that all listeners will be configured to have port *.
      4. Click NEXT.
      5. On the PERFORM IMPORT page, a summary of the selected import options is displayed. If you want to continue to import the selected regions and options, click IMPORT.
      6. Click FINISH.
    • If you select the Legacy file type:
      1. On the Choose Legacy Repostory Location page, in the Repository Location field, type the absolute file path to the legacy .dat definition file and then click Summary.

        This displays a summary of the regions and security options contained in the .dat legacy definition file.

        If you want to continue to import the content of the legacy definition file, click Next.

      2. In the Select Regions page, check Import next to the regions you want to import and then click Next.
      3. In the Select Region Import Options page, choose the options that you require:
        Set all regions to Stopped state
        Check this if you want all regions to be set to the Stopped state. Micro Focus recommends this field is checked unless you are trying to diagnose state issues in the regions.
        Import deployed Services and Packages
        Check this if you want to import deployed Web and J2EE services to the regions. You might want to uncheck this if you only want region configuration and not the associated Web and J2EE services.
        Region Import Rules
        When importing:
        Only If No Duplicates
        Import all regions and report an error if any regions are duplicates.
        Only Import Non-Duplicates
        Only import regions which are not duplicates of existing regions.
        Replace Duplicates
        Imports all regions and duplicate regions from the repository will replace definitions in the Directory Server.
        Replace All
        Deletes all existing regions and then imports all regions from repository.
        Working Mode
        When importing:
        Retain
        Retain working mode for all imported regions.
        Convert all to 32 bit
        Convert all imported regions to 32 bit working mode.
        Convert all to 64 bit
        Convert all imported regions to 64 bit working mode.
      4. Click Next.
      5. The ES Default Security Configuration page displays ES default configuration options that will be imported. Click Import and Replace All Security Configuration to delete all security configuration from the Directory Server and then import all security configuration from the legacy definition file. This includes security managers, ES default security and directory server security.
      6. Click Next.
      7. The Directory Server Security Configuration page displays Directory Server security configuration options that will be imported. Click Import and Replace All Security Configuration to delete all security configuration from Directory Server and then import all security configuration from the legacy definition file. This includes security managers, ES default security and directory server security.
      8. Click Next.
      9. The Security Managers page displays Security Manager configuration options that will be imported. Click Import and Replace All Security Configuration to delete all security configuration from directory server and then import all security configuration from this repository. This includes security managers, ES default security and directory server security.
      10. Click Next.
      11. On the Perform Import page, a summary of the selected import options is displayed. If you want to continue to import the selected regions and options, click Import.
      12. Click Finish.
Parent topic: Regions


To copy a region in ESCWA

To copy the definition of a single or multiple regions from a Directory Server in ESCWA
  1. On the Target Directory Server page, select the Directory Server you want to copy the regions from and then click Next.
  2. On the Select Regions page, check the region or regions that you want to export and then click Next.
  3. On the Security page, check the security options that you want to copy.
    Note: Their corresponding security managers will be included in the copy.
  4. Click Next.
  5. The page displays a summary of the regions to be copied. At this point the process validates that you have permissions to copy the regions and options you have selected:
    • If you need to change any of the selected options, click Back and modify your selections.
    • If the selected options pass validation and meet your requirements, click Next.
  6. On the Edit Regions page, in the New Name field, type a new name for each of the regions being copied.
  7. Next to each region being copied, check 64-Bit Working Mode if you want the copied region to operate in 64-bit working mode. Alternatively, leave it unchecked if you want the copied region to operate in 32-bit working mode.
  8. Check Clear TLS from Endpoints to configure all listeners in the copied regions to start without TLS.
  9. Check Clear Hostnames from Endpoints to configure all listeners in the copied regions to have hostname *.
  10. Check Clear Ports from Endpoints to configure all listeners in the copied regions to have port *.
  11. Click Next.
  12. On the Perform Copy page, a summary of the selected options is displayed. If you want to continue and copy using the selected regions and options, click Copy.
Parent topic: Regions


General

This menu provides pages that enable you configure general properties, listeners, control regions, and services.
  • General Properties
    Use this page to change the basic configurable attributes of an enterprise server instance.
  • Control
    Use this page to confirm that you want to start or stop a region.
  • Verify
    Use this page to verify the configuration of selected components for the enterprise server region.
  • Listeners
    Use this page to create, modify, delete, and view communication processes and listeners.
  • Services
    Use this page to view a list of the services registered for the currently selected server.
  • XA Resource
    Use this page to view a list of the external resource managers registered with the currently selected server.
  • Diagnostics
    Use this page to change the trace attributes of a server.
  • Historical Statistics
    Use this page to configure the Historical Statistics Facility (HSF), this enables you to collect data about transactions.
  • Scripts
    Use this page to edit advanced attributes of an enterprise server.
  • Validate
    This page displays a validation report for the current region.
  • Security
    Use this page to define security settings that can be used with an enterprise servers.
  • Advanced Region Properties
Parent topic: Regions


General Properties

Use this page to change the basic configurable attributes of an enterprise server instance.

Modify the options and then click Apply.

CAUTION:
Changing the properties of a registered enterprise server instance may cause application connection errors and loss of data.

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.

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.
Note: You must not 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 (Windows) or /var/mfcobol/es/es-name (UNIX), 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. 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.

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 in size.
SEP Count
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 enable 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.
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).
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 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 this enterprise server instance when the Micro Focus Directory Server process is started. The Micro Focus Directory Server process (MFDS) is usually started at system startup, for example, on Windows it is registered as a system service by default. Typical usage is to ensure a set of enterprise server instances 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.

MSS Configuration

Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).

Mainframe Subsystem Support (MSS) configuration:

MSS Enabled
Check this to provide an execution environment for migrated applications that use mainframe technologies.
JES Enabled
Check this to enable the Job Entry Subsystem (JES) for this enterprise server.
IMS Enabled
Check this to enable Information Management System (IMS) for this enterprise server.
MQ Enabled
Check this to enable MQ listener support for the MQ IMS bridge feature for this enterprise server.

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 command line Performance Monitor.
Informational
Check this box to specify informational events will be logged to the Windows Event Log.
Warning
Check this box to specify warning events will be logged to the Windows Event Log.
Error
Check this box to specify error events will be logged to the Windows Event Log.
Severe
Check this box to specify server events will be logged to the Windows Event Log.

Additional

Configuration Information
Textual configuration information that determines the startup and run-time behavior of the server. Prefix comments with #.
Description
Description of the server to aid identification. For example, specify its function and owner.

Scale-Out Configuration

PAC
The Performance and Availability Cluster (PAC) used for this region.
SOR Configuration
The Scale-Out Repository (SOR) configuration in use for this region. Micro Focus recommends that you configure this using the Install option in the PAC configuration page.
Parent topic: General
Related information
ES_CONSOLE_LOG (deprecated)


Control

Use this page to confirm that you want to start or stop a region.
Start
Click this to start the region. Clicking this opens the Region Start Options dialog box. Specify the options you require, and then click OK.
Stop
Click this to stop the region. Clicking this opens the Region Stop Options dialog box. Specify the options you require, and then click OK.
Mark as Stopped
Click the arrow-down icon ( [image]) next to the Stop button and then click Mark as Stopped if you know that all the processes for this server are already stopped.
Stop Polling
This enables you to stop polling for the region's status while starting and stopping a region.
Note: Clicking Stop Polling will not stop the region form starting or stopping.

Region Start Options

Cold Start
Click this to cold start a PAC, this will remove all existing data from each SOR in the PAC. If a region is cold started and another instance is already running in the same PAC, then the start will be changed to a warm start.
Use current user credentials
Start the region as the user you have already logged in as.
User Name
Username of the user you want to use to start the region.
Password
Password of the user you want to use to start the region.
Group
Specifies the sign-on group for the user. By default, when a user requests access some external security managers 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. This is ignored if Use All Groups is checked in the ESF security configuration. In this case, it uses all groups which the user is a member of.

Region Stop Options

Clear dynamically assigned server 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.
Use "Force stop" option
Check this if you want to perform a forced shutdown of the server.
Use current user credentials
Stop the region as the user you have already logged in as.
User Name
Username of the user you want to use to stop the region.
Password
Password of the user you want to use to stop the region.
Group
Specifies the sign-on group for the user. By default, when a user requests access some external security managers 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. This is ignored if Use All Groups is checked in the ESF security configuration. In this case, it uses all groups which the user is a member of.
Note: When an enterprise server starts or stops, it connects to Directory Server to obtain its configuration details and, later in the start or stop 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 start or stop process also requires user credentials that the enterprise server will verify and authorize. In order to run the command used to start or stop 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 or stop should use built-in default users or the credentials with which you are currently logged on to Enterprise Server Common Web 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.

Region Processes Status

The Region Processes bar indicates at which stage of the starting and stopping process the region is at. The Directory Server initiates the starting and stopping processes and queries the status at specific stages.

Communication Process Status

The Communication Process bar(s) indicate the status of each Communication Process used by the region. It indicates if the Communications Processes are started, and each listener owned by it. A disabled listener will not attempt to start, this state is indicated by red bar. A pending listener needs to be started from the Listeners page, but until then it is displayed as a yellow bar.

Monitoring and Control Access Status

The Monitoring and Control Access bar indicates if ESCWA can communicate with the monitoring and control elements of the region (formerly known as ESMAC). This will display Stopped if ESCWA cannot contact it, Starting if monitoring and control is initiating, and Started if the region is fully initiated and any correctly configured region features are started.

Region Features Status

The Region Features indicators display the status of each feature for the region:

  • When monitoring and control access cannot be contacted, the indicators will be blank.
  • If it is starting and any of the MSS, JES, IMS, MQ, TCL, CWS, and PL/I features have been enabled, the indicators for these will be displayed as a yellow bar.
  • If it is started and any of the MSS, JES, IMS, MQ, TCL, CWS, and PL/I features have been enabled but have not been configured correctly, the bars will be red to indicate that these features are not enabled as expected.
  • If it is started and any of the MSS, JES, IMS, MQ, TCL, CWS, and PL/I features have been enabled and have been correctly configured, or TRANCLASS and CWS have been configured on the region, the bars will be green to indicate that these features are enabled as expected.
Parent topic: General


Verify

Use this page to verify the configuration of selected components for the enterprise server region.

Click Verify to open the Region Verify Options dialog box and select from the verification options.

Click Run to initiate the verification process.

Click Stop Polling at any time during the verification process to stop polling the enterprise server region.

Start Mode
Verifies the enterprise server region in the context of how it is to be started in a Performance and Availability Cluster (PAC) environment:
Warm
Check this to verify the region in the context of a PAC warm start.
Cold
Check this to verify the region in the context of a PAC cold start.
Upgrade
Check this to verify the region in the context of a PAC upgrade start.
Use current user credentials
Verified the region as the user you have already logged in as.
User Name
Specify the username of the user you want to verify the region as.
Password
Specify the password of the user you want to verify the region as.
Group
The sign-on group for the user. By default, when a user requests access to a resource, some external security managers 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.
Verbosity
Specifies the verbosity of the logging:
Info
Outputs all information, warning, error, and severe messages.
Warning
Outputs all warning, error, and severe messages.
Error
Outputs all error and severe messages.
Severe
Outputs only severe messages.
Note: The default value is Info, which will output all information, warning, error, and severe messages.
Abort Level
The verification process will abort on the first occurrence of a:
Warning
Aborts on the first occurrence of a warning, error, severe, or fatal message.
Error
Aborts on the first occurrence of an error, severe, or fatal message.
Severe
Aborts on the first occurrence of a severe or fatal message.
Fatal
Aborts on the first occurrence of a fatal message.
Stages
Specify a list of verification stages to execute. This can be a single stage-id or a comma separated list of stage-id. If this field is not specified the default action will run all stages.
Poll for
Specify the total number of seconds to poll for changes.
Poll every
Specify the interval to poll for changes in seconds.

Stages and Steps

The results of the verification are displayed in a table with the following columns:

ID
Grouped by the stage-id specified in the Stages field. Each stage can contain a single or sequence of verification steps. If the stage contained a sequence of steps then you can expand the stage to view the results for each step.
Name
A descriptive name of the stage or step being verified.
Status
Displays the summary status for the stage or component step:
Complete
Verification completed and encountered only information or warning messages.
Skipped
This status occurs when the stage is not applicable to the region, for example, when a stage or feature is not enabled. It can also occur when a stage has a dependency that was not fulfilled, or a prerequisite errors. For example, an error occurs with a control block.
Failed
An error, severe, or fatal message was encountered.
Severity
Displays the most severe message type encountered:
  • Info
  • Warning
  • Error
  • Severe
  • Fatal
Message ID
The ID that corresponds to the most severe message that was encountered.
Message
The message text that corresponds to the most severe message that was encountered.
Note: This functionality implements the casverify utility. See casverify for more information.
Parent topic: General


Listeners

Use this page to create, modify, delete, and view communication processes and listeners.
  • Communications Process
    Communications processes handle communications between clients and the enterprise server instance, and consist of a number of service listeners.
  • Listeners
    Use this page to create a new listener.
Parent topic: General


Communications Process

To create a new communication process, click * New Comms Server.

To view the listeners associated with a communications process, click the communications process in the communications process list.

To display all the configurable properties of the communication process, click Configure.

Auto Start
Check this to automatically start the communications process when the enterprise server instance starts.
Status
Displays the current status of the communications process:
  • 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.
Requested Status
The requested status of the communications process. If the region is running, at least one communications process must be started.
Process ID
Displays the process ID of this communications process.
Actual Address
Displays the network address or addresses used by the communications process to accept incoming client requests. The format is:

protocol:hostname or ip-address:port

where:

protocol
This can be tcp or tcpssl.
hostname or ip-address
This can be a single hostname or multiple IP addresses that can be either IPv4 or IPv6.
Note: Specifying 0.0.0.0 binds on all available IPv4 addresses. Specifying :: binds on all available IPv6 addresses. Specifying * binds on all available IPv4 and IPv6 addresses.
port
This must be a valid port or an asterisk * which indicates that the address is dynamically assigned for the communications process when it starts.
To add additional addresses, expand CONFIGURE and then click the + icon. To remove an addresses, click the - icon.
Status Log
Displays most recent event for that communications server.

Configure

Protocol
Protocol can be tcp or tcpssl.
Hostname or IP Address
A hostname, IPv4, or IPv6 Address to accept incoming client requests. Specify * to listen on all available addresses.
Port
A port to accept incoming client requests. Specify * to pick an unused port at start up.
Custom Configuration
Specify optional textual configuration information.

TLS Settings

For an enterprise server instance, you can create a secure Communications Process control listener to encrypt the communications it handles. To do this, click TLS SETTINGS, this expands the TLS Settings group.

You must specify the following fields:

Enable TLS
Enables Transport Layer Security (TLS) for this communications process.
Certificate File
The location, on disk, of the certificate. If multiple certificates are used, separate the paths with a semicolon ';'.
Keyfile
The location, on disk, of the keyfile. If multiple keyfiles are used, separate the paths with a semicolon ';'.
Server CA Root Certificate File
Location on disk of the server CA root certificate. This root certificate is used when the Directory Server communicates with a TLS enabled Communications Process. MFDS uses this to verify if it trusts the Communications Process' certificate chain, and therefore trusts the Communications Processed server certificate itself.
Note: The following certificate file formats are supported DER, CER, PKCS #7, PKCS #8, PKCS #12 and PEM and following key file formats PKCS #8, PKCS #12 and PEM.

Advanced TLS Settings

Optionally, click Advanced to expand the advanced group of options:
Client Authentication
Select one of the client authentication types:
Accept all clients

Allow all clients to communicate with the server without being checked for a TLS/SSL certificate.

Request client certificate, and verify if present

Requests the client for a certificate, and to verify the returned certificate. If the client does not return a certificate, communication continues between the client and server. If a certificate is returned and it fails to verify, communication stops. If you select this, you must specify the CA root certificates file.

Require client certificate, and verify

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 select this, you must specify the CA root certificates file.

Honor Server Cipher List
By default, the TLS Honor Server Cipher List is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
Protocols
The list of TLS protocols to be used, in order of precedence. Each specified protocol is preceded by one of the following operators:
!
Exclude. Permanently exclude the protocol and ignore any subsequent attempt to add the protocol back in.
+
Add. Add the protocol to the existing collection.
-
Delete. Delete the protocol from the existing collection.
For example, to only use TLS1.1 and TLS1.2, type -ALL+TLS1.1+TLS1.2
Note: The Protocols field now supports TLS1.3.
Cipher Suites
Specifies the priority of cipher suites to be used. The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:
!
Exclude. Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add. Add the cipher suite to the end of the collection.
-
Delete. Delete the cipher suite from the existing collection.
By default, the following cipher suite list is used:
kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
TLS1.3 Cipher Suites
The list of cipher suites to be used with TLS1.3 separated by a colon ':'. For example:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
Diffie-Hellman Minimum Group Size
Specifies the size in bits of the modulus length of the Diffie-Hellman group.
Note: Micro Focus recommends a minimum modulus size of 2048 bits.
Key Exchange Cipher Groups
The key exchange cipher groups to be used, separated by semicolons ';'.

For example:

secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1
TLS1.3 Middlebox Compatibility
Enables workaround for TLS1.3 on networks with incompatible middleboxes, for example, routers and firewalls. Disabling this can improve performance on compatible networks but might result in dropped connections otherwise.
Parent topic: Listeners


Listeners

Use this page to create a new listener.

To create a new listener:

  1. Click * New Listener.
  2. Modify the listener properties as required.
  3. Click Save.

The properties for a listener are:

Name
Specify the unique name of the listener, up to 255 characters in length. You cannot include angle brackets (<>) or ampersands (&) in the name.
Legacy Micro Focus Application Format
Check this if you want the listener to handle non-standard TCP/IP flows, for example, for Fileshare clients.
Protocol
This can be set to tcp or smem for shared memory protocols.
Hostname or IP Address
This can be a single hostname or multiple IP addresses that can be either IPv4 or IPv6.
Note: Specifying 0.0.0.0 binds on all available IPv4 addresses. Specifying :: binds on all available IPv6 addresses. Specifying * binds on all available IPv4 and IPv6 addresses.
port
This must be a valid port or an asterisk * which indicates that the address is dynamically assigned for the listener when it starts.

To add additional addresses, click the + icon . To remove an addresses, click the - icon.

Note: If this network address is not unique in the repository, this might cause listener start-up problems.

For an enterprise server instance, you can create a secure listener to encrypt the communications it handles. To do this, click TLS Settings, this expands the TLS Settings group.

You must specify the following fields:

Enable TLS
Enables Transport Layer Security (TLS) for this communications process.
Certificate File
The location, on disk, of the certificate. If multiple certificates are used, separate the paths with a semicolon ';'.
Keyfile
The location, on disk, of the keyfile. If multiple keyfiles are used, separate the paths with a semicolon ';'.

TLS Advanced Settings

Optionally, click Advanced to expand the advanced group of options:

Client Authentication
Accept all clients
Allow all clients to communicate with the server without being checked for a TLS/SSL certificate.
Request client certificate, and verify if present
Requests the client for a certificate, and to verify the returned certificate. If the client does not return a certificate, communication continues between the client and server. If a certificate is returned and it fails to verify, communication stops.
Note: If you select this, you must specify the CA root certificates file.
Require client certificate, and verify
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.
Note: If you select this, you must specify the CA root certificates file.
Honor Server Cipher List
By default, the TLS Honor Server Cipher List is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
Protocols
The list of TLS protocols to be used, in order of precedence. Each specified protocol is preceded by one of the following operators:
!
Exclude. Permanently exclude the protocol and ignore any subsequent attempt to add the protocol back in.
+
Add. Add the protocol to the existing collection.
-
Delete. Delete the protocol from the existing collection.
For example, to only use TLS1.1 and TLS1.2, type -ALL+TLS1.1+TLS1.2
Note: The Protocols field now supports TLS1.3.
Cipher Suites
Specifies the priority of cipher suites to be used. The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:
!
Exclude. Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add. Add the cipher suite to the end of the collection. * - - Delete. Delete the cipher suite from the existing collection.
By default, the following cipher suite list is used:
kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
TLS1.3 Cipher Suites
The list of cipher suites to be used with TLS1.3 separated by a colon ':'. For example:
TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
Diffie-Hellman Minimum Group Size
Specifies the size in bits of the modulus length of the Diffie-Hellman group.Note: Micro Focus recommends a minimum modulus size of 2048 bits.
Key Exchange Cipher Groups
Key Exchange Cipher Groups - The key exchange cipher groups to be used, separated by semicolons ';'. For example:
secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1
TLS1.3 Middlebox Compatibility
Enables workaround for TLS1.3 on networks with incompatible middleboxes, for example, routers and firewalls. Disabling this can improve performance on compatible networks but might result in dropped connections otherwise.
Conversation Type
Specifies the conversation types that the listener supports:
WebServices and 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.
Note: This conversation type uses Legacy Micro Focus Application Format.
MSS Inter-System Communication (inbound only)
For CICS Intersystem Communication (peer-to-peer) and for requests for CICS transactions from non-CICS programs. This conversation type handles inbound calls only. 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.
Note: This conversation type uses Legacy Micro Focus Application Format.
CICS Transaction Gateway
This is similar in functionality to the previous two conversation types (MSS Inter-System Communication), except that it does not use Legacy Micro Focus Application Format.
Custom
This can be used for any other type of requests. You can select whether or not to use Legacy Micro Focus Application Format.
DCAS
Digital Certificate Access Server (DCAS) is a TCP/IP server that enables the generation of temporary user credentials from X.509 certificates. See DCAS conversation type for more information.
RFA
Remote File Access (RFA) is a feature of Enterprise Server which provides a set of Web APIs for reading, writing, creating, and deleting ordinary files, COBOL data files, cataloged datasets, and spool output datasets. See Remote File Access conversation type for more information.
Custom Configuration
Specify optional textual configuration information that determines the start-up and run-time behavior of the listener.
Description
Specify an optional text description of the listener, for example, its function and owner.
Status
Current status of the listener.
Requested Status
Change to request a new status for the listener. When a listener is started on a started region, this can be set to Stopped to stop the listener on this region.
Actual Address
The list of addresses where the listener is listening. This takes the form protocol:hostname or ip-address:port.
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.

Handlers and Packages

Use this to view a list of the request handlers registered for the currently selected server. From this tab you can also:

  • Edit the configurable settings of an request handler.
  • Add a new request handler.
Note: You cannot remove packages and handlers that are already in a service.
  • Create Service
    Use this page to add a new service to the current server.
  • Create Handlers
    Use this to view, add, and edit the request handlers registered for the currently selected server.
  • Create Packages
    Use this to view a list of the implementation packages registered for the currently selected server.
Parent topic: General


Create Service

Use this page to add a new service to the current server.
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, MFHRJSON, 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 is going to use the MFRHSOAP or MFRHBINP 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 is going to use 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
Specifies 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
Specifies 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
Specifies 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.
Transaction Management
Select 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.
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.
Available
Click this to set the service to available.
Handlers
Select the required request handler to be the associated handler. You must add a listener before you can see available handlers and associate a handler with the service.
Packages
Select the required package to be the associated package. You must add a listener before you can see available packages and associate a package with the service.
Configuration
Specify textual configuration information that determines the startup and run-time behavior of the service.
Description
An optional field that is used to specify a description of the service, for example, its purpose and owner.

Listeners

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.
Parent topic: Services


Create Handlers

From this page you can also:

  • Edit the configurable settings of an request handler.
  • Add a new request handler.
Note: You cannot remove packages and handlers that are already in a service.
Module Name
Specify the name of the request handler, up to 255 characters.
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.
Module Path
Specify the path where the request handler file is located.
Enabled
Check this to enable the handler.
Custom Configuration
This field is not used.
Description
An optional field that is used to specify a description of the service, for example, its purpose and owner.
Parent topic: Services


Create Packages

From this page you can also:

  • Edit the configurable settings of an implementation package.
  • Add a new implementation package.
Name
Specify the name of the new package, up to 255 characters. You cannot include angle brackets (<>) or ampersands (&) in the name.
Available
Check this to set the package to available.
Package Module
Specify the name of the library that contains the new package. You need to specify this only if the program is in a library that has a different name than the package name. Include the extension; library files have the extension .lbr or .dll on Windows, .lbr or .so on UNIX, .lbr or .sl on HP-UX PA-RISC.
Package Path
When a service is invoked, Enterprise Server will take the package path and append it to the COBPATH environment variable. The Run-time System will then load the package and execute the service.
Note: The COBPATH is dynamically modified for each service invocation.
IDT
Specify the pathname of the Interface Definition Table (IDT) for the package.
IDT 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.
Custom Configuration
This field is not used.
Description
An optional field that is used to specify a description of the package, for example, its purpose and owner.
Parent topic: Services


XA Resource

Use this page to view a list of the external resource managers registered with the currently selected server.

Click Edit to modify a resource manager definition.

Click Delete to delete an XA resource.

Click * New to add a new resource manager.

ID
The resource manager ID, used internally to identify a particular XA configuration.
Name
The name by which the resource manager is known.
Module
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.
Enabled
The status of the resource manager:
Enabled
Enables the XA resource.
Disabled
Disables the XA resource.
Reconnection attempts
The number of reconnection attempts to make.
Note: A value of 1 instructs it to continually retry the connection.

MFDS version 8 and later no longer supports XA reconnect attempts.

Open string
The string that is passed to the resource manager on the xa_open() call. It typically 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
The string that is passed to the resource manager on the xa_close() call.
Description
The optional text description of the resource manager definition.
Parent topic: General


Diagnostics

Use this page to change the trace attributes of a server.
CAUTION:
Changing the properties of a registered server might cause application connection errors and loss of data.

Diagnostic Options

Trace Table Size
Specifies the number of entries the trace buffer can hold before it wraps to the start. 2 specifies there is space for one entry. If Auxiliary Trace Active is checked then each entry is written to disk, and the trace buffer is written to disk when it wraps.
Local Trace Size
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.
Maximum Diagnostics File Size
Specifies the maximum size of the auxiliary trace and dump file in kilobytes. A value of 0 (zero) means that the file can grow to the maximum file size supported; 4GB.
Cold Start Diagnostics File
Check this to specify that the auxiliary trace and dump files are to be deleted when the server starts.
Dump on System Abend
Check this to specify 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 specify 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 specify that the server is to trace its task control component.
Storage Control
Check this to specify that the server is to trace its storage control component.
Table Management
Check this to specify that the server is to trace its table management component.
Application Container
Check this to specify that the server is to trace its application container component.
Request Handler
Check this to specify that the server is to trace its request handler component.
RM Interface
Check this to specify that the server is to trace its resource manager interface component.
Communications
Check this to specify that the server is to trace its communications component.
Application
Check this to specify that the server is to trace the CICS API calls made by a CICS application.
Exit
Check this to specify that the server is to trace user and system exits.
Parent topic: General


Historical Statistics

Use this page to configure the Historical Statistics Facility (HSF), this enables you to collect data about transactions.

Check Enable Collection of Historical Statistics Facility (HSF) Records to enable the collection of historical statistics for this server.

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 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
If you have checked 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).
Create JCL file records
This switches on the generation of JCL file (JCLF) records for 'mainframe' files. That is, 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 data set name in the same job, one record is created for each step in which the data set is accessed.
Number of Records Displayed for Monitoring
Specifies the number of HSF records that Enterprise Server will hold in memory. 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, the maximum is 4096.
Parent topic: General


Scripts

Use this page to edit advanced attributes of an enterprise server.

Click Apply to save the changes you make to the page, and refresh the page.

Start Script

Enabled
Check this to enable the enterprise server Start Script.
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.

Stop Script

Enabled
Check this to enable the enterprise server Stop Script.
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.

Not Responding Script

Enabled
Check this to enable the non-response script.
Connection attempts before execution
Specifies the number of reconnection attempts that you want to take place before running the script.
Script
Specify a script to be executed when there has been no response.
Parent topic: General


Validate

This page displays a validation report for the current region.

The report informs you of errors in the configuration of the region and warns you of any aspects of the configuration that might cause problems.

Click Update to run update operations and generate a validation report for the current region.

Note: The Directory Server will attempt to take actions to correct issues with the region you run the report for. The region's configuration might be modified.
Parent topic: General


Security

Use this page to define security settings that can be used with an enterprise servers.
Note: You cannot modify a region's security configuration while region is started.
Use Default Security Facility Configuration
Use the Default Enterprise Server security configuration for this Directory Server. Micro Focus recommends that you use this setting.
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.
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.
Use all groups
Check this if a user requesting authorization is to have the permissions of every group to which they belong. 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 TTL
Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be required from the security manager.
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.
Configuration Information
Specify any additional configuration settings that the security facility requires.
Parent topic: General


Advanced Region Properties

You can use this page to specify region-specific COBOL Application Server (CAS) properties.

The properties are split into feature groups that are displayed irrespective of the region's configured features.

Click Apply to save the modified properties and apply the changes to the startup configuration.

Click Show Dynamic to toggle the display of dynamic properties.

Click Install to apply the modified properties to the running region. Only dynamic properties can be modified and installed for a running region.
Note: These changes will not be applied to the startup configuration.
NAME
The name of the property.
VALUE
The specified value for the property, this field can be modified by double-clicking it and typing a new value or checking, depending on the data type.
ACTIVE VALUE
The specified active value for the property, the active value is the value currently being used for the started enterprise server region. This can be dynamically changed for some properties.
Note: The VALUE is the value that will be used the next time the enterprise server region starts.
METADATA
dynamic
This identifies whether a property can be dynamically updated or not. That is, it identifies if the variable can be viewed and updated whilst the region is running.
pac-wide
This identifies if a property is synchronized across the PAC for PAC or PFORCE updates. See ES Control for more information on the scope of values.
legacy-env
This specifies the legacy environment variable name of the property which will be overridden if applied to the startup configuration or installed. See Environment variables in alphabetical order for more information.
no-env-expansion
If set, this prevents the expansion of environment variables for a string type property, for example, $TXRFDIR.
DEFAULT VALUE
This is the default value of the property.
VALIDATION RULES
This indicates the valid value(s) or value range that can be specified for the property.
DATA TYPES
The property can be one of the following data types:
  • boolean
  • enum
  • integer
  • string
Note: There is an order of precedence for initial property values, ranked from highest to lowest:
  1. PAC-wide configuration provided by the PSOR.
  2. Any specified legacy environment variables.
  3. Data from MFDS used in the startup configuration.

The configuration for the CAS properties are stored in the cas.json file, located at %ProgramFiles(x86)%\Documents\Micro Focus\Enterprise Developer\etc\configdefinitions. Micro Focus recommends that you do not modify the cas.json file directly.

Remember: PAC members must be configured consistently. When considering an upgrade to the product version, Micro Focus recommends that you run the caspac -aCheckCompat command to validate that PSOR recovery will take place. See Performing a Product Upgrade to a PAC Environment for more information.
Parent topic: General


Monitor

This menu provides pages to view live properties, monitor, and view logs.
  • Live Properties
    Use this page to view system information for the server.
  • Monitor
    Use this page to view information on transactions that have recently occurred.
  • ES Control
    Use this page to view and change control information for this server.
  • SEPs
    This page displays information about the Service Execution Processes (SEPs) on the current server.
  • Internal Transaction Requests
  • TranClass Status
    Use this page to view and monitor information about TRANCLASS resource status.
  • Clients
    Use this page to view client information for this server:
  • PAC Client List
  • Locks
    Use this page to view the current resource locks on this server.
  • Environment Variables
    Use this page to view information about the environment variables used by this server.
  • Historical Statistics
    Use this page to view summary HSF information for this server.
  • Active Services
    You can obtain more information about services, packages, and handlers.
  • Dynamic Debug
    Use this page to view the debugging criteria for active dynamic debug sessions.
  • Pending Replies
    Use this page to view and reply to pending Accept From Console statements.
Parent topic: Regions


Live Properties

Use this page to view system information for the server.
Times
Displays 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
Displays 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.
Trace Blocks
The number of trace blocks generated since the server was started.
Pending Requests
The number of all requests that have been queued.
Clients Active
The number of clients that have been active since the server was started.
Clients Limit
The number of concurrent client licenses allowed.
Sizes
Displays 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 has been specified, this field is blank.
Extended User Storage
Memory allocation to the Extended User Storage area, in megabytes (MB).
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 in size.
Shared Memory Total
The amount of shared memory available to this server, shown in kilobytes (KB).
Shared Memory Cushion
The number of kilobytes (KB) 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.
Shared Memory Free
The amount of shared memory currently free, shown in kilobytes (KB).
States
Displays 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.
HSF
Displays which Historical Statistics Facility (HSF) is currently set to receive information, which can be A or B.
Dump
Displays 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
Displays 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:

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.
SIT
The name of the SIT currently used by this server.
SYSID
The system ID of the SIT.
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.
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.
ASCII CCSID
Identifies the ASCII CCSID that corresponds to the EBCDIC local CCSID specified in the SIT
Activity
Contains the following information:
Timings Latency (ms)
The average latency for transactions on this server. This is displayed in milliseconds (ms).
Rate (tasks/sec)
The average number of tasks completed per second on this server. This is displayed as a number.
Parent topic: Monitor


Monitor

Use this page to view information on transactions that have recently occurred.

You can view information on transactions that have occurred in the last n minutes, where n is 1 or 15 minutes. The display is cumulative, showing activity in n-minute intervals over the last 30 minutes for Monitor (1 minute intervals), and over the last 8 hours for Monitor (15 minute intervals).

Latency
This is plotted with circular data points and is the average latency for a transaction in hundredths of a second or milliseconds for millisecond enabled regions.
Task Time
This is plotted with square data points and is the average time taken to complete a tasks in hundredths of a second or milliseconds for millisecond enabled regions.
Task Rate
This is plotted with triangular data points and is the number of tasks completed within a second.
Note: You can click on the keys to toggle their exclusion/inclusion in the monitor.
Parent topic: Monitor


ES Control

Use this page to view and change control information for this server.

Click Stop to stop the current server.

Check Dump to take a system dump when the server is stopped.

Check Immediate to force an immediate stop. If you force an immediate stop, you will see "The page cannot be displayed" error, as there is no longer a server to connect to.

Enter Message
To send a message to all clients, type the message and then click Message All
Apply Scope
For a PAC, all changes to timeouts, trace flags, and memory strategy will be applied to:
Local
Only the local region.
PAC
All members of a PAC except the regions where local changes have been made.
PForce
All members of a PAC.

General

SEPS
Displays 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
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 SEPs
The number of Admin SEPs defined.
Initial Transaction
The transaction to run when a TN3270 session connects to the server.
Transaction Threshold
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.
HTTP Out
Displays 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
Displays the time in minutes that the system will allow an ESMAC or TN3270 client session to remain idle before session timeout. 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.
Note: If you change the value, the change will not be saved at system shutdown.
Runaway
Displays 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.
Note: If you change the value, the change will not be saved at system shutdown. You can override this value for an individual transaction through the relevant Program Control Table entry.
Input
Displays 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.
Note: If you change the value, the change will not be saved at system shutdown. You can override this value for an individual transaction through the relevant Program Control Table entry.
Deadlock
Displays 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.
Note: If you change the value, the change will not be saved at system shutdown. You can override this value for an individual transaction through the relevant Program Control Table entry.

Diagnostics

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.
Switch Dump Set
Click this to switch between the A and B data sets that are used to store dump information.
Switch Trace Set
Click this to switch between A and B data sets used to store trace information.
Size
Displays 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
Displays the current data set used for dump information.
Dump Count
Displays the number of dumps (n) that have occurred.
Trace 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.
Trace
Displays the current data set used for trace information.
Blocks
Displays the number of blocks of trace information captured.
Dump on ABEND Sys
Check this to produce a dump if an abend occurs due to an error in Enterprise Server itself.
Dump on ABEND Tran
Check this to produce a dump if an abend occurs due to a problem with any of your transaction programs. When checked, you can further control the contents of the dump file on the program level by checking or unchecking Dump on abend on the PCT Properties dialog box for a specific program. When unchecked, the setting of Dump on abendis ignored.
Debugger
Check this to enable dynamic debugging.
Enable Failure Reporting
Check this field to enable the generation of the Application Diagnostic report for this enterprise server instance. See Application Diagnostic Reporting for Enterprise Server for more information.
Core Dump on Report
Check this to enable the generation of a core dump in the Application Diagnostic report. See Application Diagnostic Reporting for Enterprise Server for more information.
Print Environment on Report
Check this to enable the printing of the contents of COBCONFIG and MFTRACE_CONFIG in the Application Diagnostic report. See Application Diagnostic Reporting for Enterprise Server for more information.
Local Trace on Report
Check this to enable printing the local trace table in the Application Diagnostic report. See Application Diagnostic Reporting for Enterprise Server for more information.
Dynamic CTF File Location
Specify the location of the dynamic CTF configuration file to use when tracing this enterprise server region.
CTF Action
Specify the dynamic CTF action for tracing based on the dynamic CTF configuration file provided:
As on file
The CTF trace will be set as specified in the dynamic CTF configuration file. The output location for the trace will be either the location configured by the original configuration file if MFTRACE_CONFIG was specified before starting the enterprise server region, otherwise it will use the enterprise server region's working directory.
All on
The CTF trace will be configured for "debug" on all components that have an mftrace.level.component_name entry in the dynamic CTF configuration file. The output location for the trace will be either the location configured by the original configuration file if MFTRACE_CONFIG was specified before starting the enterprise server region, otherwise it will use the enterprise server region's working directory.
All off
The CTF tracing will be disabled for all components that have an mftrace.level.component_name entry in the dynamic CTF configuration file.
CAUTION:
You must set the CTF Action field to All off before modifying the Dynamic CTF File Location or the file's content. Failure to do this will result in memory corruption.

HSF Data

Switch
Click Switch to switch collection to the alternate .csv file before the active file has reached the maximum size.
Enable HSF Collection
Check this to switch 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 SWITCH 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.
Max HSF Size
If you have checked 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 of 0 selects the maximum size possible (4 Gb).
Number of ESMAC Records
This displays the number of HSF records that Enterprise Server will hold in memory. When this number is reached, older records will be deleted when a new one is created. In addition, records older than one hour are deleted. The minimum value is 0 (no HSF data is displayed), the maximum is 4096.
Create JCL File Records
Check this to switch on the generation of JCL file (JCLF) records for 'mainframe' files, such as 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 data set name in the same job - one record is created for each step in which the data set is accessed.

TSC Data

Overview
Click Overview to open the TSC Data dialog box that displays a summary overview of the TSC data store.
Detail
Click Detail to open the TSC Data dialog box that displays details of the TSC data store object that starts at (block-number)/(segment-number).
Max
Specifies the limit for the size of the data store repository which contains all TS and intra-partition TD data when TranClass is enabled. This repository also contains the latest three keypoints (system state) as well as static system state items and XA recovery information.
Current Blocks
The number of 62,992 byte blocks of data store each containing 254,248 byte segments (allocation units).
Cushion
The reserved proportion of the data store that is released when a data store allocation request is required. Once released, system function is restricted until it can be re-acquired. This is a mechanism to soften the impact of running out of data store space.
Aggregate
If this is not checked, castsc flushes the OS data store buffers at thread transactional recovery boundaries.
Aggregate Time
Specifies the number of milliseconds a castsc thread OS data store buffer flush request will wait for other threads to present flush requests that can be aggregated with it before proceeding with the physical OS buffer flush request. The single OS buffer flush request satisfies all the thread requests accumulated behind it.
Disable Flush
Check this to disable all explicit OS data store flush requests within castsc.
TS Queue Expiry
Temporary Storage data queues contain a last operation date/time stamp. When this value is non-zero, a check is made periodically and non-protected queues that have not been referenced within the specified time frame are discarded.
Note: TSQ table entries can override the system default value for individual queues and groups of queues.
Keypoint Frequency
Specifies the number of transactional recovery boundaries that are encountered before the next keypoint is executed.
Keypoint Count
This is the count of keypoints executed since the server was started.

Trace

Displays the currently set trace points. The trace points displayed are those that have been set by the SIT. You can change individual trace points by checking each trace point required, or you can click All to check all trace points.
Note: This overrides the trace points set by the SIT. Any changes you make are effective at the point you click Apply. The changes are lost the next time the server is initialized.

Server

app-cont
Check this to indicate that MSS is to trace its Application container component.
mfcm
Check this to enable Configuration Manager tracing.
lock-data
Check this to trace lock management for non-threaded processes.
tmp
Check this to indicate that MSS is to trace its table management component.
tsc-data
Check this to trace the data in calls to the castsc process.
cluster
Check this to trace ES Cluster component.
msg
Check this to indicate that MSS is to trace its messages component.
trc
Check this to indicate that MSS is to trace the castrc process.
tsc-enq
Check this to indicate that MSS is to trace its castsc enqs component.
dmp
Check this to indicate that MSS is to trace its dump control component.
reqh
Check this to indicate that MSS is to trace its request handler component.
trc-data
Check this to indicate that MSS is to trace its castrc data.
tsc-mon
Check this to indicate that MSS is to trace its castsc monitors.
exits
Check this to indicate that MSS is to trace the user exits.
rm
Check this to indicate that MSS is to trace its resource manager component.
trc-enq
Check this to indicate that MSS is to trace its castrc enqs component.
tsc-thread
Check this to trace thread processing and lock management in the castsc process.
fh
Do not check this unless advised by Micro Focus.
saf (Security)
Check this to trace System Authorization Facility (SAF) calls.
trc-thread
Check this to indicate that MSS is to trace the castrc thread.
tsc-trd-stg
Check this to indicate that MSS is to trace the castsc thread storage.
fh-enable
Do not check this unless advised by Micro Focus.
scp
Check this to indicate that MSS is to trace its storage control component.
trc-trd-stg
Check this to indicate that MSS is to trace its castrc thread storage.
xfp
Check this to trace data in transformer processing.
jcp
Check this to indicate that MSS is to trace its journal control component.
sql-api
Not used.
tsc
Check this to trace calls to the castsc process.
xfp-all
Check this to trace data and processes in transformer processing.
kcp
Check this to indicate that MSS is to trace its task control component.
srv
Check this to indicate that MSS is to trace its service handler component.
tsc-buffer
Check this to indicate that MSS is to trace its castsc buffer component.
xfp-data
Check this to trace data in transformer processing for threaded processes.

RAS

Casras is a PAC related process that manages CICS resources, ensuring that they are in synchronization between regions:

ras
Check this to trace the casras process.
ras-thread
Check this to trace the casras thread component.
ras-data
Check this to trace the casras data component (currently unused).
ras-enq
Check this to trace the casras enqs component.
ras-data-all
Check this to trace the casras all data component (currently unused).
ras-trd-stg
Check this to trace the casras thread storage component.

CICS

api
Check this to indicate that MSS is to trace the CICS API calls.
fcp
Check this to indicate that MSS is to trace its file control component.
pcp
Check this to indicate that MSS is to trace its program control.
ts-td
Check this to indicate that MSS is to trace its temporary storage/transient data (TS/TD) component.
icp
Check this to indicate that MSS is to trace its interval control component.
tcp
Check this to indicate that MSS is to trace its terminal control component.
user
Check this to enable a user trace.

Communications

cci
Do not check this unless advised by Micro Focus.
com-enq
Check this to trace the comms enqs component.
sna
Check this to trace the cassna process.
sna-thread
Check this to trace the cassna thread component.
com
Check this to trace the comms process.
com-mfcs
Check this to trace the comms - mfcs component.
sna-data
Check this to trace the cassna data component.
sna-trd-stg
Check this to trace the cassna thread storage component.
com-data
Check this to trace the comms data component.
com-thread
Check this to trace the comms thread component.
sna-data-all
Check this to trace the cassna all data component.
com-data-all
Check this to trace the comms all data component.
com-trd-stg
Check this to trace the comms thread storage component.
sna-enq
Check this to trace the cassna locking component.

Memory Strategy

Use this diagnostic feature to control the frequency and type of run-time 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 OpenText Support for Micro Focus Products, Micro Focus recommends that you use only the default settings, which result in the most efficient use of memory. Setting these values inappropriately might result in a degradation of system performance and excessive memory usage.

Using invasive settings in a development or user acceptance environment might be acceptable and even desirable, but you should use 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.

Parent topic: Monitor
Related information
ES_MAX_HTTP_OUT


SEPs

This page displays information about the Service Execution Processes (SEPs) on the current server.

Click Data Displays for the TSC Service to view the TSC Data.

Click Queue Display for the IMS Service to view the queue.

You can view, stop, or kill some processes by clicking the appropriate icon at the end of the row.

Type
Displays the type of service that is 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.
Process ID
This column displays the Process ID.
Task Number
This column displays the task number for the service. You can view which clients are associated with a Process ID by displaying the Clients page, click Monitor > Clients.
Count
This column displays the number of jobs this SEP has run since it was started.
Activity
Start Time
This column displays the time at which the service was started.
Duration
This column displays the amount of time the service has been running.
Client
This column displays the Process ID (PID) of the client using this server.
Wait ID / Duration
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.
Service ID / Transaction ID
This column displays the service or transaction ID belonging to the process where available.
Transaction
This column displays the transaction where available.
Function
This column displays the function.
User ID
This column displays the ID of the signed-on client that is currently being processed.

IMS MPR Processes

Name
The IMS MPR process name.
Process ID
The process ID of the Message Processing Region (MPR) SEP.
Message Number
The task number of the current or last message processed.
Message Classes
The IMS Message Classes (up to four) that can be scheduled in this MPR.
Message Count
The count of messages processed by this MPR during the current Enterprise Server run.
Start Time
The local OS time of day that the current transaction was initiated or blank if there is no current transaction being processed.
Duration
The delta between the start time (if any) and the time this display was constructed.
Transaction ID
The transaction ID of the current Message Processing Program (MPP) scheduled in the MPR or blank.
Source / Status
Source is the LTERM that was the source of the current message being processed. Status is displayed between messages, such as:
  • Idle
  • WFI - Wait For Input
  • pWFI - Psudio Wait For INPUT, that is, waiting for input because of MPR definition rather than the transaction definition.
IMS Type
PWFI or blank, populated based on the configuration of the MPR.
PROCLIM
The number of messages that will need to be processed before the MPR reaches its processing limit. The current transaction's PROCLIM definition minus the number of messages that the MPP has already processed during this schedule. The MPR might not be rescheduled for a different MPP until this limit is reached or, for non-WFI, no further messages are waiting for this transaction/MPP. The lower limit is a value of 0 (zero).
Parent topic: Monitor


Internal Transaction Requests

This page displays the Internal Transaction Requests (ITRs) for the enterprise server region. An ITR is created and sent to each SEP. In a PAC, these ITRs are sent to all member regions within the PAC and are then distributed to every SEP in that region. For example, when requesting a NEWCOPY of a program, the SEP that accepts the request, will then issue an ITR to tell all other SEPs to fetch a NEWCOPY of that program.

Resource Name
This is the name of the resource the ITR was issued to. For example, issuing a NEWCOPY request for a program will be sent to the name of that program.
ITR Type
This is the ITR type classification. For example, issuing a NEWCOPY request for a program, will result in a "program" type. Possible values are:
File
Transient Data
Program
Terminal
Abend Fail
Fileshare Fail
IMS TMC Fail
IMS Transaction Manager Control fail
IMS DBC Fail
CASTSC Fail
COBOL Application Server
End Conversation
End Debug
End Transient
End Generic
End Generic Silent
Post Expired
SEP Dirty
XA Event
Purge Transaction
IMS DB
Unknown(n)
ITR Command
This is the command to be performed on the resource. For example, issuing a NEWCOPY request for program, will have a NEWCOPY value. Possible values are:
Open
Close
Load
Delete
NEWCOPY
Cancel
XA Changes
Cancel EoT
End of Task
PAC Rescount
PAC Discard
Requestor PID
This is the process ID of the process that issued the ITR.
Target PID
This is the process ID of the process that will process the ITR.
DCA Type
This is the type of SEP the ITR is targeting. Possible values are:
Inactive
CASMGR
SEP
System
Surrogate
Session
Batch Initiator
Fileshare
Spool
Transient SEP
Printer
IMS MPR
IMS TM
IMS DB
Event Manager
Admin SEP
CASTSC
CASTRC
CASSNA
CASMQB
CASRAS
CICS Web
Interface or CICS Web Services
CASRECDB
Requestor UUID
This is the Universal Unique Identifier (UUID) of the enterprise server region which issued the ITR.
Target Region
This is the enterprise server region that will process the ITR.
PAC Status
This is the status of the PAC ITR. Possible values are:
Unprocessed
Pending
Processing
Parent topic: Monitor


TranClass Status

Note: This feature can only be used if your product is enabled for Mainframe Subsystem Support (MSS).

Each TRANCLASS resource specifies the characteristics of a transaction class.

Registered SEPs
The number of registered service execution processes.
Available SEPs
The number of available service execution processes.
Pending Requests
The number of pending requests.

The Active SEPs table displays the following information:

Type
This column displays the type of service.
Process ID
This column displays the process ID.
Task Number
This column displays the task number for the service.
Count
This column displays the number of jobs this SEP has run since it was started.
TranClass
TRANCLASS name.
Start Time
The time at which the service was started.
Duration
The amount of time the SEP has been running.
Transaction ID
Where available, this will display the transaction ID.
Client
This column displays the process ID (pid) of the client using this server.
User ID
This column displays the user ID of the signed-on client that is currently being processed.
Max Active
This column displays the maximum number of transactions in this transaction class that can be active.
Service
This column displays the type of service.

The Available SEPs table displays the following information:

Type
This column displays the type of service.
Process ID
This column displays the process ID.
Count
This column displays the number of jobs this SEP has run since it was started.

The Queued Requests table displays the following information:

Region
The name of the region that spawned the task.
Machine
The machine name that the region that spawned the task is running on.
Region UUID
The UUID of the region that spawned the task.
TranClass
The TRANCLASS name.
Process ID
The process ID.
Task Number
The task number for the service.
Transaction ID
Where available, this displays the transaction ID.
Terminal ID
The ID of the terminal that spawned the task.
Parent topic: Monitor


Clients

Use this page to view client information for this server:

You can display, dump, or stop certain clients by clicking the appropriate icon at the end of the row.

Process ID
Displays a Process ID of the client.
Type
Displays the type of client, such as Generic, Other, Spool. For a full list of types see your product Help.
Net Name
Displays the assigned SNA network node name for that client.
User ID
Displays 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.
Active
Displays if the client is active.
Parent topic: Monitor


PAC Client List

This page provides a list of PAC members:

User ID
Specifies the user that the client belongs to.
Group ID
Specifies the user's group that the client belongs to.
Region
Specifies the enterprise server region's name.
Net Name
Specifies the assigned Systems Network Architecture (SNA) network node name for that client.
PAC UUID
Specifies the Universal Unique Identifier (UUID) of the PAC member and is used for identification purposes in a PAC.
Parent topic: Monitor


Locks

Use this page to view the current resource locks on this server.

You can remove locks if necessary. Contact OpenText Support for Micro Focus Products for more information and guidance on removing locks. To remove locks, click Remove Locks. This opens the Enable Lock Removal dialog box. If you accept the risk associated with removing locks and want to proceed, check I understand and want to proceed. This will enable the Remove Lock option in the Actions column. Clicking this will open the Remove Lock? dialog box which will prompt you to confirm the action.

CAUTION:
Incorrectly removing locks can result in system instability and corruption or loss of data.
Owner Process ID
The process ID (PID) of a process that has issued a lock or wishes to issue a lock.
Owner Process TID
The thread/task ID that owns the process.
Owner Lock Info
The Job No and Job Step of the lock owner.
ID
The 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
The type of lock. This can be either:
  • Exclusive
  • Shared
State
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 asynchronous request.
Persistence
Displays 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.
Sequence
The order in which requesters are to be handled.
QNAME
The type of target resource for the lock.
RNAME
The target resource name for the lock.
Share Mode
This can be either:
  • Exclusive
  • Shared
Length
The length of the resource name in characters.
Name
The name of the resource given to it by the requester.
Hex
The name of the resource given to it by the requester in hex, where applicable.
Scope
The scope for the lock:
N/A
Not applicable. This occurs when the enterprise server region is the Global Lock Manager.
LOCAL
The lock is local.
GLOBAL
The lock is global.
Parent topic: Monitor


Environment Variables

Use this page to view information about the environment variables used by this server.
Environment Name

Lists all of the environment variables currently in use by the server.

Environment Value
Lists the values for all of the environment variables listed in the Environment Name column.
Parent topic: Monitor


Historical Statistics

Use this page to view summary HSF information for this server.

This shows the period of time, displayed in milliseconds, next to Historical Statistics between the earliest records displayed and the current time. Records older than one hour are deleted. The following information is displayed for each transaction:

Transaction Count
Provides a count of how many times the task has run. Displayed as a crosshatched bar.
Average Latency (ms)
The average time, in milliseconds, between Enterprise Server receiving the requests and the tasks beginning to run. Displayed as a forward slash bar.
Average Response Time (ms)
The average time, in milliseconds, that the tasks ran for. Does not include latency time. Displayed as a backslash bar.
Note: You can click Toggle View to switch between the default and table view.
  • Historical Statistics Detail for Transaction
    Use this page to view detailed HSF information for a transaction.
Parent topic: Monitor


Historical Statistics Detail for Transaction

PID
This is the process ID of the SEP which ran the task.
Task Number
A unique task number.
Date and Time
The date and time the task started to run.
Time Data
A graphical representation of the latency and response times.
Latency
Latency time average, in milliseconds (ms).
Response Time
Response time average, in milliseconds (ms).
Logical Unit
For CICS tasks, the logical unit or net name is the identifier of the terminal used to initiate the task.

For JCL, this is 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, for example, STEP01 are generated when a step ends. JOBEND records are generated when a job completes.

Program Name
For CICS and IMS tasks, this is the program name.

For JCL, this is the program name or the job number, depending on the JCL record type.

User
For CICS tasks, this is the ID of the user that initiated the task.

For JCL STEP and END records, this is the condition code or an error string.

Note: You can click Toggle View to switch between the default and table view.
Parent topic: Historical Statistics


Active Services

You can obtain more information about services, packages, and handlers.
  • Active Services
    Use this page to view information about a particular service.
  • Active Packages
    Use this page to view information about a particular implementation package. You can also use this page to force the load of a new copy of the IDT.
  • Active Handlers
    Use this page to view information about a particular request handler.
Parent topic: Monitor


Active Services

Use this page to view information about a particular service.

Click Edit to display the Active Service Overview dialog box.

In the Active Service Overview dialog box, click View Package to open the corresponding Active Package Overview dialog box.

In the Active Service Overview dialog box, click View Handler to open the corresponding Active Handler Overview dialog box.

Name
Displays the service namespace.
Transaction
Displays the characteristics of the service. The characteristics relate to the commit/rollback of protected resources accessed by the service. Values can be:
  • Container Managed
  • 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
Specifies whether, for each request for this service the request and response blocks are written to the enterprise server dump data set:
None
Nothing is logged.
Dump
Request and response blocks are written to the enterprise server dump data set.
Note: Only use this option if you need diagnostics, as it can degrade performance.
Reference Count
Displays the number of applications that reference this service.
Service Status
Displays the current status of the service:
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.
Package
The name of the package this service is associated with.
Package Status
Displays the current status of the package:
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.
Request Handler
The name of the handler this service is associated with.
Handler Status
Displays the current status of the handler:
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: Active Services


Active Packages

Use this page to view information about a particular implementation package. You can also use this page to force the load of a new copy of the IDT.

Click View to open the Active Package Overview dialog box.

Name
Displays the name of the implementation package for this service.
IDT
Displays the path of the IDT (interface definition table) for the package.
IDT Size
Displays 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 IDT 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 IDT Copy removes it, forcing the system to reload the IDT from disk the next time a service requests it.
Module
Displays the name of the library that contains the package, if any.
Status
Displays 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.
Reference Count
Displays the number of programs that have made use of this package since the server started.
Location
Displays the path where the package file is located.
Parent topic: Active Services


Active Handlers

Click View to open the Active Handler Overview dialog box.

Name
Displays the name of the request handler.
ID
Displays the unique ID assigned to this handler by the server.
Status
Displays 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
Displays the type of request handler:
  • Other
  • Soap
  • CGI
  • Undefined
Reference Count
Displays the number of programs that have made use of this handler since the server started.
Location
Displays the path where the handler is located.
Parent topic: Active Services


Dynamic Debug

Use this page to view the debugging criteria for active dynamic debug sessions.
Type
The type of application or service being debugged.
Criteria
The criteria used to identify the application or service instance to debug.
Process ID
The Process ID or PID of the application or service being debugged.
Note: Stopping an active debug session in ESCWA does not end the debugging process in the IDE.
Parent topic: Monitor


Pending Replies

Use this page to view and reply to pending Accept From Console statements.

The table displays a list of the Accept From Console statements that are pending a reply:

Process ID
This is the Process ID of the job waiting for a reply.
Description
This is a description of the job waiting for a reply.

To reply to an Accept From Console statement:

  1. Click the Reply icon belonging to the process that you want to reply to. This opens the Send Reply dialog box.
  2. In the field, type the reply, and then click Reply
Parent topic: Monitor


Logs

You can obtain more log information from the Console, Communications Process Log, Trace, and Dumps.
  • Console Logs
    The console contains the region activity since startup and hence shows what happened leading up to a failure.
  • Communications Log
    Communications (MFCS) log messages are displayed on this page.
  • Trace
    Use this page to view trace information contained in a data set or in memory.
  • Dumps
    Use this page to view dump information, contained in a data set, for the transactions on this server.
Parent topic: Regions


Console Logs

The console contains the region activity since startup and hence shows what happened leading up to a failure.

You should review this log to see which errors have occurred, when they occurred, and which process was responsible. The Process ID and time from this log lets you associate other log entries with this particular error or entry in the console log.

You can specify the page and number of lines to display and then page through the log by clicking forwards ( forwards) backwards ( backwards) or by jumping to the start ( jump to start) or the end ( jump to end).

Parent topic: Logs


Communications Log

Communications (MFCS) log messages are displayed on this page.
Timestamp
The date and time stamp at the point the message was created.
Comms Process ID
This is an instance identifier.
Message
The message contained in the log file.

By default, there is only one log file which grows continuously until it is deleted by an administrator. 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. 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, and so on. When a log file reaches a configured size, MFCS moves on to the next file. If the file already exists then it will be deleted first. When it reaches the configured number of log files, it returns to log-1.html, overwriting it.

See Communications Process Log Files for more information.

Parent topic: Logs
Related information
Communications Log


Trace

Use this page to view trace information contained in a data set or in memory.

Stores can be A or B, for the A or B data sets, or X to indicate an in-memory trace.

Click Details to see detailed information for the trace selected.

Blocks
Specifies 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 value is 1000 blocks.
Level
Specifies the 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 entries.
3
All entries where it is possible to provide some formatting of the data.
4
All trace entries.
PIDS
These are the Process IDs (PIDS), if you want to filter the details by PIDS, check the PIDS of the processes you want detailed trace information for.
TIDS
These are the Task IDs (TIDS), if you want to filter the details by TIDS, check TIDS of the tasks you want detailed trace information for.
Parent topic: Logs


Dumps

Use this page to view dump information, contained in a data set, for the transactions on this server.

The data set can be A, B, or X.

Timestamp
The time stamp is in hours, minutes, seconds, and hundredths of a second.
PID
The Process ID (PID).
Code
A code that helps identify the dump.
Caller
The origin of the dump request.
Level
Displays the level of trace information in the dump:
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.
Parent topic: Logs


CICS

This menu provides pages that enable you to manage CICS configuration and resources.
Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).
  • CICS Configuration
    Use this page to configure CICS support for this server.
  • CICS Resources
    Use this page to display, modify, and add CICS resources.
Parent topic: Regions


CICS Configuration

Use this page to configure CICS support for this server.
System Initialization Table
Specify the system initialization table (SIT) to be used by this enterprise server. This defaults to DFH$IVP.
Resource Definition File Path
Specify the full path of the resource definition file for this enterprise server. Mandatory if you use a SIT other than 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 a SIT other than DFH$IVP.
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 a SIT other 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 a SIT other than DFH$IVP.

EZASOKET Support
Check this to enable support for CICS and JCL applications that use the EZASOKET APIs.
Parent topic: CICS


CICS Resources

Use this page to display, modify, and add CICS resources.

You can filter the resources displayed by selecting from the resource list:

By Group
This includes:
  • SIT
  • Startup Lists
  • Groups
By Type
This includes:
  • Bundle
  • DCT
  • DocTemp
  • ENQ Model
  • FCT
  • JCT
  • PCT
  • Pipeline
  • PLT
  • PPT
  • Sys62
  • SysC
  • TCPIPSv
  • Term
  • TRANCLASS
  • TS Model
  • TST
  • T-Type
  • URIMap
  • WebService
  • XAT
In Startup List
This includes:
  • DCT
  • ENQ Model
  • FCT
  • JCT
  • PCT
  • PLT
  • PPT
  • Sys62
  • SysC
  • Term
  • TS Model
  • TST
  • T-Type
  • XAT
  • DocTemp
  • TCPIPSv
  • URIMap
  • Threshold
Active
Lists active resources.

To filter by resource name, in the Resource Filter field, type a string of characters to search for and then click Filter. Only the resource names that contain the specified characters will be displayed.

To create a new SIT click SIT, and then click * New

To create a new Startup List click Startup Lists, and then click * New

To create a new Group click Groups, and then click * New

Note: Some resource types will not be available depending on the configuration of the enterprise server region.
  • CICS Resources - SIT
    Use this to view, add, or edit a resource in all SITs available to this enterprise server.
  • CICS - Startup Lists
    Use this to view, add, or edit a resource in the startup lists on this enterprise server.
  • CICS - Groups
    Use this to view, add, or edit a resource group.
  • CICS - Active
    Use this to view, add, or edit an active resource.
Parent topic: CICS


CICS Resources - SIT

Use this to view, add, or edit a resource in all SITs available to this enterprise server.
Name
The name of the SIT.
Description
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.
Group List
Type the group lists that you want to associate with this SIT. You can specify up to four comma-delimited patterns that matches a Startup List. This means that the SIT can use more than one Startup List. Each pattern can be up to 8 characters long and must only contain A through Z, 0 through 9, @, and the wildcard characters $, #, *, and +.
Note: Using multiple startup lists loads more resources into the process shared memory which might have an impact on an enterprise server region's performance. Micro Focus recommends you limit active resources where possible.
Development SIT
Check this to indicate that this is a development SIT. If you have specified a group with the same name as the SIT, the group is automatically added to the startup list and security is turned off even if the group has security turned on.
Work Area (CWA)
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.
Minimum Commarea
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. When a program is passed to a COMMAREA smaller than the COMMAREA specified in the program, the passed COMMAREA is automatically extended in length to fill the defined space.
SysID
Specifies the system ID of the region. This is the name by which it is known to other regions.
Initial Tran ID
Specifies the ID of an initial transaction that runs on every terminal when it logs on to the region.
Force Program Phase In
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.
Defer Install Groups (PCTs only)
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.
Addressing Mode
Specifies the format in which pointers are stored:
Native
Pointers are stored in the format used by the operating system.
24 Bit
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 your code.
31 Bit
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 your code.
Program List Post Initialization (PLTPI)
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.
Program List Shut Down (PLTSD)
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.
IBM Client Sessions
The number of IBM Universal Client sessions you want allocated to servicing inbound requests per connection, where connection corresponds to a client machine.
CICS Release
The version of CICS that MSS is emulating. This is the number returned by an EXEC CICS INQUIRE SYSTEM RELEASE () command.
NQRNL
Enable global resource serialization to use RNL processing for enqueue and dequeue requests from CICS.
TCP Connect
Not used.
Port
Not used.

3270

Auto Install Exit
The name of the program to be used to autoinstall terminals:
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.
3270 Print
Check this to indicate that the region supports a printer.
Print Destination
Specify the printer destination, up to 14 characters in length. You must check 3270 Print before you specify a printer destination.
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 on orig sys
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.
Force Terminal Wait on Send
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.
GMTRAN
The disconnect parameter for CESN transaction. If Exit is selected a user can do F3/Clear to terminate CESN/CESL. If Disconnect is selected, a user will see the TN3270 disconnected if F3 or clear is used.

Date & Time

Reset Time
The action that CICS should take to handle automatic time changes:
Immediate
The system detects a timezone (date) change at any time. It then changes the clock in the region on the next transaction which is started.
No
The system detects a timezone change at midnight and writes a notification in the console.log. You then need to run a transaction that will issue the PERFORM RESETTIME for the time to be changed.
Yes
The system detects a timezone change at midnight and automatically resets the clock.
Date Format
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.
Date Separator
The character used to separate the day, month and year components of the date. You can specify any displayable character.
Time Separator
The character used to separate the hours, minutes and seconds components of the time. You can specify any displayable character.

Thresholds & Timeouts

ID Timeout
The time in minutes that the system will allow an ESMAC or TN3270 client session to remain idle before session timeout. A value of 0 indicates that there is no timeout.
Input Timeout
The maximum time in seconds allowed for an operator response to an explicit CICS RECEIVE command before the transaction is abended. A value of 0 indicates that there is no timeout.
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. You can override this value for an individual transaction through the relevant Program Control Table entry.
Deadlock Timeout
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 for an individual transaction through the relevant Program Control Table entry.
Transaction Threshold
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: All fields in this group have been deprecated and are provided for backward compatibility only.
IBM MQ
Check this to enable support for IBM WebSphere MQ. See Configuring Enterprise Server for IBM WebSphere MQ in your product Help for more information.
IBM MQ CKTI
Check this to enable the transaction CKTI, which monitors the IBM WebSphere MQ initiation queue.
Q Manager
The name of the IBM WebSphere MQ queue manager. Can be up to 48 characters.
Initiation Q
The name of the IBM WebSphere MQ initiation queue. Can be up to 48 characters.

Dump & Trace

Cold Start Dump & Trace Datasets
Check this to indicate that the auxiliary trace and dump file is to be deleted at region startup.
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.
Local Trace Entry Count (MFCS)
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 Enterprise Server Administration. If you specify a value here it overrides that value.
Local Trace Entry Count (AUX)
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, and so on. 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 Enterprise Server Administration. If you specify a value here it overrides that value.
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.

Fileshare

Fileshare Integrated
Check this to create a dedicated Fileshare server process as part of region startup.
Fileshare User
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 100 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. See Security in the Fileshare Guide chapter of your product Help.
Fileshare User Password
The password used in conjunction with Fileshare User 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 100 characters.

Shutdown

External Shutdown
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 by 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
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.

Temporary Storage

Cold Start
Check to indicate that MSS should reset temporary storage queues at region startup.
FS Server
A Fileshare server ID for non-recoverable temporary storage queues.
Path (nr)
The path for non-recoverable temporary storage queues.
Cold Start
Check this to indicate that MSS should reset temporary storage queues at region startup.
FS Server
A Fileshare server ID for non-recoverable temporary storage queues.
Path (rc)
The path for recoverable temporary storage queues.

Transient Data

Cold Start
Check this to indicate that MSS should reset transient data queues at region startup.
FS Server
A Fileshare server ID for non-recoverable transient data queues.
Require Def.
Check this 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 might result in unexpected program and/or system behavior if the intention was to write to a pre-defined TDQ of a similar name. Micro Focus recommends that this option is always checked.
Path (nr)
The path for non-recoverable transient data queues.
Cold Start
Check this to indicate that MSS should reset transient data queues at region startup.
FS Server
A Fileshare server ID for non-recoverable transient data queues.
Path (rc)
The path for recoverable transient data queues.

Trace Points - Server

cluster
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.
trd
dmp
Check this to indicate that MSS is to trace its dump control component.
kcp
Check this to indicate that MSS is to trace its task control component.
srv
Check this to indicate that MSS is to trace SEP-hosted task control functions.
xfp-all
All
exits
Check this to indicate that MSS is to trace the user exits.
lock-data
tmp
Check this to indicate that MSS is to trace its table management component.
xfp-data
fh-enable
Do not check this unless advised by Micro Focus.
mds
trd-enq
xfp
fh
saf (security)
trd-stg

JCL/JES

common
Check this to indicate that MSS is to trace its communications component.

CICS

api
Check this to indicate that MSS is to trace the CICS API calls.
fcp
Check this to indicate that MSS is to trace its file 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.
cws
icp
Check this to indicate that MSS is to trace its interval control component.
tcp
Check this to indicate that MSS is to trace its terminal control component.
user
Check this to enable user trace.

IMS

data
DB_ctl
storage
TM-ctl

Communications

cci
Do not check this unless advised by Micro Focus.
com-data
com-mfcs
com
com-data-all

Basic Mapping

Paging Command
Retrieve
Specify the character string that BMS control is to interpret as the BMS paging command RETRIEVE.
Chain
Specify the character string that BMS control is to interpret as the BMS paging command CHAIN.
Purge
Specify the character string that BMS control is to interpret as the BMS paging command PURGE.
Copy
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 to equate to a BMS paging command. Prefix the character string with the command you want to execute when the key is pressed, followed by any additional commands. For example, if the BMS PAGIN RETRIEVE command is set to /P and you want PF1 to execute a page forward, specify the /PN character string where /P executes the BMS PAGIN RETRIEVE command and N executes NEXT.
Parent topic: CICS Resources
Related reference
Configuring Enterprise Server for IBM WebSphere MQ
Security
Related information
CICS_SIT


CICS - Startup Lists

Save
Click this to save changes you have made to the page and refresh the page.
Note: This button is only displayed if you have permission to edit the startup list.
Delete
Click this to delete the startup list. You will be prompted to confim the delete.
Note: This button is only displayed 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 display a dump of the startup list information.
+ Add
Click this to add a new group.

Startup list properties

Name
The name of the startup list.
Description
A short description of the 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.

Groups

A list of resource groups is displayed in the startup list. A startup list can reference up to 64 resource groups.

To add a resource group:

  1. Click a startup list, and then click + Add.

    This opens the Available Groups dialog box.

  2. Check the resource group required.
  3. Click Select.

You can change the order of the resource groups in the startup list. Click the Down arrow at the end of the group row to move a resource down the list. Click the Up arrow at the end of the group row to move a resource up the list. Click the Delete icon at the end of the group row to remove the group from the list.

Parent topic: CICS Resources


CICS - Groups

Use this to view, add, or edit a resource group.

To create a new group, click * New.

Name
The name of the group.
Description
A short description of the group.
Save
Click this to save changes you have made.
Note: Some resource types will not be available depending on the configuration of the enterprise server region.
  • CCI System Connection
    Use this page to create a new SysC resource.
  • Document Template
    Use this page to create a new DocTemplate.
  • ENQ Model
    Use this page to create a new ENQ model resource.
  • FCT
    Use this page to create a new FCT.
  • Journal Control Table
    Use this page to create a new Journal Control Table (JCT).
  • LU6.2 System Connection
    Use this page to create a new Sys62 resource.
  • PCT
    Use this page to create a new PCT.
  • PLT
    Use this page to create a new Program Load Table (PLT).
  • PPT
    Use this page to create a new PPT.
  • TCP/IP Service
    Use this page to create a new TCPIPSERVICE.
  • Term
    Use this page to create a new Term (terminal).
  • Threshold
    Use this page to create a new THRESHOLD.
  • TranClass
    Use this page to create a new TRANCLASS.
  • Transient Data Queue
    Use this page to create a new Destination Control Table (DCT).
  • TS Model
    Use this page to create a new Temporary Storage (TS) model resource.
  • TST
    Use this page to view and edit the Temporary Storage Queue (TST) tst_name.
  • T-Type
    Use this page to view and edit the T-type (terminal type definition) ttype_name.
  • Universal Resource Identifier Map
    Use this page to create a new Universal Resource Identifier Map (URIMap) resource.
  • XAT
    Use this page to create a new Extended Architecture Table (XAT).
Parent topic: CICS Resources


CCI System Connection

Use this page to create a new SysC resource.

A SysC is a definition of a CCI system connection.

Click Active to make this resource active.

Click Delete to delete this SysC resource.

Click Copy to create a new SysC resource, using the values set on this page as the basis for the new SysC resource.

Click Dump to create and view dump information for this SysC.

Click Apply to save your changes to the SysC.

Description
Specify a description of the transaction program, this can be up to 60 characters long.

Connection Parameters

Protocol
Specify the CCI protocol to be used by this connection:
  • TCP/IP
  • Shared Memory
Net Name
Specify the name of the network over which the connection is established.
Session Maximum
Specify the maximum number of sessions that can use this connection.
MF Node
Specify the text hostname or IP address of the target server.
MF Port
Specify the decimal value of the port that the target server listens on.

Connection Usage

Transaction Code
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
Specifies the priority for transactions run from this terminal. The default value is 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
Note: The sum cannot be greater than 255.
In Service
Check this to specify that the connection defined by this SysC is in service by default.

Connection Security

User ID
Specify a user ID to be associated with the connection. Mandatory if no sign-on takes place on the connection.
Session Name
Specifies the security name of the connection. Can be up to eight alphanumeric characters from the set A through Z, 0 through 9, $, @ and #.
Operator ID
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.
Operator Priority
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. The default value is 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)
Note: The sum cannot be greater than 255.
Language
Choose the national language in which messages are sent over the connection.
Attach-time User Security
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.
Parent topic: CICS - Groups


Document Template

Use this page to create a new DocTemplate.

Click Install to install and make this resource active.

Click Active to display the currently installed definition of this resource.

Click Delete to delete this DocTemplate resource.

Click Copy to create a new DocTemplate resource, using the values set on this page as the basis for the new DocTemplate resource.

Click Dump to create and view dump information for this DocTemplate.

Click Save to save changes you have made to the page.

Click Apply to save your changes to the DocTemplate.

Name
The name of this template.
Group
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.
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 the Name field.
Content Type
The format of the template contents:
  • BINARY
  • ASCII
  • 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.
Append CR/LF
Check this to specify that CICS deletes trailing spaces and appends a carriage return and line feed to each logical record of the template.
Template Type
The type for the source of the template. You can select one of the following:
File
The name of a CICS file which contains the template. This name can be up to 8 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 4 characters long.
Program
The name of the CICS program that contains the template. This name can be up to 8 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 8 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.
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.
The default value is File.
Parent topic: CICS - Groups


ENQ Model

Use this page to create a new ENQ model resource.

An ENQ model defines a named resource for which the EXEC CICS ENQ and EXEC CICS DEQ commands have a sysplex-wide scope.

Note: You can use a ENQ model across a Performance and Availability Cluster (PAC).

Click Install to install this resource.

Click Active to make this resource active.

Click Delete to delete this ENQ model.

Click Copy to create a new ENQ model, using the values set on this page as the basis for the new ENQ model.

Click Dump to create and view dump information for this ENQ model.

Click Apply to save your changes to the ENQ model.

Description
A description of the ENQ model resource and its use.
Enable
Check this to enable the ENQ model resource.
ENQ Scope
Specifies the set of regions that share the same enqueue scope. If the ENQ scope attribute is left blank (the default value), CICS treats any matching ENQ or DEQ as local to the issuing CICS region. If the ENQ scope is non-blank, CICS treats the ENQ or DEQ as sysplex-wide and passes a queue name and the resource name to GRS to manage the enqueue.
ENQ Name
Specifies the 1 to 255-character resource name. You can also use an * (asterisk) as the last character, to denote a generic name.
ENQ in Shared Memory
Check this to force the ENQ to be stored in shared memory.
Note: This must only be used when you can ensure that the ENQ will be taken from a single region.
Parent topic: CICS - Groups


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.

To display the currently installed definition of this resource, click Active.

To install and make this resource active, click Install.

To delete this FCT, click Delete.

To create a new FCT, using the values set on this page as the basis for the new FCT, click Copy.

To create and view dump information for this FCT, click Dump.

Name
The name for this resource.
Group
The group to which this FCT will belong. The list of groups from which you can choose includes only those which can be edited by you.
Description
A description of the resource, which can be up to 60 characters long.
Status
Specifies 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.
Read Access
If checked, enables applications to read records from the file.
Add Access
If checked, enables applications to add records to the file.
Browse Access
If checked, enables applications to browse the file.
Delete Access
If checked, enables applications to delete records from the file.
Update Access
If checked, enables applications to update records in the file.
Exclusive Access
If checked, the CICS Exclusive Control enables the application to gain exclusive control of a record within a file.
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.
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.
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.
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.
Use Catalog
Check this if you want to use the catalog to store information about the file. If you check this, certain options on this page become irrelevant; the description for each parameter indicates whether Use Catalog affects that parameter.
Dataset Name
The dataset name for this file as used on the mainframe.
Note: You must check Use Catalog to display the Dataset Name field.
Remote SysID
The system ID of the remote system on which the file resides, specify the 4-character, remote system identifier (as defined in the TCT). If the program resides in the local region, leave this field blank. 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
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.
FCT Type
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).
Base Name
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.
File Path
The path of the physical file if you want to override the default. Do not include the filename or file extension. This can be up to 255 characters long. 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.
File Name Override
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.
Path Extension
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.
Format
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
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 LRECL Max. For fixed length records, set this value equal to LRECL Max. 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
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 LRECL Min. For fixed length records, set this value equal to LRECL Min.
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 LRECL Min.
Fileshare Server
The ID of the Fileshare server on which the file resides. This can be up to 16 characters long. 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.
Parent topic: CICS - Groups


Journal Control Table

Use this page to create a new Journal Control Table (JCT).

Click Install to install this resource.

Click Active to make this resource active.

Click Delete to delete this JCT.

Click Copy to create a new JCT, using the values set on this page as the basis for the new JCT.

Click Dump to create and view dump information for this JCT.

Click Apply to save your changes to the JCT.

Description
Specify a description for the JCT, this can be up to 60 characters long.

Journal File Location Details

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 controlling this data set.

Journal File Characteristics

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
Select 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.
Parent topic: CICS - Groups


LU6.2 System Connection

Use this page to create a new Sys62 resource.

A Sys62 is a definition of an LU6.2 system connection.

Click Active to make this resource active.

Click Delete to delete this Sys62 resource.

Click Copy to create a new Sys62 resource, using the values set on this page as the basis for the new Sys62 resource.

Click Dump to create and view dump information for this Sys62.

Click Apply to save your changes to the Sys62.

Description
Specify a short description of the Sys62. Acceptable characters are A through Z, 0 through 9, $, @ and #.

Connection Parameters

Logical Unit Alias
Specify the parameter used to connect this definition to the LU6.2 protocol stack definition for this connection.
Model Table
Specify the parameter that tells the LU6.2 protocol stack which Mode Table (or session characteristics) 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. The 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. Note: 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.
Fully Qualified Partner
Identifies a fully qualified partner name for LU62 connection definitions. This field is formed of a NETWORK ID and a Partner LU name. Both must be no longer than eight characters, separated by a period ('.'). For example, BBNET1.CICSDEV1.If the Fully Qualified Partner name in the connection is validated and installed, it is used at run time on the APPC Allocate verb, whereas the PARTNER LU Alias is set to binary zeroes.
Session Maximum
Specifies the maximum number of parallel sessions permited to be active on this LU.

Connection Usage

Transaction Code
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.
SYNCLEVEL
Specifies whether two-phase commit (level 2) is required on the connection or not (level 1).
In Service
Check this to enable this facility to default to (or start initially as) being "in service".

Connection Security

User ID
Specify the permanent user ID for this LU. Any work running against this facility will inherit the permissions of this user ID.
Session Name
Specify the name for the session.
Operator ID
Specify the three-character Operator ID associated with the permanent User ID - returned on ASSIGN OPID() command for transaction attached to this facility.
Operator 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. The default value is 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)
Note: The sum cannot be greater than 255.
Language
Specifies the default language for user interfaces connected to this facility.
Attach-time User Security
Specifies 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.
Parent topic: CICS - Groups


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.

To display the currently installed definition of this resource, click Active.

To install and make this resource active, click Install.

To delete this PCT, click Delete.

To create a new PCT using the values set on this page as the basis for the new PCT, click Copy.

To create and view dump information for this PCT, click Dump.

Name
The name for this PCT. This can be up to 4 characters or 8 characters if hexadecimal, for example, x'a1b2c3d4'. The hex is case insensitive including the first x and is up to 4 pairs of hexadecimal digits.
Description
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. This can be up to eight characters (A-Z, 0-9, #, @, or $). The name is translated to upper case.
Remote SysID
The system ID of the remote system on which the file resides, specify the 4-character, remote system identifier (as defined in the TCT). If the program resides in the local region, leave this field blank. 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 PCT
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.
Priority
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.
Work Area
The size of the transaction program's Transaction Working Area (TWA) in bytes, in the range 0 through 32767.
Enabled
Check this to enable the transaction program.
In Doubt
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.
3270 Screen
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).
Tracing
Choose the type of tracing to be performed for the transaction program:
  • No - No tracing is performed.
  • Standard - Tracing is performed.
  • Special - Special tracing is performed.
System Purgeable
If set to Yes when a PURGE is issued, the transaction has the SPURGE option set to yes, an ITR is sent to the SEP running the TASK to abend the task with abend AICG.
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.
Translate to Upper Case
Check this if you want the transaction program to translate input into upper case.
Dump on ABEND
Check this to create a program dump if the transaction program abends.
Inbound
Check this to indicate that this transaction can be initiated by an inbound user action.
RLS Security
RLS (Resource Level Security), if checked Enterprise Server will check the user's authorization for all resources that the transaction accesses, for example, file access, TDQ, TSQ, LINK, DPL, START and so on.
CMD Security
CMD (Command), check this to check the authorization on all the EXEC CICS command operations, for example, EXEC CICS SET/ENABLE/DISABLE.
Cat3 Security
Cat3 (IBM Category 3) Transactions do not have security checking at all, so the transactions are allowed for everyone with no authorization calls.
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.
System Default
Check this to use the system wide value for Runaway Timeout rather than the PCT entry.
Runaway Timeout
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.
System Default
Check this to use the system wide value for Runaway Timeout rather than the PCT entry.
Deadlock Timeout
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.
System Default
Check this to use the system wide value for Deadlock Timeout rather than the PCT entry.
Transaction Threshold
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.
System Default
Check to use the system wide value for the transaction time threshold rather than the PCT entry.
Parent topic: CICS - Groups


PLT

Use this page to create a new Program Load Table (PLT).

Click Save to save the PLT.

Click Copy to create a new PLT, using the values set on this page as the basis for the new PLT.

Click Delete to delete this PLT.

Click Dump to create and view dump information for this PLT.

Click * New to add a program to load.

Click Apply to save your changes to the PLT.

Name
Specify a name for the PLT.
Group
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).

Programs

Program Name
The name of the PLT program.
Run
Specify how the program is run:
Once
The program should be run once, when the PLT is first initiated.
In each process
The program is run in each process, every time the PLT is initiated.
Parent topic: CICS - Groups


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.

To display the currently installed definition of this resource, click Active.

To install and make this resource active, click Install.

To delete this PPT, click Delete.

To create a new PPT, using the values set on this page as the basis for the new PPT, click Copy.

To create and view dump information for this PPT, click Dump.

Description
A description of the resource (can be up to 60 characters).
Enabled
Check this to enable this program to be used.
PPT Type
Choose a type for the resource:
Program
This resource is a program.
Data
This resource is a data table.
Language
Choose the language the program is written in.
  • COBOL
  • PL1
  • Assembler
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
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.
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.
Remote TransID
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 Program
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.
Parent topic: CICS - Groups


TCP/IP Service

Use this page to create a new TCPIPSERVICE.

Click Install to install this resource.

Click Copy to create a new TCPIPSERVICE resource, using the values set on this page as the basis for the new TCPIPSERVICE resource.

Click Delete to delete this TCPIPSERVICE resource.

Click Active to make this resource active.

Click Dump to create and view dump information for this TCPIPSERVICE.

Click Save to save your changes to the TCPIPSERVICE.

Name
The name of this TCPIPSERVICE definition.
Description
A description of this definition.
Group
The group to which this resource will belong.
Port
Specifies the port number on which CICS listens for incoming client requests.
Protocol
The application level protocol used on the TCP/IP port:
  • HTTP
  • User
Open
Check this to set the initial status of the service after installation to open, otherwise it is closed.
Socket Close
Check this if CICS should close the socket after an amount of time.
Socket Close Time
Specifies the amount of time, in seconds, to wait until CICS closes the socket.
Max Data Length
Specifies the maximum length, in kilobytes, of data that CICS can receive.
Transaction
Specifies the ID of the CICS transaction to process new requests received.
URM
Specifies the name of a user-replaceable program that this service invokes.

Security

Authentication
Specifies the authentication and identification scheme to use:
  • No
  • Automatic
  • Basic
  • Auto Register
  • Certificate
SSL Type
Specifies whether the service should use SSL:
  • No
  • Yes
  • ClientAuth
Certificate
See SSL Support for CICS Web Interface Servers for more information.
Cipher
This can be specified in one of the following ways:
  • A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
  • The name of the SSL cipher suite specification file can be up to 28 characters long including the extension which must be .xml. The file name can only contain the characters A-Z a-z 0-9 # - . @ _.
Note: Use the USSCONFIG environment variable to point to the location of the SSL cipher suite specification file(s) used. See USSCONFIG for more information.
Realm
Specifies the realm used for HTTP basic authentication.
Parent topic: CICS - Groups


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.

Click Dump to create and view dump information for this Term.

Click Install to install this resource.

Click Active to make the resource active.

Click Delete to delete this Term.

Click Apply to save your Term settings.

Description
Specify a description for this Term.

Auto Install

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 Identifiers

Terminal Type
Mandatory, specify the associated Typerterm definition, which must exist.
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.

Terminal Usage

Fixed Transaction
If specified, this specifies the only transaction that users can run from this terminal, apart from print and paging requests. If a fixed transaction is 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
Note: 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.

Associated Printers

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.
Print 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 field is unavailable. This printer must be owned by the system that owns the terminal. The name can be up to four characters in length.
Alternate Print 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.

Terminal Security

User ID
Specify a user ID to be associated with the terminal. If the terminal definition includes a user ID, Enterprise Server honors the terminal user ID, and you can leave the this field blank.CAUTION: When the user ID is specified in the terminal definition, this logs you into the terminal without password verification.
Language
Choose the national language in which messages are sent over the connection.
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.
Operator 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.
Operator 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. This 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.
Parent topic: CICS - Groups


Threshold

Use this page to create a new THRESHOLD.

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

Click Dump to create and view dump information for this THRESHOLD.

Click Install to install this resource.

Click Active to make this resource active.

Click Delete to delete this THRESHOLD.

Click Apply to save your threshold settings.

Note: For Windows, the Windows Management Instrumentation (WMI) service must be started for the THRESHOLD feature to work.

For Enterprise Server regions that support CICS or JES, you can specify a threshold that will trigger a warning message and/or a threshold that triggers a warning message followed by a task purge (kill) function which operates within a target region. The thresholds can be specified for each of the following:

  • CPU consumption, in milliseconds (ms).
  • Memory usage, in kilobytes (kB).
  • Elapsed time, milliseconds (ms).

Warning messages are sent to the console. See CASKC6000 - CASKC6019 and CASKC6020 - CASKC6039 for more information on returned warning messages.

Note: There are no constraints on the combination of warning or purge thresholds that can be specified.
Name
The THRESHOLD name is a transaction match name. You can specify a prefix followed by the wildcard *. For example, the threshold name of AC* will match any transaction starting with AC, such as AC01, ACCT, and so forth.

For CICS, if the program starts with DFH*, EZACIC*, but excluding DFHWB*, the threshold will not be applied to the transaction.

Default values can be defined for CICS, JES, IMS, or CGI by creating a threshold name of =CIC, =JES, =IMS, or =CGI respectively.

Note: The CGI type will apply to the ESCWA and ESMAC casrdxxx modules.
Group
Choose a group to which this resource will belong. The list of groups from which you can choose include only those that can be edited by you.
Description
This is a description of the resource.
Resource Type
Type of resource the threshold will be applied to:
  • CICS
  • JES
  • IMS
  • CGI
Stepname
The stepname to be applied to the threshold.
CPU Warning
Amount of CPU usage, in milliseconds (ms), before a warning message is issued.
CPU Purge
Amount of CPU usage, in milliseconds (ms), before the process is purged (killed).
Memory Warning
Amount of MEM usage, in kilobytes (kB), before a warning message is issued.
Memory Purge
Amount of MEM usage, in kilobytes (kB), before the process is purged (killed).
Elapsed Time Warning
Amount of elapsed time, in milliseconds (ms), before a warning message is issued.
Elapsed Time Purge
Amount of elapsed time, in milliseconds (ms), before the process is purged (killed).
Parent topic: CICS - Groups


TranClass

Use this page to create a new TRANCLASS.

A TRANCLASS resource defines the characteristics of a transaction class.

Click Install to install this resource.

Click Active to make this resource active.

Click Delete to delete this TRANCLASS.

Click Copy to create a new TRANCLASS, using the values set on this page as the basis for the new TRANCLASS.

Click Dump to create and view dump information for this TRANCLASS.

Click Apply to save your changes to the TRANCLASS.

Description
Specify a description of the resource. This can be up to 60 characters long.
Purge Transactions
Check this to enable the transaction purging threshold.
Purge Threshold
Specifies a limit to the number of transactions queuing for this transaction class. After this limit is reached, transactions are purged.
Max Active
Specify the maximum number of transactions in this transaction class that are allowed to be active, in the range 0 through 999.
Parent topic: CICS - Groups


Transient Data Queue

Use this page to create a new Destination Control Table (DCT).

A DCT is a definition of a transient data queue.

Click Install to install this resource.

Click Active to make this resource active.

Click Delete to delete this DCT.

Click Copy to create a new DCT, using the values set on this page as the basis for the new DCT.

Click Dump to create and view dump information for this DCT.

Click Apply to save your changes to the DCT.

Name
Specify a name for the DCT (can be up to 60 characters).
Group
Click this to display the CICS Group group_name.
Description
Specify a description for the DCT (can be up to 60 characters).
Type
Choose the destination for transient data:
Intra-Partition
Indirect
Extra-Partition
Internal Reader
The internal reader to which CICS applications can direct a JCL jobstream for execution by the JCL engine.
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.

Remote Queue

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

Intra-Partition Triggering

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.

Extra-Partition File Location Details

File Name
The filename of the extra-partition file.
File Path
The pathname of the extra-partition file.
Path Extension
The filename extension of the extra-partition file.
Fileshare Server
The name of the stand-alone Fileshare server that controls this file, if required.

Extra-Partition File Characteristics

Record Max
The maximum length of a record in the extra-partition file.
Record Min
The minimum length of a record in the extra-partition file.
Initial State
Specifies the initial state of the data set:
  • Closed
  • Open
File Type
Specifies whether the file is line sequential or normal:
  • Normal
  • Line Sequential
Print Attributes
Specifies whether or not a form's control character is contained in the first position of each record:
  • No Control
  • ASA
  • Machine
I/O Type
Specifies the type of input/output:
  • Input
  • Output
  • Read Backward
Disposition
Specifies the type of access a user wants the data set to have:
MOD
Gives the user exclusive access to add data to the end of a sequential data set.
OLD
Gives the user exclusive access until they have finished using it.
SHR
Gives the user non-exclusive access so that other users can share the data set while it is being used.
Note: If SHR is selected and the enterprise server region is running in a PAC and a DCT is declared to be an Internal Reader then the Internal Reader queue will be stored in the SOR. Otherwise, it will be stored on disk.
Parent topic: CICS - Groups


TS Model

A TS model specifies the properties of a set of TS queues. Individual TS queues are associated with a TS model by the prefix, a character string that matches the leading characters of the queue name.

Note: You can use a TS model across a PAC.

Click Install to install this resource.

Click Active to make this resource active.

Click Delete to delete this TS model.

Click Copy to create a new TS model, using the values set on this page as the basis for the new TS model.

Click Dump to create and view dump information for this TS model.

Click Apply to save your changes to the TS model.

Description
A description of the TS model resource and its use. The description text can be up to 58 characters in length. No restrictions apply to the characters that you can use.
Location
The storage the queue will be held in:
Auxiliary
Queues matching this model are to be held in auxiliary temporary storage. Whatever is specified on the API request is disregarded.
Main
Queues matching this model are to be held in main temporary storage. Whatever is specified on the API request is disregarded.
Recoverable
Check this to enable matching queues to be recoverable.
Expiry Interval
Specifies the duration in minutes a matching queue must not be used before it becomes eligible for automatic deletion. A value of 0 indicates it is never eligible for deletion.
Prefix
Specifies the string CICS uses to match with temporary storage queues. The prefix can be up to 16 characters in length. You can use the + character for generic matching of any character.
X Prefix
This can be used as an alternative to the Prefix field. You can specify a hexadecimal ASCII string which CICS uses to match with temporary storage queues. The prefix can be up to 16 characters in length. You can use the character X'2B' for generic matching of any character.
Remote System
Specifies the name of the connection that links the local system to the remote system where the temporary storage queue is located.
Remote Prefix
Specifies the character string that CICS uses to identify temporary storage queues in the remote system. The prefix can be up to 16 characters in length. You can use the + character for generic matching of any character.
X Remote Prefix
This can be used as an alternative to the Remote Prefix field. The hexadecimal ASCII string CICS will use to match with temporary storage queues in the remote system. The generic character X'2B' can be used to match any character.
Security
Check this to indicate that the mainframe performs security checking on matching queues.
Note: This field is not supported.
Parent topic: CICS - Groups


TST

Use this page to view and edit the Temporary Storage Queue (TST) tst_name.

The title bar gives details of the TST you are editing and the resource group it belongs to.

Click Dump to create and view dump information for this TST.

Click Copy to create a new TST, using the values set on this page as the basis for the new TST.

Click Save to save the TST, you must specify a Group to which the resource belongs before you can save.

Click Delete to delete this TST.

Click Back to return to the temporary storage queue resources list.

Click Apply to save your changes to the TST.

Description
Specify a description for the TST (can be up to 60 characters).
TST Type
Specify the action to take in the event of an abnormal termination of either MSS or the transaction processing the destination:
  • Non Recoverable
  • Recoverable
  • Process Local
  • Exclusive
Expiry
Specifies the resource expiry condition, this can be:
  • Never
  • Use System Default
  • Specify Interval - If you choose this option, you can specify the interval in minutes.

Remote Queue

Name
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.
Parent topic: CICS - Groups


T-Type

Use this page to view and edit the T-type (terminal type definition) ttype_name.

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

Click Install to install this resource.

Click Active to make this resource active.

Click Dump to create and view dump information for this T-type.

Click Copy to create a new T-type, using the values set on this page as the basis for the new T-type.

Click Delete to delete this T-type. You only see this button if you have editing permissions for the group to which the T-type belongs.

Click Apply to save your settings.

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
Printer device.
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. If a 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.

BMS Mapping Properties

Max 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 9999.
Max 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 9999.
Alternate Map Width
Specify the page size for the terminal type being defined, if you have specified an alternate screen size. Alternate page size width is defined as a number of columns, in the range 0 through 9999.
Note: Unexpected results may occur if the number of columns is not the same as the number of columns you specify for the Alternate Screen Width field. Defaults to the values specified in Max Size Width.
Alternate Map Height
Specify the page size for the terminal type being defined, if you have specified an alternate screen size. Alternate page size height is defined as a number of rows, in the range 0 through 9999.
Note: Unexpected results may occur if the number of columns is not the same as the number of columns you specify for the Alternate Screen Height field. Defaults to the values specified in Max Size Height.
OB Oper ID
Check this to enable MSS to use the outbound operator identifiers to support the BMS routing facilities required by this terminal type definition.
Outboard Format
Check this to enable MSS BMS to delegate part of the presentation formatting to the client facility.

Session Properties

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.

Message Receiving Properties

Routed Message
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 Message
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.

Operational Properties

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 Session
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 No.

Diagnostic Display

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

Recovery Properties

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:
System 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.

Device Properties

Default 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 255. The default is 80. There is no validity checking; incorrect sizes might lead to unpredictable behavior.
Default 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 255. The default is 24. There is no validity checking; incorrect sizes might lead to unpredictable behavior.
Alternate 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 255. The default is 80. There is no validity checking; incorrect sizes might lead to unpredictable behavior.
Alternate 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 255. 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 Character Set
Check this to specify that the terminal type can support the APL text character set.
Datastream Extensions
Check this to specify that the terminal type supports extensions to the 3270 data stream. You must check this if Color or Highlight 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.
Color
Check this to specify that the terminal type has the color feature, which enables colors to be selected for individual fields.
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).
Form Feed
Check this to specify that the device has the form feed feature.
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 Form
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.
Dual Case (Typewriter) Keyboard
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.
Katakana Terminal
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.
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.
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.
Text-Keyboard
Check this to specify that the 3270 device has the text-keyboard feature.
Audible Alarm
Check this to specify that the terminal type has the audible alarm feature.
Copy
Check this to specify that the terminal type has the copy feature.
Light Pen Selector
Check this to specify that the terminal type has the light pen selector feature. MSS emulates this feature using mouse clicks.
EWA Support
Check this to enable a 3270 device to shift its display into its alternate mode.
Outline
Check this to specify that the terminal type supports field outlining.
Numeric Lock
Check this to enable the numeric lock.
Print Adapter
Check this to specify that output BMS screens with the PRINT option set on are copied automatically to an attached printer.
Background 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.
Magnetic Stripe Reader
Check this to specify that the terminal type has the magnetic stripe reader feature. MSS emulates this feature using mouse clicks.
Validation
Check this to enable the extended validation feature for 8775 devices or for the validation feature for 3290 devices.
Partition Support
Check this to enable the device to use partitions. This option is not valid for SCS printers.

Application Features

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.
Uppercase Translation
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.
Transaction IDs
Transaction identifiers input in lower case are translated to upper case; not other input data is translated.
User Area
Specify the size, in bytes, of the user area of a terminal of this type. Defaults to 0 (zero).
User Area In Shared Stage
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.
I/O Area Min
Specify the minimum sizes, in bytes, of the terminal I/O area to be passed to a transaction program when it issues a RECEIVE.
I/O Area Max
Specify the maximum sizes, in bytes, of the terminal I/O area to be passed to a transaction program when it issues a RECEIVE.
Parent topic: CICS - Groups


Universal Resource Identifier Map

Use this page to create a new Universal Resource Identifier Map (URIMap) resource.

Click Install to install this resource.

Click Copy to create a new URIMap resource, using the values set on this page as the basis for the new URIMap resource.

Click Delete to delete this URIMap resource.

Click Active to make this resource active.

Click Dump to create and view dump information for this URIMap.

Click Save to save your changes to the URIMap.

General

Name
The name of this URIMap definition.
Description
A description of this URIMap definition.
Enabled
Check this to enable the resource when it is installed.
Usage
Specifies whether this URIMap definition is for:
  • Server
  • Client
  • Pipeline

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.
Path
The path component of the URI.
Socket Close
The duration for which the HTTP connection is held for once Enterprise Server has finished using it. Enter 0 for immediate release, or a figure corresponding to hhmmss. For example, 011230 corresponds to 1 hour, 12 minutes, and 30 seconds.
Host
The host name, or IPv4 or IPv6 address, of the URI.

Associated CICS Resources

TCP/IP Service
The name of a TCPIPSERVICE resource definition that defines an inbound port.
Analyzer
Check this to use an analyzer program when 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
The pipeline from the inbound web service request made by the client.
Web Service
The inbound web service request made by the client.

Security Attributes

User ID
The user ID to be used in the transaction.
Ciphers
This can be specified in one of the following ways:
  • A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
  • The name of the SSL cipher suite specification file name can be up to 28 characters long including the extension which must be .xml. The file name can only contain the characters A-Z a-z 0-9 # - . @ _.
Note: Use the USSCONFIG environment variable to point to the location of the SSL cipher suite specification file(s) used. See USSCONFIG for more information.
Certificate
The label of the X.509 certificate that is used as the SSL client certificate during the SSL handshake.
Authenticate
Check this to send basic authentication information in the HTTP response. Basic authentication can only be set when the enterprise server region itself is secure.

Static Document Properties

Media Type
The media type of the response provided to the HTTP request.
HFS File
The HFS file that will be sent as part of the response to the HTTP request.
Parent topic: CICS - Groups
Related information
USSCONFIG


XAT

Use this page to create a new Extended Architecture Table (XAT).

Click Copy to create a new XAT resource, using the values set on this page as the basis for the new XAT resource.

Click Delete to delete this XAT resource.

Click Active to make this resource active.

Click Dump to create and view dump information for this XAT.

Click Save to save your changes to the XAT.

Name
Specify the name of this XAT.
Group
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 (Windows), or .so (UNIX) that contains the entry point that returns the xa_switch_t structure to the enterprise server.

Open String

Fixed Format
Switch to the right to enable open string fixed format:
Database Name
Specify the name of the resource manager database.
User ID
A resource manager ID, used internally to identify a particular XA configuration. This must be unique within the enterprise server instance.
Password
The password required for the User ID.
Confirm Password
If you are creating a new password, specify the password again to verify you have entered it correctly.
Fixed Format
Switch to the left to disable open string fixed format:
Open String
The string that is passed to the resource manager on the xa_open() call. As a minimum, an entry in this field typically contains the database name, and the User ID and password for connecting to the database. The contents of this string are database specific.

Close String

Close String
Specify the string that is passed to the resource manager on the xa_close() call. See your database vendor's documentation to determine whether or not you need to specify a close string.

Resource Manager RTS Support

Load Module
Choose an external resource manager that the server needs to communicate with on behalf of container-managed applications:
  • None
  • DB2
  • Oracle
  • Sybase
  • User
Load Module Name
If you choose User from the Load Module list, specify the name of the module that supplies the run-time support for the database calls made by the application.
Parent topic: CICS - Groups


CICS - Active

Note: Some resource types will not be available depending on the configuration of the enterprise server region.
  • Active ACEE
    Use this page to view the active Access Control Environment Element (ACEE) for a user.
  • Active CCI System Connection
    Use this page to view the active SysC on this server.
  • Active Document Template
    Use this page to view the active DOCTEMPLATE resources that are available on this server.
  • Active ENQ Model
    Use this page to view an active ENQ model resource.
  • Active FCT
    Use this page to view information and modify the status for an active File Control Table (FCT) resource.
  • Active Job Control Table
    Use this page to view the active JCT on this server.
  • Active PCT
    Use this to view information and modify the status for an active Program Control Table (PCT) resource.
  • Active PPT
    Use this to view information and modify the status for an active Program Processing Table (PPT) resource.
  • Active Resource Name List
    Use this page to view and edit the RNLs available.
  • Active TCPIPSv
    Use this page to view the active TCP/IP Service resources that are available on this server.
  • Active Temporary Storage Queue List
    Use this page to view the Temporary Storage (TST) queue active on this server.
  • Active Terminal Type
    Use this page to view information about the active Terminal Type named ttype_name.
  • Active Threshold
    Use this page to view an active THRESHOLD resource.
  • Active Transaction Class
    Use this page to view the TRANCLASS resources active on this server.
  • Active Transient Data Queue List
    Use this page to view the Destination Control Table (DCT) available on this server.
  • Active TS Model
    Use this page to view an active TS model resource.
  • Active Universal Resource Identifier Map
    Use this page to view the active Universal Resource Identifier Map (URIMap) available on this server.
  • Active XAT
    Use this page to view the Active Extended Architecture Table (XAT) defined for the server.
Parent topic: CICS Resources


Active ACEE

Use this page to view the active Access Control Environment Element (ACEE) for a user.

Click Dump to display a dump of the ACEE Entry for the mfuser.

Click Apply to save your changes to the ACEE.

Long Name
The long name of the user.
Priority
The value used by the system to determine task priority for CICS transactions invoked by the user at a terminal.
Timeout
The time in minutes that the system will permit an ESMAC or TN3270 terminal client session to remain idle before logging off the user. If the value is 0, the system value is used.
Timeout Description
Operator ID
The identification code that you assign to the operator.
Operator Class
The operator class used for routing messages initiated in a CICS transaction.
Parent topic: CICS - Active


Active CCI System Connection

Use this page to view the active SysC on this server.

A SysC is a definition of a CCI system connection.

Click Apply to save your changes to the SysC.

Click Dump to create and view dump information for this active SysC.

SYSID
Displays the name of the active SysC.
Status
Displays the status of the active SysC.
In Service
Check this to specify if the active connection is in service.
Service Status
Displays the status of the active SysC.
Service Message
Displays the service message for the active SysC.
Parent topic: CICS - Active


Active Document Template

Use this page to view the active DOCTEMPLATE resources that are available on this server.

Click Dump to view a dump of the resource.

Name
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.
Content Type
The format of the template contents:
  • BINARY
  • EBCDIC
  • ASCII
Cached Size
The size of the resource in the cache.
Template Name
The name by which the template is known to application programs that use it. The name can be up to 48 characters long. If a value has not been specified, it defaults to the value of the Name field.
Template Type
The type for the source of the template:
File
The name of a CICS file which contains the template. This name can be up to 8 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 4 characters long.
Program
The name of the CICS program that contains the template. This name can be up to 48 characters long. If a value has not been specified, the template name is used.
Exit Program
The name of the exit program that generates this template. This name can be up to 8 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 8 characters long. The default DD name used is "DFHHTML".
Member Name
The name of a member in the PDS. This name can be up to 8 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.
File
A CICS file which contains the template.
Parent topic: CICS - Active


Active ENQ Model

Click Uninstall to uninstall this resource.

Click Apply to save your changes to the ENQ model.

Click Dump to create and view dump information for this active ENQ model.

Enable
Check this to enable the active ENQ model resource.
Status
The status of the resource.
ENQ Scope
The ENQ model scope name. If the ENQ scope attribute is left blank, CICS treats any matching ENQ or DEQ as local to the issuing CICS region or PAC. This means that the ENQ will be stored in the region database (scope SYSTEM).

If the ENQ scope is non-blank, the ENQ will be stored in the cross-region database (scope SYSTEMS).

Note: If the ENQMODEL has been configured to force the ENQ to be stored in shared memory, then the ENQ Scope will display "&SHM".
ENQ Name
The ENQ model resource name. An asterisk (*) as the last character, denotes a generic name.
Parent topic: CICS - Active


Active FCT

Use this page to view information and modify the status for an active File Control Table (FCT) resource.

Click DUMP to create and view dump information for this FCT.

Click FCT Fix Up to apply the Fix Up process to FCTs which point to catalog DSNs. Typically this happens automatically on first access, and once only. If a change is made to a catalog entry which is referred to by an FCT, this button enables you to force a Fix Up process to prevent run time divergence between the physical file's DCB information and that held in the live table(s).

Dataset Name
The data set name for this file as used on the mainframe.
State
Displays information about the current state of the file. The first item of information is the open/closed status. This is 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.
FCT Type
Displays the FCT 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.
Status
Indicates whether the resource 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.
Read Access
If checked, indicates that users can read records from the file.
Add Access
If checked, indicates that users can add records to the file.
Browse Access
If checked, indicates that users can browse the file.
Delete Access
If checked, indicates that users can delete records from the file.
Update Access
If checked, indicates that users can update records in the file.
Exclusive Access
If checked, indicates that the file cannot be read by other transactions while an update is in progress.
Group
Displays which resource group this FCT resource belongs to.
Use Count
Displays the number of times this FCT has been used.

Flags

Disabling
A tick indicates that the file is currently being disabled. Disabling is a transient state controlled by the system.
Start Empty
A tick indicates that the current contents of the file are deleted at system startup.
Backward Recovery
A tick 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 Recovery
A tick indicates that journals are used to record changes to the file to enable forward recovery. The file must be accessed through a Fileshare server.

Records

LRECL Min
The minimum logical record length of the file, in bytes.
LRECL Max
The maximum logical record length of the file, in bytes.
Key Position
For files of type KSDS or ALT, specify the byte number at which the record key begins. Bytes are numbered from 1.
Key Length
For files of type KSDS or ALT, specify the length of the record key in bytes.
Parent topic: CICS - Active


Active Job Control Table

Use this page to view the active JCT on this server.

Click Apply to save your changes to the JCT.

Click Dump to create and view dump information for this active JCT.

Name
The name of the JCT.
Parent topic: CICS - Active


Active PCT

Click Dump to create and view dump information for this PCT.

TranClass
The name of the transaction class to which the transaction belongs.
Program Name
The program name of a local program to be run when this transaction is invoked. Leave this field blank if you enter a value in the remote system ID field.
PCT Type
Indicates whether the program is local or remote. If the program is remote, the system and transaction IDs are also displayed.
Default BREXIT
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
Displays the current settings that apply to this transaction.
Enabled
Check this to enable the resource.
In Doubt
Specifies what is to happen if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing:
Backout
This indicates 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.
Commit
This indicates that if a transaction program using intersystem communication abends at a critical moment during syncpoint or abend processing, any changes are committed.
Wait
This indicates 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.
3270 Screen
Specify the screen size to be used by the transaction program:
Default
The transaction program uses the default screen size, as defined in the Typeterm entry.
Alternate
The transaction program uses the alternate screen size, as defined in the Typeterm entry.
Tracing
Choose the type of tracing to be performed for the transaction program:
Standard
Standard tracing is performed.
Special
Special tracing is performed.
Suppress
No tracing is performed.
Translate to Upper Case
Check this if you want the transaction program to translate input into upper case.
Dump on Abend
Check this to indicate that a program dump is to be created if the transaction program abends.
Purgeable
If this is checked, when a PURGE is issued, the transaction has the SPURGE option set to yes, an ITR is sent to the SEP running the TASK to abend the task with abend AICG.
Security
The type of security applied to the PCTs:
RLS
Resource Level Security, Enterprise Server will check the user's authorization for all resources that the transaction accesses, for example, file access, TDQ, TSQ, LINK, DPL, START and so on.
CMD
Command, checks the authorization on all the EXEC CICS command operations, for example, EXEC CICS SET/ENABLE/DISABLE.
All
Both RLS and CMD security will be applied to the PCT.
Cat3
IBM Category 3 transactions do not have security checking at all, so the transactions are allowed for everyone with no authorization calls.
None
No security type has been selected, also returned when the region is not secure.
Unknown
An error occurred retrieving security type.

Transaction

TWA Size
Displays 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
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
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.

Threshold

CPU Warning
Amount of CPU usage, in milliseconds (ms), before a warning message is issued.
Memory Warning
Amount of memory usage, in kilobytes (kB), before a warning message is issued.
Elapsed Time Warning
Amount of elapsed time, in milliseconds (ms), before a warning message is issued.
CPU Purge
Amount of CPU usage, in milliseconds (ms), before the process is purged (killed).
Memory Purge
Amount of memory usage, in kilobytes (kB), before the process is purged (killed).
Elapsed Time Purge
Amount of elapsed time, in milliseconds (ms), before the process is purged (killed).

Counts

Priority
Displays the transaction priority of the transaction program.
Use Count
Displays the number of times this transaction has been used.
Average Duration
Displays the average execution time in seconds for this transaction.
Parent topic: CICS - Active


Active PPT

Use this to view information and modify the status for an active Program Processing Table (PPT) resource.

Click Dump to create and view dump information for this PPT.

Load Module
Displays 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.
Enabled
Check this to enable the program.
Language
Choose the language the program is written in:
  • COBOL
  • PL1
  • C
  • Assembler
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 if you want to enable this program to reside in the application server's program cache after it has been loaded.
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.
Load HOLD
Check this to indicate that the module is to be loaded using the HOLD option on the EXEC CICS LOAD API. This module is not released until explicitly released by the application.

Type

PPT Type
The type of this resources.
Subtype
Indicates the extension of the module:
  • DLL
  • EXE
  • INT
  • GNT
  • MOD
  • Generic

Size

Module
The size of the module.
Commarea
The minimum size of the Commarea.

Counts

Resident
Check this if you want to enable this program to reside in the application server's program cache after it has been loaded.
Reference Count
Specifies the number of times the module has been referenced or used.
Index
The number of times a LOAD SET ENTRY() has been executed.
Parent topic: CICS - Active


Active Resource Name List

A Resource Name List (RNL) is used to specify the scope of a lock which can be local or global and can be used in a PAC. All RNLs are defined in the RNL descriptor file (ESCLRNLs.cfg). At the start up of the PAC, RNLs are verified and loaded into the member regions. Once these initial definitions are installed, the RNLs can be updated in the PAC only by using the Active RNL page. The PAC will push the changes to all member regions.

Use this page to view the RNLs available in this PAC member:

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)

This 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: - -
*
Enables matching for a substring of any characters and for any length, including zero.
?
Enables matching for any single character.
QNAME
This is the major name for the resource.
RNAME
This is the minor name for the resource.
Parent topic: CICS - Active


Active TCPIPSv

Use this page to view the active TCP/IP Service resources that are available on this server.

Click Apply to save changes you make to the page, and refresh the page.

Click Dump to view a dump of the resource.

Name
The name of this TCPIPSERVICE definition.
Host
The IP address or hostname which CICS will listen for incoming connections on.
IP Address
If an IP address has been specified in the TCPIPSERVICE definition then that address is returned. Otherwise, the default IP address is returned.
Port
Specifies the port number on which CICS listens for incoming client requests.
Protocol
Specifies the application level protocol used on the TCP/IP port:
  • HTTP
  • User
Open
Check this to set the initial status of the service after installation to open, otherwise it is closed.
Socket Close Time
Specifies the amount of time, in seconds, to wait until CICS closes the socket.
Max Data Length
Specifies the maximum length, in kilobytes, of data that CICS can receive.
Backlog
Specifies the maximum number of requests which can be queued in wait to be processed by the service.
Transaction
Specifies the ID of the CICS transaction to process new requests received.
TSQ Prefix
A code to identify items in the temporary storage queue (TSQ).
URM
A user-replaceable program this service invokes. An 8 character name of Service URM invoked by an attached task.

Security

Authentication
Specifies the authentication and identification scheme to use:
  • No
  • Automatic
  • Basic
  • Auto Register
  • Certificate
SSL Type
Specifies whether the service should use SSL:
  • No
  • Yes
  • ClientAuth
Privacy
The level of SSL encryption required.
Cipher
This is specified in one of the following ways:
  • A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
  • The name of the SSL cipher suite specification file name can be up to 28 characters long including the extension which must be .xml. The file name can only contain the characters A-Z a-z 0-9 # - . @ _.
Note: The location of the SSL cipher suite specification file is specified by the USSCONFIG environment variable. See USSCONFIG for more information.
Certificate
Specifies the certificate to use for the SSL handshake.
Attach Security
Returns the attached security requirements of a CICS client:
Verify
The CICS client must provide a userid and password to the host. These are checked before the CICS client is allowed to communicate with the host.
Notapplic
This option has no meaning for the web interface.
Local
The CICS client is not required to provide a userid and password to the host.

DNS Connection Balancing

DNS Status
The current state of Workload Manager/Domain Name System (DNS) of this service.
DNS Group
This is the name of the group for the TCP listener that handles inbound communications for the group to join when using Workload Manager. The maximum length for this field is 18 characters.
GRP Critical
Identifies if the service is a critical member of the DNS group.
Parent topic: CICS - Active


Active Temporary Storage Queue List

Use this page to view the Temporary Storage (TST) queue active on this server.

Click Edit to edit the TST entry.

The TST list displays the following information:

Name
The name of the TST.
Status
The status of the TST.
  • Active Temporary Storage Queue
    Use this page to view information about the Temporary Storage (TST) queue named tst_name.
Parent topic: CICS - Active


Active Temporary Storage Queue

Use this page to view information about the Temporary Storage (TST) queue named tst_name.

To set values for the TST, use the CICS TST queue page.

Click Apply to save changes you have made to the page.

Click Dump to create and view a dump of the TST.

Click Back to return to the CICS TST queue page.

Recoverable
Specifies if the TST is recoverable or not.
Expiry
Specifies the resource expiry condition, this can be Never, Use Sys, or the number of minutes.
Parent topic: Active Temporary Storage Queue List


Active Terminal Type

Use this page to view information about the active Terminal Type named ttype_name.

To set values for the Terminal Type, use the CICS Terminal Type page.

Click Dump to create and view a dump of the Terminal Type.

Click Back to return to the CICS Terminal Type page.

Parent topic: CICS - Active


Active Threshold

Use this page to view an active THRESHOLD resource.

Click Dump to create and view dump information for this THRESHOLD.

Click Uninstall to uninstall this resource.

Note: For Windows, the Windows Management Instrumentation (WMI) service must be started for the THRESHOLD feature to work.
Name
The THRESHOLD name is a transaction match name. You can specify a prefix followed by the wildcard *. For example, the threshold name of AC* will match any transaction starting with AC, such as AC01, ACCT, and so forth.

For CICS, if the program starts with DFH*, EZACIC*, but excluding DFHWB*, the threshold will not be applied to the transaction.

Default values can be defined for CICS, JES, IMS, or CGI by creating a threshold name of =CIC, =JES, =IMS, or =CGI respectively.

Note: The CGI type will apply to the ESCWA and ESMAC casrdxxx modules.
Resource Type
Type of resource the threshold will be applied to:
  • CICS
  • JES
  • IMS
  • CGI
Stepname
The stepname to be applied to the threshold.
CPU Warning
Amount of CPU usage, in milliseconds (ms), before a warning message is issued.
CPU Purge
Amount of CPU usage, in milliseconds (ms), before the process is purged (killed).
Memory Warning
Amount of memory usage, in kilobytes (kB), before a warning message is issued.
Memory Purge
Amount of memory usage, in kilobytes (kB), before the process is purged (killed).
Elapsed Time Warning
Amount of elapsed time, in milliseconds (ms), before a warning message is issued.
Elapsed Time Purge
Amount of elapsed time, in milliseconds (ms), before the process is purged (killed).
Parent topic: CICS - Active


Active Transaction Class

Use this page to view the TRANCLASS resources active on this server.
Active
The number of active transactions.
Max Active
Specify the maximum number of transactions in this transaction class that are allowed to be active, in the range 0 through 999.
Pending
The number of pending transactions.
Purge Threshold
Specifies a limit to the number of transactions queuing for this transaction class. After this limit is reached, transactions are purged.
Parent topic: CICS - Active


Active Transient Data Queue List

Use this page to view the Destination Control Table (DCT) available on this server.

Click Edit to edit the DCT entry.

The DCT list displays the following information:

Name
The name of the DCT.
Status
Indicates if the DCT is enabled or disabled.
Type
The destination for transient data of the DCT.
  • Active Transient Data Queue
    Use this page to view information about the Destination Control Table (DCT) named dct_name.
Parent topic: CICS - Active


Active Transient Data Queue

Use this page to view information about the Destination Control Table (DCT) named dct_name.

To set values for the DCT, use the CICS DCT page.

Click Apply to save changes you have made to the page and refresh the page.

Click Dump to create and view a dump of the DCT.

Click Back to return to the CICS DCT page.

Type
The destination for transient data.
Recoverable
Enables recovery of the destination in the event of an abnormal termination of either MSS or the transaction processing the destination.
Trigger, Items
The number of items to be accumulated before a task is automatically initiated to process them.
Transaction
The name of the transaction that is to be automatically initiated when the trigger level specified in Trigger Level is reached.
Terminal
The terminal associated with the transient data destination.
Parent topic: Active Transient Data Queue List


Active TS Model

Use this page to view an active TS model resource.

Click Uninstall to uninstall this resource.

Click Apply to save your changes to the TS model.

Click Dump to create and view dump information for this active TS model.

Enable
Check this to enable the active TS model resource.
Location
This displays the storage the queue will be held in:
Auxiliary
Queues matching this model are to be held in auxiliary temporary storage. Whatever is specified on the API request is disregarded.
Main
Queues matching this model are to be held in main temporary storage. Whatever is specified on the API request is disregarded.
Recoverable
This displays whether matching queues are recoverable.
Expiry Interval
This displays the duration in hours a matching queue must not be used before it becomes eligible for automatic deletion. A value of 0 indicates it is never eligible for deletion.
Prefix
This displays a string CICS uses to match with temporary storage queues. A plus (+) character is used for generic matching of any character.
X Prefix
This displays a hexadecimal string which CICS uses to match with temporary storage queues. The character X'4E' is used for generic matching of any character.
Remote System
This displays the name of the connection that links the local system to the remote system where the temporary storage queue is located.
Remote Prefix
This displays the character string that CICS uses to identify temporary storage queues in the remote system. A plus (+) character is used for generic matching of any character.
X Remote Prefix
This displays a hexadecimal string CICS will use to match with temporary storage queues in the remote system. The character X'4E' is used for generic matching to any character.
Security
This displays whether security checking is performed on matching queues.
Parent topic: CICS - Active


Active Universal Resource Identifier Map

Use this page to view the active Universal Resource Identifier Map (URIMap) available on this server.

Click Dump to view a dump of the resource.

General

Name
The name of this URIMAP definition.
Enabled
Check this field to specify that the installed definition is in an enabled state.
Usage
Specifies whether this URIMAP definition is for:
Server
CICS as an HTTP server.
Client
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.
Socket Close
The duration for which the HTTP connection is held for once Enterprise Server has finished using it. Enter 0 for immediate release, or a figure corresponding to hhmmss. For example, 011230 corresponds to 1 hour, 12 minutes, and 30 seconds.

Associated CICS Resources

TCP/IP Service
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
The pipeline from the inbound web service request made by the client.
WebService
The inbound web service request made by the client.

Security Attributes

User ID
The user ID to be used in the transaction.
Ciphers
This is specified in one of the following ways:
  • A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
  • The name of the SSL cipher suite specification file name can be up to 28 characters long including the extension which must be .xml. The file name can only contain the characters A-Z a-z 0-9 # - . @ _.
Note: The location of the SSL cipher suite specification file is specified by the USSCONFIG environment variable. See USSCONFIG for more information.
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

Media Type
The media type (data content) of the static response that CICS provides to the HTTP request.
Character Set
The 1 to 40 character name of the character set into which CICS converts the entity body of the response that is sent to the web client.
Host Codepage
The 1 to 10 character name of the IBM code page (EBCDIC) in which the text document that forms the static response is encoded.
Template Name
The 1 to 48 character name of a CICS document template that forms the body of the static response that is sent to the HTTP request from the web client.
HFS File
The fully qualified (absolute) or relative name of a z/OS UNIX System Services zFS file that forms the body of the static response that is sent to the HTTP request from the web client. This can be up to 255 characters long.

Redirection

Redirect Type
The type of redirection for requests that match this URIMAP definition. The URL specified by the LOCATION attribute is used for redirection when required:
NONE
The requests are not redirected. Any URL specified by the LOCATION attribute is ignored.
TEMPORARY
The requests are redirected on a temporary basis. The URL specified by the LOCATION attribute is used for redirection, and the status code that is used for the response is 302 (Found).
PERMANENT
The requests are redirected permanently. The URL specified by the LOCATION attribute is used for redirection, and the status code that is used for the response is 301 (Moved Permanently).
Location
A URL of up to 255 characters to which the client request is redirected. The URL must be complete, including scheme, host, path components, and appropriate delimiters.
Parent topic: CICS - Active
Related information
USSCONFIG


Active XAT

Use this page to view the Active Extended Architecture Table (XAT) defined for the server.
Enabled
Check this to enable the XAT resource.
Switch Module
The location of the executable file .dll (Windows) or .so (UNIX) that contains the entry point that returns the xa_switch_t structure to the enterprise server instance.
Open String
The string that is passed to the resource manager on the xa_open() call. As a minimum, an entry in this field typically contains the database name, and the User ID and password for connecting to the database. The content of this string is database specific.
Close String
Specify the string that is passed to the resource manager on the xa_close() call. See your database vendor's documentation to determine whether or not you need to specify a close string.
Connected SEPs
The count of connected SEPs.
Parent topic: CICS - Active


JES

This menu provides pages that enable you to configure, control, and monitor the Job Entry Subsystem (JES).
Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).
  • JES Configuration
    Use this page to configure Job Entry Subsystem (JES) for JCL support for this server.
  • Spool
    Use this page to view the spool files that have been created as a result of submitting JCL on this server.
  • Catalog List
    Use this page to view the data catalog.
  • JES Control
    Use this page to submit JCL jobs and start batch initiator and batch printer SEPs for this server.
  • JES Alias
    This page lists the Micro Focus implementations of mainframe utilities.
Parent topic: Regions


JES Configuration

Use this page to configure Job Entry Subsystem (JES) for JCL support for this server.

JES Configuration

JES Program Path
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.
Restriction: May not exceed 4095 characters.
System Catalog
The full name (including the path) of your system catalog file. This file holds the details of data files, their attributes and locations.
Notes:
  • You cannot share a catalog between servers
  • May not exceed 260 characters
Default Allocated Dataset Location
The default directory to be used for the creation of new data sets.
Restriction: May not exceed 260 characters.
System Procedure Library
The name of your system procedure library.
  • The default value is MFE.PROCLIB.L01
  • This field can accommodate up to 15 library names, each separated by a semicolon (;)
  • Values in this field are searched after the JCLLIB entries in a JCL job are searched for cataloged procedures
Fileshare Configuration Location
The path and name of the Fileshare Configuration file.

Initiators

You can add a batch initiator that will be a permanent feature of the enterprise server. It will start when the enterprise server is started.

To add a new batch initiator:

  1. Click * New.

    This opens the JES Initiator dialog box.

  2. In the Name field, type the name of your initiator.
  3. In the Class field, type the list of job classes that you want the initiator to run.
  4. Optionally, in the Description field, type a description of the initiator.
  5. Click Save.
Note: Initiators can be modified once the enterprise server region has been stopped.

If you delete an initiator whilst the enterprise server region is running, an initiator of the same class will also be stopped from the running region.

Printers

You can add a printer SEP that will be a permanent feature of the enterprise server. It will start when the enterprise server is started.

To add a new printer SEP:

  1. Click * New.

    This opens the JES Printer dialog box.

  2. In the Name field, type the name of the printer.
  3. In the Class field, type the list of job classes that you want the printer to run.
  4. In the Exit Module field, type the program name that is to be associated with the printer process.
  5. Optionally, in the Description field, type a description of the printer.
  6. Click Save.
Note: Printers can be modified once the enterprise server region has been stopped.
Parent topic: JES


Spool

Use this page to view the spool files that have been created as a result of submitting JCL on this server.

The spool is displayed as a paginated list which can be navigated through using the left and right arrows and by specifying a page and the number of spool records to display.

Note: Rows that have an Output Type of Active or Dispatch can be cancelled, otherwise they can be deleted.
Name
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.
Merged Spool Index
The merged spool index identifier.
Job ID
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.
Class
The class of the job, as specified on the JOB card.
User
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.
Condition Code
The condition code returned by the job.
Submitted
The date and time when the job was submitted.
Started
The date and time when the job was started.
Completed
The date and time when the job was completed.
MPR
Message Processing Region (MPR) associated with the job.
Priority
The priority of the job, as specified on the JOB card.
Message Class
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.
Process ID
The Process ID (or PID) of the job.
Codeset
The codeset of the output file.
Restart Count
The number of times the job was restarted.
File
The full path of the file containing the JCL that was run.
Region
The name of the enterprise server region on which the JCL was run.

Filters

You can filter the list by clicking Filter. Selecting from the filter options, and then click Apply.

Merged Spool
Check this to filter the merged spool file.
Merged Spool Index
Enter the merged spool index identifier.
Name
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
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 Number
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.
Class
The class of the job, as specified on the JOB card.
Cond
The condition code of the job.
Output Types
Input
Jobs waiting to start. Typically, because no initiator for the correct class is currently available.
All
Check this to check all output and queue types.
In Hold
The Held Input queue. This lists jobs that are held. Specified as HOLD on the JOB card, or Hold button on a job's entry in the input queue.
Dispatch
Click this to see the Dispatch queue. This lists jobs that are scheduled to a batch or printer process but not yet actioned, otherwise known as a transient state.
Active
Click this to see the Active queue. This lists jobs that are currently running.
Complete
Click this to see the complete queue. This lists data sets with the following statuses:
Queue
This lists data sets with the following statuses:
Output
The output files waiting to be printed (usually waiting for a printer for the correct class to be available).
Out Hold
The output files that are held (Hold button on a job's entry in the Complete Queue).
Printed
The output files currently being printed.
Sorted By
You can specify the fields to sort in ascending order or check Descending to reverse the order:
  • Name
  • Job ID
  • Submitted
  • User
  • Class
  • Condition Code
Descending
Check this to sort the output in descending order.
Submitted From
Limit the result to Job Submitted after the given date.
Submitted To
Limit the result to Job Submitted before the given date.
Started From
Limit the result to Job Started after the given date.
Started To
Limit the result to Job Started before the given date.
Ended From
Limit the result to Job Ended after the given date.
Ended To
Limit the result to Job Ended before the given date.
Load on navigation
Check this to load the enterprise server region's spool when navigating to this page. This will filter based on the previously selected conditions.

Click Apply to apply the selected filters to the spool list.

Click Reset to restore the previously applied filters.

Click Defaults to display the following options:
Reset Default Filter
Resets the spool filter configuration to the product default for all users.
Set Current Filter as Default
Saves the current spool filter configuration as the default for all users.
Reload Default Filter
Reloads the default spool filter configuration. Taking this action will also reset the spool list.
  • JES Spool Job job-number
  • JES Spool Job job-name - ddname
Parent topic: JES


JES Spool Job job-number

Use this page to view details of a job's execution and change control information for a job.

Apply Click this to apply any changes you have made.

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.

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.

Display Click this to display details of the output from an individual job step. The maximum number of lines returned will never exceed 99999.

DDNAME
The name of the data set produced by the job step; the first entry is always for the system log, sys.log.
Status
The current status of the data set:
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.
Records
The number of records in the output file.
LRECL Min
The minimum record length.
LRECL Max
The maximum record length.
Codeset
The codeset of the output file.
Created
The date and time the output file was created.
Class
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 APPLY. For example, you might want to change the class of a job to a class that has a batch printer SEP specified for it, so that the output data sets can be printed.
Step
The name of the job step that produced this file.
Step Number
The number of the job step that produced this file.
Proc Step
The name of the procedure step, where an output data set was created by a step in a procedure.
Proc Step Number
The number of the procedure step, where an output data set was created by a step in a procedure.
Referenced
The date and time the file was last used in a job.
DS Name
The data set name of the output file, in mainframe format.
Physical File
The filename of the output file, in the format of your local operating system.
Parent topic: Spool


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

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.

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.

Apply Click this to save any changes made.

Delete Click this to delete the job.

General

Name
The name of the job as specified on the JOB card.
Status
Displays the current status of the job. 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 held awaiting release.
SYSOUT Ready
The output data set is available to be scheduled to an output device.
User
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.
COND
Used to test return codes from previous job steps to determine whether to bypass this job step.
File
The full path of the file containing the JCL that was run.
PAC Member
When part of a PAC, this specifies the UUID of the PAC member that processed the job.
Class
The class of the job, as specified on the JOB card. If you want to change the class of the file, specify the new class and click Apply.
Priority
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 Apply.
Step
Displays the name of the job step that produced this file.
Proc Step
Displays the number of the procedure step, where an output data set was created by a step in a procedure.
Restart
Click this to request that the job is restarted.
Advanced Restart Parameters
Accepts the advanced restart parameter format without the job number. See the Job Restart chapter in your product Help for more information.

Messages

Lists the messages for this job.

DD Entries

This table displays the following information:

Status
Displays the current status of the job. The possible values are listed above.
Class
The class of the job, as specified on the JOB card.
DD Name
The name of the data set produced by the job step; the first entry is always for the system log, sys.log.
Step
Displays the name of the job step that produced this file.
Step Number
Displays the number of the job step that produced this file.
Proc Step
Displays the number of the procedure step, where an output data set was created by a step in a procedure.
Records
Displays the number of records in the output file.
Actions
Enables you to perform one of the following actions:
  • View Click to view the content of the DD entry. The maximum number of lines returned will never exceed 99999.
  • Edit
  • Delete

Job Step

Displays job step information.

Parent topic: Spool


Catalog List

Use this page to view the data catalog.

To displays information about data sets, click List.

To add an entry for a data set to the catalog, click * New.

Click entries in the catalog list, and then click Delete to delete the selected entries. Alternatively, click the delete icon [image] on individual rows.

List
This is a filter. Enter a string of one or more characters to limit the list of data sets displayed to those that begin with the string. For example, enter ABC* to display only those data sets that begin with ABC. You can use a single asterisk as a wildcard.
Cataloged Only
Check to view just cataloged data sets or leave unchecked to view uncataloged ones as well as cataloged.
Disable Additional Qualifiers
Use this option to make catalog searching and filtering more consistent with the results produced on the mainframe. Check the option to disable the use of additional qualifiers when filtering the catalog results. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B, as if A.B** had been entered.
DS Org
Displays 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.
DS Name
Displays the data set name of the output file, in mainframe format.
LRECL
Displays the record length for fixed-length records, or the maximum record length for variable-length records, including the 4-byte record header.
RECFM
Displays the record format of the data set.
File Size
Displays the size of the catalog entry file in bytes.
BLKSIZE
Displays the length of a block in bytes.

Actions

The following actions can be performed on each row in the catalog list:

Click Display ( [image]) to display the content of the catalog file. The maximum number of records returned will never exceed 99999. If the DS Org is partitioned (PO) then a list of the Partitioned Data Set (PDS) members will be displayed.

Click DCB ( [image]) to view and modify information for a cataloged data set.

Click Delete to delete this catalog entry.

Filters

Use the following options to filter the catalog list:

DS Name
Filter the available data sets by name, you can use an asterisk '*' as a wildcard.
Cataloged Only
Check this to view just the cataloged data sets or leave unchecked to view uncataloged ones, as well as cataloged.
Disable Additional Qualifiers
Check this to disable the use of additional qualifiers when filtering the catalog results making catalog searching and filtering more consistent with the results produced on the mainframe. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B, as if A.B** had been entered.
DS Org
Limit the returned data sets to those with the selected data set organization. You can use an asterisk '*' to include all types of data set organizations:
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
UNKNOWN
Physical File
Filter the available data sets by the physical file. You can use an asterisk '*' as a wildcard.
Created From
Limit the returned data sets to those which were created after the specified date and time.
Created To
Limit the returned data sets to those which were created before the specified date and time.
Last Referenced From
Limit the returned data sets to those which were last referenced after the specified date and time.
Last Referenced To
Limit the returned data sets to those which were last referenced before the specified date and time.
Expiration Date From
Limit the returned data sets to those which expire after the specified date. This must take the form YYYY/DDD, where YYYY is the year and DDD is the day of the year, where January 1st is 001 and December 31st is 365 or 366 for a leap year.
Expiration Date To
Limit the returned data sets to those which expire before the specified date. This must take the form YYYY/DDD, where YYYY is the year and DDD is the day of the year, where January 1st is 001 and December 31st is 365 or 366 for a leap year.
Load on navigation
Check this to load the enterprise server region's catalog when navigating to this page. This will filter based on the previously selected conditions.
  • Adding and Editing the Catalog Entry
  • PO List
Parent topic: JES


Adding and Editing the Catalog Entry

Use this page to when adding or modifying an entry to the catalog or cataloged data set.

To rename a data set in a catalog, click Rename. This open the Rename Catalog Entry dialog box. In the New Name field, type the new name for the catalog data sets and then click Rename.

Note: When a data set is renamed, the underlying physical file is also renamed, as long as it is stored within a directory under the one in which the catalog file is stored. To enable a physical file stored outside of the catalog subdirectories to be renamed, set the environment variable MF_PCRENAME_LAX=Y. This enables the filename to be changed, but the location remains the same. For allocation overrides to take effect, which might include changing the directory the file is stored in, set MF_PCRENAME_LAX=D. See JCL-specific environment variables for more information.
Catalog
Check this if you want the file to be included in the catalog. By default, this is checked.
DS Name
Specify the data set name of the file, in mainframe format. If you are viewing an entry, it displays the data set name of the file, in mainframe format.
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.
DS Org
The data set organization can be one of the following:
GDG
Generation Data Group
IS
Indexed Sequential
PO
Partitioned
PS
Physical Sequential
VSAM
Virtual Storage Access Method
UNKNOWN
Note: Depending on the value selected additional fields might be displayed. See below for more information.
Codeset
Specify the codeset in which you want the contents to be stored as. This field defaults to ASCII:
  • ASCII
  • EBCDIC
  • Unknown
LRECL
The record length in bytes for fixed-length records, or the maximum record length for variable-length records, including the 4-byte record header.
BLKSIZE
The length of a block in bytes.
RECFM
The record format of the data set. For all data set organizations except VSAM can be one of the following:
F
Fixed format with no control characters and no record delimiters.
FA
Fixed format with ANSI control characters and no record delimiters.
FB
Fixed blocked format with no control characters and no record delimiters.
FBA
Fixed blocked format with ANSI control characters and no record delimiters.
FBM
Fixed blocked format with machine control characters and no record delimiters.
FBS
Fixed blocked spanned format with no control characters and no record delimiters.
FM
Fixed format with machine control characters and no record delimiters.
FS
Fixed spanned format with no control characters and no record delimiters.
LSEQ
Line sequential format with no control characters and carriage return and line feed as record delimiters.
U
Undefined format. Results can be unpredictable on Windows and UNIX.
V
Variable format with no control characters and Micro Focus type record delimiters.
VA
Variable format with ANSI control characters and Micro Focus type record delimiters.
VB
Variable blocked format with no control characters and Micro Focus type record delimiters.
VBA
Variable blocked format with ANSI control characters and Micro Focus type record delimiters.
VBM
Variable blocked format with machine control characters and Micro Focus type record delimiters.
VBS
Variable blocked spanned format with no control characters and Micro Focus type record delimiters.
VM
Variable format with machine control characters and Micro Focus type record delimiters.
VS
Variable spanned format with no control characters and Micro Focus type record delimiters.

If VSAM data set organization has been selected then the following options are available:

ES
Entry Sequence
KS
Key Sequence
LS
Linear Sequence
RR
Relative Record
Created
The date and time the file was created.
Last Referenced
The date and time the file was last used in a job.
Expiration Date
The expiration date of the catalog entry. Takes the format YYYY/DDD where YYYY is the year and DDD is the day or the year, where January 1st is 001 and December 31st is 365 or 366 for a leap year.
MGMTCLASS
The management class for an SMS-managed data set.
File Size
The size of the catalog entry file in bytes.

Additional GDG Fields

If you specify GDG in the DS Org field, then the following additional fields will be displayed:

GDG Max
This is the maximum number of Generation Data Sets (GDS) in the Generation Data Group (GDG).

The minimum value is 1 and the maximum value supported is 255.

Roll Disp

The following options are available:

No Scratch and No Empty
If the data set is a non-SMS managed then the data set is not removed from any volumes it occupies. If the data set is an SMS-managed data set then it is recataloged as a non-VSAM data set in rolled-off status, and is no longer associated with the GDG base.

In addition, only the oldest GDS entry are removed when a new GDS is created that causes GDG LIMIT to be exceeded.

Scratch and No Empty
The GDS is deleted from all disks it occupies when uncataloged from the GDG base.

In addition, only the oldest GDS entry are removed when a new GDS is created that causes GDG LIMIT to be exceeded.

Scratch and Empty
The GDS is deleted from all disks it occupies when uncataloged from the GDG base.

In addition, all GDS entries are removed from GDG base when a new GDS is created that causes the GDG LIMIT to be exceeded.

No Scratch and Empty
If the data set is a non-SMS managed then the data set is not removed from any volumes it occupies. If the data set is an SMS-managed data set then it is recataloged as a non-VSAM data set in rolled-off status, and is no longer associated with the GDG base.

In addition, all GDS entries are removed from GDG base when a new GDS is created that causes the GDG LIMIT to be exceeded.

Additional PO Fields

If you specify PO in the DS Org field, then the following additional fields will be displayed:

Dynamic PDS
Check this field to enable a dynamic Partitioned Data Set (PDS) which will require you to specify the Physical File and PDS Exts fields.
Note: In this case, the Physical File field will point to a folder, not a file.
PDS Exts
Specifies the files to include by typing in a list of one or more filename extensions separated by spaces or commas. Alternatively, to include all files regardless of the filename extension and to also include files that have no filename extension at all, specify * (asterisk).

Additional VSAM Fields

If you specify VSAM in the DS Org field, then the following additional fields will be displayed:

VSAM Type

The following options are available:

  • Cluster
  • Index
  • Data
  • Alternate Index
  • Path
  • DSCB Model
VSAM Attr
Indicates if the key/index is unique or if duplicates exist.
Key Start
Indicates the position in the record the key starts, in bytes.
Key Length
Indicates the length of the key, in bytes.
Record Maximum Length
Indicates the maximum record length, in bytes.
Record Average Length
Indicates the average record length, in bytes.
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 more information.
Cross System
Valid values are 0, 3 or 4. Any value set 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.
Parent topic: Catalog List


PO List

This page displays a lists of the Partitioned Data Set (PDS) members for the selected data set.

Note: In an MVS mainframe environment, a file can be defined as an individual data set or as part of a partitioned data set (PDS). MSS supports both of these methods.

The data sets listed here are associated with a Partitioned Organized (PO) data set, and are known as its members. The member data sets have an organization of Partitioned Data Set Member (PDSM).

Check single or multiple entries in the catalog list then click Delete to delete the selected entries. Alternatively, click the delete Delete icon on individual rows.

Click DCB to view and modify information for the corresponding cataloged data set.

DS Org
Displays the data set organization of the data set. Can be one of:
PDSM
Partitioned data set member (Micro Focus organization)
PO
Partitioned Organized
DS Name
Displays the data set name of the output file, in mainframe format.
Display
Click Display to display the content of the Partitioned Data Set (PDS) member.
DCB
Click [image] to view and modify information for the corresponding cataloged data set.
Parent topic: Catalog List


JES Control

Use this page to submit JCL jobs and start batch initiator and batch printer SEPs for this server.

To submit JCL to JES, drag and drop the file into the dotted area. Alternatively, click the area and browse to the location of your file. Click VSE, JES2, or JES3, depending on what the job uses, and then click Submit to run the JCL job you have specified.

Submit JCL to JES

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 JES Initiators and Printers

Classes
The classes that you want the batch initiator SEP or a batch printer SEP you are about to start to support.
Exit Module / MPR Name
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 field.
Type
Choose the type of SEP you want to start from the list:
  • Initiator
  • Printer
  • IMS MPR
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.
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.
Note: If CASRDO44_NEWSUB=OFF has been specified in the region's Configuration Information field of the General Properties page or as an environment variable, then the JES control page will submit only local jobs, rather than remote jobs.
Parent topic: JES


JES Alias

This page lists the Micro Focus implementations of mainframe utilities.

If your user has appropriate access rights, you can add, delete, or change an entry so that your own utility is used. See Resource Classes for ESMAC and Operator Command Security in your product Help for more information.

Click * New to create a new entry in the table.

Click Edit at the end of the row which you want to edit.

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
Displays the name of the mainframe utility.
Alias
Displays the name of the Micro Focus implementation of the utility.
Parent topic: JES
Related reference
Resource Classes for ESMAC and Operator Command Security


IMS

This menu provides pages that enable you to configure, control, and view IMS transactions.
Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).
  • IMS Configuration
    Use this page to configure IMS support for this enterprise server.
  • IMS Transaction List
    Use this page to view the IMS transactions defined on the current server.
  • IMS Control
    Use this page to start a Message Processing Region (MPR) and perform a number of other IMS-related administration functions for this server.
Parent topic: Regions


IMS Configuration

Use this page to configure IMS support for this enterprise server.

Click Apply to save any configuration changes.

IMS General

Codeset Bias
Choose the default codeset to use for transactions running on this enterprise server:
ASCII
Transactions use ASCII.
EBCDIC
Transactions use EBCDIC.
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.

DB General

Database Path
Specify the location of the IMS data files and any .slf files to be used by the IMSDBUEA segment exit routine.

Locking

IRLM Locking
Check this to enable 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
Check this to create 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
Check this to create a system dump when a deadlock is detected. Maps to the ES_IMS_DUMP_ON_DEADLOCK environment variable.
Locked Resource Timeout
Specify 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.

Recovery

Enable Forward Recovery
Check this to enable 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.

Compression

Key Compression
Check this to turned on key compression.
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.

Application

Application Path
Specify the location of the transaction programs running on this enterprise server. Default is $IDE_LAODLIB.
Trailing Space
Check this to specify that you must add a trailing space when entering transaction names in this enterprise server. This is checked by default.
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. The default is 0.
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
The programs define attributes as binary values. This is the default.
Character
The programs define attributes as characters.
MFS Null Character
Specify the character to use as the MFS NULL character. The default is X'36'.
Hexadecimal
Check this to if you specify the MFS Null Character in hexadecimal form. This setting only has an effect on programs compiled using the ASCII character set; it is ignored for programs compiled using EBCDIC.

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.
Queue Name
Specify an alternative path and filename for the IMS message queue. The default is ESDEMO/IMSMESGQ.dat in the enterprise server's work area directory.
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 more information.
Buffer Count
This is the tuning control. More buffers means less swapping of blocks in memory for message queue activity. By default this is 2.
Cold Start
Choose the information that is deleted when you next start this enterprise server:
None
No information is deleted. This is the default setting.
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 field occurs each time this enterprise server starts. The default setting is unchecked.
Active 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.

Message Processing Regions

Click * New to open the MPR Properties dialog box and configure a message processing region (MPR) for this server:

Name
Specify the name of the MPR.
Class(es)
Specify the list of transaction classes that this MPR can run.
Enable Pseudo Wait-for-Input (PWFI)
Check this field to enable Pseudo Wait-For-Input (PWFI) dispatch behavior. When enabled, the MPR stays scheduled until another input message is received.
Description
Optionally, specify a text description of the MPR.

You can view a list of MPRs displayed in the Message Processing Regions table.

Parent topic: IMS
Related reference
IMS Control
Related information
ES_ACBLIB
ES_IMS_ROLLFORWARD


IMS Transaction List

Use this page to view the IMS transactions defined on the current server.

Click * New to specify a new transaction for use on the current server.

Click Edit to edit the IMS transaction.

Click Delete to delete the IMS transaction.

The list displays the following information for a transaction:

Name
The name of the transaction.
PSB Name
The name of the PSB associated with this transaction.
Class
Specifies the message class for this transaction.
Priority
Specifies 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 value is 1.
Process Limit
Specifies 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. A value of 9999 indicates that no limit is to be imposed.
Description
The description for the transaction.
  • IMS Transaction (Create)
  • IMS Transaction Edit
Parent topic: IMS


IMS Transaction (Create)

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 simultaneously:
Parallel
The application program can be scheduled into more than one message processing region simultaneously.
Serial
The application program cannot be scheduled into more than one message processing region simultaneously. This option is not supported.
SPA Size
Specify the size of the conversational scratchpad area (SPA). The size specified must be between 16 bytes and 32767 bytes.
SPA Truncate
Check this field to set the truncate data option to on.
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.
Use System Value
Check this to use the system wide value for the transaction time threshold set in the 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 Priority 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 Priority Limit Count. The priority must be in the range 0 through 14. The default is 1.
Priority 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.
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.
Process Limit Time
The maximum time that a program can spend processing this transaction (or a message from it) in a single scheduling. 65535 indicates that no limit is to be imposed.
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.
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.
Enabled
Check this field to enable the transaction program.
To Uppercase
Check this field to translate the input data to uppercase.
Fast Path
Specify 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.
Character
The program defines attributes as characters. 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.
Password Reverification Required
If checked, every time the transaction is invoked, the password of the user that invoked it is reverified and access to it is denied if the verification fails.
Parent topic: IMS Transaction List


IMS Transaction Edit

Use this page to define a new transaction or view an existing one.

Click Apply to save your changes.

Click Install to install and make the resource active.

Click Delete to delete this transaction.

Click Copy to create a new transaction. The values on the current page will be used as the basis for the values in the new transaction.

Click Dump to create and display a dump of the transaction information.

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 simultaneously:
Parallel
The application program can be scheduled into more than one message processing region simultaneously.
Serial
The application program cannot be scheduled into more than one message processing region simultaneously. This option is not supported.
SPA Size
Specify the size of the conversational ScratchPad Area (SPA). The size specified must be between 16 bytes and 32767 bytes.
SPA Truncate
Check this field to set the truncate data option to on.
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.
Use System Value
Check this to use the system wide value for the transaction time threshold set on the 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 value 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 value is 1.
Priority 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.
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.
Process 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.
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.
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.
Enabled
Check this field to enable the transaction program.
To Uppercase
Check this field to translate the input data to uppercase.
Fast Path
Specify 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.
Character
The program defines attributes as characters.
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 value 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.
Password Reverification Required
If checked, every time the transaction is invoked, the password of the user that invoked it is reverified and access to it is denied if the verification fails.
Parent topic: IMS Transaction List


IMS Control

Use this page to start a Message Processing Region (MPR) and perform a number of other IMS-related administration functions for this server.

Execution

Start
Click this to start the IMS Message Processing Region (MPR).
Class(es)
Specify the transaction classes that can run in the message processing region.
Name
The transaction names that can run in the message processing region.
Debug
Check this if you want to debug the IMS transactions that will run in this message processing region.
P-WFI
Pseudo Wait-For-Input (PWFI) dispatch behavior. When enabled, the MPR stays scheduled until another input message is received.
Renew
Click this to delete information from the system cache and to reload the current information from disk.
Submit
Choose a command to submit and then click SUBMIT to execute the command. The results are displayed below the Command Input field:
/?
Choose this to display a list of available commands.
/dis TRAN all
Choose this to execute a /dis TRAN all command.
/dis USER all
Choose this to execute a /dis USER all command.
/dis TPIPE all
Choose this to execute a /dis TPIPE all command.
/dis TPIPE free
Choose this to execute a /dis TPIPE free command.
/dis DB all
Choose this to execute a /dis DB all command.
/dump TM
Choose this to execute a /dump TM command.
/dump DB
Choose this to execute a /dump DB command.
Command Input
Type a command to execute then click SUBMIT.

TM

Click Apply to apply settings for the 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.
Current Message Queue Size
The current size of the IMS message queue in blocks.
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 cushion 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.
Enable Q Flush Aggregate
Enables the aggregation of transactional flushing of operating system buffers to disk.
Q Flush Time
An interval of time, in milliseconds, during which flush requests are held and allowed to accumulate before flushing. Valid values are 0 through 255.
Disable Dynamic Flushing
Check this to disable 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 value is 64. Specifying 0 indicates that keypoints are only generated when the enterprise server starts and shuts down.
Count since Last Keypoint
The KEYPOINT count is a count of the number of KEYPOINTs written since a restart.

Message Queue Diagnostics

Click Summary to display a summary overview of IMS message queues.

Click Display to display a block-number/segment of the message queue as specified in the Segment field.

Application Codeset Bias
Displays the codeset used for this transaction:
Default
The transaction inherits the system bias codeset.
ASCII
The transaction uses ASCII.
EBCDIC
The transaction uses EBCDIC.
ASCII Application MFS Attribute Bias
This displays how attributes are defined for transaction programs running on this enterprise server:
Binary
The programs define attributes as binary values, this is the default.
Character
The programs define attributes as characters. This setting only has an effect on programs compiled using the ASCII character set; it is ignored for programs compiled using EBCDIC.
ASCII Application MFS null Character Bias
Displays the character to be use as the MFS NULL character. This can be a character or in 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.
Transaction
Trailing Blank Required - If this is true then a trailing space has to be added when entering transaction names for this enterprise server. The default setting is true.
TM Control Start Request
Cold start the IMS TM message queue.
Message Queue File Buffers
The message queue buffer count.
Message Queue File Size
The current size of queue file on disk. This can change over time as a result of dynamic expansion.
Message Queue File Name
The message queue file name.
Parent topic: IMS


MQ

This menu provides pages that enable you to configure MQ listeners, writers, and startup MQ listeners.
Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).
  • Startup MQ Listeners
    Use this page to create, edit, delete, and view startup MQ listeners.
  • MQ Listeners
    Use this page to create, edit, delete, and view MQ listeners.
  • MQ Writers
    Use this page to view information about the dynamically created MQ writers available on the current server.
Parent topic: Regions


Startup MQ Listeners

Use this page to create, edit, delete, and view startup MQ listeners.

The table displays the following information:

Name
Specifies the name for the startup MQ listener.
MQ Queue Name
Specifies the name of an existing MQ Queue defined for the specified MQ Queue Manager.
MQ Queue Manager Name
Specifies the name of an existing MQ Queue Manager. You create Queue Managers and Queues in WebSphere MQ.
Enabled
Specifies if the MQ listener is enabled.

To create a new startup MQ Listener, click * New. This opens the MQ Listener Configuration dialog box:

  1. In the Name field, type the name for the startup MQ listener.
  2. In the MQ Queue Name field, type the name of an existing MQ Queue defined for the existing MQ Queue Manager.
  3. 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.
  4. Ensure that the Enabled field is checked, this field is checked by default.
  5. Click Save.

You can modify an existing startup MQ listener configuration by clicking the Edit icon at the end of the row for the required MQ listener. This will open the MQ Listener Configuration dialog box. You can delete the startup MQ listener by clicking the Delete icon at the end of the row for the required MQ listener.

Parent topic: MQ


MQ Listeners

Use this page to create, edit, delete, and view MQ listeners.

To enable MQ listener support, click MQ listener support enabled, and then click Apply.

The table displays the following information:

Name
Specifies the name for the new MQ listener.
MQ Queue Name
Specifies the name of an existing MQ Queue defined for the specified MQ Queue Manager.
MQ Queue Manager Name
Specifies the name of an existing MQ Queue Manager. You create Queue Managers and Queues in WebSphere MQ.
Enabled
Specifies if the MQ listener is enabled.

To create a new MQ Listener, click * New. This opens the MQ Listener Configuration dialog box:

  1. In the Name field, type the name for the MQ listener.
  2. In the MQ Queue Name field, type the name of an existing MQ Queue defined for the existing MQ Queue Manager.
  3. 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.
  4. Ensure that the Enabled field is checked, this field is checked by default.
  5. Click Save.

You can modify an existing MQ listener configuration by clicking the Edit Edit icon at the end of the row for the required MQ listener. This opens the MQ Listener Configuration dialog box. You can delete the MQ listener by clicking the Delete Delete icon at the end of the row for the required MQ listener.

Parent topic: MQ


MQ Writers

Use this page to view information about the dynamically created MQ writers available on the current server.

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.

An MQ writer is an Enterprise Test Server component that sends messages back to a WebSphere MQ output queue. You do not define MQ writers. Enterprise Test Server creates them dynamically as needed.

See MQ-IMS Bridge for more information.

The following MQ writer information is displayed:

Name
The name of the MQ writer.
Status
The status of the MQ writer:
  • Connected
  • Starting
  • Stopping
  • Retrying
  • Lost
  • Deleted
  • Initial
  • Stopped
  • None
Type
The type of the MQ writer:
  • Unkn - Unknown
  • Trig - Trigger Monitor
  • C-Br - CICS Bridge
  • C-VSE - CICS VSE
  • I-Br - IMS Bridge
  • Note - Notes Agent
  • Win - Windows
  • WinNT - Windows NT
  • Othr - Other
  • CICS
  • DOS
  • OS400
  • IMS
  • Java
  • NSK
  • OS/2
  • Unix
  • VMS
  • VOS
  • XCF
  • z/OS
Message Count
The number of messages processed.
Queue Name
The name of the MQ queue being written to.

You can view an existing MQ writer configuration by clicking the View icon at the end of the row for the required MQ writer. This will display the writer information.

You can delete an MQ writer by clicking the Delete icon at the end of the row for the required MQ writer.

Parent topic: MQ


Character encoding support for enterprise server region

If your enterprise server region needs to support a character set other than windows-1252 then you can set the MFACCCGI_CHARSET environment variable. See General Enterprise Server Environment Variables for more information. In addition you will need to install the corresponding Coded Character Set Identifier (CCSID) translation table. See Installing CCSID translation tables for more information.

Note: The installed CCSID translation table must support the required character set and unicode.
Parent topic: Regions
Related reference
General Enterprise Server Environment Variables
Installing CCSID translation tables


Servers

You can configure an enterprise server so that all I/O for CICS or JCL-related files are handled by a stand-alone Fileshare server. The advantage of this setup is that it provides transactional VSAM file access for CICS-related files. Micro Focus recommends this approach for VSAM file support in Enterprise Server.

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.

See Using Fileshare with Enterprise Server in your product Help for more information.

Click Delete to delete the selected Fileshare server.

Parent topic: Regions & Servers
Related reference
Using Fileshare with Enterprise Server


Properties

You can configure settings, connection properties, and view statistics and status information for your Directory Servers.
  • Directory Server Configuration
    Use this page to change configuration settings for the Directory Server.
  • Connection Properties
    Use this page to specify the security settings to be used with this Directory Server:
  • Directory Server Statistics
    Use this page to view statistics and status information about the Directory Server.
Parent topic: Directory Servers


Directory Server Configuration

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.
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.
Listen on Loopback Only
Check this to only allow connections to this directory server on loopback. If this directory server is running on a different machine from ESCWA it will no longer be available.
Maximum Object Count
The maximum number of objects that the repository can hold.
Timeout UI Sessions
Check this if the user interface sessions in the directory server should be subject to a timeout.
UI Session Timeout
If the Timeout UI Sessions field is checked, then you can specify the length of time (in seconds) a session had to be inactive for before it is timed out and the user has to log back in. The default value is 600 seconds (10 minutes).
Generate UDP Broadcast Search Requests
Check this so that 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 for the field to be checked.
Restore Server States on Directory Server Startup
Check this if servers that were previously started when the directory server closed down are to be restarted when the directory server is started.
Mark Servers "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 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 ESCWA. By default this is unchecked.
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 state is unchecked.
Show System Server Types
Check this so that ANIM servers can be displayed if required.
Timeout API Sessions
Check this if API sessions (including ESCWA) in the directory server should be subject to a timeout. The default setting is checked.
API Session Timeout
If the Timeout API Sessions field is checked, then you can set the timeout (in seconds) with a minimum of 60 seconds. The default value is 1200 seconds (20 minutes)

Journal

Use this group to change configuration settings for the Directory Server journal.

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.
Level
Select the type of messages to be written to the journal:
Errors Only
Select this if you want journal entries to be written for errors only.
Errors and Warnings
Check this if you want journal entries to be written for errors and warnings only.
All Standard Information
Check this if you want journal entries to be written for all events.
Extra Debug Information
Check this if you want journal entries to be written for additional file and internal operations. Only check this option if specifically requested to by OpenText Support for Micro Focus Products.
CTF Trace
Check this if you want journal entries to be written through the Consolidated Trace Facility (CTF).

Monitor

Use this group to change configuration settings for the Server Monitor.

Enabled
Check this field to start the server monitor. Uncheck it to stop the server monitor at the next keep-alive interval timeout. The default is checked.
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.
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.
Parent topic: Properties


Connection Properties

Use this page to specify the security settings to be used with this Directory Server:
Enabled
Check this to specify that the directory server will use a TLS connection.
TLS Port
The port the directory server will use for TLS connections.
Use Custom Certificates
If TLS is enabled, check this option and specify the paths for root certificates, server certificate, key file, and passphrase. In addition, the MF_ROOT_CERT environment variable will need to be set to the root-certificates file path.
Certificate File
Specifies the absolute path to the certificate file (.pem). If multiple certificates are used, separate the paths with a semicolon ';'.
Keyfile
Specifies the absolute path to the keyfile (.pem).
Keyfile Password
The password for the keyfile specify it here. If multiple keyfiles are used, separate the passwords with four colons '::::'.
Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This takes the following form:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path

Advanced

Certificate Password
If the certificate is locked with a password, specify it here. If multiple certificates are used, then separate the passwords with two colons '::'.
Honor Server Cipher List
By default, the Honor Server Cipher List is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
Protocols
The list of TLS protocols to be used, in order of precedence. Each specified protocol is preceded by one of the following operators:
!
Exclude: Permanently exclude the protocol and ignore any subsequent attempt to add the protocol back in.
+
Add: Add the protocol to the existing collection.
-
Delete: Delete the protocol from the existing collection. For example, to only use TLS1.1 and TLS1.2, type:
-ALL+TLS1.1+TLS1.2
Note: The Protocols field now supports TLS1.3.
Cipher Suites
Specifies the priority of cipher suites to be used. The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:
!
Exclude: Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add: Add the cipher suite to the end of the collection.
-
Delete: Delete the cipher suite from the existing collection. By default, the following cipher suite list is used:
kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL
!eNULL !LOW !MD5 !EXP
Diffie-Hellman Minimum Group Size
Specifies the size in bits of the modulus length of the Diffie-Hellman group:
  • Default
  • 512 bit
  • 1024 bit
  • 2048 bit
  • 4096 bit
Note: Micro Focus recommends a minimum modulus size of 2048 bits.
Key Exchange Cipher Groups
The key exchange cipher groups to be used, separated by semicolons ';'. For example:
secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1
Parent topic: Properties


Directory Server Statistics

Use this page to view statistics and status information about the Directory Server.
Location
Displays 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
Displays the last action performed on the repository.

Options

User Access
Displays what level of access is available to users:
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 the level of journal logging that is in force.

Licensed Features

SOA
Specifies whether the Service-Oriented Architecture (SOA) is part of the licensed features.
MSS
Specifies whether the Mainframe Subsystem Support (MSS) is part of the licensed features.

Server Objects

Total Count
Displays the total number of objects stored in the local repository.
Servers
Displays the number of servers stored in the local repository.
Communications processes
Displays the number of communications processes stored in the local repository.
Listeners
Displays the number of listeners stored in the local repository.
Services
Displays the number of service operations stored in the local repository.
Handlers
Displays the number of request handlers stored in the local repository.
Packages
Displays the number of implementation packages stored in the local repository.
XA Resources
Displays the number of definitions of XA resources stored in the local repository.
JES Initiators
Displays the number of JES initiators that are available on the current server.
JES Printers
Displays the number of JES printers that are available on the current server.
IMS MPRs
Displays the number of Message Processing Regions (MPRs) that are available on the current server.
MQ Listeners
Displays the number of MQ listeners that are available on the current server.

Request Processing

TCP Requests
Displays 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
Displays the number of UDP requests received since the Directory Server was started. These come only from program clients.
MLDAP Requests
Displays 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
Displays the maximum number of concurrent MLDAP requests that have been processed at any time since the Directory Server was started.
Current Thread Count
Displays the number of MLDAP requests currently being processed.
Successful Log On Requests
Displays the number of successful log on requests made to this directory server.
Failed Log On Requests
Displays the number of failed log on requests made to this directory server.

Internal Security Objects

Administration Users
Displays the number of administration users for this directory server.
User Groups
Displays the number of user groups for this directory server.
Permissions
Displays the number of available permissions that can be assigned to a group.
Access Control Lists
Displays the number of Access Control Lists (ACLs) that are set for this directory server.

Paths

COBDIR
Displays 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
Displays the location of the system programs that make up Enterprise Server.
Artwork
Displays the location of the graphics files that the Directory Server uses in its interface.
Help and Documentation
Displays the location of the documentation for Enterprise Server.
Default Trace and Journaling
Displays the location of the default trace files and journals created by Enterprise Server.
Current Trace and Journaling
Displays the location of the current trace files and journals created by Enterprise Server.
Options Configuration
Displays the location of the current Directory Server option settings.
Security Configuration
Displays the location of the current Directory Server security configuration.
Parent topic: Properties


Security

You can configure security managers and security settings for Directory Servers.
  • Defined External Security Managers
    Use this page to manage the pool of security managers available for Directory Server and enterprise servers to use for resolving security queries.
  • Default Security Facility Configuration
    Use this page to define default security settings that can be used with Directory Server and enterprise servers.
  • Directory Server Security Facility Configuration
    Use this page to define security settings that can be used with a Directory Server.
Parent topic: Directory Servers


Defined External Security Managers

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.

Click +Add to add a new security manager. This opens the External Security Manager Configuration dialog box.

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.
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.
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. See the documentation supplied with the module for more information.
Authorized ID
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. See the documentation supplied with the module for more information.
Password
The password for the authorized ID.
Description
Specify a description of the security manager.
Configuration Information
Specify any additional configuration settings that the module requires.
Cache limit
If the module has a configurable cache for holding responses from the security manager, enter its maximum size in kilobytes here.
Cache TTL
If the module has a configurable cache for holding responses from the security manager, enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be required from the security manager.
Note: Enterprise Server and Directory Server also have their own configurable caches for security information. These are checked before submitting queries to the security manager module.

In the defined external security managers list, the Used By column displays the security manager lists that include this security manager.

To edit an external security manager, click Edit at the end of the row for the security manager you want to modify.

To remove an external security manager, click Remove at the end of the row for the security manager you want to remove.

Parent topic: Security


Default Security Facility 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.

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.
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.
Use all groups
Check this if a user requesting authorization is to have the permissions of every group to which they belong. 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 TTL
Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be required from the security manager.
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.
Configuration Information
Specify any additional configuration settings that the security facility requires.
Parent topic: Security


Directory Server Security Facility Configuration

Use this page to define security settings that can be used with a Directory Server.
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.
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.
Use all groups
Check this if a user requesting authorization is to have the permissions of every group to which they belong. 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 TTL
Enter the maximum time in seconds that an entry in the cache can be used to satisfy requests before the details must be required from the security manager.
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.
Configuration Information
Specify any additional configuration settings that the security facility requires.
Parent topic: Security


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.

Click Show All to display all entries in a single list.

Click Download to download the entire Journal. This file will contain all columns as displayed by the Raw View option.

Click Export to export the journal entries to a text file. The text file will be called journal.txt and will be saved to C:\ProgramData\Micro Focus\<product name> (assuming your %SYSTEMDRIVE% is C:) (Windows), or /var/mfcobol/logs (UNIX). You might do this to load the journal file into a text editor to search for events involving specific objects or to annotate entries. If journal.txt already exists, it will be overwritten.

Click Delete 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.

Click View to apply the changes made to the Page and entries fields.

Entry ID
Displays 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.
Timestamp
Displays the local date and time that the journal record was written to the journal file.
Source
Displays the unique identifier string associated with a particular session.
Process ID
Displays the process ID of the journal entry.
Thread ID
Displays the thread ID of the journal entry.
Message ID
Displays the message ID of the journal entry.
Message Type
Message types are:
I
Information
W
Warning
E
Error
S
Severe
Message
This is the message text in the journal entry.

Some messages are colorized, warning messages are yellow and are denoted with an exclamation point in a triangle icon. Error messages are red and are denoted with a lightning icon.

Parent topic: Directory Servers


Scale-Out Repositories

These resources represent a connection to a third-party configuration store for use in scale-out infrastructure.

To create a PAC:

  1. In the menu bar, click Native.
  2. In the navigation pane, click SORs.
  3. Click +Add, this opens the Scale-Out Repository Configuration dialog box.
  4. In the Name field, type the name of the SOR.
  5. In the Type list, select the SOR type. Redis and Oracle Coherence are supported as SORs. See Scale-Out Performance and Availability Clusters for more information.

    The default is Redis.

    • If Redis is selected, in the Connection Path(s) field, type the server name and port number.

      If you are connecting to a TLS enabled Redis repository, click Enable TLS and then complete the certificate and keyfile fields as required.

      Note: You must specify the Certificate Authority Filepath, Certificate Filepath, and Private Key Filepath properties on the Advanced Region Properties page for all enterprise server region that are part of a PAC which has a TLS enabled Redis SOR.

      If you are using Redis Sentinel or Cluster, you can specify the connection details for multiple nodes. Click + to add an additional node name and port number.

    • If Coherence is selected, in the Connection String field, type the connection string which takes the form [userid@][configfile][,property=[value]]…

      See PAC and SOR Environment Variables for more information.

  6. Click Save.
To edit a SOR:
  • Click the [image] Edit icon at the far right of the row.

SORs in this group are available for use in a PAC.

Important: Only one SOR can be associated with a given PAC. A SOR can be specified with multiple Redis Sentinel or Cluster connections. This configuration can help support high availability. You can specify multiple connections in the Connection Path(s) field.
  • Scale-Out Repository Information
    This page displays information on the PAC and its corresponding Scale-Out Repository (SOR) and regions.
Parent topic: Native


Scale-Out Repository Information

This page displays information on the PAC and its corresponding Scale-Out Repository (SOR) and regions.

Click Reconnect to close the current connection to this SOR. ESCWA will then attempt to establish a new connection.

Note: Reconnecting might affect other users and take some time.

Connection Information

Type
Type of Scale-Out Repository (SOR) being used:
  • Redis
  • Coherence
TLS Connection
Identifies if the connection to the Redis Server is TLS enabled.
Redis Server Address
Specifies the address of the Redis Server used by this SOR (ip-address:port).
Using Redis Sentinel
Identifies if this SOR is using Redis Sentinel.
Redis Sentinel Address
Specifies the Redis Sentinel instance that provided the master address (ip-address:port).

Performance and Availability Clusters

Name
The name of this Scale-Out Repository's (SORs) PAC.
Version
The version of the product the PAC is running on.
  • Performance and Availablity Cluster Information
Parent topic: Scale-Out Repositories


Performance and Availablity Cluster Information

PAC Information

Name
The name of this Scale-Out Repository's (SORs) PAC.
Status
Displays the status of the PAC:
  • Starting
  • Started
  • Failed
Start Type
Displays how the PAC was started:
  • Cold
  • Warm
PAC Working Mode
The bitism of the first region started:
  • 32 bit
  • 64 bit
Version
The version of the product the PAC is running on.
OS
Displays the type and version of the first started region's operating system.
SORs Used by Regions
Lists of comma separated SORs used by regions in this PAC.

Region and Server List

Name
Displays the region name that the SOR is associated with.
Host
Displays the server name or IP address (IPv4 or IPv6) of the region.
Port
Displays the port number used by the region.
Parent topic: Scale-Out Repository Information


Mainframe

This page lists Mainframe Access servers and their key configuration properties.
Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).

To enable the mainframe features you must set REST_API="1" in your mainframe XML configuration file and give users appropriate permission. See REST_API and Define Mainframe Access Web API to the Security Subsystem for more information.

To add a new Mainframe Access server:

  1. Click +ADD

    This opens the MAINFRAME ACCESS SERVER dialog box.

  2. In the Name field, type the name of your Mainframe Access server.
  3. In the Host field, type the name of the host or IP address. If you are connecting via TLS, type its Subject Alternate Name (SAN), or the Common Name (CN) of the identification certificate that the server is using.
  4. Optionally, in the Port field, you can modify the default port number.
  5. Optionally, click Enable TLS to enable secure communications with the Mainframe Access server.
  6. From the Codepage list, choose the codepage to use with the Mainframe Access server. By default, the codepage is set to 037.
  7. Optionally, in the Description field, type a short description for the Mainframe Access server.
    Note: The description is displayed in the Mainframe Access servers list.
  8. Click Save.

You can edit or remove Mainframe Access servers by clicking the appropriate icon at the far right of a Mainframe Access server row.

  • Mainframe Access Server Task List
    Use this page to view a list of Mainframe tasks.
  • Mainframe Access Server User List
    Use this page to view information on users currently logged on Mainframe Access servers.
  • Mainframe Access Server Statistics
    Use this page to view Mainframe Access (MFA) statistics:
Parent topic: Enterprise Server Common Web Administration


Mainframe Access Server Task List

Use this page to view a list of Mainframe tasks.

The task list can be filtered by typing in characters into the filter fields. Only matching rows will be displayed. Clicking on the displayed column headers will toggle the order in which the list is sorted:

XDBOUT
Click this to download a copy of the //XDBOUT DD SYSOUT data set from the running server.
SET TRACE LEVEL
Click this and choose the trace level required:
Off
Sets tracing to off.
Short
Limits the display of send data, receive data, and storage areas to 256 characters.
Full
Sets tracing to on.
JOB NAME
The JES identifier for a Job, Task, or TSO instance. This can be up to 8 alphanumeric characters long.
JOB ID
The JES identifier for a Job, Task, or TSO instance. This field has the format XYZNNNNN where XYZ is either JOB, STC, or TSO and NNNNN is an integer.
ASID
The Address Space ID (ASID) which is a hexadecimal value up to 4 characters long.
OWNER
The ASID of the address space that started this job.
GROUP
Identifies the type of Application Server the task belongs to. It can have one of the following values:
CHGX
ChangeMan Application Server.
ENDV
Endevor Application Server.
MFAS
Data Connect Dependant Address Space.
AMSQ
AMS Application Server.
TSOX
TSO Application Server.
PROCEDURE NAME
The name of the procedure that was run in JCL when the job started.
USER ID
The User ID which can be up to 8 characters long.
Parent topic: Mainframe


Mainframe Access Server User List

Use this page to view information on users currently logged on Mainframe Access servers.

The users list can be filtered by typing in characters into the filter fields. Only matching rows will be displayed. Clicking on the displayed column headers will toggle the order in which the list is sorted:

USER ID
The User ID which can be up to 8 characters long.
USER INDEX
The User Index which can be up to 8 digits long.
LAST TRANSACTION
The last transaction to be issued by the user.
JOB ID
The JES identifier for a Job, Task, or TSO instance. This field has the format XYZNNNNN where XYZ is either JOB, STC, or TSO and NNNNN is an integer.
JOB NAME
The JES identifier for a Job, Task, or TSO instance. This can be up to 8 alphanumeric characters long.
ADMIN PERMISSIONS
Permissions can be:
  • NONE
  • READ
  • ALTER
Parent topic: Mainframe


Mainframe Access Server Statistics

Use this page to view Mainframe Access (MFA) statistics:

MAINFRAME ACCESS

Tempfile Creates
Number of temporary data sets created.
Killfile Deletes
Number of killfile deletes.
SNAP Count
Number of MFA SNAP dumps.
User Logons
Number of MFA user logons.
User Logoffs
Number of MFA user logoffs.
Maximum Number of Users
Maximum number of concurrent MFA users that have been logged on.
ESTAEs Driven
Number of ESTAE driven recovery processes.
ESTAEs Retried
Number of ESTAE retried recovery processes.

PUBLIC

Opens
Number of public item libraries opened.
Closes
Number of public item libraries closed.

JES

SSI API Calls
The number of Subsystem Interface (SSI) API calls performed.
System Commands
The number of JES system commands performed.

PDS

Directory Scans
Number of Partitioned Data Set (PDS) directory scans.

QSAM

Statistics related to Queued Sequential Access Method (QSAM):

Opens
QSAM user files opened.
Closes
QSAM user files closed.
Reads
QSAM records read.
Writes
QSAM records written.

VSAM

Statistics related to Virtual Storage Access Method (VSAM):

Opens
VSAM files opened.
Closes
VSAM files closed.
Reads
VSAM records read.
Writes
VSAM records written.

DSS

Errors
Number of Data Set Services (DSS) errors.

SMF

Writes
Number of System Management Facility (SMF) records written.

CPOOL

Statistics relating to the Cell Pool (CPOOL) macro:

Gets
Number of CPOOL cells available.
Frees
Number of CPOOL cells returned to the cell pool.
Errors
Number of CPOOL errors.
Recoveries
Numbers of CPOOL recoveries.
Parent topic: Mainframe


Auditing

There are two methods for auditing different types of activity by configuring the ESCWA interface:

Enable Consolidated Tracing Facility Auditing

You can configure process auditing by enabling the Consolidated Tracing Facility (CTF) trace file, this will collect information on security-related events and preserve it for later review. To enable CTF auditing, perform the following steps:

  1. Click the configuration ( [image]) icon at the top right of the page.

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Click Tracing and Logging Settings.

    This expands the section.

  3. Check Enable Auditing.
  4. Click Apply.

This will log ESCWA audit events in category 2 and 5. See Audit Event Codes for more information.

Enable External Security Facility Auditing

You can configure External Security Facility (ESF) auditing to collect information about ESCWA ESF events. To enable ESCWA ESF auditing, perform the following steps:

  1. In the menu bar, click Security.
  2. Click ESCWA Configuration in the navigation pane.

    This displays the ESCWA Security Facility Configuration page.

  3. Check Create audit events.
  4. Click Apply.

See Enterprise Server Auditing chapter and the Configuring Enterprise Server Auditing topic for more information on the configuration requirements outside of ESCWA including the audit.cfg file.

Note: You can also configure ESF auditing in the context of Directory Servers, the default security ESF configuration, and specific enterprise server region ESF configuration.
Parent topic: Enterprise Server Common Web Administration
Related reference
Tracing and Logging Settings
Enterprise Server Auditing
Restricting ESCWA with ESF
Audit Event Codes
Configuring Enterprise Server Auditing


Security

This chapter covers various aspects of security configuration for ESCWA. It includes External Security Facility (ESF), component administration, security manager's properties, restricting access to components, and configuring Transport Layer Security (TLS).
  • Restricting ESCWA with ESF
    Security configuration is performed from the Security option in the menu bar.
  • Security Manager Administration Operation
    You can access the security administration component from the navigation pane.
  • Security Manager's Properties
    You can configure the security manager's properties from various options, dialogs, and pages.
  • ESF Authentication and ESCWA
    Components in Enterprise Server can have restricted access.
  • Transport Layer Security (TLS) in ESCWA
    The ESCWA server can communicate through multiple channels and across multiple hosts. Micro Focus strongly recommends that you secure your channels of communication.
  • Security Resources to Control ESCWA and API Access
    You can create user view permissions for functional areas of ESCWA by specifying an Access Control List (ACL) string for the listed resource entities.
  • Configuration Report
    You can generate a security report for a specific ESCWA and directory server configuration.
  • Role-based Access
    You can take a role-based access approach to the ESCWA user interface.
Parent topic: Enterprise Server Common Web Administration


Restricting ESCWA with ESF

Security configuration is performed from the Security option in the menu bar.

You can specify multiple external security managers which you can add to the security manager list, also known as the security manager stack.

ESCWA uses an External Security Facility (ESF) to relay authorization requests to one or more security managers. These security managers can control authorization requests for ESCWA itself, directory servers, and enterprise server instances that ESCWA administers.

The order of the security managers on the security manager list determines the order in which they are queried by the security facility. In addition you can specify the following settings to modify the order that the security managers are queried:

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.

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.

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.

ESCWA enables you to display and administer large numbers of users, groups, and resources in the configured security manager.

Note: The user used to login to ESCWA requires Update, Add, Delete access from the User Administration resource. This resource can be found under the Enterprise Server Administration resource class in your data store.
Important: Support for nested groups is not provided within the interface. If required, you can administer nested groups from the esfadmin command-line utility.
  • Specifying an External Security Manager
    This topic shows you how to specify an External Security Manager (ESM).
  • Changing the order of Security Managers
    You can change the order in which the security managers are applied.
  • Group Permissions Cached in ESCWA
    ESCWA caches groups that users belong to, this can have an impact on user administration.
Parent topic: Security


Specifying an External Security Manager

This topic shows you how to specify an External Security Manager (ESM).

To specify an External Security Manager and add it to the security managers list used in the Security Facility Configuration tab:

  1. In the menu bar, click Security.
  2. In the navigation tab, click Security Managers.
  3. Click + Add.

    This opens the External Security Manager Configuration dialog box.

  4. Ensure Enabled is checked.
  5. In the Name field, type the name of your security manager.
    Note: This is the name that will be displayed in the navigation tree.
  6. In the Module field, type the name of the ESM module to use. If you are integrating with an LDAP repository such as Active Directory or OpenLDAP, specify mldap_esm. Use vsam_esm for the VSAM ESM Module. See About Security Managers for more information.
  7. In the Connection Path field:
    • For MLDAP ESM Module, type the hostname or IP address and port number of the LDAP server being connected to. For example ad-host:389. The default is localhost:389.
    • For VSAM ESM Module, type the path to the security data directory. The default is %ProgramData%\Micro Focus\product-name\vsam_esm.
    • For other ESM modules, refer to the documentation for that module. Most will leave this field blank.
  8. In the Description field, type a description of the security manager.
  9. In Authorized ID field, for mldap_esm, type the DN of a user with appropriate permissions for the security manager. For example, CN=Administrator,CN=users,DC=somecorp,DC=com. The default is to use the read-only account MFReader which is defined in the sample LDIF file supplied with the product. For other ESM modules, leave this blank.
  10. In the Password field, type the password for the user specified in the Authorized ID field, if any. The default for mldap_esm is the default password for the MFReader account.
  11. In the Configuration Information field, type the required configuration options. See the documentation for your ESM module, such as MLDAP ESM Module Custom Configuration Information for more information.
  12. By default, the Cache Limit and Cache TTL fields are set to 1024 kB and 600 seconds respectively. Currently, only the MLDAP ESM Module makes use of these settings. See MLDAP ESM Module Caching for more information.
  13. Click Save.

    This adds the specified security facility to the Defined External Security Managers list.

  14. To add the specified external security manager to the ESCWA Configuration in the Security Managers in list, click ESCWA Configuration in the navigation pane, and then click + Add.

    This opens the Defined External Security Managers dialog box.

  15. Check the external security managers that you want to add to the security managers list.
  16. Click Select.
Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
Parent topic: Restricting ESCWA with ESF
Related reference
Enabling and Configuring ESF Caching
Configuring mldap_esm Security Manager for an LDAP Server


Changing the order of Security Managers

You can change the order in which the security managers are applied.

To change the order in the security managers list you can use either of the following methods:

  • You can drag and drop security managers to its new position in the list.
  • You can click the [image] (up) and [image] (down) icons at the end of the row containing the security manager you want to move.
Parent topic: Restricting ESCWA with ESF


Group Permissions Cached in ESCWA

ESCWA caches groups that users belong to, this can have an impact on user administration.

When ESCWA initializes the security facility with its configuration and security manager stack, it caches the groups that users belong to. This is to improve performance by reducing the number of security manager queries. If you subsequently delete a user from a group using ESCWA then the change will filter down to the security manager being pointed at. If you then use that user in ESCWA it will still have the group permissions that were deleted because that is still cached.

Micro Focus recommends that if you modify groups in this manner you should reinitialize the ESCWA cache. To reinitialize the ESCWA cache, click Reinitialize, and then click Renew when prompted in the Reinitialize Security Configuration dialog box.

Parent topic: Restricting ESCWA with ESF


Security Manager Administration Operation

You can access the security administration component from the navigation pane.

Click ESCWA Configuration > Name of security manager. Depending on how you have configured the security manager, you might be prompted for an administrator's username and password.

  • Managing Users
    Adding, editing, and deleting a user.
  • Managing Groups
    Adding, editing, deleting, and viewing group permissions.
  • Managing Resources
    Adding, editing, and deleting resource classes and resource entities.
Parent topic: Security


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: Security Manager Administration Operation


To Add a User

To add a user perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Users.
  3. Click * NEW.

    This opens the User options dialog box.

  4. Click PROPERTIES.

    This expands the list of parameters that you can specify.

  5. In the Account Id field, type the account ID.

    Specify the remaining user details. See Users for more information about the fields.

  6. Click SAVE.
Parent topic: Managing Users
Related reference
Users


To Edit a User

To edit a user perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Users.
  3. Click Edit EDIT in the row containing the user you want to edit.

    This opens the User Options dialog box.

  4. Edit the fields as required.

    See Users for more information about the fields.

  5. Click SAVE.
Parent topic: Managing Users
Related reference
Users


To Delete a User

To delete a user perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Users.
  3. Click Delete DELETE in the row containing the user you want to delete.

    This opens DELETE USER confirmation dialog box.

  4. Click DELETE.
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: Security Manager Administration Operation


To Add a Group

To add a group perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Groups.
  3. Click * NEW.

    This opens the Group options dialog box.

  4. Click PROPERTIES.

    This expands the list of parameters that you can specify.

  5. In the Group field, type the group.

    Specify the remaining group details. See Groups for more information about the fields.

Parent topic: Managing Groups
Related reference
Groups


To Edit a Group

To edit a group perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA > Name of security manager > Groups.
  3. Click Edit EDIT in the row containing the group you want to edit.

    This opens the Group Options dialog box.

  4. Edit the fields as required.

    See Groups for more information about the fields.

  5. Click SAVE.
Parent topic: Managing Groups
Related reference
Groups


To Delete a Group

To delete a group perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Groups.
  3. Click Delete DELETE in the row containing the group you want to delete.

    This opens the DELETE GROUP confirmation dialog box.

  4. Click DELETE.
Parent topic: Managing Groups


Managing Resources

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: Security Manager Administration Operation


To Add a Resource Class

To add a resource class perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Resources.
  3. Click * NEW CLASS.

    This opens the ADD CLASS dialog box.

  4. In the Name field, type a name.
    • Optionally, in the Description field, type a description of the class.
  5. Click SAVE.
Parent topic: Managing Resources


To Add a Resource Entity

Resource entities can only be added to resource classes. To add a resource entity perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Resources.
  3. Click the class that you want to add a resource entity to.
  4. Click * NEW RESOURCE.

    This opens the NEW RESOURCE dialog box.

  5. In the Name field, type a name for the resource entity.

    See Resource Entity for more information about available fields.

  6. Click SAVE.
Parent topic: Managing Resources
Related reference
Resource Entities


To Edit a Resource Class

To edit a resource class perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Resources.
  3. Click the class that you want to edit.
  4. In the Description field, type the new description.
  5. Click APPLY.
Parent topic: Managing Resources


To Edit a Resource Entity

To edit a resource entity perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Resources.
  3. Click the class that contains the resource entity you want to edit.
  4. In the RESOURCE LIST, click [image] EDIT in the row containing the resource entity you want to edit.

    This displays the ENTITY details.

  5. Specify the details for the resource entity as required.

    See Resource Entity for more information about the fields.

  6. Click APPLY.
Parent topic: Managing Resources
Related reference
Resource Entities


To Delete a Resource Class

To delete a resource class perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Resources.
  3. Click the class that you want to delete.
  4. Click DELETE.

    This opens the DELETE CLASS confirmation dialog box.

  5. Click DELETE.
    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 Resources


To Delete a Resource Entity

To delete a resource entity perform the following steps:

  1. In the menu bar, click SECURITY.
  2. In the navigation tab, click ESCWA Configuration > Name of security manager > Resources.
  3. Click the class that contains the resource entity you want to edit.
  4. In the RESOURCE LIST, click [image] DELETE in the row containing the resource entity you want to delete.

    This open the DELETE RESOURCE confirmation dialog box.

  5. Click DELETE to confirm the permanent deletion of the resource entity.
Parent topic: Managing Resources


Security Manager's Properties

You can configure the security manager's properties from various options, dialogs, and pages.
  • Users
    You can specify properties about your security managers users on the User options dialog box.
  • Groups
    You can specify properties about your security managers groups on the Group options dialog box.
  • Resource Classes
    You can specify properties about your security manager resource classes on the RESOURCES OPTIONS page.
  • Resource Entities
    You can specify properties about your security manager resource entities on the RESOURCES OPTIONS page.
Parent topic: Security


Users

You can specify properties about your security managers users on the User options 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 password expiration date. The date format depends on the security manager 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.
Account Expires
Specifies the account expiration date.
Use Token
Permission to use passtokens.
Create Token
Permission to create passtokens.
Custom Configuration
Custom text (not used by Micro Focus).

GROUP MEMBERSHIP

The Selected field lists the groups that the user has joined. Below that is a list of the available groups. You can use the Group's filter to limit the list.

Selected
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 user's PROPERTIES.

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: Security Manager's Properties


Groups

You can specify properties about your security managers groups on the Group options dialog box.

PROPERTIES

List of properties and their definitions:

Group
The group name.
Description
A description of the group.

MEMBERS

Users member properties and their definitions:

Selected
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. You can use the filter to limit the list of users.

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: Security Manager's Properties


Resource Classes

You can specify properties about your security manager resource classes on the RESOURCES OPTIONS page.
Name
Specifies the unique name of the resource class which is displayed in the resource options tree.
Description
Specifies the description of the resource class
Parent topic: Security Manager's Properties


Resource Entities

You can specify properties about your security manager resource entities on the RESOURCES OPTIONS page.
Name

Specify the unique name of the resource class.

Description

Specify a description of the resource class.

ACL
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, for example, "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 Manager's Properties


ESF Authentication and ESCWA

Components in Enterprise Server can have restricted access.

This means that the component's functionality can be restricted to users who have credentials and authorization. Access restriction is controlled by the Security Managers which can be stacked. ESCWA uses this stack to control authorization requests for ESCWA itself, Directory Servers, and enterprise server instances that ESCWA administers. ESF also has its own configuration options along with the stack it is using.

See About the External Security Facility (ESF) and About Security Managers for more information.

Note: Micro Focus recommends that you use the same ESF configuration settings and security manager stack throughout ESCWA and other Enterprise Server components. This will simplify system configuration as you will not need to login to different components as different users.

It is valid to have a single security manager in the stack and this will simplify system configuration.

  • Restricting Directory Servers with ESF
    This topic outlines the steps you need to take to restrict a Directory Server with an External Security Facility (ESF).
  • Restricting Regions with ESF
    This topic outlines the steps you can take to restrict regions with an External Security Facility (ESF).
  • Restricting Enterprise Server for .NET with ESF
    This topic outlines the steps you need to take to restrict Enterprise Server for .NET with an External Security Facility (ESF).
Parent topic: Security
Related reference
About the External Security Facility (ESF)


Restricting Directory Servers with ESF

This topic outlines the steps you need to take to restrict a Directory Server with an External Security Facility (ESF).
To restrict a Directory Server with ESF, perform the following steps:
  • Specify Security Managers for your External Security Managers in your Security Manager List. See Defined External Security Managers for more information.
  • Add the Security Managers you want in the stack to the list that the Directory Server is using and then restrict the Directory Server. See Default Security Facility Configuration for more information.
  • Amend the ESF configuration settings to be used with the stack. See Directory Server Security Facility Configuration for more information.
Parent topic: ESF Authentication and ESCWA
Related reference
Defining a Security Manager List
Setting MF Directory Server Security Configuration
MF Directory Server Security


Restricting Regions with ESF

This topic outlines the steps you can take to restrict regions with an External Security Facility (ESF).

To restrict regions with ESF you have two options:

  1. Use the default ES security configuration for the directory server. This ESF configuration and stack of security managers will be applied to each region by default. See Defined External Security Managers and Default Security Facility Configuration for more information.
  2. Alternatively, you can override the default option on a per region basis. See Security under the General chapter for more information.
Parent topic: ESF Authentication and ESCWA
Related reference
Default ES Security Configuration
Add to Default ES Security Manager List
Server Instance Properties: Security


Restricting Enterprise Server for .NET with ESF

This topic outlines the steps you need to take to restrict Enterprise Server for .NET with an External Security Facility (ESF).

Security managers and security configurations for Enterprise Server for .NET are configured separately from those used by other Enterprise Server components. Use the Enterprise Server for .NET MMC snap-in to create and administer security managers and security configurations for Enterprise Server for .NET.

To restrict Enterprise Server for .NET with ESF:

  1. Open the seeadminserver.exe.config configuration file in an editor. The configuration file is located in the product under binAnyCPU\SEE.
  2. Uncomment the <security> XML element and change as required.
  3. You can then set a security configuration and stack of security managers as required.
Parent topic: ESF Authentication and ESCWA


Transport Layer Security (TLS) in ESCWA

The ESCWA server can communicate through multiple channels and across multiple hosts. Micro Focus strongly recommends that you secure your channels of communication.

You can implement Transport Layer Security (TLS) to ensure that your data and applications remain secure. Communications that are not secured risk being attacked and/or intercepted, leading to a data breach and ultimately impacting on your organization's reputation.

Micro Focus recommends:

  • You use one set of certificate(s) and key(s) per host, which all components on that host should use.
  • Certificates across all the hosts should be signed by the same Certificate Authority (CA) to simplify configuration and management.
  • If you use certificates created by Demo CA, supply the full path to the certificate and key files.

Enterprise Server can use the following list of communication channels:

  • ESCWA to MF Directory Server.
  • ESCWA to ESMAC (enterprise server instance).
  • Communications Process to MF Directory Server.
  • ESCWA to ES for .NET.
Note: Typically, TLS communications do not need to be implemented for communications which are set to communicate via loopback only.
  • Securing Communications between ESCWA and MF Directory Server using TLS
  • Securing Communications between ESCWA and Region Monitor and Control
  • Securing Communications between ESCWA and ES for .NET using TLS
  • Securing Communications Process to MF Directory Server using TLS
Parent topic: Security


Securing Communications between ESCWA and MF Directory Server using TLS

Communications between ESCWA and a Directory Server can be secured by configuring TLS settings on the Connection Properties page. See Connection Properties for more information.

To enable TLS security in ESCWA:

  1. In the menu bar, click Native.
  2. In the navigation pane, expand Directory Servers.
  3. Click the directory server that you want to configure.
  4. Click Properties > Connection.
  5. Check Enable TLS.
  6. In the TLS Port field, type the port number to be used.
  7. Check Use Custom Certificates.
  8. In the Certificate File and Keyfile fields, type the path to your certificate and keyfile respectively.
  9. Click Apply.
Note: The TLS Port specified is not required by the ESCWA configuration for the Directory Server.

Set the MF_ROOT_CERT environment variable to point to the file containing the CA certificate(s) needed to verify the certificate used by the MF Directory Server. Make sure that the .pem file that is pointed to contains the public CA certificate information of the CA that has signed the certificate used by the MF Directory Server.

Note: If your TLS certificate's CN and Subject Alternative Names (SANs) are using hostnames rather than IP addresses, then you must ensure the MFDS_DNS_RESOLVE environment variable is set to Y for the Directory Server, otherwise TLS connections will fail.
Parent topic: Transport Layer Security (TLS) in ESCWA
Related reference
Communications Process
Connection Properties


Securing Communications between ESCWA and Region Monitor and Control

A started enterprise server instance, or region, must have a Web Services and J2EE listener to enable a JSON interface for monitoring and controlling the live instance.

Communications between ESCWA and the region can be secured by configuring the Web Services and J2EE listener. See TLS Advanced Settings in the Listeners topic for more information.

ESCWA will communicate with the listener as a client and therefore requires TLS client configuration. Like COBOL web-service clients and Enterprise Server command-line utilities, ESCWA uses the Micro Focus Common Client (MFCC). This requires the MFCC configuration file mf-client.dat on the ESCWA host machine needs to be configured appropriately. See Micro Focus Common Client for more information.

Typically, you will need to set the "root" configuration item to point to a file containing the CA certificate(s) needed to verify the server certificate sent by your enterprise server instance.

  • If your enterprise server instance uses a server certificate from a public CA, you can probably use the collection of public CA root and intermediate certificates supplied with the product, CARootCerts.pem.
  • If your enterprise server instance uses a certificate generated by Demo CA, use the file entities/CAs/EC_CAcollection.pem from your Demo CA instance.
  • For server certificates generated with an organizational CA, you will need a CA certificate collection from the CA administrator.

See Installing a Client Certificate for Enterprise Server for more information on configuration if your Web Services and J2EE listener requires a client certificate for TLS authentication.

Parent topic: Transport Layer Security (TLS) in ESCWA
Related reference
Listeners
Installing a Client Certificate for Enterprise Server


Securing Communications between ESCWA and ES for .NET using TLS

Communications between ESCWA and ES for .NET can be secured by modifying the seeadminserver.exe.config file located in the binAnyCPU/SEE folder. Ensure that the SEE Admin Server is stopped before you edit the file.

You need to uncomment the <ssl> section. You will require a Personal Information Exchange (.pfx) file to enable transfer of certificates and their private keys.

You can create a .pfx file by using the following openssl command:

openssl pkcs12 -export -inkey key.pem -in cert.pem -out new.pfx

Specify the file and passphrase for the <certificate> tag in the config file, and then start the SEE Admin Server again.

ESCWA talks to ES for .NET as a client, and will require you to install a client certificate. See Installing a Client Certificate for Enterprise Server for more information. Ensure that the root in mf-client.dat on ESCWA's host machine points to the Certificate Authority (CA) list .pem file which contains the public CA certificate information that has signed the certificate used by the SEE Admin Server.

Parent topic: Transport Layer Security (TLS) in ESCWA
Related reference
Installing a Client Certificate for Enterprise Server


Securing Communications Process to MF Directory Server using TLS

ESCWA can communicate to a remotely hosted MF Directory Server and its enterprise server instance. The instances use a Communication Processes to connect to the MF Directory Server. If you have configured your MF Directory Server to use TLS then you need to configure the Communications Process to communicate as a TLS enabled client. See Communications Process for more information.

Communications between Communications Process and a Directory Server can be secured by configuring TLS settings on the Directory Server's Connection Properties page. See Connection Properties for more information. Check Enable TLS, and then check Use Custom Certificates. Specify your certificate and keyfile information.

Note: The MF_ROOT_CERT environment variable must be set to point to the file containing the CA certificate(s) needed to verify the certificate used by the MF Directory Server.

The Directory Server does not support authentication to a Communications Process using a client certificate, so it will not be able to connect to a Communications Process TLS-enabled listener that is configured to require client certificate authentication.

Parent topic: Transport Layer Security (TLS) in ESCWA
Related information
MF_ROOT_CERT


Security Resources to Control ESCWA and API Access

You can create user view permissions for functional areas of ESCWA by specifying an Access Control List (ACL) string for the listed resource entities.

Use the allow:*:read and deny:*:read to grant permissions to groups or users as required. See Access Levels and Permissions for more information.

The following list of default resource entities can be found under the Common Web Administration resource class in the default ESCWA security configuration:

Configuration
Provides access to reading and modifying configuration properties for the Common Web Administration server.

The subsequent resource entities relating to configuration are more specific versions of this entity.

Read, add, update, and delete permissions are queried, depending on the action you want to perform.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
ESCWA Configuration
Provides access to general configuration properties for the Common Web Administration server. Specific version of the configuration entity which relates to the BasicConfig, TraceConfig, and AuditConfig sections of the ESCWA configuration file.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
Communications Server Log
Provides access to Communications Server Log for the Common Web Administration server. Read permission is checked to see if a user can view the communications log for the ESCWA process.

The ACL string for this resource entity:

allow:#DSAdmin group:read
Control
Provides control of the Common Web Administration server. Execute permission is checked to see if a user can shutdown the ESCWA process from an API, or view the list of current ESCWA sessions.

The ACL string for this resource entity:

allow:#DSAdmin group:execute
Dashboard Configuration
Provides access to dashboard configuration properties for the ESCWA server. Specific version of the configuration entity which relates to the DashboardList section of the ESCWA configuration file.

The permissions for this resource control access, edit, and reset actions for the user default dashboard. See Dashboard for more information.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
K8s Configuration
Provides access to kubernetes configuration properties for the Common Web Administration server. Specific version of the Configuration entity which relates to the K8sConfig section of the ESCWA configuration file.

This is an optional part of the configuration file.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
Logon
Provides access control to any ESCWA page preventing it from loading without specific user access. If access is not granted, the ESCWA application still loads and the logon screen is displayed but any further page access is impossible, including any API access.

The ACL string for this resource entity:

allow:*:execute
Mainframe Access Access
Provides access to Mainframe functionality via the Common Web Administration server. Read permission is checked to see if a user can view the MAINFRAME tab in the ESCWA user interface, and use any of the corresponding APIs relating to pages under this node.

The ACL string for this resource entity:

allow:*:read,update,add,delete,execute
Managed Access
Provides access to Managed functionality via the Common Web Administration server. Read permission is checked to see if a user can view the ES .NET tab in the ESCWA user interface, and use any of the corresponding APIs relating to pages under this node.

The ACL string for this resource entity:

allow:*:read,update,add,delete,execute
MFA Configuration
Provides access to mainframe configuration properties for the ESCWA server. Specific version of the configuration entity which relates to the MfaList section of the ESCWA configuration file.

The permissions for this resource control access, add, edit, and delete connections to Mainframe Access (MFA) servers. See Mainframe for more information.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
MFDS Configuration
Provides access to the MFDS configuration properties for the Common Web Administration server. Specific version of the configuration entity which relates to the MfdsList section of the ESCWA configuration file.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
Native Access
Provides access to Native functionality via the Common Web Administration server. Read permission is checked to see if a user can view the NATIVE tab in the ESCWA user interface, and use any of the corresponding APIs relating to pages under this node.

The ACL string for this resource entity:

allow:*:read,update,add,delete,execute
Scale-out Configuration
Provides access to scale-out configuration properties for the Common Web Administration server. Read permissions checked to see if a user can install a PAC to a region. The Directory Server resources will then be checked for that user to see if they can modify that region.

Specific version of the Configuration entity, which relates to the LogicalGroupList, SorList, and PacList sections of the ESCWA configuration file.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
Security Access
Provides access to Security functionality via the Common Web Administration server. Read permission is checked to see if a user can view the SECURITY tab in the ESCWA user interface, and use any of the corresponding APIs relating to pages under this node.

The ACL string for this resource entity:

allow:*:read,update,add,delete,execute
Security Configuration
Provides access to security configuration properties for the Common Web Administration server. Specific version of the configuration entity which relates to the SecurityConfig and ESMList sections of the ESCWA configuration file.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
Server Configuration Access
Provides access to Enterprise Server Administration Configuration functionality via the Common Web Administration server. Read permissions is checked to see if a user can view the configuration spanner and dialog in the ESCWA user interface, and use any of the corresponding APIs relating to this dialog.

The ACL string for this resource entity:

allow:*:read,update,add,delete,execute
Spool Filter Configuration
Provides access to spool filter configuration properties for the ESCWA server. Specific version of the configuration entity which relates to the SpoolFilterList section of the ESCWA configuration file.

The permissions for this resource control access, edit, and reset for the spool filter defaults. See Spool for more information.

The ACL string for this resource entity:

allow:#DSAdmin group:update,add,delete;allow:*:read
Table Column Configuration
Provides access to get, set, and clear the default column list for tables within the ESCWA user interface. A user getting the default columns for a table requires Read permission. A user setting the default columns for a table requires Update permission. A user clearing the default columns for a table requires Delete permission. If this resource does not exist, the Configuration resource entity will be used.

The ACL string for this resource entity:

allow:#DSAdmin group:update,delete;allow:*:read
User Administration
Provides access to user administration via the Common Web Administration server. Update permission is checked to see if a user can administer a security manager.

Update permissions checked to see if a user can change the active security configuration used by ESCWA.

The ACL string for this resource entity:

allow:#DSAdmin group:read,update,add,delete
Parent topic: Security
Related reference
Access Levels and Permissions


Configuration Report

You can generate a security report for a specific ESCWA and directory server configuration.

This report clearly highlights three-tier results:

  • Tick symbols to denote components that are considered secure.
  • Caution or hazard symbols to prompt you to examine a component's security configuration to ensure that it is sufficient for your requirements.
  • Cross symbols indicate that a component has a security vulnerability.

Clicking any of the report cells will display more information on a component's security considerations and suggestions for modifications to mitigate any identified vulnerability.

Before submitting the report, select the domains you require the report to cover.

Check Enterprise Server Common Web Administration to include ESCWA processes.

Check All to include all directory servers in the security report. Alternatively, you can check each directory server individually.

The following topics correspond to the report column headers and contain information on how you can configure these components to mitigate any detected vulnerabilities:

  • Logon Required
  • External Security
  • Default ESF Configuration
  • Auditing
  • Session Timeout
  • TLS Encryption
  • Custom Certificates
  • Honor Cipher List
  • Anonymous Access
  • Loopback
  • Vault Facility
  • ESCWA Single Sign On
Parent topic: Security


Logon Required

In the context of:

ESCWA

If ESCWA has no Security Managers defined in its Security Manager list, then it will not require a verification process (login) for users to interact with the process. Access to ESCWA will not be restricted. This leaves ESCWA open to use from any actors with network access.

The full-page login page for ESCWA will appear if a user has never logged into ESCWA before, or a user's session has timed out.

Directory Server

If a Directory Server has not got Restrict Directory Server Access checked, then it will not require a verification process (login) for users to interact with the process. Access to the Directory Server will not be restricted. This leaves the Directory Server open to use from any actors with network access. Therefore, it is critical that this endpoint has a verification requirement in place for preventing access from bad actors.

The login screen for a Directory Server in the ESCWA UI is a logon dialog that is displayed when Directory Server functions require verification. The Directory Server requiring verification will be indicated in the title, and there is the option to attempt to login with the current user credentials from the ESCWA UI session.

Configuration options

ESCWA
To ensure that ESCWA has a verification process required, using the ESCWA UI, perform the following steps:
  1. In the top menu bar, click Security.
  2. In the Security Navigation pane, click ESCWA Configuration
  3. On this ESCWA Security Facility Configuration page, specify a Security Manager in the Security Managers list.

You can specify Security Managers from the Security Managers list in the Security Navigation pane. See Securing an Enterprise Server Installation for more information.

Directory Server

To ensure a Directory Server has a verification process required, using the ESCWA UI, perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Directory Server Configuration.

    This takes you to the Directory Server Security Facility Configuration page.

  4. Check Restrict Directory Server Access.
  5. Click Apply.

Micro Focus strongly recommends that you implement External Security for Directory Servers. See External Security for more information.

Parent topic: Configuration Report


External Security

In the context of:

Directory Server
If a Directory Server has Restrict Directory Server Access checked, but there are no Security Managers in the Security Manager list, then it will be using internal security only and will require verification. Micro Focus strongly recommends that you do not rely on internal security and that an External Security Manager must always be used.
Region
A region will default to CASESM security if there are no Security Managers in the Security Manager list. Micro Focus strongly recommends that you do not rely on CASESM and that an External Security Manager must always be used.

Configuration options

Directory Server

To prevent a Directory Server from using internal security, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Directory Server Configuration.

    This takes you to the Directory Server Security Facility Configuration page.

  4. Click Add.

    This opens the Defined External Security Managers dialog box.

  5. Choose an external security manager and then click Select.

If the Use ES Default Security Managers check box is checked, then an External Security Manager can be added. Click Security > Default ES Configuration.

If there are no External Security Managers specified, click Security > Security Managers and then click Add. See Securing an Enterprise Server Installation for more information about External Security Managers (ESMs)

Region

To prevent a region from using CASESM security, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Security.
  5. Add a Security Manager to the Security Managers list, so that the region is using External Security.
  6. Restart the region so the changes are applied.

If the Use Default Security Facility Configuration check box is checked, then an External Security Manager can be added. Click Security > Default ES Configuration.

If there are no External Security Managers specified, then you must specify one. For the Directory Server you require, click Security > Security Mangers. See Securing an Enterprise Server Installation for more information about External Security Managers (ESMs).

Parent topic: Configuration Report


Default ESF Configuration

In the context of:

Directory Server

There are three possible security domains within the Enterprise Server architecture, ESCWA, Directory Servers, and enterprise server regions. Each of them uses an External Security Facility (ESF) configuration. An ESF configuration consists of a security manager stack and ESF configuration information. Micro Focus recommends that ESCWA, Directory Servers, and regions all use the same ESF configuration.

For Directory Servers, you can configure a Default ES Configuration security manager stack to be used for multiple domains.

For a Directory Server's own ESF configuration, you can set it to use the configured Default ES Configuration.

Using a different ESF configuration to that of the Default ES Configuration is something that you should reassess, unless it was configured this way for a specific requirement.

Region

There are three possible security domains within the Enterprise Server architecture, ESCWA, Directory Servers and enterprise server regions. Each of them uses an External Security Facility (ESF) configuration. An ESF configuration consists of a security manager stack and ESF configuration information. Micro Focus recommends that ESCWA, Directory Servers and live regions all use the same ESF configuration.

For Directory Servers, you can configure a Default ES Configuration security manager stack to be used for multiple domains.

A region will automatically be configured to use the Default ES Configuration for its ESF configuration and will use this when it is started.

Using a different ESF configuration to that of the Default ES Configuration is something that you should reassess, unless it was configured this way for a specific requirement.

Configuration options

Directory Server

To configure a Default ES Configuration, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Default ES Configuration.

    This takes you to the Default ES Security Facility Configuration page.

  4. Click Add.

    This opens the Defined External Security Managers dialog box.

  5. Choose a security manager and then click Select.
    • Micro Focus recommends that you check Use all groups.
  6. Click Apply.

To ensure a Directory Server is using the Default ES Configuration, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Directory Server Configuration.

    This takes you to the Directory Server Security Facility Configuration page.

  4. Check Use ES Default Security Managers.
  5. Click Apply.

    You might be prompted for credentials for the ESF configuration.

Region

To configure a Default ES Configuration, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Default ES Configuration.

    This takes you to the Default ES Security Facility Configuration page.

  4. Click Add.

    This opens the Defined External Security Managers dialog box.

  5. Choose a security manager and then click Select.
    • Micro Focus recommends that you check Use all groups.
  6. Click Apply.

To ensure a live region is using the Default ES Configuration, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Security.
  5. Check Use Default Security Facility Configuration.
  6. Click Apply.
Parent topic: Configuration Report


Auditing

In the context of:

ESCWA

Enterprise Server can be configured to log auditable events that occur during operation. Audit logs can be used to identify potential security issues or review system changes.

ESCWA's server configuration can be modified to emit network type audit events.

ESCWA's ESF configuration can be modified to emit security type audit events.

See Enterprise Server Auditing for more information.

Directory Server

Enterprise Server can be configured to log auditable events that occur during operation. Audit logs can be used to identify potential security issues or review system changes.

A Directory Server will emit both process specific and security audit events when its ESF configuration is modified to enable auditing.

See Enterprise Server Auditing for more information.

Region

Enterprise Server can be configured to log auditable events that occur during operation. Audit logs can be used to identify potential security issues or review system changes.

A region will emit both process specific and security audit events when its ESF configuration is modified to enable auditing.

See Enterprise Server Auditing for more information.

Configuration options

ESCWA

To ensure ESCWA auditing has been enabled, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Tracing and Logging Settings
  3. Check Enable Auditing.
    • Optionally, check Audit Request Bodies.
      Note: This will generate significantly more audited event information.
  4. Click Apply.

To ensure that ESCWA ESF configuration has auditing enabled, use ESCWA to perform the following steps:

  1. In the menu bar, click Security.
  2. In the Security Navigation pane, click ESCWA Configuration.
  3. Check Create audit events.
  4. Click Apply.
Directory Server
To ensure a Directory Server's ESF configuration has auditing enabled, use ESCWA to perform the following steps:
  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Directory Server Configuration.

    This takes you to the Directory Server Security Facility Configuration page.

  4. Check Create audit events.
  5. Click Apply.

To ensure a Directory Server's Default ES Configuration has auditing enabled, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Security > Default ES Configuration.

    This takes you to the Default ES Security Facility Configuration page.

  4. Check Create audit events.
  5. Click Apply.
Parent topic: Configuration Report


Session Timeout

In the context of:

ESCWA

Irrespective of whether ESCWA has verification required (and is therefore restricted), all clients will require a session to perform actions.

ESCWA has a session timeout which can be removed.

Timeouts limit exposure to a variety of session-based attacks and therefore should be implemented.

Directory Servers

Irrespective of whether a Directory Server has verification required (and is therefore restricted), all clients will require a session to perform actions.

Directory Servers have a session timeout which can be removed.

Timeouts limit exposure to a variety of session-based attacks and therefore should be implemented.

Configuration options

ESCWA

To ensure ESCWA has a session timeout enabled, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Security Settings
  3. In the Session Inactivity Timeout field, set it to the timeout required.
    Note: If this field is set to 0, then there is no timeout.
  4. Click Apply.
Directory Server

To ensure a Directory Server has a session timeout enabled, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Properties > Configuration.

    This takes you to the Directory Server Configuration page.

  4. Check Timeout API Sessions.

    This ensures that the API session timeout is set to the specified value.

  5. Click Apply.
Parent topic: Configuration Report


TLS Encryption

In the context of:

ESCWA
ESCWA has a network endpoint which clients use to communicate with. Those communications are not inherently secure and can expose sensitive data in communications across the network.

Transport Layer Security (TLS) can be used to secure these communications through encryption. The process network endpoint will only accept secure TLS communications.

Directory Server
A Directory Server has a network endpoint which other Enterprise Server processes will use to communicate with it. Those communications are not inherently secure and can expose sensitive data in communications across the network.

Transport Layer Security (TLS) can be used to secure these communications through encryption. The process network endpoint will only accept secure TLS communications.

Communications Process
A Communications Process has a network endpoint which other Enterprise Server processes will use to communicate with it. Those communications are not inherently secure and can expose sensitive data in communications across the network.

Transport Layer Security (TLS) can be used to secure these communications through encryption. The process network endpoint will only accept secure TLS communications.

Listener
A Listener has a network endpoint which clients which other Enterprise Server processes will use to communicate with it. Those communications are not inherently secure and can expose sensitive data in communications across the network.

Transport Layer Security (TLS) can be used to secure these communications through encryption. The process network endpoint will only accept secure TLS communications.

Configuration options

ESCWA

To secure a network endpoint you will require the following, as a minimum:

  • A TLS certificate.
  • A TLS key with a passphrase.

To ensure the ESCWA network endpoint is TLS enabled, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Server Settings
  3. Click TLS Settings.
  4. Check Enable TLS.
  5. In the Certificate File field, type the location of the TLS certificate on the machine where this process runs.
  6. In the Keyfile field, type the location of the TLS key on the machine where this process runs.
  7. In the Keyfile Password field, type the TLS key passphrase.
  8. Click Apply.
  9. Restart the ESCWA process.
Directory Server

To secure a network endpoint you will require the following, as a minimum:

  • A TLS certificate.
  • A TLS key with a passphrase.

To ensure a Directory Server network endpoint is TLS enabled, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Properties > Connection.

    This takes you to the Connection Properties page.

  4. Check Enable TLS.
  5. Check Use Custom Certificates.
  6. In the Certificate File field, type the location of the TLS certificate on the machine where this process runs.
  7. In the Keyfile field, type the location of the TLS key on the machine where this process runs.
  8. In the Keyfile Password field, type the TLS key passphrase.
  9. Click Apply.
  10. Restart the Directory Server process.

The MF_ROOT_CERT environment variable will need to be set for processes to communicate with the Directory Server. See Securing Communications between ESCWA and MF Directory Server using TLS and Securing Communications Process to MF Directory Server using TLS for more information.

Communications Process

To secure a network endpoint you will require the following, as a minimum:

  • A TLS certificate.
  • A TLS key with a passphrase.

To ensure a region's Communications Process network endpoint is TLS enabled, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Listeners.

    This opens the Communications Server Properties page.

  5. In the Native Listener Navigation pane, click the Communications Process you require.
  6. Expand Configure.
  7. Click TLS Settings.
  8. Check Enable TLS.
  9. In the Certificate File field, type the location of the TLS certificate on the machine where this region runs.
  10. In the Keyfile field, type the location of the TLS key on the machine where this region runs.
  11. In the Server CA Root Certificate File field, type the location of the server CA root certificate on the machine where this region runs.
  12. Click Apply.

Next time the region is started, the network endpoint will have TLS security. The certificate and keyfile passphrases will need to be set in the mf-server.dat configuration file. See To Configure the Passphrase in a File for more information.

Listener

To secure a network endpoint you will require the following, as a minimum:

  • A TLS certificate.
  • A TLS key with a passphrase.

To ensure a region's Listener network endpoint is TLS enabled, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Listeners.

    This opens the Communications Server Properties page.

  5. In the Native Listener Navigation pane, click the listener you require.
  6. Click TLS Settings.
  7. Check Enable TLS.
  8. In the Certificate File field, type the location of the TLS certificate on the machine where this region runs.
  9. In the Keyfile field, type the location of the TLS key on the machine where this region runs.
  10. Click Apply.

Next time the region is started, the network endpoint will have TLS security. The certificate and keyfile passphrases will need to be set in the mf-server.dat configuration file and the Certificate Authority root location will need to be set in the mf-client.dat configuration file. See To Configure the Passphrase in a File and Securing Communications between ESCWA and ESMAC using TLS for more information.

Parent topic: Configuration Report


Custom Certificates

Custom Certificates
A Directory Server can have TLS encryption enabled, without Use Custom Certificates being enabled. This means it will attempt to use the demonstration certificates which can be installed with the product. Micro Focus strongly recommends that you use custom certificates for all deployments especially production systems.

Configuration options

Custom Certificates

To secure a network endpoint you will require the following, as a minimum:

  • A TLS certificate.
  • A TLS key with a passphrase.

To ensure a Directory Server network endpoint is TLS secured with custom certificates, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Properties > Connection.

    This takes you to the Connection Properties page.

  4. Check Enable TLS.
  5. Check Use Custom Certificates
  6. In the Certificate File field, type the location of the TLS certificate on the machine where this process runs.
  7. In the Keyfile field, type the location of the TLS key on the machine where this process runs.
  8. In the Keyfile Password field, type the TLS key passphrase.
  9. Click Apply.
  10. Restart the Directory Server process.

See Securing Communications between ESCWA and MF Directory Server using TLS and Securing Communications Process to MF Directory Server using TLS for more information.

Parent topic: Configuration Report


Honor Cipher List

Honor Cipher List
A TLS encrypted endpoint will have a cipher list specified, if none is specified then a default is used. When the Honor Server Cipher List option is enabled, the server determines which cipher suite the client will use. When this is disabled, the client can decide which cipher suite to use. It is insecure for the client to choose a cipher suite, as an attacker can then choose a weaker encryption to exploit. See Specifying a Server Protocol and Cipher Suite Preference for more information.

Configuration options

ESCWA

To ensure the ESCWA network endpoint will honor the server cipher list, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Server Settings
  3. Click TLS Settings.
  4. Expand Advanced.
  5. Check Honor Server Cipher List
  6. Click Apply.
  7. Restart the ESCWA process.
Directory Server

To ensure a Directory Server network endpoint will honor the server cipher list, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Properties > Connection.

    This takes you to the Connections Properties page.

  4. Check Enable TLS.
  5. Check Use Custom Certificates.
  6. Expand Advanced.
  7. Check Honor Server Cipher List.
  8. Click Apply.
  9. Restart the Directory Server process.
Communications Process

To ensure a region's Communications Process' network endpoint will honor the server cipher list, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Listeners.

    This opens the Communications Server Properties page.

  5. In the Native Listener Navigation pane, click the Communications Process you require.
  6. Expand Configure.
  7. Click TLS Settings.
  8. Check Enable TLS.
  9. In the Certificate File field, type the location of the TLS certificate on the machine where this region runs.
  10. In the Keyfile field, type the location of the TLS key on the machine where this region runs.
  11. In the Server CA Root Certificate File field, type the location of the server CA root certificate on the machine where this region runs.
  12. Expand Advanced.
  13. Check Honor Server Cipher List.
  14. Click Apply.
  15. Restart the region so the changes are applied.

See To Configure the Passphrase in a File for more information on setting the keyfile passphrase.

Next time the region is started, the network endpoint will be TLS enabled.

Listener

To ensure a region's listener's network endpoint will honor the server cipher list, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Listeners.

    This opens the Communications Server Properties page.

  5. In the Native Listener Navigation pane, click the listener you require.
  6. Click TLS Settings.
  7. Check Enable TLS.
  8. In the Certificate File field, type the location of the TLS certificate on the machine where this region runs.
  9. In the Keyfile field, type the location of the TLS key on the machine where this region runs.
  10. Expand Advanced.
  11. Check Honor Server Cipher List.
  12. Click Apply.
  13. Restart the region so the changes are applied.

Next time the region is started, the network endpoint will be TLS enabled.

Parent topic: Configuration Report


Anonymous Access

Directory Servers can allow read access to anonymous clients which have not been verified, even with a verification process in place. By default, this behavior is disabled in Directory Server versions 1.27 and later.

Configuration options

Use the /b option on the mfds command line to configure the availability of the anonymous read access. See mfds for more information.

Parent topic: Configuration Report


Loopback

Process network endpoints enable communicate between and into the elements of Enterprise Server. If these network endpoints do not run in a loopback mode, then this leaves external communications to them exposed if TLS encryption is not enabled.

Micro Focus strongly recommends that any network endpoint, which does not require external communication for administrators or clients, should run in a loopback only mode.

Those endpoints that must require external communication must use TLS encryption.

Configuration options

ESCWA
If the ESCWA process network endpoint must be external and not on loopback, see TLS Encryption for more information.

If the ESCWA endpoint can run on loopback, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Server Settings
  3. In the Hostname or IP Address field, type localhost.
  4. Click Apply.
  5. Restart the ESCWA process. ESCWA can now only be accessed from localhost or an equivalent IP address in the browser.
Directory Server

If the Directory Server process network endpoint must be external and not on loopback, see TLS Encryption for more information.

If the Directory Server endpoint can run on loopback, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the directory server you require, then click Properties > Configuration.

    This takes you to the Directory Server Configuration page.

  4. Check Listen on Loopback Only.
  5. Click Apply.
  6. Restart the Directory Server process.
Communications Process
Typically, a Communications Process can be made to listen on loopback only if the ESCWA instance viewing the region is on the same machine.

If the Communications Process network endpoint must be external and not on loopback, see TLS Encryption for more information.

If the Communications Process endpoint can run on loopback, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Servers.
  3. Click the region you require.
  4. Click General > Listeners.

    This opens the Communications Server Properties page.

  5. In the Native Listener Navigation pane, click the communications process you require.
  6. Expand Configure.
  7. In the Hostname or IP Address field, type localhost.
  8. Click Apply.
  9. Restart the region so the changes are applied.

Next time the region is started, the network endpoint will be on loopback only.

Listener

If the Listener process network endpoint must be external and not on loopback, see TLS Encryption for more information.

If the Listener process endpoint runs on loopback, use ESCWA to perform the following steps:

  1. In the top menu bar, click Native.
  2. In the Native Navigation pane, expand Directory Server.
  3. Click the region you require.
  4. Click General > Listeners.

    This opens the Communications Server Properties page.

  5. In the Native Listener Navigation pane, click the listener you require.
  6. In the Hostname or IP Address field, type localhost.
  7. Click Apply.
  8. Restart the region so the changes are applied.

Next time the region is started, the network endpoint will be on loopback only.

Parent topic: Configuration Report


Vault Facility

In the context of:

ESCWA

ESCWA will attempt to use the Micro Focus Vault Facility by default. The Vault Facility enables you to store sensitive data in a secure form.

It is possible to explicitly disable the use of the Vault Facility from the ESCWA command line, or to specify an incorrect vault specification, which will result in the Vault Facility not being used. Micro Focus recommends that you use the Vault Facility for storing ESCWA's sensitive data.

Directory Server
A Directory Server from Enterprise Server version 8.0 or later will always attempt to use the Vault Facility by default. In addition, it will attempt to automatically migrate sensitive data values when it first starts. However, it is possible due to file permissions or connection issues that it will not be able to use the Vault Facility.

To ensure a Directory Server can use the Vault Facility, check the following:

  • Ensure you are using Enterprise Server version 8.0 or later.

    Ensure the default vault specification of the Vault Facility is valid.

    Ensure permissions of any Vault Facility related files are correct, including the configuration file and any stored secrets.

Configuration options

ESCWA

To ensure that ESCWA is using the Vault Facility correctly, check the following:

  • Ensure ESCWA was started without the command-line option which can disable use of the Vault Facility.
  • Ensure ESCWA is using a valid vault specification.

To modify the vault specification, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Security Settings
  3. In the Vault Encryption Specification file, ensure that it is empty so that the default specification is used. Alternatively, type the name of the specification you want to use.
  4. Click Apply.

See Vault Facility for more information.

Directory Server

To ensure a Directory Server is using the Vault Facility, check the following:

  1. Ensure you are using Enterprise Server version 8.0 or later.
  2. Ensure the default vault specification of the Vault Facility is valid.
Parent topic: Configuration Report


ESCWA Single Sign On

ESCWA communicates with processes which can have verification process. This means that ESCWA can pass credentials over the network on behalf of a user.

If the process network endpoints that ESCWA communicates with support TLS encryption, ESCWA will attempt to use the currently signed in user's credentials automatically to verify with the processes.

However, if those processes do not support TLS encryption, then ESCWA will prompt users with a login dialog before sending credentials over the network.

These login dialogs can be disabled with the Enable Single Sign On for Unsecured Resources option. Micro Focus recommends that you do not use this option as it can result in credentials being automatically sent over the network to endpoints without TLS encryption.

Configuration options

See TLS Encryption for more information on setting a process network endpoint to use TLS encryption.

To prevent automatic insecure sign on, use ESCWA to perform the following steps:

  1. Click

    This opens the Enterprise Server Administration Configuration dialog box.

  2. Expand Security Settings
  3. In the Single Sign On Behaviour list, select Only Secure and Loopback
  4. Click Apply.
Parent topic: Configuration Report


Role-based Access

You can take a role-based access approach to the ESCWA user interface.

This enables you to tailor access for groups of users, referred to as roles. Users might only require limited or specific access to features that enable them to accomplish a specific function or role. Limiting access to aspects of the user interface can provide a better experience for users that might not make use of the full ESCWA interface.

  • Role-based Approach to Access
  • Configuring Role-based Access
  • Manually Modifying a Role Task ACL String
  • Limitations & Restrictions to Role-based Access
Parent topic: Security


Role-based Approach to Access

Verification and authorization security features are enabled on ESCWA through its ESF configuration. This means that for any given user, they are challenged to login to ESCWA through a verification process and their level of access will be determined through authorization. Therefore you will require the following:

  • An ESF configuration that contains an ESM stack.
  • The ESM stack will include at least one ESM which is either an LDAP or VSAM based security manager. This ESM will be used for resource checks which will determine authorization.
  • There must be a list of resource classes which contain resource entities.
  • When ESCWA makes authorization checks using the LDAP or VSAM ESM, it will check the Common Web Administration resource class and whichever relevant resource entity is contained within it.
  • As part of the ESF configuration, a user will be a member of a group and users and groups will be referenced in the resource entity ACL strings.
  • The authorization is performed by checking ACEs within an ACL string. ACEs contain references to users, groups, and permission levels.

With the addition of the Role Tasks resource class, new resource entities have been added which ESCWA can check for authorization.

Parent topic: Role-based Access


Configuring Role-based Access

To configure role-based access, click Configure to open the Configure Role Tasks dialog box. The role hierarchy is displayed on the left-hand pane along with icons to indicate if the Role Task has been added or not and if the corresponding ACL string has been incorrectly configured. On the right-hand side of the dialog box, a description of the Role Task is provided along with details of the any incorrect ACL configuration. Click Add to enable a role or Delete to disable. Once a Role Task has been enabled you can enable access by checking the required group. To do this, perform the following steps:

  1. In the menu bar, click Security.
  2. Expand ESCWA Configuration.
  3. Expand the security manager and then click Roles.

    This displays the Role Options page.

  4. Check the roles you want to restrict access for.
  5. Click Apply.

The role task resource entities are located in the Roles Task resources class. In the menu bar, click Security. Expand ESCWA Configuration. Expand the security manager and then click Resources. In the Security Resources Navigation pane, click Role Tasks.

You can configure the following Roles Task resource entities:

Native Access
This role task enables you to manage access to the Native features of the ESCWA application. Administrators can use this role to simplify the user interface when Enterprise Server is not required. This role is not available under the Role Tasks resource class as this is a historic role. You can find this under the Common Web Administration resource class.
Managed Access
This role task enables you to manage access to the ES for .NET features of the ESCWA application. Administrators can use this role to simplify the user interface when ES for .NET is not required. This role is not available under the Role Tasks resource class as this is a historic role. You can find this under the Common Web Administration resource class.
Security Access
This role task enables you to manage access to the Security features of the ESCWA application. Administrators can use this role to simplify the user interface when security configuration is not required. This role is not available under the Role Tasks resource class as this is a historic role. You can find this under the Common Web Administration resource class.
Server Access
This role task enables you to manage access to the Enterprise Server Administration Configuration dialog box. Administrators can use this role to restrict a user’s access to configuring the ESCWA server. This role is not available under the Role Tasks resource class as this is a historic role. You can find this under the Common Web Administration resource class.
Mainframe Access
This role task enables you to manage access to the Mainframe features of the ESCWA application. Administrators can use this role to simplify the user interface when mainframe functionality is not required. This role is not available under the Role Tasks resource class as this is a historic role. You can find this under the Common Web Administration resource class.
ESCWA Logon
This role task enables you to manage ESCWA logon. Administrators can use this role to restrict a user’s access to ESCWA. This role is not available under the Role Tasks resource class as this is a historic role. You can find this under the Common Web Administration resource class.
Region Startup Configuration Administration
This role task enables you to view the pages for a stopped enterprise server regions. These are the legacy pages for the MF Directory Server user interface. Administrators can use this role to restrict a user from viewing pages and information related to a running enterprise server region.
Started Region Administration
This role task enables you to view the pages for started enterprise server regions. These are the legacy pages for the Enterprise Server Monitoring And Control (ESMAC) user interface. Administrators can use this role task to restrict users to only be able to view pages and information related to a stopped enterprise server region.
JES Spool and Catalog
This role task enables you to view the Spool and Catalog pages. Administrators can use this role to restrict users to viewing only Spool and Catalog pages.
Note: This role task takes precedence over Region Startup Configuration Administration.
Region Control
This role task enables you to start and stop enterprise server regions and view the region Control page. Administrators can use this role to restrict users from starting and stopping regions.
Groups Administration
This role task enables you to view the Groups displayed in the Native Navigation pane. Administrators can use this role to restrict users from administering the Logical and PACs nodes, including installing to an enterprise server region to make it a PAC member when started.
Directory Server Administration
This role task enables you to access the Directory Server properties, connection configuration, security configuration, and journal. Administrators can use this role to restrict users from performing administration type changes to the Directory Server when the user should only be concerned with region-based actions.
Scale-Out Administration
This role task enables you to view the SORs displayed in the Native Navigation pane. Administrators can use this role to restrict users from configuring SORs to view the enterprise server regions associated with their PAC.
Security Configuration Report
This role task enables you to manage access to the Configuration Report in the Security Navigation pane.
Parent topic: Role-based Access


Manually Modifying a Role Task ACL String

You can modify the ACL strings for a resource entity under Role Tasks. You can use the role-based access feature entirely by configuring ACL strings.

The supported strings are:

allow:*:read
This allows all roles/groups for the Role Task.
deny:*:read
This denies all roles/groups for the Role Task.
allow:MYGROUP1 group:read;…;allow:MYGROUPN group:read
This allows the specified roles/groups for the Role Task.
Parent topic: Role-based Access


Limitations & Restrictions to Role-based Access

You can still access network endpoints directly, such as MFDS and ESMAC directly and this feature does not add security directly to those endpoints if they are exposed.

Micro Focus recommends that you:

  • Use this feature in conjunction with the resource classes for those processes. See Resource Classes used by Enterprise Server for more information.
  • Restrict network access to the MFDS and ESMAC endpoints. This could be by making them loopback only or through firewall configuration. This will mean you can limit how many of the above Resource Classes you must change.
  • Use the same ESF configuration for ESCWA, MFDS and enterprise server region.

A role-based approach can be used with a multiple stacked ESM configuration, however, you will not be able to use the roles user interface features in ESCWA. The resource entities’ ACL strings will have to be set through other tooling. See Manually Modifying a Role Task ACL String for more information.

Parent topic: Role-based Access


ESCWA Client Web API

Micro Focus has provided the HTTP and JSON Application Programming Interface (API) used by the ESCWA client. This is to enable you to write your own custom scripts to support and automate your organization's specific Enterprise Server administration requirements.
  • Before You Start
    You need to ensure that you use the API in a secure manner.
  • Session Management
    Irrespective as to whether ESCWA has been restricted or not, all clients must use a session to perform their actions. This topic details how you can establish a session.
  • ESCWA Interactive API Library
    The API library documents all of the requests ESCWA provides.
  • MFA Interactive API Library
    The MFA API library documents all of the requests that are provided.
  • Using ESCWA with a TLS Enabled API Client
Parent topic: Enterprise Server Common Web Administration


Before You Start

You need to ensure that you use the API in a secure manner.

Micro Focus recommends that you apply the following points when using the interactive API library:

  • The X-Requested-With header must be set. For Web browser clients, this is typically set to XMLHttpRequest. For your script, you should give this a value that clearly identifies it as your script.
  • The host header must be set to the location of your ESCWA instance, for example, localhost:10086.
    Note: This is not applicable for GET requests.
  • One of the Origin or Referer headers must be set to the location of the ESCWA instance, for example, https://localhost:10086.
    Note: This is not applicable for GET requests.
  • For any endpoint that produces output, the Accept header must be set to application/json.
  • For any endpoint that requires a body to be provided, the Content-Type header must be set to application/json and the Content-Length header must be set to the length of the body in bites.
  • All sent and response bodies must use the UTF-8 character encoding.

Some methods in the interactive library will do some or all of these for you. See Enterprise Server Administration Server API for more information.

Parent topic: ESCWA Client Web API


Session Management

Irrespective as to whether ESCWA has been restricted or not, all clients must use a session to perform their actions. This topic details how you can establish a session.
  • If ESCWA is secured, a request should first be sent to the endpoint /logon with your credentials.
  • If ESCWA is unsecured, a request should first be sent to the endpoint /validate.

In either case, the response will have a set-cookie header containing ESAdmin-Cookie. This cookie should be sent with every subsequent request.

If you need to logon to any other resources, such as directory severs, regions, or ES for .NET then the session information will be added to your ESCWA session and so only the ESAdmin-Cookie is required.

Once your script is complete it should finish with a request to the /logoff endpoint to clean up the session. This is to reduce the risk of reaching the session limit and minimize resource usage.

Parent topic: ESCWA Client Web API


ESCWA Interactive API Library

The API library documents all of the requests ESCWA provides.

The library runs as an interactive client on your instance of ESCWA. This enables you to test actual requests and responses against your configuration.

To access the interactive API library, add /docs to the end of your base ESCWA URI, for example http://localhost:10086/docs.

To start using the interactive API:

  1. Click Authorize.

    This opens the Available authorizations dialog box.

  2. For the X-Requested-With, in the Value field, type an identifier.
  3. Click Authorize.
  4. Click Close.

The interactive API library manages the Host, Origin, Referer, Accept, Content-Type, and Content-Length headers for you. It also stores and applies the cookie for session handling.

Note: The interactive API library and ESCWA share a session. Logging in or out from one will affect the other.
  • ESCWA Interactive API Library - Version 2
Parent topic: ESCWA Client Web API


ESCWA Interactive API Library - Version 2

Version 2 of the API library provides an enhanced set of RESTful methods. Version 2 incorporates improved readability of property names, handling of property values, and restructuring of endpoints. Version 2 is not a complete implementation of version 1, where version 2 methods are not yet available, version 1 equivalents can be used to achieve a complete set of functionality.

To access the interactive API library documentation, add /docs to the end of your base ESCWA URI, for example http://localhost:10086/docs and then click API Version 2 in the menu bar.

Attention: Micro Focus strongly recommends that you transition to version 2 of the API.
Parent topic: ESCWA Interactive API Library


MFA Interactive API Library

The MFA API library documents all of the requests that are provided.
Note: These features can only be configured and used if your product is enabled for Mainframe Subsystem Support (MSS).

The library runs as an interactive client on your instance of ESCWA. This enables you to test actual requests and responses against your configuration.

To access the interactive MFA API library, add /docs/#/MFA to the end of your base ESCWA URI, for example http://localhost:10086/docs/#/MFA.

To start using the interactive API:

  1. Click Authorize.

    This opens the Available authorizations dialog box.

  2. For the X-Requested-With, in the Value field, type an identifier.
  3. Click Authorize.
  4. Click Close.

The interactive MFA API library manages the Host, Origin, Referer, Accept, Content-Type, and Content-Length headers for you. It also stores and applies the cookie for session handling.

Note: The interactive MFA API library and ESCWA share a session. Logging in or out from one will affect the other.
Parent topic: ESCWA Client Web API


Using ESCWA with a TLS Enabled API Client

ESCWA can be configured for TLS security. See Configuring TLS for the ESCWA Client for more information. When this configuration is performed you must ensure that the process that accesses the API also trusts the root certificate authority which signed the certificate that ESCWA is using for TLS.

For the ESCWA application, or the interactive API, this will be the browser which you are using.

Note: The FireFox browser does not use the Windows certificate store. This means that you need to add the root CA certificate to your FireFox store.

If you are using a scripting language like PowerShell or Python, you will need to ensure that they trust the root certificate authority before making API requests to the TLS enabled ESCWA.

Parent topic: ESCWA Client Web API


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 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, however, cause problems during operation. 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

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.

Typically, enterprise server regions is started using the Micro Focus Enterprise Server Common Web Administration (ESCWA) user interface, the Web interface to the MF Directory Server. In this event, ESCWA 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 an enterprise server region 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: 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 ESCWA 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 region 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 utility, rather than through ESCWA.

  • 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 an enterprise server region is started from ESCWA, it will inherit MFDS's user credentials.

    The disadvantages of this method are similar to the method above, though ESCWA can be used to start and stop enterprise server regions 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: Your programs will need to use UNC paths, that is, file path names 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.

Micro Focus recommends 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, do not grant it any permissions that the COBOL programs does not need. For additional security, you can set ACLs to grant or deny access to particular objects, such as directories, files, registry keys, for this user to further control what COBOL service programs can do.

Parent topic: Planning your Configuration
Related information
Network File Access (Known Issues)
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 regions, 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 region, 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

The facility in the Interface Mapping Toolkit to deploy services automatically to a running enterprise server delivers your services using a system service called a deployment service.

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
  • The .mfdeploy file
    Enables deployment and configures mfdepinst, the deployment installer.
  • Restricting access to service deployment
    Configuring additional security for deploying services to Enterprise Test Server.
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 that 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 Test Server\bin and modify it as necessary.

For example, if Enterprise Test 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

Deployment listeners allow a deployment client, such as the Enterprise Developer IDE or the imtkmake utility, deploy COBOL web services or EJBs to an Enterprise Server instance. The combination of a deployment listener, an associated deployment service, and the .mfdeploy file in the deployment directory control how deployment requests are handled.

Several aspects of deployment are determined by settings in the configuration information for a deployment listener, which consists of these sections:

  • The section named [virtual paths], containing a list of URL top-level directories and the paths they will be converted to.
  • A section named [allow], with rules for what can be retrieved from the virtual paths.
  • Optionally, a [security] section configuring security for deployment.

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
docs=<ES>/help

[allow]
cgi=mfdeploy.exe
uploads=*.txt *.car *.wsdl

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.

The "docs" virtual path can be used to retrieve product documentation, but is present largely for historical reasons.

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.

The entries in the "[allow]" section restrict what files can be retrieved from a virtual path. Its entries are the names of virtual paths, and their values are filename patterns (delimited by spaces), one of which must match the requested file. The configuration created for a new deployment service will allow only mfdepinst.exe from the "cgi" virtual directory; and only text (*.txt), COBOL archive (*.car), and WSDL (*.wsdl) files from deployment directories under the "uploads" virtual directory.

The [security] section

Beginning with Enterprise Test Server 5.0, deployment listeners have additional optional security features:

  • Deployment listeners may require user authentication for each request. This prevents anonymous access to deployment and ensures deployment is only performed by clients with valid credentials. (Credentials may be a username/password pair, validated against the Enterprise Server instance's security configuration, or a client certificate, depending on listener configuration.)
  • When user authentication is enabled, the Enterprise Server security system may also be configured to restrict access to particular users.
  • Also, with user authentication enabled, it is possible to configure the mfdepinst program to use the authenticated user when binding to the Micro Focus Directory Server (MFDS) to create the new service and package objects. This is useful for administrators who want more fine-grained control over updates to the Enterprise Server configuration information. For more information refer to the documentation for the .mfdeploy file.

These features are enabled in the optional [security] section of the deployment listener's configuration text area. For example:

[security]
restricted=yes
authentication=MF, HTTP

Here:

  • The setting restricted=yes enables user authentication. It also enables access restriction if the server's security configuration supports resource access control (most commonly using LDAP-based security for Enterprise Server), and the resource class "Enterprise Server Web" is defined to the External Security Manager. (A different name can be configured for this class with the class setting.) See the topic Restricting access to service deployment for more information.
  • The setting authentication=MF, HTTP instructs the listener to support username/password user credentials from the client, passed in one of two ways: a proprietary mechanism used by older versions of Enterprise Developer (for backward compatibility) and standard HTTP Basic Authentication.

A full description of the syntax for the [security] section can be found in the Web conversation type topic.

Certificate authentication for deployment

A deployment listener can be configured to identify users using client certificates. When a deployment client connects to a deployment listener in this configuration, it sends a certificate (and proves it has the private key that corresponds to the certificate, as part of the TLS handshake). The listener can associate the certificate with an Enterprise Server user, and then check whether that user is authorized to deploy services.

Certificate authentication has the following requirements:

  1. The Enterprise Server instance must be configured to use External Security (ESF). This is true for all types of deployment listener authentication and access control.
  2. The deployment listener must be configured to use SSL/TLS.
    1. The SSL/TLS configuration for the listener must be set to request client certificates and verify them (require a certificate), or verify them when present (allow but do not require, making certificate authentication optional).
    2. The SSL/TLS configuration must specify a collection of trusted Certification Authority signing certificates, sometimes called root certificates.
  3. The listener's configuration must enable certificate authentication in the configuration text area. It must include the [Security] section with Authentication specifying the certificate and/or register tokens.
  4. The deployment client must be configured, usually using the mf-client.dat file, to send a client certificate. This certificate must be signed by one of the Certification Authority signing certificates in the collection specified for the listener.
  5. The client certificate must be known to the Enterprise Server instance and associated with a user. There are two ways to accomplish this:
    1. The certificate can be registered with Enterprise Server using the cascertreg command-line utility.
    2. If automatic registration is enabled, as described in the next section, the user can connect to the deployment listener with a web browser that has been configured to send the same client certificate. The browser will prompt for the Enterprise Server username and password to be associated with the certificate. If Enterprise Server successfully authenticates the username and password, it will register the certificate.

      Automatic registration can also be performed with deployment clients that allow the user to specify a username and password. If the deployment client is configured to use a client certificate, and also configured with a username and password, it will attempt to automatically register the certificate if the server does not recognize it. Once the certificate is registered, the username and password can be removed from the client's configuration.

Automatic client certificate registration for deployment listeners

Automatic certificate registration is a mechanism to help administrators move to using certificate authentication for deployment. It relieves administrators of the need to manually register each client certificate.

To enable automatic registration, include the register token in the list of authentication methods configured for the listener (the Authentication setting in the optional Security section of the listener's text configuration area).

When automatic registration is enabled, if the listener receives a client certificate that is not already registered, it will check the request for a username and password sent using the standard HTTP Basic Authentication header. If they are not present, the listener will send back an HTTP response requesting them.

Once the listener has a username and password, it will ask the Enterprise Server instance's security stack to validate the credentials. If that succeeds, it will register the client certificate with the username, and proceed to check whether the user is authorized to perform the requested action.

Parent topic: Deployment Services and Listeners
Related reference
The .mfdeploy file
cascertreg
Related information
Web conversation type
Restricting access to service deployment


The .mfdeploy file

The .mfdeploy file is used by the Enterprise Developer deployment feature, which is used by application developers and administrators to deploy COBOL Web Services and EJBs to Enterprise Server instances.

The .mfdeploy file serves two purposes:

  • A .mfdeploy file must exist in the parent directory of the directory where the COBOL Archive (.CAR) file is being processed. This is a security measure to prevent abusing the deployment mechanism to create or overwrite files outside an authorized deployment area.
  • The contents of the .mfdeploy file are configuration information for mfdepinst, the Micro Focus Deployment Installer.

When deploying using a deployment client, such as an IDE, the imtkmake utility, or the web-deploy.html web form, some of the configuration settings in .mfdeploy may be overridden or supplemented by information sent by the client.

Important: Starting with release 6.0, you can pass any required install configuration options to the mfdepinst command at the command line instead of in the .mfdeploy file. See mfdepinst command for more details.

Classic .mfdeploy configuration

The traditional .mfdeploy file contents are a series of name=value pairs, similar to environment-variable settings. In fact, in mfdepinst versions prior to 1.8, these settings are simply added to the mfdepinst process environment, then queried as needed.

An example setting is MFES_SERVER=ESDEMO, which tells mfdepinst which Enterprise Server instance will own the new service being installed, if the deployment client did not provide that information.

Settings recognized by mfdepinst include:

MFDS
MFC_MFDS
Specifies the location of the Micro Focus Directory Server. The default is "localhost".
MFDS_USER
The username to use when binding to MFDS.
MFDS_PASSWORD
The password to use when binding to MFDS.
MFES_SERVER
The name of the Enterprise Server instance under which the new service will be installed.
MFUS_SERVER
An old name for the above setting, maintained for backward compatibility.
MFES_LISTENER
The name of the Enterprise Server listener that will host the new service.
MFUS_LISTENER
An old name for the above setting, maintained for backward compatibility.
UPDATE_MODE
If this is defined with the value add, the deployment installer will allow a deployment package to specify additional operations for an existing service. If it is defined with the value replace, a deployment package can replace an existing service and its associated package in its entirety. Otherwise, the service being deployed must not already exist.

Advanced .mfdeploy configuration

From Enterprise Test Server 5.0 onwards, the .mfdeploy file also supports an advanced configuration syntax with additional features. The classic and advanced styles can be used in the same file, as long as classic entries appear first.

The advanced syntax uses the "ini" format, with name=value lines grouped in named sections. Section names are enclosed in square brackets. Blank lines are ignored, and comments can be included by prefixing them with a hash sign (#). For example:

# Location of MFDS and credentials for binding
# These will usually be overridden by the deployment request,
# but apply when mfdepinst is run manually.
[MFDS]
MFDS=localhost
User=admin
Password=Secret password for admin

With the new syntax, the available sections and their settings are:

[MFDS]
MFDS=hostname[:port]
User=username
Password=password

[ES]
Server=ES-name
Listener=listener-name
Default server=ES-name
Default listener=listener-name

[Operation]
Update_mode=add

[Environment]
name=value

[Passwords]
username=password

In the [ES] section, the Default server and Default listener values are used only if the deployment client did not specify a target server and listener. The Server and Listener values, if set, will override any server or listener requested by the deployment client.

In the [Operation] section, the Update_mode setting has the same effect as setting UPDATE_MODE using the classic syntax. Note the underscore in the name. The value add is case-sensitive, for historical reasons.

The [Environment] section can be used to set arbitrary environment variables for the mfdepinst process. It is not generally necessary to use this section.

The [Passwords] section can be used to make mfdepinst bind to MFDS using the credentials of the user making the deployment requests. To enable this behavior:

  • The Enterprise Server instance must be configured for External Security.
  • The deployment listener must be configured for restricted mode, with HTTP and/or certificate authentication enabled.
  • The user's password must be included in the [Passwords] section. This is because with HTTP and certificate authentication, the user's password is not otherwise available to the mfdepinst process.

If these criteria are not satisfied, mfdepinst will look in the request for a username and password to use when binding to MFDS. If none is found, it will use the default username and password specified in the [MFDS] section; and if those are not set, it will use a hard-coded default.

An example of a classic .mfdeploy file is:
MFDS=localhost
MFES_SERVER=ESDEMO
MFES_LISTENER=Web Services and J2EE

An example of a .mfdeploy file using the new syntax is:

# New configuration syntax with mfdepinst 1.8. The old syntax is still
# supported for backward compatibility, but the new format provides more
# options.

# The optional [Environment] section sets values in the mfdepinst environment.
# Any name=value items before the first section header are also put in the
# environment.
# [Environment]
# Name=value

[MFDS]
MFDS=localhost
# User=username for MFDS, if not supplied with request
# Password=password for MFDS, if not supplied with request

[ES]
# Default server is used if no server is specified in the request, and
# mfdepinst is not running under MFCS. If mfdepinst is running under MFCS,
# it uses the MFCS server name.
#
# The MFCS server name can be overridden with:
#    Server=name
# or with the old syntax (MFES_SERVER set in the environment, or in this ES
# section).
Default server=ESDEMO
Default listener=Web Services and J2EE

# The [Passwords] section can be used to set the MFDS password based on the
# remote user ID supplied using HTTP Basic Authentication.
# [Passwords]
# Username=password
Parent topic: Deployment Services and Listeners
Related reference
mfdepinst command
Related information
Deployment Listeners


Restricting access to service deployment

As described in the topic Deployment Listeners, Enterprise Test Server (beginning with version 5.0) provides optional features to prevent unauthorized users from deploying Web Services and COBOL EJBs.

If your Enterprise Server is enabled for security, you can configure your deployment listener or listeners to require user authentication. This ensures only known users can deploy services. User authentication is configured in the [security] section of the configuration text for the listener using the restricted and authentication settings. More information can be found under Deployment Listeners and The Web Conversation Type.

If your Enterprise Server security configuration includes an External Security Manager that supports resource access controls, such as LDAP-based security using the MLDAP ESM Module, you can additionally restrict which users can deploy services or retrieve deployed artifacts and deployment logs. This provides finer-grained control over deployment. It is enabled by creating an additional resource class (if it does not already exist) and adding rules to that class.

The Enterprise Server Web resource class

Resource access controls for service deployment are defined in the Enterprise Server Web resource class. (A different class name can be configured in the listener configuration.) The virtual directory from the request is matched against the names of the rules found in this class. The rule names can include wildcards, but usually they will match the virtual directories listed in the Web listener configuration, such as uploads. See the topic Deployment Services and Listeners for more information about virtual directories.

With LDAP-based security, you can use an LDAP administration tool or an LDIF file to add a container named CN=Enterprise Server Web under the resource container in your LDAP repository. By default, that container is named CN=Enterprise Server Resources.

Within the resource class, create rules for the virtual directories you wish to restrict. With the default Enterprise Server configuration, you would typically create rules named cgi and uploads. The "cgi" rule controls access to the mfdeploy program which accepts deployment requests, so only users who are granted access will be able to deploy. The "uploads" rule controls access to the actual deployment area, so it can restrict who can download deployed artifacts (such as service programs) or view deployment logs.

If you are using LDAP-based security, you would create these rules as LDAP objects of type microfocus-MFDS-Resource, with the names CN=cgi and CN=uploads. The attributes microfocus-MFDS-Resource-Class and microfocus-MFDS-UID are mandatory and must be set to some value, but they are not actually used by Enterprise Server and you can supply any value for them.

Permissions in Enterprise Server Web rules

To grant or deny permissions to users and groups, use the deployment resources by adding Access Control Entries (ACEs) to the microfocus-MFDS-Resource-ACE multi-valued attribute of the appropriate rule.

For both the "cgi" and "uploads" rules, you should add a default ACE to control access for users who are not covered by more-specific ACEs. Normally, this would be deny:*:all, which blocks access by default. Alternatively, you can allow access by default using allow:*:all, in which case only users who are specifically blocked with deny ACEs would be prevented from deploying.

After the default ACE, you would add one or more ACEs to grant access to specific users or groups. For the "cgi" rule, to permit deploying services, a user must have both the "execute" permission (to run the mfdeploy.exe program) and the "add" permission (to perform an HTTP POST operation). So, for example, you might add an ACE like allow:SYSADM group:execute,add to the "cgi" rule to grant members of the SYSADM group permission to invoke the deployment service and upload a deployment package.

For the "uploads" group, authorized users need the "read" permission. This enables them to retrieve deployment logs, browse the deployment area, and download files from it (though that's not normally done, except for the deployment logs). A typical ACE for "uploads" is allow:SYSADM group:read.

Changes to these security settings normally take effect immediately. If ESF caching is enabled, there may be some delay until any cached security results expire.

Parent topic: Deployment Services and Listeners
Related information
Deployment Listeners
Deployment Services and Listeners
The Web Conversation Type


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, and what information is traced. Most of these options are fairly straightforward, but detailed advice on them 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.

  • 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 Test Server Architecture in the chapter Introduction). It is measured in pages of 4KB each, and 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 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]
Note: This section heading is case-sensitive.

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.

You can also configure a setting that allows you to access and run JCL files from the local 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
  • 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
    Describes setting the initial environment for all Enterprise Server regions, and how to further configure an enterprise server region by set environment variables that are specific to that particular region.
  • 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

Describes setting the initial environment for all Enterprise Server regions, and how to further configure an enterprise server region by set environment variables that are specific to that particular region.

Initial environment settings

The initial environment used for a specific enterprise server region depends on the method you use to start it:

  • When you start an enterprise server region from the Enterprise Server Common Web Administration (ESCWA) interface, it inherits its environment from the Micro Focus Directory Server Directory Server.
  • When you start an enterprise server region from the command line using the casstart command, it inherits its environment from that command shell.
This means that the initial configuration for all enterprise server regions, including directory settings for third-party software, can be set in the session where you start the Micro Focus Directory Server.
Note: If Micro Focus Directory Server is running as a Windows service, it will have the system environment.

Specific environment settings

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

Note: For service interfaces created using the Interface Mapping Toolkit, environment variables set at the service level override the settings at the region 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 a reserved environment variable used to point to the product location, and overriding its value could cause undefined results.

Instead, if you want to specify the location of service programs at the region level, consider using the COBPATH environment variable. However, if you do this, you must also specify "$COBPATH" in Package Path in the Add Package or Edit Package page for services that should be located using COBPATH.

To use a defined environment variable in the value definition of another environment variable, precede the name of the defined variable 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 and not as an indicator for a referenced environment variable, escape the dollar sign character 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 regions controlled by MFDS.
  • Environment variables defined as part of the enterprise server region configuration apply to that region only.
    Note: You can set some environment variables on the Advanced Region Properties page in ESCWA. The environment variable topic indicates this when it is an option.
  • Environment variables set at a command prompt apply to the enterprise server region started from the same prompt.
  • Setting Environment Variables for Micro Focus Directory Server
  • To set environment variables from ESCWA
  • To set environment variables from the command line
  • To specify dataset allocation using environment variables
    Describes a preferred method for allocating datasets for an enterprise server region using environment variables instead of defining the full path to each dataset.
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 ESCWA

From the Enterprise Server Common Web Administration (ESCWA) user interface, you can set environment variables to apply to each listed enterprise server region.

  1. In ESCWA, click Native.
  2. In the navigation pane, expand Directory Server > Default.
  3. Select your enterprise server region.
  4. On the General Properties page in the Configuration Information text box, type the following section heading:
    [ES-Environment]
    Note: This section heading is case sensitive.
  5. Within this section, enter each environment variable you want to configure for this enterprise server region, using a separate line for each, and following the syntax specified. See Environment Variables in Alphabetical Order or one of the Environment Variables by Groups topics for details.
  6. Click Apply to apply the settings to the region.

Example:

To configure your enterprise server region to use an alternative default ESMAC user:

[ES-Environment]
ES_USR_DFLT_ESMAC=ESMACUSR
Parent topic: Setting Environment Variables
Related information
Environment variables in alphabetical order


To set environment variables from the command line

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

  1. Start an Enterprise Server command prompt. See To start an Enterprise Server command prompt for details
  2. Use the following syntax:
    set env-var=value(s)
    Where env-var is any Enterprise Server environment variable, and value(s) represents valid parameters for the environment variable. See Environment Variables by Groups or Environment Variables in Alphabetical Order for details on each environment variable.

    For example, to set the name for the enterprise server region:

    set ES_SERVER=MYSERVER
Parent topic: Setting Environment Variables
Related information
Environment variables in alphabetical order


To specify dataset allocation using environment variables

Describes a preferred method for allocating datasets for an enterprise server region using environment variables instead of defining the full path to each dataset.

An obvious method to configure datasets is to specify the full path for each dataset accessed by Enterprise Server. However, as the number of datasets accessed increases, the more cumbersome this method becomes. In addition, having a hard-coded location for each dataset 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 by an enterprise server region:

  1. From the Enterprise Server Administration page, click the Edit button that corresponds to the enterprise server region 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 env-var=path syntax where:
    • env-var 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 a variable for each required path, click OK. The settings are applied to the enterprise server region.
  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 ($).

    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 topics list the environment variables by functional group.

Tip: For details about setting environment variables, see Setting Environment Variables, To set environment variables from ESCWA, and To set environment variables from the command line.
  • Assembler Option Environment Variables
    Lists environment variables used to configure the component locations for Assembler.
  • Common Communications Interface Environment Variables
    Lists environment variables related to CCI.
  • CICS Environment Variables
    Lists environment variables related to configuring the CICS environment.
  • Database File Handling Environment Variables
    Lists environment variables related to the configuration of the database file handler, which enables you to store your data files for Enterprise Server applications within a supported database.
  • File Handling and Dataset Environment Variables
    Lists environment variables related to configuring file and dataset handling.
  • General Enterprise Server Environment Variables
    Lists environment variables that apply to all components of Enterprise Server.
  • IMS Environment Variables
    Lists environment variables related to configuring the IMS environment.
  • Input, Output, and Display Environment Variables
    Lists environment variables related to configuring the input and output and the display.
  • JCL Environment Variables
    Lists environment variables related to configuring the JCL environment.
  • Mainframe Access Environment Variables
    Lists environment variables related to the Mainframe Access functionality.
  • WebSphere MQ Environment Variables
    Lists environment variables related to configuring the WebSphere MQ environment.
  • PAC Environment Variables
    Lists environment variables related to configuring a PAC in Enterprise Server..
  • Security and Auditing Environment Variables
    Lists environment variables related to configuring the security and auditing environment.
  • SORT Engine Environment Variables
  • Spool Housekeeping Environment Variables
    Lists environment variables relatee to the configuration of the spool housekeeping processes.
  • Tracing and Debugging Environment Variables
    Lists environment variables related to the tracing and debugging functionality.
  • Windows Environment variables
    Lists environment variables related to configuring Enterprise Server for a Windows environment.
  • Reserved Environment Variables
Parent topic: Configuring Environment Variables


Assembler Option Environment Variables

Lists environment variables used to configure the component locations for Assembler.
Parent topic: Environment Variables by Groups

ES_MFASM_SUPPORT

Enables Assembler support in a CICS enterprise server region.
ES_MFASM_SUPPORT={Y|N}
Parameters
Y
Assembler supported for CICS server regions.
N
No Assembler supported for CICS server regions.
Default
ES_MFASM_SUPPORT=N

STEPLIB

The path or paths to search for Loader input-load member .390 files.
STEPLIB=path-name[;path-name[...]]
Parameter
path-name
The full path to a location containing input-load member .390 files.
Comments
.390 files must contain SYSLMOD.

SYSIN

The path for macro input .MLC files.
SYSIN=path-name
Parameter
path-name
The full path to the location that contains macro input .MLC files.

SYSLIST

The path for Assemble and Link listing files.
SYSLIST=path-name
Parameter
path-name
The full path to the location that contains Assemble and Link listing files, including .MAT, .PRN, and .LST files.

SYSWORK

The path to Assemble, Link and Animator/370 work files.
SYSWORK=path-name
Parameter
path-name
The full path to the location that contains Assemble, Link, and Animator/370 work files, including .BAL, and .IDF/.IDX files.

SYSPUNCH

The path to Assemble output files for PUNCH statements.
SYSPUNCH=path-name
Parameter
path-name
The full path to the location that contains Assemble output files for PUNCH statements, including .PCH files.

SYSMPC

The path to Assemble input precompiled macros.
SYSMPC=path-name
Parameter
path-name
The full path to the location that contains Assemble input precompiled macros, including .MPC.

SYSLIB

The paths for Assemble input macro and copy files.
Syntax
SYSLIB=path-name[;path-name[...]]
Parameter
path-name
The full path to a location containing Assemble input macro and copy files, including .MAC and .CPY files.

SYSLIN

The path to Link input and Assemble output files.
SYSLIN=path-name
Parameter
path-name
The path to Link input (.LIN) files and Assemble output (.OBJ) files.

SYSLMOD

The path for Link output load-member (.390) files.
Syntax
SYSLMOD=path-name
Parameter
path-name
The path to Link output load-member (.390) files.

SYSPARM

The path for the Macro input SYSPARM value.
SYSPARM=path-name
Parameter
path-name
The path to the Macro input SYSPARM value.


Common Communications Interface Environment Variables

Lists environment variables related to CCI.
Parent topic: Environment Variables by Groups

CCIERRLOG

Specifies the location of and filename for CCI error log output.
Syntax
CCIERRLOG=path-name\file-name
Parameters
path-name
The full path to the output location.
file-name
The name of the output file.
Default
Not set. The default path is the working directory of the application calling CCI, and the default filename is ccierr.log.
Comments
The CCI error log 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. See CCI.INI - The CCI Configuration File for more information.

CCITCP2

Sets the TCP address of the machine running the MFDS (formerly CCITCP2) registration daemon.
Syntax
CCITCP2=host-name
Parameter
host-name
The TCP host name, IPv4 address, or IPv6 address of the machine running the MFDS daemon you want to contact from the session.
Default
Not set. The local system is used.
Comments
Use this environment variable to set the TCP address of the machine running the MFDS registration daemon, which holds the registration of the service you are contacting, or will hold the registration of the service you are starting.

CCITCP2_PORT

Sets the port used for the MFDS registration process.
Syntax
CCITCP2_PORT=port-number
Parameter
port-number
The number of the port on which the MFDS service is listening.
Default
Not set. Uses the port specified by the mfcobol service name in %WINDIR%\system32\drivers\etc\services . If not found there, uses the official Micro Focus directory port, which is 86.

CCITCPS_service-name

Associates the name of a service being registered with a different service name, one or more ports, and/or one or more network interfaces.
Syntax
CCITCPS_old-service-name=[new-service-name],
   {MFNODE:node-name | MFPORT:port-number |
    MFNODE:node-name, MFPORT:port-number}
Parameters
old-service-name
The name of the CCI server.
new-service-name
The new name to use for the CCI server. If omitted, the old-service-name is used.
node-name
The host name or IP address on which to listen for connections.
port-number
The TCP port on which to listen for connections.
Default
Not set. A port is assigned by the operating system, and the server listens on all available network interfaces.
Comments
CCITCPS is set in the environment of a CCI server process, and changes how it listens for connections and how its service name is registered.
Example
CCITCPS_MYSERVICE=,MFPORT:3000

CCITCPT_service-name

Specifies the host, and/or port for a client to use when connecting to a service.
Syntax
CCITCPT_serice-name=[unused], MFNODE:node-name, MFPORT:port-number
Parameters
service-name
The name of the CCI service to which the client is to connect.
unused
The parameter before the comma is not used with CCITCPT, but supported for consistency with CCITCPS.
node-name
The host name or IP address to connect.
port-number
The TCP port to connect.
Default
Not set. The client attempts to look the service up in the MFDS directory.
Comments
Use this environment variable to instruct a CCI client to connect directly to the specified host and port rather than querying MFDS for the location of the named service.
Example
CCITCPT_MYSERVICE=,MFNODE:localhst.MFPORT:3000

CCITIMEOUT

Sets a maximum time-out period used with non-data connect applications.
Syntax
CCITIMEOUT=wait-time
Parameter
wait-time
The number of seconds to wait before timing out times 10, up to a maximum value of 2,147,483,647.
Default
CCITIMEOUT=1200

(2 minutes)

Comments
Use this variable with non-data connect applications such as Drag and Drop, SourceConnect, and the Monitor.
Example
This example sets the wait time to 4 minutes:
CCITIMEOUT=2400

CCITRACE

Specifies the type of information to record using CCI tracing.
Syntax
CCITRACE={/|-}{F|P|D}[...]
Parameters
/
Turns on the specified option.
-
Turns off the specified option.
F
Logs the details of CCI API calls to CTF. This option is implied when either P or D is specified. You can override this using -F.
P
When turned on, logs the details of protocol-level calls to CTF, which could greatly increase function tracing. When not set, only the details of the CCI user-level API are traced.
D
Logs the contents of all buffers passed to and from the CCI functions.
Warning: Setting this option might not produce the desired results if the application has been coded to prohibit data tracing.
Default
Not set. CCI tracing is controlled via the ctf.cfg and CCI.INI trace options.
Comments
The ctf.cfg and the CCI.INI file ([ccitrace_base] section) can also be used to control trace options, but any values specified by the CCITRACE environment variable take precedence. For details, see Tracing Options for CTF.CFG and CCI.INI - The CCI Configuration File.
Example
CCITRACE=/F/D


CICS Environment Variables

Lists environment variables related to configuring the CICS environment.
Parent topic: Environment Variables by Groups

CICS_SIT

The name of the SIT used by the enterprise server region.
Syntax
CICS_SIT=sit-name
Parameter
sit-name
The name of the CICS SIT to use for the enterprise server region.
Default
Not set. The CICS SIT specified in ESCWA is used.

ES_ABORT_PLTPI_ERROR

Enables the user to set the error on which to abort PLTPI processing, bypassing the prompt.
Syntax
ES_ABORT_PLTPI_ERROR={YN|NY|YY}
Parameters
YN
Abort on PGMIDERR.
NY
Abort on ABEND.
YY
Abort on PGMIDERR or ABEND.
Default
Not set. When an error occurs during PLTPI processing, mainframe CICS enterprise servers display a prompt that enables the user to cancel the startup or ignore the error.
Comments
Set ES_ABORT_PLTPI_ERROR to bypass the prompt and automatically abort the initialization as dictated by the value provided.

ES_CICS_SINGLE

Configures CICS so that a user can only log on once when the enterprise server region is running in a PAC with CICS enabled.
Syntax
ES_CICS_SINGLE={Y|N}
Parameters
Y
A user can only log on once.
N
The same user may sign on to multiple terminals with CICS.
Default
ES_CICS_SINGLE=Y
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPCT

Controls the CICS PCT resource class.
Syntax
ES_CLASS_XPCT={YES|NO|class-name
Parameters
YES
ACICSPCT is the default PCT class.
NO
Security for PCTs is bypassed.
class-name
The name of a class to override the default PCT ACICSPCT class.
Default
ES_CLASS_XPCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XCMD

Controls the CICS CMD resource class.
Syntax
ES_CLASS_XCMD={YES|NO|class-name}
Parameters
YES
CICS CMD is the default CMD class.
NO
Security for CMDs is bypassed.
class-name
The name of a class to override the default CMD CICSCMD class.
Default
ES_CLASS_XCMD=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XDCT

Controls the CICS DCT resource class.
Syntax
ES_CLASS_XDCT={YES|NO|class-name}
Parameters
YES
DCICSDCT is the default DCT class.
NO
Security for DCTs is bypassed.
class-name
The name of a class to override the default DCT DCICSDCT class.
Default
ES_CLASS_XDCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XFCT

Controls the CICS FCT resource class.
Syntax
ES_CLASS_XFCT={YES|NO|class-name}
Parameters
YES
FCICSFCT is the default FCT class.
NO
Security for FCTs is bypassed.
class-name
The name of a class to override the default PCT FCICSFCT class.
Default
ES_CLASS_XFCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XJCT

Controls the CICS JCT resource class.
Syntax
ES_CLASS_XJCT={YES|NO|class-name}
Parameters
YES
JCICSJCT is the default JCT class.
NO
Security for JCTs is bypassed.
class-name
The name of a class to override the default JCT JCICSJCT class.
Default
ES_CLASS_XJCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPPT

Controls the CICS PPT resource class.
Syntax
ES_CLASS_XPPT={YES|NO|class-name}
Parameters
YES
MCICSPPT is the default PPT class.
NO
Security for PPTs is bypassed.
class-name
The name of a class to override the default PPT MCICSPPT class.
Default
ES_CLASS_XPPT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPSB

Controls the CICS PSB resource class.
Syntax
ES_CLASS_XPSB={YES|NO|class-name}
Parameters
YES
PCICSPSB is the default PSB class.
NO
Security for PSBs is bypassed.
class-name
The name of a class to override the default PSB PCICSPSB class.
Default
ES_CLASS_XPSB=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XRES

Controls the CICS DOCTEMPLATE resource class.
Syntax
ES_CLASS_XRES={YES|NO|class-name}
Parameters
YES
RCICSRES is the default RES class.
NO
Security for DOCTEMPLATEs is bypassed.
class-name
The name of a class to override the default RES RCISRES class.
Default
ES_CLASS_XRES=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XTST

Controls the CICS TST resource class.
Syntax
ES_CLASS_XTST={YES|NO|class-name}
Parameters
YES
SCITST is the default TST class.
NO
Security for TSTs is bypassed.
class-name
The name of a class to override the default TST SCITST class.
Default
ES_CLASS_XTST=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XTRAN

Controls the CICS TRAN resource class.
Syntax
ES_CLASS_XTRAN={YES|NO|class-name}
Parameters
YES
TCICSTRN is the default TRAN class.
NO
Security for TRANs is bypassed.
class-name
The name of a class to override the default TRAN TCICSTRN class.
Default
ES_CLASS_XTRAN=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CSKL_NO_MSG_CONSOLE

Stops the EZ Sockets CICS listener (CSKL) from writing messages to console.log.
Syntax
ES_CSKL_NO_MSG_CONSOLE=ON
Parameter
ON
CSKL does not write message to console.log.
Default
Not set. CSKL writes messages to console.log.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CWS_WSBIND_COMP

Enables support for CICS applications that use COMP declarations.
Syntax
ES_CWS_WSBIND_COMP={Y|N}
Parameters
Y
Enables support for COMP declarations in CICS applications.
N
Support for COMP declarations is disabled for CICS applications.
Default
ES_CWS_WSBIND_COMP=N

ES_DISABLE_DFLTUSR_SIGNON

Disables the default user (mfuser) signon when invoking ES Monitor & Control (ESMAC).
Syntax
ES_DISABLE_DFLTUSR_SIGNON=Y
Parameter
Y
Disables the mfuser auto-logon after starting Enterprise Server administration via your MFDS internal security account.
Default
Not set. mfuser is signed in to ESMAC.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_ECI_MAX_RESP

Specifies the maximum expected response size to use when using Micro Focus ECI support to invoke CICS programs.
Syntax
ES_ECI_MAX_RESP=resp-size
Parameter
resp-size
A decimal from 1 to 16777215 representing the maximum expected response size in bytes.
Default
Not set. The maximum expected response size is calculated dynamically by multiplying the size of the TIOA by 2.
Comments
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.
Syntax
ES_ESM_CMDSEC=YES
Parameter
YES
CICS overrides the CMDSEC option, and always calls its command security checking routine to issue the appropriate call to the SAF interface.
Default
Not set. 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.

ES_ESM_IDPW_CASE

Forces the case of user ID and password for a single attempt ESM authentication.
Syntax
ES_ESM_IDPW_CASE=xy
Parameters
x
Specifies the case for the user ID. Use one of the following:
U | All upper case
L | All lower case
M | Mixed case and case-sensitive
y
Specifies the case for the password. Use one of the following:
U | All upper case
L | All lower case
M | Mixed case and case-sensitive
Default
Not set. Uses legacy behavior.
Comments
When this environment variable is set, Enterprise Server makes only one attempt to identify a user presenting the user ID and password as is (M), folded to upper case (U), or folded to lower case (L).

For the legacy behavior for CICS, the user ID and the password are used as supplied possibly filtered by the upper-case translation configuration of the sign-on transaction.

For ESMAC and IMS, the legacy behavior is that, first, the user ID and password are used as supplied. If the authentication fails, the user ID is folded to upper case and used again. If this fails as well, both the user ID and the password are folded to upper case and then used.

Example
This example tries a single authentication with the user ID folded to upper case, and the password used as-is:
ES_ESM_IDPW_CASE=UM

ES_ESM_PLTPISEC

The level of security checking for PLTPI processing.
Syntax
ES_ESM_PLTPISEC={NONE|CMDSEC|RESSEC|ALL}
Parameters
NONE
No security checking is performed on PLT initialization programs.
CMDSEC
CICS performs command security checking only.
RESSEC
CICS performs resource security checking only.
ALL
CICS performs both command and resource security checking.
Default
ES_ESM_PLTPISEC=NONE

ES_ESM_PLTPIUSR

Specifies the user ID under which PLT programs run during CICS initialization.
Syntax
ES_ESM_PLTPIUSR=userid
Parameter
userid
The user ID for CICS to use for security checking for PLT programs that run during CICS initialization.
Default
Not set. The user specified when starting the CICS-enabled enterprise server region is used.
Comments

The user ID specified must have appropriate authorization to access all the resources used by the programs as determined by the ES_ESM_PLTPISEC environment variable.

ES_ESM_RCF

Determines how RACF is used for command authorization.
Syntax
ES_ESM_RCF={A|C|N|S|T|Y}
Parameters
A
A combination of options T, C, and S.
C
Use RACF for ETO terminal command authorization.
N
RACF does not perform sign-on, transaction, or command authorization.
S
Use RACF for static and ETO terminal command authorization. Includes option C.
T
Use RACF for sign-on and transaction authorization.
Y
A combination of options T and C.
Default
ES_ESM_RCF=N

ES_ESM_RESSEC

Indicates whether CICS processing honors the RLS security setting specified on a transaction definition (PCT).
Syntax
ES_ESM_RESSEC=ALWAYS
Parameter
ALWAYS
CICS processing always performs resource level security checking irrespective of the RLS security setting on the transaction definition.
Default
Not set. The RLS security setting of a transaction is honored. That is, resource-level security checking is performed only when the RLS security checkbox is marked in the PCT definition.

ES_ESM_SECPRFX

Indicates whether CICS processing adds a prefix to resource names when making security queries.
Syntax
ES_ESM_SECPRFX={NO|YES|prefix}
Parameters
NO
Use no prefixes.
YES
Uses prefix resource names with the CICS region user ID.
prefix
Define a prefix for resource names as an alphanumeric string that starts with an alphabetic character, and is one to eight upper-case characters in total.
Default
ES_ESM_SECPRFX=NO
Comments
This environment variable is applied only to CICS classes.

ES_ESM_XUSER

Indicates whether CICS processing performs surrogate user checks.
Syntax
ES_ESM_XUSER={NO|YES}
Parameters
NO
No surrogate user checking is performed.
YES
Perform surrogate user checking wherever such checks are permitted.
Default
ES_ESM_XUSER=YES

ES_EUSA_SIZE

Sets the size of the extended user storage area, allowing large memory allocations to be set using the GETMAIN SHARED command.
Syntax
ES_EUSA_SIZE=number
Parameter
number
A numeric value representing the number of MB to allocate for the extended user storage area.
Default
ES_EUSA_SIZE=16

ES_INQFILE_RETURN

Modifies EXEC CICS INQUIRE FILE behavior for cataloged files.
Syntax
ES_INQFILE_RETURN={DSN|PCN}
Parameters
DSN
The DSN is returned. For an alternative file, the BASEDSNAME is the DSNAME of the BASE file.
PCN
The PC name of the file (truncated at 44 characters) is returned if the file is open, or if FCT fix-up has been performed. Otherwise, the dataset name is returned.
Default
ES_INQFILE_RETURN=PCN

ES_JES_FREE_SSTM_SYSOUT

Determines whether to free the memory assigned to store details about each CICS spool file that you create using the CICS Spool Write APIs, once the spool file has been created.
Syntax
ES_JES_FREE_SSTM_SYSOUT={Y|N}
Parameters
Y
Free the memory assigned to store details about each CICS spool file.
N
Do not free the memory assigned to store details about each CICS spool file.
Default
ES_JES_FREE_SSTM_SYSOUT=N
Comments

Setting ES_JES_FREE_SSTM_SYSOUT=Y helps to avoid problems with receiving out of memory errors when creating multiple new files.

CAUTION:
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.

ES_LE370_SUPPORT

Enables support for Language Environment (LE) in CICS applications
Syntax
ES_LE370_SUPPORT=Y
Parameter
Y
Enables LE support.
Default
Not set. LE support is not enabled.
Comments
Parameter value is not case sensitive.

ES_LEGACY_ECI

Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG.
Syntax
ES_LEGACY_ECI=Y
Parameter
Y
Micro Focus ECI is used.
Default
Not set. IBM CTG is used.
Comments
Parameter value is not case sensitive.

ES_MFASM_SUPPORT

Enables Assembler support in a CICS enterprise server region.
ES_MFASM_SUPPORT={Y|N}
Parameters
Y
Assembler supported for CICS server regions.
N
No Assembler supported for CICS server regions.
Default
ES_MFASM_SUPPORT=N

ES_MQ_1PC

Indicates whether the IBM WebSphere MQ switch module ESMQXA operate in one-phase commit mode.
CAUTION:
Set this environment variable only when advised to do so by OpenText Support for Micro Focus Products.
Syntax
ES_MQ_1PC={[Y|y|Yes|T|True]|[N|n|No|F|False}
Parameters
Y|y|Yes|T|True
The ESMQXA switch module operates in one-phase commit mode.
N|n|No|F|False
The ESMQXA switch module operates in two-phase commit mode.
Default
ES_MQ_1PC=F

ES_MQ_XA

The type of XA structure to use for the two-phase commit XA switch module.
Syntax
ES_MQ_XA={D|S}
Parameters
D
Use a dynamic XA structure
S
Use a static XA structure.
Default
ES_MQ_XA=D

ES_SSTM_CICS

Location of the JCL used to initialize the SSTM CICS environment.
Syntax
ES_SSTM_CICS=file-location
Parameter
file-location
The full path to the location of the SSTMCICS.JCL file used to initialize the SSTM CICS environment.
Default
Not set.

ES_SURROGATE_JOB_USER

Associates a user ID with a job when submitting the job for processing through the internal reader from CICS.
Syntax
ES_SURROGATE_JOB_USER=ON
Parameter
ON
The user ID that started the enterprise server region is used in the job submission.
Default
Not set. The CICS default user CICSUSER, or as specified by ES_USR_DFLT_CICS, is used in the job submission.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_TEST_TRANCLASS

Activates transaction class support.
Syntax
ES_TEST_TRANCLASS={Y|N}
Parameters
Y
Activate transaction class support.
N
Do not activate transaction class support.
Default
ES_TEST_TRANCLASS=N
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_TRANCLASS_CWI

For CICS Web Services, enables the prioritizing and limiting of Web requests in a TRANCLASS-enabled region.
Syntax
ES_TRANCLASS_CWI={TCPIPSERVICE|URIMAP}
Parameters
TCPIPSERVICE
Prioritize and limit TCPIPSERVICE transactions.
URIMAP
Prioritize and limit URIMAP transactions.
Default
ES_TRANCLASS_CWI=TCPIPSERVICE
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_TSC_AGGREGATE

Controls the performance environment for CICS TS/TD data stores.
Syntax
ES_TSC_AGGREGATE=wait-time,{Y|N|D}
Parameters
wait-time
The time in milliseconds to wait for additional flush requests to accumulate.
Y
Use aggregate data store flush-buffers-to-disk operations
N
Do not aggregate
D
Disable flush operations.

ES_USR_DFLT_CICS

Allows you to override the default user when no user is logged on for CICS authentication.
Syntax
ES_USR_DFLT_CICS=userid
Parameter
userid
An alternative default user name.
Default
ES_USR_DFLT_CICS=CICSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_XA_%xaname%_OPTIONS

When set with ES_XA_RECONNECT=Y, configures the XA reconnect process to operate in a multi-attempt mode.
Syntax
ES_XA_%xaname%_OPTIONS={reconnect_attempts,wait-time|EX}
Parameters
%xaname%
The name of the RM as specified in MFDS or ESCWA.
reconnect_attempts
The number of reconnect attempts to the target RM. Maximum is 9999.
wait-time
The number of seconds to delay between each attempt.
EX
Exclude the target RM from XA reconnect processing.
Default
Not set.
Comments
ES_XA_%xaname%_OPTIONS must be set along with ES_XA_RECONNECT=Y.

You might need to set ES_XA_%xaname%_OPTIONS multiple times — once for each RM that you require to operate in a multiple-attempt mode.

Examples
Specify that an XA reconnect processing attempts to reconnect to MQPROD 100 times and waiting for 10 seconds between each reconnect attempt:
ES_XA_MQPROD_OPTIONS=100,10

Specify that the XA reconnect processing is to exclude MQPROD from the XA reconnect processing:

ES_XA_MQPROD_OPTIONS=EX

ES_XA_ABEND

Recycles non-batch SEPs when a severe error is returned by an xa-start by an Oracle switch.
Syntax
ES_XA_ABEND=RECYCLE
Parameter
RECYCLE
Recycles non-batch SEPs when a severe error is returned by an xa-start by an Oracle switch.
Default
Not set. Non-batch SEPs are not recycled.

ES_XA_RECONNECT

Configures the XA reconnect process to operate in a single-attempt mode.
Syntax
ES_XA_RECONNECT=Y,wait-time[,retry_count]
Parameters
Y
Enables the reconnect process.
wait-time
The number of seconds to delay before triggering the XA recovery transaction after a two-phase commit failure and between each reschedule of the XA recovery transaction if the syncpoint phase 2 returns an RC 04. Maximum is 300.
retry_count
The number of recovery retries to attempt when the XA commit or rollback executed by the XA recovery transaction returns an RC-04. Default is 5.
Default
Not set. XA reconnect operates in multi-attempt mode.
Comments
In case of failure, the following messages are sent to the console:
CASXO0054W XA recovery error RC=4 on commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG           000000***********000010000000**        0000

When the maximum number of retries is reached, the following message is sent to the console:

CASXO0055S XA MAX recovery attempts, manually commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG       000000***********000010000000**        0000
Example
ES_XA_RECONNECT=Y,120,4

TXMAPP

The location of the BMS load module.
Syntax
TXMAPP=path-name
Parameter
path-name
The full path to the location of the BMS load module.

TXTRANP

The location of the CICS application object files.
Syntax
TXTRANP=path-name
Parameter
path-name
The full path to the location of the CICS application object files.

USSCONFIG

Points to the location of the SSL cipher suite specification file(s) used by the CIPHERS attribute in the CICS URIMAP or TCPIPSERVICE resource.
Syntax
USSCONFIG=cipher-path
Parameter
cipher-path
The absolute path to the cipher suite specification file or files.
Comments
For details about ciphers and cipher files, see the Security Attributes > Ciphers section of the Universal Resource Identifier Map topic.


Database File Handling Environment Variables

Lists environment variables related to the configuration of the database file handler, which enables you to store your data files for Enterprise Server applications within a supported database.
Parent topic: Environment Variables by Groups

ES_DB_FH

Enables or disables database file handler support. This is required if your data files are stored in a datastore, or your enterprise server region stores some of its resources in a database; see Micro Focus Database File Handler and Enterprise Server Region Database Management for more information.
Syntax
ES_DB_FH={[Y|true]|[N|false]}
Parameters
Y|true
Use the Micro Focus Database File Handler (MFDBFH) to direct file handling.
N|false
Disable database file handling.
Default
ES_DB_FH=N
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.
Important: The configuration file specified by the MFDBFH_CONFIG environment variable must contain a corresponding <server> entry for the database server. <dsn> entries for the region, cross-region, and master databases must also be specified in the configuration file to enable use of region database operations.
Syntax
ES_DB_SERVER=server-instance
Parameter
server-instance
The name of a valid database server instance.
Default
Not set.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Example
ES_DB_SERVER=MYSERVER

In this example, your database configuration file would need to contain something similar to the following:

<datastores usevault="false">
   <server name="MYSERVER" type="sqlserver" access="odbc">
       <dsn name="SS.MYMASTER" type="database" dbname="master"/>
       <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO"
          feature="all"/>
       <dsn name="SS.CAS.CROSSREGION" type="crossregion.cas"/>
   </server>
</datastores>

ES_LOCKDB

Specifies the region database that is to process resource locking (step- and system-scoped ENQs) for an enterprise server region within a cluster, where resources such as catalogs are deployed to a database.
Syntax
ES_LOCKDB=region-db
Parameter
region-db
The name of the region database responsible for processing step- and system-scoped ENQs.
Default
Not set.
Comments
This variable must be used in conjunction with ES_SERVER, in which ES_SERVER is set to the database server that houses the region database; see Resource Locking for more information.

MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.
Syntax
MFDBFH_CONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The file name of the configuration file.
Default
Not set. Uses the mfdbfh.cfg file found in the current working directory.
Comments
You can also set MFDBFH_CONFIG as a system environment variable.

MFDBFH_GRANT_USER_PERMISSIONS

Grants execute privileges to specific users or roles, for types and procedures that are created when configuring an Oracle database for MFDBFH access.
Syntax
MFDBFH_GRANT_USER_PERMISSIONS={user|role}[{user|role}[...]]
Parameters
user
A user granted execute privileges for types and procedures created by MFDBFH.
role
A role granted execute privileges for types and procedures created by MFDBFH.
Default
Not set. Oracle default permissions are applied, which are to grant execute permissions to the schema owner of that type/procedure only.
Comments
This variable has no effect on permissions for any other database provider used with MFDBFH.

MFDBFH_RECORD_LOCKING

Specifies the type of record locking that it is to be used when the database file handler is in effect.

Syntax
MFDBFH_RECORD_LOCKING={table|database}
Parameters
table
A file's record locks are held in a seperate lock table. (When using this locking mode, the behavior of record locking COBOL file operations closely follows the same behavior when using Fileshare.)
database
The native record locking mechanism of the database engine is used to establish and test locks on the data file records. This method improves performance, but at the cost of the locking behavior not exactly matching that of traditional COBOL record locking; see Record Locking Strategies for more information.
Default
MFDBFH_RECORD_LOCKING=table

MFDBFH_SCRIPT_DIR

Specifies the location of the scripts and stored procedures required when the database file handler is in effect.
Syntax
MFDBFH_SCRIPT_DIR=path-name
Parameter
path-name
The full path to the directory containing the required resources.
Default
MFDBFH_SCRIPT_DIR=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mfdbfh\scripts

MFDBFH_VAULT

Specifies the name of a secrets vault.
Syntax
MFDBFH_VAULT=vault-name
Parameter
vault-name
The name of a vault that is defined in the product's secrets.cfg file.
Default
Not set. Uses the default vault as defined in secrets.cfg.
Comments
For more information on secrets vaults, see Vault Facility.


File Handling and Dataset Environment Variables

Lists environment variables related to configuring file and dataset handling.
Parent topic: Environment Variables by Groups

COBDATA

Specifies the directory or directories that the run-time system is to search for data files.
Syntax
COBDATA=path-name[[;path-name][...]]
Parameter
path-name
The full path to a directory for the run-time system to search for application data files. When more than one path-name is present, a null path-name represents the current working directory.
Default
Not set. The run-time searches the current working directory.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

COBDATA provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time.

COBDATA affects the compiler and other utilities. During compilation, for example, program source is regarded as a data file by the compiler. If you intend to use any COBOL development system utilities, we recommend that the COBDATA value starts with a colon (:).

COBDATA is considered set if there is an environment variable of this name in your environment space, and its value is non-empty.

The full mapping order for files is:

  1. Any dd_ environment mappings
  2. Any ASSIGN TO EXTERNAL mappings
  3. Any COBDATA environment variable mappings

For multiple directory paths specified either in the COBDATA environment variable or a dd_ environment variable, the system searches the first directory specified followed by a slash (/) as a prefix to the user name.

If the filename is not found, or is not readable, the search continues with the next directory until the final directory has been searched. If no file is found, the first directory is used if a file is to be created.

Any dd_ and COBDATA mappings are ignored for any filename that starts with a hyphen () or a slash (/). In addition, it is illegal to have a hyphen in an environment variable name.

When using this facility, you should not use a filename that starts with "COB... "(these are reserved for the COBOL system).

You can use the COBDATA environment variable for files open in any mode (including OUTPUT) and for fixed or variable length files. If you are using indexed files, both the data and index files must be in the same directory.

The COBDATA environment variable affects file deletes, using the rules given here, as well as file opens.

If you intend to use COBOL development system programs, we recommend that you first unset COBDATA, as many of these programs open data files and are thus affected by the value of COBDATA. If you have to set COBDATA, you should include the paths :$COBDIR/dynload/helptbox.lbr and :$COBDIR/dynload/check.lbr at the beginning of the COBDATA value. If you want to see the Animator Help pages, also include COBDIR/dynload/advanim.lbr.

Example

The following causes COBDATA to be set to instruct the run-time system to search for data files in the current directory, then in the current directory's demo subdirectory, and finally in the C:\data\progs directory.

COBDATA=.;.\demo;C:\data\progs

DB2DBDFT

The default database against which the DB2 SQL preprocessor processes SQL statements.
Syntax
DB2DBDFT=path-name/database-name
Parameters
path-name
The location of the default database.
database-name
The name of the default database.
Default
Not set. Uses the database name specified in the project.

ES_DB_FH

Enables or disables database file handler support. This is required if your data files are stored in a datastore, or your enterprise server region stores some of its resources in a database; see Micro Focus Database File Handler and Enterprise Server Region Database Management for more information.
Syntax
ES_DB_FH={[Y|true]|[N|false]}
Parameters
Y|true
Use the Micro Focus Database File Handler (MFDBFH) to direct file handling.
N|false
Disable database file handling.
Default
ES_DB_FH=N
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.
Important: The configuration file specified by the MFDBFH_CONFIG environment variable must contain a corresponding <server> entry for the database server. <dsn> entries for the region, cross-region, and master databases must also be specified in the configuration file to enable use of region database operations.
Syntax
ES_DB_SERVER=server-instance
Parameter
server-instance
The name of a valid database server instance.
Default
Not set.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Example
ES_DB_SERVER=MYSERVER

In this example, your database configuration file would need to contain something similar to the following:

<datastores usevault="false">
   <server name="MYSERVER" type="sqlserver" access="odbc">
       <dsn name="SS.MYMASTER" type="database" dbname="master"/>
       <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO"
          feature="all"/>
       <dsn name="SS.CAS.CROSSREGION" type="crossregion.cas"/>
   </server>
</datastores>

ES_LOCKDB

Specifies the region database that is to process resource locking (step- and system-scoped ENQs) for an enterprise server region within a cluster, where resources such as catalogs are deployed to a database.
Syntax
ES_LOCKDB=region-db
Parameter
region-db
The name of the region database responsible for processing step- and system-scoped ENQs.
Default
Not set.
Comments
This variable must be used in conjunction with ES_SERVER, in which ES_SERVER is set to the database server that houses the region database; see Resource Locking for more information.

ES_RLS_FILE_SUPPORT

If a record is locked because a program is doing a read for update, and the application needs to ensure that no other program can access that record, you can set this environment variable to avoid returning a dirty record until the program holding the lock has completed.
Syntax
ES_RLS_FILE_SUPPORT=Y
Parameter
Y
Stops dirty records being returned when a record is locked by another process.
Default
Not set. Dirty records are returned.
Comments
The timeout in fileshare also needs to be set to 0 using /t 0 in the fileshare configuration file. See Using a Fileshare Configuration File for details.

Parameter values are not case sensitive.

EXTFH

Specifies a configuration file for the Callable File Handler.
Syntax
EXTFH=file-name.cfg
Parameter
file-name
The prefix name of the configuration (.cfg) file.
Default
Not set. The default configuration file name prefix is extfh.
Example
EXTFH=c:\mydir\myconfig.cfg

FHREDIR

Specifies a configuration file to be used by the Fileshare Client.
Syntax
FHREDIR=[path-name\]prefix.cfg
Parameters
path-name
The full path to the location of the Fileshare Client configuration file.
prefix
The prefix name of the configuration (.cfg) file.
Default
Not set. Uses the fhredir.cfg file in the current working directory.
Example
FHREDIR=C:\mydir\myconfig.cfg

FS

Specifies a configuration file to be used by the Fileshare Server.
Syntax
FS=file-name.cfg
Parameter
file-name
The prefix name of the configuration (.cfg) file.
Default
FS=fs.cfg
Example
FS=myfsconf.cfg

FSCOMMS

Specifies that the Fileshare system is to run in single user mode.
Syntax
FSCOMMS="\$local"
Parameter
$local
Run the Fileshare System in single user mode.
Default
Not set. Fileshare system runs in multi-user mode.

GDG.RECALL

Controls the recall of HSM archived datasets when accessing mainframe GDGs using MFA Data Access Services.

HCOBND (deprecated)

Specifies a directory to be used for bind files generated by the DB2 External Compiler Module (ECM).
Attention: HCOBND is deprecated and provided for backward compatibility only. We recommend that you use either the BIND or the BINDDIR compiler directive option instead.
Syntax
HCOBND=path-name
Parameter
path-name
The directory that the DB2 ECM is to use to store bind files.
Default
Not set. Looks only in the current working directory for bind files generated by the DB2 ECM.
Comments
The DB2 ECM uses the specified directory until the variable is unset or reset to a different directory. The DB2 Compiler directive option BIND overrides this environment variable.
Example
HCOBND=d:\mydir\binds

LIB

The location of the DB2 LIB directory.
Syntax
LIB=path-name
Parameter
path-name
The path to your Windows SDK LIB directory (x86) containing .lib files such as odbc32.lib.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

MF_CBLQDA

Determines if QSAM files are dynamically allocated
Syntax
MF_CBLQDA={ON|OFF}
Parameters
ON
Dynamically allocate QUSAM files when processing an OPEN I-O or OPEN EXTEND statement for an optional file (i.e., a file opened using the SELECT OPTIONAL syntax in the FILE-CONTROL paragraph) or a file opened for OUTPUT, whether it is optional or not.
OFF
Dynamic allocation is not permitted.
Default
MF_CBLQDA=OFF
Comments
This is an emulation of the CBLQDA Language Environment (LE) run-time option.

When set to ON, and your JCL contains a misspelled or no DD statement for the file being opened, a temporary file is created as a result of the OPEN statement, and then deleted after the program has run. For optional files opened for I-O or for EXTEND, you receive a return code of 05; for files opened for OUTPUT, you receive a return code of 00.

This variable has no effect on VSAM applications or the JCL utility programs.

For programs that use ESDS files and have this variable set ON, ensure that FILETYPE is set to 15 or 16; otherwise these files will be affected by the variable, and treated as QSAM files.

MF_LEX_API

Specifies whether the JES configuration uses single or multiple LEX files, and enables JES configuration to specify subdirectories for LEX files as necessary.
Syntax
MF_LEX_API={1|2|D}|1D|2D|D
Parameters
1
Use multiple LEX files.
2
Use a single LEX file. Disk-based access only.
D
Use directories to store LEX files.
Default
MF_LEX_API=1
Comments
Do mix these settings in a Region/PAC. They must be consistent for all.
Example
This example sets the JES configuration to use a single LEX file stored in directories.
MF_LEX_API=2D

MF_NEWSPACE

Indicates whether SPACE is required for NEW datasets.

MF_SYSLOGDSN

The Syslog Dataset name.

MFALLOC_LOC

The default allocated dataset location.
Syntax
MFALLOC_LOC={path-name|SQL-URL}
Parameters
path-name
The full path to the dataset location.
SQL-URL
For a database-hosted dataset, the SQL URL to that location.
Default
Not set.
Example
Set the default allocated dataset to the sql://localhost/JCLTEST?folder=/JCLDEMO/data location:
MFALLOC_LOC=sql://localhost/JCLTEST?folder=/JCLDEMO/data

MFALLOC_PROP

Rules for generated PC dataset names on allocation (that is, the default catalog PC DSN format).

MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.
Syntax
MFDBFH_CONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The file name of the configuration file.
Default
Not set. Uses the mfdbfh.cfg file found in the current working directory.
Comments
You can also set MFDBFH_CONFIG as a system environment variable.

MFDBFH_RECORD_LOCKING

Specifies the type of record locking that it is to be used when the database file handler is in effect.

Syntax
MFDBFH_RECORD_LOCKING={table|database}
Parameters
table
A file's record locks are held in a seperate lock table. (When using this locking mode, the behavior of record locking COBOL file operations closely follows the same behavior when using Fileshare.)
database
The native record locking mechanism of the database engine is used to establish and test locks on the data file records. This method improves performance, but at the cost of the locking behavior not exactly matching that of traditional COBOL record locking; see Record Locking Strategies for more information.
Default
MFDBFH_RECORD_LOCKING=table

MFDBFH_SCRIPT_DIR

Specifies the location of the scripts and stored procedures required when the database file handler is in effect.
Syntax
MFDBFH_SCRIPT_DIR=path-name
Parameter
path-name
The full path to the directory containing the required resources.
Default
MFDBFH_SCRIPT_DIR=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mfdbfh\scripts

MFDBFH_VAULT

Specifies the name of a secrets vault.
Syntax
MFDBFH_VAULT=vault-name
Parameter
vault-name
The name of a vault that is defined in the product's secrets.cfg file.
Default
Not set. Uses the default vault as defined in secrets.cfg.
Comments
For more information on secrets vaults, see Vault Facility.

MFFTP_ASCII_CMD_XLATE

For EBCDIC datasets, translates from EBCDIC to ASCII using a PUT, and ASCII to EBCDIC using a GET.
Syntax
MFFTP_ASCII_CMD_XLATE={Y|N}
Parameters
Y
Converts from EBCDIC to ASCII in PUTs and from ASCII to EBCDIC in GETs, for files cataloged as EBCDIC when TYPE A or ASCII sub command is also issued.
N
Standard conversion.
Default
MFFTP_ASCII_CMD_XLATE=N

MFLOCKING

Enables Locking Support.

PROCLIB

Under a mainframe emulation, determines whether a status of 37 is returned.
Syntax
PROCLIB={ON|OFF}
Parameters
ON
Under a mainframe emulation, returns a file status of 37 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.
OFF
No file status is returned.
Default
PROCLIB=OFF

STRICTVSAM

Specifies strict mainframe emulation during file processing of VSAM files.
Syntax
STRICTVSAM={ON|OFF}
Parameters
ON
File status 37 is returned when an existing VSAM file is opened for OUTPUT if the file has data or previously had data written to it, or the file is of a different format to the file on disk.
OFF
File status 0 is returned and a new file is created when an existing VSAM file is opened for OUTPUT.
Default
STRICTVSAM=OFF

TXFILEP

The location of Micro Focus VSAM files.
Syntax
TXFILEP={path-name|datastore-location}
Parameters
path-name
The full path to the VSAM files on disk.
datastore-location
For database-hosted files, the location of the datastore containing the VSAM files. Use the notation described in the The dbfhdeploy Command Line Utility topic under Category > data.

XFHLOG

Determines the location of the log file when the LOG option is active.
Syntax
XFHLOG=DEFAULT
Parameter
DEFAULT
Generates the log file in the current working directory.
Default
Not set. The log file is generated in %ProgramData%\Micro Focus\File Handler\version-number, where version-number represents the version of your Micro Focus product.
Comments
The effect of this variable can be overridden by the LOGFILENAME configuration option.


General Enterprise Server Environment Variables

Parent topic: Environment Variables by Groups

ES_3270_REMOVE_NULL_COLOR_ATTRIB

Sets the extended color attribute to low-values and does not send it to the 3270 emulator.
Syntax
ES_3270_REMOVE_NULL_COLOR_ATTRIB=Y
Parameter
Y
Sets the extended color attribute to low-values and does not send it to the 3270 emulator.
Default
Not set. Enterprise Server uses the default screen size.
Comments
This fixes an IBM issue related to Personal Communications (PCOM) which is described at http://www-01.ibm.com/support/docview.wss?uid=swg21461404.

ES_CSKL_NO_MSG_CONSOLE

Stops the EZ Sockets CICS listener (CSKL) from writing messages to console.log.
Syntax
ES_CSKL_NO_MSG_CONSOLE=ON
Parameter
ON
CSKL does not write message to console.log.
Default
Not set. CSKL writes messages to console.log.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_ELAPSED_DISPATCH_SECONDS

Specifies how frequently casmgr checks for Jobs in the waiting state and then starts them.
Syntax
ES_ELAPSED_DISPATCH_SECONDS=wait-time
Parameter
wait-time
The number of seconds that casmgr waits before checking for Jobs in the waiting state and then starting them.
Default
ES_ELAPSED_DISPATCH_SECONDS=5

ES_ESM_DISABLE_DFLTUSER_ESMAC

Allows you to disable the default ESMAC user to increase the security of your server.
Syntax
ES_ESM_DISABLE_DFLTUSER_ESMAC=Y
Parameter
Y
Disables the default ESMAC user, disables the DEFAULT button on the logon screen, and forces users to always enter a valid user ID and password.
Default
Not set. The ESMAC user is enabled.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_ESMAC_DISP_MAX_OVERRIDE

Limits the number of lines shown when viewing an individual catalog entry in the ESMAC catalog view or when viewing a SYSOUT file from the job list view.
Syntax
ES_ESMAC_DISP_MAX_OVERRIDE=value
Parameter
value
An integer denoting the number of lines to display to a maximum of 99999.
Default
ES_ESMAC_DISP_MAX_OVERRIDE=1000
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_LEGACY_ECI

Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG.
Syntax
ES_LEGACY_ECI=Y
Parameter
Y
Micro Focus ECI is used.
Default
Not set. IBM CTG is used.
Comments
Parameter value is not case sensitive.

ES_HARD_KILL_PROCESS

Enables you to modify how Enterprise Server kills a process.
Syntax
ES_HARD_KILL_PROCESS={Y|N}
Parameters
Y
Issue a hard kill after a soft kill when the soft kill fails.
N
No hard kill is attempted after the soft kill.
Default
ES_HARD_KILL_PROCESS=Y
Comments
This variable only applies to the region within an Enterprise Server cluster designated as the Global Lock Manager (GLM).

ES_MAX_CATALOG_LINES

Restricts the number of entries displayed in ESMAC catalog view.
Syntax
ES_MAX_CATALOG_LINES=number
Parameter
number
The number of lines to display up to a maximum of 99999.
Default
ES_MAX_CATALOG_LINES=5000
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_MAX_HTTP_OUT

Specifies the maximum size of the HTTP response sent by Enterprise Server.
Syntax
ES_MAX_HTTP_OUT=value
Parameter
value
A number representing the maximum size of the HTTP response in bytes.
Default
ES_MAX_HTTP_OUT=
Comments
In earlier releases, the size of the HTTP response was controlled by the HTTP Out field on the ESCWA ES Control page.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_MEM_STRATEGY

Selects the types of memory processes supported.
Comments
Memory strategy can also be set via the memory_strategy run-time tunable.

ES_MFDS_ADDRESS

Specifies the server address is used by casstart when the /m parameter is not provided.

ES_OTMA_TIMEOUT

The time in seconds that an OTMA client should wait for an answer.
Syntax
ES_OTMA_TIMEOUT=wait-time
Parameter
wait-time
The number of seconds to wait. The maximum is 43199.
Default
ES_OTMA_TIMEOUT=120

(2 minutes)

ES_PRODUCTION

Prevents the initiation of a debugging session from the IDE.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_RDO_MAX_RESOURCES

Specifies the maximum number of records for CICS resource types that display in Enterprise Server Common Web Administration (ESCWA) or Enterprise Server Monitor and Control (ESMAC).
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_RTLS_CERT_AUTH_FILEPATH

The absolute path to the certificate authority file used for a TLS-enabled Redis SOR.
Syntax
ES_RTLS_CERT_AUTH_FILEPATH=path-name
Parameter
path-name
The full path to the certificate authority file used for a TLS-enabled Redis SOR.

ES_RTLS_CERT_FILEPATH

Absolute file path to the certificate file used for a TLS-enabled Redis SOR.
Syntax
ES_RTLS_CERT_FILEPATH=path-name
Parameter
path-name
The full path to the certificate file used for a TLS-enabled Redis SOR
Default
Not set.

ES_RTLS_PRIVATE_KEY_FILEPATH

Absolute file path to the private key file used for a TLS-enabled Redis SOR.
Syntax
ES_RTLS_PRIVATE_KEY_FILEPATH=path-name
Parameter
path-name
The full path to the private key file used for a TLS-enabled Redis SOR.
Default
Not set.

ES_SEP_DORMANT_TIME

Allows override of Transient SEP dormant time. Rather than automatically terminating transient SEPs on completion of a stateful request, the server manager allows a period of inactivity before scheduling their termination. This allows new requests to re-use the SEP rather than starting a new instance. This environment variable allows you to control the period of inactivity.
Syntax
ES_SEP_DORMANT_TIME=wait-time
Parameter
wait-time
The number of seconds that the Transient SEP is inactive.
Default
ES_SEP_DORMANT_TIME=2
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_SERVER

The default server name used if no -r switch is specified on casstart or casstop.
Syntax
ES_SERVER=server-name
Parameter
server-name
The server name.
Defaults
32-bit
ES_SERVER=ESDEMO
64-bit
ES_SERVER=ESDEMO64

ES_SYSOUT_HOLD

Determines which SYSOUT files are sent to the Complete queue with an Out Hold status.
Syntax
ES_SYSOUT_HOLD={msg-class}[msg-class[...]]
Parameter
msg-class
A message class to send to the Complete queue with an Out Hold status.
Default
Not set. No specific message classes are sent to the Complete queue with an Out Hold status.
Example
Message classes A and B are sent to the Complete queue with an Out Hold status:
ES_SYSOUT_HOLD=AB

ES_TN3270_FORCE_ALT

Enables you to use a screen size other than the default when using a TN3270 terminal emulator.
Syntax
ES_TN2370_FORCE_ALT=ON
Parameter
ON
Enables alternative screen size.
Default
Not set. The default screen size is used.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

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.
Syntax
ES_TN3270_MODEL_LOG=Y
Parameter
Y
Model names are written to TSQ TN32MODL.
Default
Not set. Model names are not logged.

ES_USR_DFLT_CICS

Allows you to override the default user when no user is logged on for CICS authentication.
Syntax
ES_USR_DFLT_CICS=userid
Parameter
userid
An alternative default user name.
Default
ES_USR_DFLT_CICS=CICSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_ESMAC

Allows you to override the default user when no user is logged on for ESMAC authentication.
Syntax
ES_USR_DFLT_ESMAC=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_ESMAC=MFUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_IMS

Allows you to override the default user when no user is logged on for IMS authentication.
Syntax
ES_USR_DFLT_IMS=user-id
Parameter
user-id
The user name to override the default.
Default
ES_USR_DFLT_IMS=IMSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_JES

Allows you to override the default user when no user is logged on for JES authentication.
Syntax
ES_USR_DFLT_JES=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JES=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_WS_RUNAWAY_TIMEOUT

Time that the client waits for a response from the Web service. Valid values are 0 to 65535 seconds.
Syntax
ES_WS_RUNAWAY_TIMEOUT=wait-time
Parameter
wait-time
Time in seconds that the client waits for a response from the Web service. Valid range is 0 through 65535.
Default
Not set.

IMSCPY

The location of copybook files for DBDGEN, PSBGEN and MFSGEN utilities.
Syntax
IMSCPY=path-name
Parameter
path-name
The full path to the location of compiled COBOL applications.

ISPPROF

The location of ISPF dialog profiles.

JAVA_HOME

Specifies the location of the JDK.
Syntax
JAVA_HOME=path-name
Parameter
path-name
The full path to the location of the JAVA_HOME location.

LANG

Specifies the locale.
Syntax
LANG=win-language[_territory[.code-page]]
Parameters
win-language
The spoken/written language in which your program is to run. This determines which message catalog is open so that if an error occurs, the error message is output in the selected language. win-language can take any of the following values:
Value | Language
1 | US English
2 | Canadian French
3 | Danish
4 | Dutch
5 | UK English
6 | Finnish
7 | French
8 | German
9 | Italian
10 | Norwegian
11 | Portuguese
12 | Spanish
13 | Swedish
territory
The country in which your program is to run.
code-page
The character set code to use for your program.
Default
Not set.
Example
LANG=7

MAINFRAME_FLOATING_POINT

Specifies the format to use for floating point data items. Possible formats are IBM hexadecimal and IEEE.
Syntax
MAINFRAME_FLOATING_POINT={true|false}
Parameters
true
Use IBM hexadecimal-format floating-point data items.
false
Use IEEE-format floating-point data items.
Default
MAINFRAME_FLOATING_POINT=false
Comments
The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MF_AMODE31ONLY

Indicates that all programs are AMODE(31).

MF_CHARSET

Specifies the system character set.
Syntax
MF_CHARSET={{A|ASCII}|{E|EBCDIC}}
Parameters
A|ASCII
Use the ASCII character set.
E|EBCDIC
Use the EBCDIC character set.
Default
MF_CHARSET=A

MF_USESCA5

Specifies that the server should use version 5 of the Open Service Component Architecture (Open SCA).
Syntax
MF_USESCA5={ON|OFF}
Parameters
ON
The server uses version 5 of the Open SCA.
OFF
The server uses the default version of Open SCA.
Default
MF_USESCA5=ON

MFACCCGI_CHARSET

Specifies the charset used in the HTTP header returned by ESMAC.
Syntax
MFACCCGI_CHARSET=iana-string
Parameter
iana-string
An IANA-defined charset string.
Default
MFACCCGI_CHARSET=windows-1252

MFCODESET

Specifies which translation tables to use.
Syntax
MFCODESET=country-code
Parameter
country-code
The country code required for translation. See Supported Country Codes for a list of countries and codes.
Default
Not set. Uses the country code returned from the CBL_GET_OS_INFO routine.
Comments
If you are not using UK or US language settings, you must also set MFCODESET as a Windows system variable. See your Windows documentation for details.

MFCSCFG

Specifies a configuration file to be used by the Client/Server Binding client program.
Syntax
MFCSCFG=[path-name\]file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The name of the configuration file.
Default
MFCSCFG=mfclisrv.cfg
The default path-name is the current working directory, and if not found, the default settings for the configuration entries are used.
Comments
The value of MFCSCFG is overridden by any value defined in the command line.
Example
MFCSCFG=d:\mydir\mfclisrv.cfg

MFEXTMAP

Location of a mapper file.

MFJSDCBOUTFIL

MFJSDCBOUTFIL
Determines whether the DCB's LRECL value is honored during an OUTFIL statement.
MFJSDCBOUTFIL={ON|OFF}
Parameters
ON
The LRECL specified in the DCB properties is used during an OUTFIL statement.
OFF
Emulates the ICE222A/ICE217A mainframe restriction.
Default
MFJSDCBOUTFIL=OFF
Comments
When MFJSDCBOUTFIL=ON is in effect, if the DCB LRECL value differs from that calculated by OUTFIL, records are either truncated or padded with space to match the DCB LRECL value.
Example
MFJSDCBOUTFIL=ON

MFLECONFIG

Specifies a configuration file for Language Environment (LE) run-time options.
Syntax
MFLECONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the ile containing the LE run-time options you want to use.
file-name
The name of the file containing the LE run-time options you want to use.
Default
Not set. No LE run-time options are used.

MFLOGDIR

Specifies a directory to be used by Client/Server Binding for log files.
Syntax
MFLOGDIR=path-name
Parameter
path-name
The full path to the location of log files.
Default
Not set.
Example
MFLOGDIR=d:\mydir\logs

MFPRELOAD_USE

Calls MFPRELOAD to improve performance.

MFRU_NOINHERIT

Determines whether to skip registering processes in shared memory during initialization of the run-time system.
Syntax
MFRU_NOINHERIT={Y|TRUE}
Parameters
Y|TRUE
Do not register processes in shared memory during initialization of the run-time system.
Default
Not set. Processes are registered.
Comments
Consider setting this variable to avoid COBRT105 errors, which can occur during initialization if a very large number of COBOL processes are running and there are no available slots in the shared memory segment.

When set, various run-time settings such as switches, shared memory, console window settings, and so on, are no longer inherited by any child processes.

MFSUB

Specifies whether to use SUBI or ASUBI.
Syntax
MFSUB={SUBI|ASUBI}

MFSYSCATDIR

The location of the system catalog directory.

MFUSER

Enables you to change the user from the default User ID to an alternative ID.

MFUSERCAT_LOC

Specifies the location and name of each additional catalog, matching the values provided in the MFUSERCAT_NODE value.
Syntax
MFUSERCAT_LOC={[path-name\]file-name}[;{[path-name\]file-name}[...]]
Parameters
path-name
The full path to a catalog file.
file-name
The name of the catalog file.
Default
Not set. No file names or locations are provided for additional catalogs specified by MFUSERCAT_NODE.
Comments
Parameter values are limited to a total of 4096 characters.

If multiple catalog files are in the same location, you can use the environment variable MFUSERCAT_LOC to store that location. If you do this, you only need to specify the file name of each catalog file in MFUSERCAT_LOC.

MQSERVER

The names of one or more minimal channels.
Syntax
MQSERVER=channel-name/transport-type/{machine-name|ip-address(port-number)}
   [,{machine-name|ip-address}(port-number)][...]]
Parameters
channel-name
The name of a channel as defined on the server.
transport-type
The communications protocol, which can be any of the following:
  • TCP
  • LU62
  • NETBIOS
  • SPX
machine-name
The name of the server machine.
ip-address
The machine IP address.
port-number
The number of the port used.
Comments
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.

Examples
MQSERVER=CHANNEL3/TCP/QServer(1414)
MQSERVER=CHANNEL1/TCP/10.120.99.999(1414),10.120.98.888(1414)

MULTIMFENTMAP

Specifies whether special characters such as < and & are replaced with the equivalent HTML entities such as &lt; and &amp;.

OOSW

OO run-time switches.

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.
Syntax
TXMAPP=path-name
Parameter
path-name
The full path to the location of the BMS load module.

TXRDTP

The location of MSS resource definition (RDO) files.
Syntax
TXRDTP=path-name
Parameter
path-name
The full path to the MSS resource definition (RDO) files.


IMS Environment Variables

Lists environment variables related to configuring the IMS environment.
Parent topic: Environment Variables by Groups

ES_ACBLIB

Specifies the location of the IMS ACB files.
Syntax
ES_ACBLIB=path-name
Parameter
path-name
The path location of the IMS ACB files.
Default
Not set. ACB files are assumed to be in the project directory.

ES_DFS3650

Specifies the default transaction to execute or the MOD file display after successfully signing onto IMS.
Syntax
ES_DFS3650={MOD|TRX}
Parameters
MOD
Set ES_MOD3650 to the name of the MOD you want to display.
TRX
Set ES_TRX3650 to the name of the transaction.
Default
Not set. No transaction or MOD executes after successfully signing onto IMS.
Comments
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_APARM_DLI

Determines whether APARMs use ASCII and a positional parameter set to 19 when obtained from EBCDIC applications, or use EBCDIC and a positional parameter set to 20 when obtained from EBCDIC applications.
Syntax
ES_IMS_APARM_DLI={Yes|1}
Parameters
Yes|1
Sets the APARM positional parameter for DLI to 19.
Default
Not set. The default behavior sets the APARM positional parameter for DLI to 20.
Comment
The APARM positional parameter for BMP applications remains at 19 regardless of the ES_IMS_APARM_DLI setting.

ES_IMS_BASIC_CHKP_OPT

Enables a basic checkpoint call to process as if a SYNC call had been issued.
Syntax
ES_IMS_BASIC_CHKP_OPT={0|1}
Parameters
1
Checkpoint calls process as a SYNC call.
0
Checkpoint calls process normally.
Default
ES_IMS_BASIC_CHKP_OPT=0

ES_IMS_BYPASS_OTMA_DEST_RES

By default, a CHNG call issued from an OTMA- or IMS Connect-submitted transaction assumes that the destination is the OTMA client.
Syntax
ES_IMS_BYPASS_OTMA_DEST_RES={Y|N}
Parameters
Y
The destination is the OTMA client.
N
Assumes a non-OTMA client.
Default
ES_IMS_BYPASS_OTMA_DEST_RES=N
Comments
In some circumstances, the behavior of assuming a non-OTMA client is desirable.
Example
ES_IMS_BYPASS_OTMA_DEST_RES=Y

ES_IMS_CANCEL_MODE

Controls the caching of IMS binaries.
Syntax
ES_IMS_CANCEL_MODE={P|L|D}
Parameters
P
Performs a physical cancel; every transaction will have new-copy behavior. This option is the default behavior, but is the poorest performing of the options.
L
Performs a logical cancel. This gives the best performance of the options, but can only be used it there is only one DLITCBL entry point in an MPR.
D
Performs a deferred cancel, which will yield the same behavior as a logical cancel when the MPR services the same MPP back-to-back. It will behave as P (physical cancel) when the transaction changes.
Default
ES_IMS_CANCEL_MODE=P

ES_IMS_CLIENTID_LTERM

Sets LTERM to the client ID instead of the port ID.
Syntax
ES_IMS_CLIENTID_LTERM={Y|N}
Parameters
Y
Sets LTERM to the client-ID instead of the port-ID.
N
Sets LTERM to the client ID when commit-mode is zero, and to the port-ID when commit-mode is one.
Default
ES_IMS_CLIENTID_LTERM=N
Comments
By default, an IMS Connect request sets LTERM (if not explicitly overridden) to the client-ID when commit-mode is zero, and to the port-ID when commit-mode is one.

ES_IMS_CONFIG

The IMS TM parameters.

ES_IMS_DB_COMMIT_FLUSH

Enables you to force the flushing of database buffers to disk on COMMIT only.
Syntax
ES_IMS_DB_COMMIT_FLUSH={0|1}
Parameters
0
Forces the flushing of database buffers to disk on CLOSE only.
1
Forces the flushing of database buffers to disk on COMMIT only.
Default
ES_IMS_DB_COMMIT_FLUSH=0

ES_IMS_DB_TLOG_WRITETHRU

Enables you to force the flushing of TLOG buffers to disk on all database I/O.
Syntax
ES_IMS_DB_TLOG_WRITETHRU={0|1}
Parameters
0
Forces the flushing of TLOG buffers to disk on COMMIT only.
1
Forces the flushing of TLOG buffers to disk on all database I/O.
Default
ES_IMS_DB_TLOG_WRITETHRU=0

ES_IMS_DEADLOCK_WAIT

Sets the time to wait before checking for a deadlock.
Syntax
ES_IMS_DEADLOCK_WAIT=wait-time
Parameter
wait-time
Time in milliseconds to wait before checking for a deadlock.
Default
ES_IMS_DEADLOCK_WAIT=1000

(1 second)

ES_IMS_DIAGNOSE

Marks IMS TM as diagnose mode only for IMSMSGQ.
Syntax
ES_IMS_DIAGNOSE={Y|N}
Parameter
Y
The Transaction Manager (TM) works in diagnostic mode only, and no activity key points are written to the message queue.
N
Transaction Manager writes activity key points to the message queue.
Default
ES_IMS_DIAGNOSE=N
Comments
CAUTION:
Do not set ES_IMS_DIAGNOSE=Y unless advised to do so by OpenText Support for Micro Focus Products.

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 the DFSNDMX0.cbl exit routine program and its compiled code, which contains segment, field, and/or print exits.
Syntax
ES_IMS_EXITPATH=path-name
Parameter
path-name
The full path to the directory that contains the DFSNDMX0.cbl exit routine program and its compiled code.
Default
Not set.

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_GOTO_CICS_ON_SIGNOFF

Sets the behavior after logging off or timing out to return to CICS.
Syntax
ES_IMS_GOTO_CICS_ON_SIGNOFF=
Parameter
Returns to CICS after logging off or timing out.
Default
Returns to the IMS sign-on screen after logging off or timing out.

ES_IMS_IBMPLATFORM

Sets the emulation for the IMS run-time.
Syntax
ES_IMS_IBMPLATFORM={M|D}
Parameter
M
Sets the IMS run time to MVS.
D
Sets the IMS run time to DOSVS.
Default
ES_IMS_IBMPLATFORM=M
Comment
This variable rarely requires a change from the 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

Allows the user to specify the IMS System ID returned to the AIBTDLI INQY ENVIRON call.

ES_IMS_IRLM

Enables Internal Lock Resource Manager (IRLM) locking.
Syntax
ES_IMS_IRLM={0|1}
Parameters
0
Disables IRLM locking.
1
Enables IRLM locking.
Default
ES_IMS_IRLM=0
Comments
IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock.

ES_IMS_JES_DIRTY_ABEND

Determines whether IMS marks a JES container as dirty when an IMS application abends or is aborted.
Syntax
ES_IMS_JES_DIRTY_ABEND={Y|N}
Parameter
Y
IMS marks a JES container as dirty when an IMS application abends or is aborted.
N
Disables the IMS behavior of marking a JES container as dirty when an IMS application abends or is aborted.
Default
ES_IMS_JES_DIRTY_ABEND=Y

ES_IMS_LINKAGE_NULL

When an IMS program passes more linkage addresses than there are PCBs in the PSB, sets each extraneous linkage address to a value of NULL.
Syntax
ES_IMS_LINKAGE_NULL={Y|N}
Parameter
Y
Sets each extraneous linkage address to a value of NULL.
N
Extraneous linkage addresses are invalid.
Default
ES_IMS_LINKAGE_NULL=N

ES_IMS_LOCALDLI (deprecated)

Determines whether batch program execution processes all IMS DB calls entirely in the JES initiator.
Syntax
ES_IMS_LOCALDLI=1
Parameter
1
Directs batch program execution to process all IMS DB calls entirely in the JES initiator.
Disables the IMS behavior of marking a JES container as dirty when an IMS application abends or is aborted.
Default
ES_IMS_LOCALDLI=1
Comments
Deprecated. See IMS Database Locking.

Processing IMS DB calls in the JES initiator can significantly improve performance.

Stop all IMS DB control processes accessed from the batch program before execution because they become exclusively owned by JES until the program completes.

ES_IMS_LOCK_RETRY_DELAY

Sets the wait time for retrying an IMS DB lock.
Syntax
ES_IMS_LOCK_RETRY_DELAY=wait-time
Parameter
wait-time
The amount of time in milliseconds to delay retrying the IMS DB lock.
Default
ES_IMS_LOCK_RETRY_DELAY=5

ES_IMS_LOCK_TIMEOUT

Sets the time duration during which IMS DB control continues to retry a locked record before timing out
Syntax
ES_IMS_LOCK_TIMEOUT={0|wait-time}
Parameter
0
Sets an indefinite wait time.
wait-time
A number from 1 through 65525 that represents the number of seconds during which IMS DB control continues to retry a locked record before timing out.
Default
ES_IMS_LOCK_TIMEOUT=30

ES_IMS_LTERM_PREFIX

Sets an LTERM prefix alternative to the default (OTMA) to use when the ES_IMS_SINGLE environment variable is set to N.
Syntax
ES_IMS_LTERM_PREFIX=prefix
Parameter
prefix
A one- to four-character string to use as the LTERM prefix when the ES_IMS_SINGLE environment variable is set to N.
Default
ES_IMS_LTERM_PREFIX=OTMA
Comments
Enterprise Server pads the value specified with numeric digits up to eight characters, enabling the LTERM pool to be expanded from 9999 up to 999999. The pool size is dictated by the number of characters used in the specified prefix. For example, the LTERM pool size for a four-character prefix is 9999; for a three-character prefix is 99999; and so on.

Using an alternative prefix to OTMA enables you to exercise control over name conflicts.

The default setting of this environment variable suggests that the LTERMS apply only to OTMA clients; however, this is not the case. LTERMS can also be applied to second and subsequent 3270 user connections.

ES_IMS_LU_LTERM

Determines the value of the LTERM literal returned by the MFS system.
Syntax
ES_IMS_LU_LTERM={Y|N}
Parameters
Y
Returns the LU name.
N
Returns the user ID.
Default
ES_IMS_LU_LTERM=

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.
Syntax
ES_IMS_MESGQ=[ds-file-name;]max-blocks;buffer-count;start-control;[cushion-size]
Parameters
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).
Default
ES_IMS_MESGQ=IMSMESGQ.dat;4;2;Y;4
Comments
CAUTION:
Manually set this variable only when advised to do so by OpenText Support for Micro Focus Products.

ES_IMS_DISPLAY_NEW

Changes the timestamp format for /DISPLAY output.
Syntax
ES_IMS_DISPLAY_NEW={Y|N}
Parameters
Y
Timestamp output follows the current z/OS system style, YYDDD/HHMMSS.
N
Timestamp output follows the old z/OS system style, MM/DD/YYYY HH:MM:SS.
Default
ES_IMS_DISPLAY_NEW=N

ES_IMS_MFS_OPT2_LEGACY

Configures MFS input type option 2 to behave the same as MFS input type option 1.
Syntax
ES_IMS_MFS_OPT2_LEGACY={Y|N}
Parameters
Y
Enables legacy MFS input type option 2 behavior.
N
MFS input type option 2 behavior is the same as MFS on z/OS mainframes.
Default
ES_IMS_MFS_OPT2_LEGACY=N

ES_IMS_OPEN_TIMEOUT

Defines the time period during which IMS retries the opening of a database file that is in use by another task.
Syntax
ES_IMS_OPEN_TIMEOUT=wait-time
Parameter
wait-time
The number of seconds IMS waits before making a subsequent attempt to open a database file that is in use by another task.
Default
ES_IMS_OPEN_TIMEOUT=30

ES_IMS_OTMA_DEST

Defines one or more destinations to which data is redirected for IMS Connect (IMSCON), the MQ-IMS Bridge (MQ), or the IMS print exit (NONOTMA).
Syntax
IMS Connect
ES_IMS_OTMA_DEST={LTERM-name,IMSCON}[;...]
MQ-IMS Bridge
ES_IMS_OTMA_DEST={LTERM-name,MQ,MQ-queue-manager-name,MQ-queue-name}[;...]
IMS Print Exit
IMS_OTMA_DEST={printer-name,NONOTMA,{LU1|LU3}}[;...]
Parameters
LTERM-name
A destination name specified as a literal value for a single destination, or specified using a literal value followed by one or more asterisks to represent a series of multiple destinations. For example, an LTERM-name of TERM*** creates 1000 LTERM destinations named TERM000 through TERM999. Use this method to avoid defining each destination separately.
MQ-queue-manager-name
The name of the MQ queue manager.
MQ-queue-name
The name of the MQ queue.
printer-name
The printer name.
Default
Not set.

ES_IMS_PATH

The location of compiled COBOL applications.
Syntax
ES_IMS_PATH=path-name
Parameter
path-name
The full path to 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.
Syntax
ES_IMS_PLI_INDIRECT_PCBADDR={Y|N}
Parameters
Y
Always converts address as long as the PSB language is PL/I.
N
Never converts addresses.
Default
Not set. When the main program is a PL/I program, PCB addresses are converted from a direct to an indirect addressing technique.

ES_IMS_RCLASS

Creates a set of newly-named IMS security resource classes, appending a value to the default character of each resource class.
Syntax
ES_IMS_RCLASS=value
Parameters
value
Up to seven alphabetic characters.
Default
Not set. No new resource classes are created.
Comments
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

Specifies 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.
Syntax
ES_IMS_ROLLFORWARD={Y|N}
Parameters
Y
Enables forward recovery logging.
N
Disables forward recovery logging.
Default
ES_IMS_ROLLFORWARD=N

ES_IMS_SINGLE

Enables or disables functionality that allows a single user to sign on to multiple LUs simultaneously.
Syntax
ES_IMS_SINGLE={Y|N}
Parameters
Y
Disables multiple sign-on functionality.
N
When ES_IMS_SINGLE is set to N, and a user attempts to sign on to an LU using a sign-on that is currently active at another LU, IMS Transaction Manager (TM) assigns a temporary LTERM to the user and LU using a name constructed from the ES_IMS_LTERM_PREFIX setting followed by a numerical value totalling eight characters (see IMS_LTERM_PREFIX for details). The temporary LTERM is the destination for the user and LU irrespective of activity at other LUs controlled by the user. When a user disconnects from an LU that is served by a temporary LTERM, the LTERM is returned to the temporary pool for reuse.

Also when ES_IMS_SINGLE is set to N, the execution of /dis USER all returns a sub-list for each user that shows all active connections. These connections persist throughout a session, and are dynamically recreated during a warm start. See IMS Control for details.

Default
ES_IMS_SINGLE=Y
Comments
No KEYPOINT activity is associated with the use of ES_IMS_SINGLE.

If an enterprise server region is running in a PAC with the IMS features enabled, then single signon will be enforced for IMS. If you want to change the behavior then set ES_IMS_SINGLE=N to enable the same user to signon to multiple terminals for IMS.

ES_IMS_SPARSE_EXIT_LANG

Specifies the language for IMS DB secondary index sparse routines.
Syntax
ES_IMS_SPARSE_EXIT_LANG=C
Parameter
C
Sets the language for IMS DB secondary index sparse routines to COBOL.
Default
Not set. Sparse exits are disabled.

ES_IMS_SUPPORT

Enables IMS support.

ES_IMS_TLOG_COMPRESS

Determines whether Backward Recovery TLOG files are compressed or not compressed.
Syntax
ES_IMS_TLOG_COMPRESS={0|1}
Parameters
0
Disables compression of the Backward Recovery TLOG file. When not compressed, the file contains only the information required to recover databases.
1
The Backward Recovery TLOG file is compressed. Enterprise Test Server reclaims space in the file when information becomes obsolete.
Default
ES_IMS_TLOG_COMPRESS=1

ES_IMS_TLOG_FLUSH (deprecated)

Determines whether the frequent flushing of TLOG and database buffers to disk is forced.
Attention: This environment variable is deprecated and provided for backward compatibility only. Use ES_IMS_DB_TLOG_WRITETHRU to flush TLOG buffers and ES_IMS_DB_COMMIT_FLUSH to flush database buffers.
Syntax
ES_IMS_TLOG_FLUSH={0|1}
Parameters
0
Does not flush TLOG and database buffers to disk.
1
Forces the frequent flushing of TLOG and database buffers to disk.
Default
ES_IMS_TLOG_FLUSH=0
Comments
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.

ES_IMS_TLOG_MAXSIZE

Specifies the maximum size of the IMS DB transaction logging file.
Syntax
ES_IMS_TLOG_MAXSIZE=hex-value
Parameter
hex-value
A hexadecimal value that represents the maximum size for the transaction logging file in bytes.
Default
ES_IMS_TLOG_MAXSIZE=h"FFF00000"

(4GB)

ES_IMS_TLOG_PATH

The location of IMS DB transaction logging (TLOG) files.
Syntax
ES_IMS_TLOG_PATH=path-name
Parameter
path-name
The full path to the location where TLOG files are stored.
Default
Not set. Uses the Enterprise Test Server system directory.
Comments
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_THRESHOLD

Sets the threshold size of the IMS DB transaction logging file. When the threshold is reached, the current TLOG file is closed and a new TLOG file created for subsequent transactions.
Syntax
ES_IMS_TLOG_THRESHOLD=hex-value
Parameter
hex-value
A hexadecimal value that represents the threshold size for the transaction logging file in bytes.
Default
ES_IMS_TLOG_THRESHOLD=h"7FFFFFFF"

(2GB)

ES_IMSCFG

The location of the IMSCONFG.DAT IMS configuration file.
Syntax
ES_IMSCFG=path-name
Parameters
path-name
The full path to the location of the IMSCONFG.DAT file.
Default
Not set.

ES_IMSDAT

The location of IMS DB data files.
Syntax
ES_IMSDAT=path-name
Parameters
path-name
The full path to the directory that stores IMS DB data files.
Default
Not set. Uses the current working directory.

ES_IMSLIB through ES_IMSLIB25

ES_IMSLIB specifies the location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files. You can use this same variable with a sequential number appended to search additional locations.
Syntax
ES_IMSLIB[1...25]=path-name
Parameters
path-name
The full path to the location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files.
Default
Not set. Looks for the .DAT files in the current working directory.
Comments
You may specify up to 25 locations.
Example
ES_IMSLIB=$BASEPATH\ED_SETS\IMSLIB		      /*sets the first location for IMSLIB objects */
ES_IMSLIB2=$BASEPATH \ED_SETS_SYS\IMSLIB  /* sets the next location to search */
ES_IMSLIB3=$BASEPATH \ED_SETS_QA\IMSLIB		 /* and the next */
ES_IMSLIB4=$BASEPATH \ED_SETS_PROD\IMSLIB	/* etc. */

ES_MFSLIB

The location of the control blocks generated by the MFS generation program.
Syntax
ES_MFSLIB=path-name
Parameter
path-name
The path to the MFS directory.
Default
ES_MFSLIB=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ims

ES_MOD3650

Replaces the default MOD file displayed after a successful sign-on to IMS. See ES_DFS3650 for further details.
Syntax
ES_MOD3650=file-name
Parameter
file-name
The name of the replacement default MOD file.

ES_SSTM_IMS

Location of the JCL used to initialize the SSTM IMS environment.
Syntax
ES_SSTM_IMS=file-location
Parameter
file-location
The full path to the location of the JCL used to initialize the SSTM IMS environment.
Default
Not set.

ES_TMC_AGGREGATE

Initializes performance settings for the IMS message queue, and enables dynamic performance tuning. 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.
Syntax
ES_TMC_AGGREGATE={[,N|,D]|nnn,Y}
Parameters
,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 ESCWA. 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.
Notes: To avoid unpredictable results when using this setting, Micro Focus recommends that you also set the static options as follows on ESCWA. Select enterprise server region you require, click IMS > Configuration and then click the TM tab:
  • Set the Cold start list to Everything.
  • Check Persist.

See Server Instance Properties: MSS IMS TM General for more information.

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.

Typically, when the message queue resides on a higher performance I/O subsystem such as one using SSDs, a smaller value, for example 1 or 2, produces the best results. A value of 10 or higher seldom improves performance.

Default
ES_TMC_AGGREGATE=,N

ES_TRX3650

The default transaction to run after a successful sign-on to IMS. See ES_DFS3650 for further details.
Syntax
ES_TRX3650=transaction
Parameter
transaction
The default transaction to run.
Default
Not set.

ES_USR_DFLT_IMS

Allows you to override the default user when no user is logged on for IMS authentication.
Syntax
ES_USR_DFLT_IMS=user-id
Parameter
user-id
The user name to override the default.
Default
ES_USR_DFLT_IMS=IMSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ICONN1

Controls the client TCP connection status of an IMS Connect emulator.

IMSCPY

The location of copybook files for DBDGEN, PSBGEN and MFSGEN utilities.
Syntax
IMSCPY=path-name
Parameter
path-name
The full path to the location of compiled COBOL applications.

MF_SPLJNO_LOCK

Determines whether job number acquisition is enqueued to reduce file and disk access or handled with file locks to improve performance when running JCL jobs on multiple processes.
Syntax
MF_SPLJNO_LOCK=Y
Parameter
Y
Enqueue job number acquisition.
Default
Not set. Job number acquisition is handled with file locks, which can improve performance when running JCL jobs on multiple processes.
Comments
The parameter value is not case sensitive.

Setting MF_SPLJNO_LOCK to no value or any value other than Y or y results in the default behavior.

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.


Input, Output, and Display Environment Variables

Parent topic: Environment Variables by Groups

CCITCP2

Sets the TCP address of the machine running the MFDS (formerly CCITCP2) registration daemon.
Syntax
CCITCP2=host-name
Parameter
host-name
The TCP host name, IPv4 address, or IPv6 address of the machine running the MFDS daemon you want to contact from the session.
Default
Not set. The local system is used.
Comments
Use this environment variable to set the TCP address of the machine running the MFDS registration daemon, which holds the registration of the service you are contacting, or will hold the registration of the service you are starting.

CCITCP2_PORT

Sets the port used for the MFDS registration process.
Syntax
CCITCP2_PORT=port-number
Parameter
port-number
The number of the port on which the MFDS service is listening.
Default
Not set. Uses the port specified by the mfcobol service name in %WINDIR%\system32\drivers\etc\services . If not found there, uses the official Micro Focus directory port, which is 86.

CCITCPT_service-name

Specifies the host, and/or port for a client to use when connecting to a service.
Syntax
CCITCPT_serice-name=[unused], MFNODE:node-name, MFPORT:port-number
Parameters
service-name
The name of the CCI service to which the client is to connect.
unused
The parameter before the comma is not used with CCITCPT, but supported for consistency with CCITCPS.
node-name
The host name or IP address to connect.
port-number
The TCP port to connect.
Default
Not set. The client attempts to look the service up in the MFDS directory.
Comments
Use this environment variable to instruct a CCI client to connect directly to the specified host and port rather than querying MFDS for the location of the named service.
Example
CCITCPT_MYSERVICE=,MFNODE:localhst.MFPORT:3000

COBCONFIG

Specifies a run-time configuration file that tailors run-time configurable options in some way.
Syntax
COBCONFIG=path-name
Parameter
path-name
The directory that contains the COBOL configuration file, which tailors the run-time system.
Default
Not set. Enterprise Server searches for the file in $COBDIR/etc/cobconfig.
Example
COBCONFIG=C:\mydir\cobconfig

COBCONFIG.BLOCK

The location of the application configuration file.
Syntax
COBCONFIG.BLOCK=path
Parameter
path
The full path to the location of the application configuration file.
Default
Not set.

COBDIR

Specifies the directory where Enterprise Server is installed. Many system components and utilities require and use this information.
Syntax
COBDIR=path-name
Parameter
path-name
The directory that contains the required Micro Focus COBOL system software.
Default
Not set. The default path is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer /opt/microfocus/EnterpriseDeveloper .
Comments

The Micro Focus COBOL system is normally installed in the default COBOL system directory and so does not require COBDIR to be set. COBDIR only needs to be set when your COBOL system has been installed in a different directory such as when more than one version of the COBOL system is available at the same time.

Example

This example causes the compiler to search the directory C:\products\cobse20 for the Micro Focus COBOL system software:

COBDIR=C:\products\cobse20

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.
Syntax
COBKEYTIMEOUT=trans-time
Parameter
trans-time
A number in the range 1 through 126 that represents the maximum elapsed time required for a terminal to transmit any valid escape sequence to the run-time system over the line or network connection.
Default
Not set.
Comments
On encountering a lone Escape character, the run-time system waits n tenths of a second before assuming that the character does not introduce an escape sequence.

The run-time system calculates an appropriate default value for n from the baud rate of the terminal.

When a terminal key is depressed, the terminal might send in response a single character or a group of characters to the run-time system. Typically, such a group of characters starts with an escape character and the group of characters is known as an escape sequence. A terminal might send an escape sequence for one depression of a function key. It might also send the same sequence of characters for a depression of the Escape key followed by the depression of one or more alphabetic or numeric data keys. The only difference apparent to the run-time system is the interval between the arrival of each character? the user cannot type as fast as the escape sequence is generated by the terminal.

If a terminal is connected over a network that sends the characters to the run-time system in discrete packets, then the network can alter the intervals between each character arriving at the run-time system. COBKEYTIMEOUT is available to help compensate for typical network delays so the run-time system identifies escape sequences correctly.

COBLANG

Sets the language environment in which your COBOL program runs.
Syntax
COBLANG=LE-option
Parameter
LE-option
A COBOL language environment (LE) option.
Default
Not set.

COBLPFORM

Used to define and print to printer channels C01-C12.
Syntax
COBLPFORM line-number[[:line-number][...]]
Parameter
line-number
A single line number of a channel. Null entries are ignored. Those channels that have line number zero, function-names S01-S052, CSP, or are undefined, are set to line 1.
Default
Not set.
Comments
Any WRITE BEFORE/AFTER PAGE statements cause positioning to be at line 1. Each line advance increases the line number by one. A request to skip to a line number less than or equal to the current line causes a new page to begin. The appropriate number of line feeds are then generated.
Examples

In the following example, C01 equals 1, C02 equals 3, and so on:

COBLPFORM 1:3:5:7:9:11:13:15:17:19:21:23

In this next example, C01 equals 3, C02 equals 5, C03 equals 1, and C04 equals 9. C03 equals 1 because its value is a space and therefore undefined, and channels C05 - C12 are also undefined:

COBLPFORM :3::5: :9
Note: If a print statement specifies channel C05 - C12, the line is printed at line 1.

COBMAINSTACK

Specifies the size of the main stack.
Note: This variable applies to native COBOL applications on UNIX, and Enterprise Server on both Windows and UNIX.
Syntax
COBMAINSTACK=stack-size
Parameters
stack-size
The size of the main stack in bytes.
Default
Not set.
Comments
The main stack size defaults to three times the size of a threaded stack. The size of a threaded stack is either specified when the stack is created (using CBL_THREAD_CREATE), or it defaults to 160KB for a 32-bit application or 320KB for a 64-bit application.

You might need to set COBMAINSTACK in any of the following circumstances:

  • If you are deploying native OO COBOL Enterprise JavaBeans (EJBs) to WebSphere on the AIX platform.
  • If you are using the multi-threaded run-time system.
  • If you have IF STATEMENTS with a very large number of ELSE clauses.
  • If you have a large amount of local-storage data.

COBPATH

Specifies the directory or directories that the run-time system searches for dynamically loadable .int and .gnt files, or callable shared objects.
Syntax
COBPATH=path-name[;path[...]]
Parameter
path-name
The full or relative path to a directory for the run-time system to search for a dynamically loadable program (.int, .gnt or callable shared object) file.
Default
None. Dynamically set based on enterprise server region configuration.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

When more than one path-name is specified, a null path name represents the current working directory.

Example
COBPATH=C:\mydir\srclib;;\otherlib

COBPRFDIR

Location of .ipf files created by programs compiled with the PROFILE compiler directive.
Syntax
COBPRFDIR=path-name[[;path-name][...]]
Parameter
path-name
The full path of a directory to search.
Default
Not set. .ipf files are created in and expected to be in the current working directory.

COBSW

Specifies the run-time system switch settings for the run-time system to observe when running an application.
Syntax
COBSW={+|-}switch[...]
Parameters
+
Sets the switch.
-
Unsets the switch.
switch
A run-time switch. See Run-time Switches for details.
Default
COBSW=-A
Example
This example enables run-time switch 0 and the ANSI COBOL debug switch:
COBSW=+0+D

ES_CONSOLE_LOG (deprecated)

ES_CONSOLE_LOG (deprecated)
Sends console messages to the Windows Event Log.
Note: ES_CONSOLE_LOG is deprecated, and provided for backward compatibility only. We recommend that you use MFDS configuration options instead. For details, see the Windows Monitoring and Management section in the General Properties topic.
ES_CONSOLE_LOG={I|W|E|S}[...]
Parameters
I
Send informational messages to the Windows Event Log.
W
Send warning messages to the Windows Event Log.
E
Send error messages to the Windows Event Log.
S
Send severe messages to the Windows Event Log.
Default
Not set. No console messages are sent to the Windows Event log.

ES_CSKL_NO_MSG_CONSOLE

Stops the EZ Sockets CICS listener (CSKL) from writing messages to console.log.
Syntax
ES_CSKL_NO_MSG_CONSOLE=ON
Parameter
ON
CSKL does not write message to console.log.
Default
Not set. CSKL writes messages to console.log.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_ESMAC_DISP_MAX_OVERRIDE

Limits the number of lines shown when viewing an individual catalog entry in the ESMAC catalog view or when viewing a SYSOUT file from the job list view.
Syntax
ES_ESMAC_DISP_MAX_OVERRIDE=value
Parameter
value
An integer denoting the number of lines to display to a maximum of 99999.
Default
ES_ESMAC_DISP_MAX_OVERRIDE=1000
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_JES_SPOOL_ORDER

The order in which the spool list is displayed when you first open ESMAC.
Syntax
ES_JES_SPOOL_ORDER=1
Parameter
1
Displays the list in descending order by JOBID.
Default
Not set. Displays the list in ascending order by JOBID.

ES_LEGACY_ECI

Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG.
Syntax
ES_LEGACY_ECI=Y
Parameter
Y
Micro Focus ECI is used.
Default
Not set. IBM CTG is used.
Comments
Parameter value is not case sensitive.

ES_MAX_CATALOG_LINES

Restricts the number of entries displayed in ESMAC catalog view.
Syntax
ES_MAX_CATALOG_LINES=number
Parameter
number
The number of lines to display up to a maximum of 99999.
Default
ES_MAX_CATALOG_LINES=5000
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_MEM_STRATEGY

Selects the types of memory processes supported.
Comments
Memory strategy can also be set via the memory_strategy run-time tunable.

ES_OTMA_TIMEOUT

The time in seconds that an OTMA client should wait for an answer.
Syntax
ES_OTMA_TIMEOUT=wait-time
Parameter
wait-time
The number of seconds to wait. The maximum is 43199.
Default
ES_OTMA_TIMEOUT=120

(2 minutes)

ES_SEP_DORMANT_TIME

Allows override of Transient SEP dormant time. Rather than automatically terminating transient SEPs on completion of a stateful request, the server manager allows a period of inactivity before scheduling their termination. This allows new requests to re-use the SEP rather than starting a new instance. This environment variable allows you to control the period of inactivity.
Syntax
ES_SEP_DORMANT_TIME=wait-time
Parameter
wait-time
The number of seconds that the Transient SEP is inactive.
Default
ES_SEP_DORMANT_TIME=2
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_SERVER

The default server name used if no -r switch is specified on casstart or casstop.
Syntax
ES_SERVER=server-name
Parameter
server-name
The server name.
Defaults
32-bit
ES_SERVER=ESDEMO
64-bit
ES_SERVER=ESDEMO64

ES_SYSOUT_HOLD

Determines which SYSOUT files are sent to the Complete queue with an Out Hold status.
Syntax
ES_SYSOUT_HOLD={msg-class}[msg-class[...]]
Parameter
msg-class
A message class to send to the Complete queue with an Out Hold status.
Default
Not set. No specific message classes are sent to the Complete queue with an Out Hold status.
Example
Message classes A and B are sent to the Complete queue with an Out Hold status:
ES_SYSOUT_HOLD=AB

ES_TN3270_FORCE_ALT

Enables you to use a screen size other than the default when using a TN3270 terminal emulator.
Syntax
ES_TN2370_FORCE_ALT=ON
Parameter
ON
Enables alternative screen size.
Default
Not set. The default screen size is used.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

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.
Syntax
ES_TN3270_MODEL_LOG=Y
Parameter
Y
Model names are written to TSQ TN32MODL.
Default
Not set. Model names are not logged.

ES_USR_DFLT_CICS

Allows you to override the default user when no user is logged on for CICS authentication.
Syntax
ES_USR_DFLT_CICS=userid
Parameter
userid
An alternative default user name.
Default
ES_USR_DFLT_CICS=CICSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_ESMAC

Allows you to override the default user when no user is logged on for ESMAC authentication.
Syntax
ES_USR_DFLT_ESMAC=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_ESMAC=MFUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_JES

Allows you to override the default user when no user is logged on for JES authentication.
Syntax
ES_USR_DFLT_JES=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JES=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_ESM_DISABLE_DFLTUSER_ESMAC

Allows you to disable the default ESMAC user to increase the security of your server.
Syntax
ES_ESM_DISABLE_DFLTUSER_ESMAC=Y
Parameter
Y
Disables the default ESMAC user, disables the DEFAULT button on the logon screen, and forces users to always enter a valid user ID and password.
Default
Not set. The ESMAC user is enabled.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

IMSCPY

The location of copybook files for DBDGEN, PSBGEN and MFSGEN utilities.
Syntax
IMSCPY=path-name
Parameter
path-name
The full path to the location of compiled COBOL applications.

ISPPROF

The location of ISPF dialog profiles.

JAVA_HOME

Specifies the location of the JDK.
Syntax
JAVA_HOME=path-name
Parameter
path-name
The full path to the location of the JAVA_HOME location.

MAINFRAME_FLOATING_POINT

Specifies the format to use for floating point data items. Possible formats are IBM hexadecimal and IEEE.
Syntax
MAINFRAME_FLOATING_POINT={true|false}
Parameters
true
Use IBM hexadecimal-format floating-point data items.
false
Use IEEE-format floating-point data items.
Default
MAINFRAME_FLOATING_POINT=false
Comments
The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MF_AMODE31ONLY

Indicates that all programs are AMODE(31).

MF_CHARSET

Specifies the system character set.
Syntax
MF_CHARSET={{A|ASCII}|{E|EBCDIC}}
Parameters
A|ASCII
Use the ASCII character set.
E|EBCDIC
Use the EBCDIC character set.
Default
MF_CHARSET=A

MF_SPOOL_ARCHIVE_LOC

The base location for files archived as part of the spool housekeeping process, where the contents of the MVS SPOOL spool file are archived prior to deletion.
Syntax
MF_SPOOL_ARCHIVE_LOC=path-name
Parameter
path-name
The base location for files archived as part of the spool housekeeping process
Default
Not set.

MF_USESCA5

Specifies that the server should use version 5 of the Open Service Component Architecture (Open SCA).
Syntax
MF_USESCA5={ON|OFF}
Parameters
ON
The server uses version 5 of the Open SCA.
OFF
The server uses the default version of Open SCA.
Default
MF_USESCA5=ON

MF_USESCA7

Determines whether MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors.
Syntax
MF_USESCA7={ON|OFF}
Parameters
ON
Accepts CA7 Scheduler control statements as comments.
OFF
Diagnoses CA7 Scheduler control statements as errors.
Default
MF_USESCA7=ON

MFCODESET

Specifies which translation tables to use.
Syntax
MFCODESET=country-code
Parameter
country-code
The country code required for translation. See Supported Country Codes for a list of countries and codes.
Default
Not set. Uses the country code returned from the CBL_GET_OS_INFO routine.
Comments
If you are not using UK or US language settings, you must also set MFCODESET as a Windows system variable. See your Windows documentation for details.

MFCSCFG

Specifies a configuration file to be used by the Client/Server Binding client program.
Syntax
MFCSCFG=[path-name\]file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The name of the configuration file.
Default
MFCSCFG=mfclisrv.cfg
The default path-name is the current working directory, and if not found, the default settings for the configuration entries are used.
Comments
The value of MFCSCFG is overridden by any value defined in the command line.
Example
MFCSCFG=d:\mydir\mfclisrv.cfg

MFEXTMAP

Location of a mapper file.

MFLECONFIG

Specifies a configuration file for Language Environment (LE) run-time options.
Syntax
MFLECONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the ile containing the LE run-time options you want to use.
file-name
The name of the file containing the LE run-time options you want to use.
Default
Not set. No LE run-time options are used.

MFLOGDIR

Specifies a directory to be used by Client/Server Binding for log files.
Syntax
MFLOGDIR=path-name
Parameter
path-name
The full path to the location of log files.
Default
Not set.
Example
MFLOGDIR=d:\mydir\logs

MFLECONFIG

Specifies a configuration file for Language Environment (LE) run-time options.
Syntax
MFLECONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the ile containing the LE run-time options you want to use.
file-name
The name of the file containing the LE run-time options you want to use.
Default
Not set. No LE run-time options are used.

MFPRELOAD_USE

Calls MFPRELOAD to improve performance.

MFSUB

Specifies whether to use SUBI or ASUBI.
Syntax
MFSUB={SUBI|ASUBI}

MFSYSCATDIR

The location of the system catalog directory.

MFUSER

Enables you to change the user from the default User ID to an alternative ID.

MQSERVER

The names of one or more minimal channels.
Syntax
MQSERVER=channel-name/transport-type/{machine-name|ip-address(port-number)}
   [,{machine-name|ip-address}(port-number)][...]]
Parameters
channel-name
The name of a channel as defined on the server.
transport-type
The communications protocol, which can be any of the following:
  • TCP
  • LU62
  • NETBIOS
  • SPX
machine-name
The name of the server machine.
ip-address
The machine IP address.
port-number
The number of the port used.
Comments
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.

Examples
MQSERVER=CHANNEL3/TCP/QServer(1414)
MQSERVER=CHANNEL1/TCP/10.120.99.999(1414),10.120.98.888(1414)

MULTIMFENTMAP

Specifies whether special characters such as < and & are replaced with the equivalent HTML entities such as &lt; and &amp;.

OOSW

OO run-time switches.

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.
Syntax
TXMAPP=path-name
Parameter
path-name
The full path to the location of the BMS load module.

TXRDTP

The location of MSS resource definition (RDO) files.
Syntax
TXRDTP=path-name
Parameter
path-name
The full path to the MSS resource definition (RDO) files.


JCL Environment Variables

Lists environment variables related to configuring the JCL environment.
Parent topic: Environment Variables by Groups
Related reference
JOB Statement Extensions

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.
Syntax
CASSPOOL_LOCK_RETRY_COUNT=retry-count
Parameter
retry-count
The number of retries made to obtain a record lock.
Default
CASSPOOL_LOCK_RETRY_COUNT=20

DBG_MVSPSKEL

The skeleton JCL for debugging.

ES_ALLOC_EXPAND

Expands an environment variable when used to specify an allocation path, or overrides this behavior.
Syntax
ES_ALLOC_EXPAND={Y|N}
Parameters
Y
Expand the environment variable used to specify an allocation path.
N
Do not expand the variable used in the path.
Default
ES_ALLOC_EXPAND=Y

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.
Syntax
ES_ALLOC_OVERRIDE=path-name\rules-file
Parameters
path-name
The full path to the dataset rules file.
rules-file
The name of the dataset rules file.
Default
Not set.

ES_CAT_RETRY_COUNT

Determines the number of attempts made to open a catalog file that has produced an error when the initial attempt to open it was made.
Syntax
ES_CAT_RETRY_COUNT=attempt-count
Parameter
attempt-count
The number of attempts made to open a catalog file.
Default
ES_CAT_RETRY_COUNT=0
Comments
Use this variable in conjunction with the ES_CAT_RETRY_WAIT variable, which determines how long to wait in between each attempt.

Take care when setting these variables as they could impact the time taken to report an error and therefore will delay processing of a job whilst the checks take place. These variables can be useful if you experience file access problems (for example, network connection drop-outs) that only last a second or two, so that it gives the system a chance to recover, before aborting.

ES_CAT_RETRY_WAIT

Determines the amount of time (in seconds) to wait between attempts made to open a catalog file that has produced an error when the initial attempt to open it was made.
Syntax
ES_CAT_RETRY_WAIT=wait-time
Parameter
wait-time
The number of seconds to wait between attempts made to open a catalog file.
Default
ES_CAT_RETRY_WAIT=0
Comments
Use this variable in conjunction with the ES_CAT_RETRY_COUNT variable, which determines how many attempts to make to open a catalog file that initially failed to open.

Take care when setting these variables as they could impact the time taken to report an error and therefore will delay processing of a job whilst the checks take place. These variables can be useful if you experience file access problems (for example, network connection drop-outs) that only last a second or two, so that it gives the system a chance to recover, before aborting.

ES_CLUSTER

Identifies a region as participating in an Enterprise Server cluster.
Syntax
ES_CLUSTER=ON
Parameter
ON
Sets the region to participate in an Enterprise Server cluster.
Default
Not set. The enterprise server region does not participate in an Enterprise Server cluster.
Comments
Mandatory for all enterprise server regions in a cluster.

ES_CLUSTER_ISC_TRACE

Enables tracing on the Enterprise Server cluster ISC listeners.
Syntax
ES_CLUSTER_ISC_TRACE=ON
Parameter
ON
Tracing of ISC listeners for an Enterprise Server cluster is enabled.
Default
Not set. Enterprise Server cluster ISC listeners are not traced.

ES_CLUSTER_LISTENER_PORT_TO_USE

Sets a specific port for an Enterprise Server cluster listener.
Syntax
ES_CLUSTER_LISTENER_PORT_TO_USE=port-number
Parameter
port-number
The port number to assign to a cluster listener.
Default
Not set. The Enterprise Server cluster listener uses an ephemeral port.

ES_DSENQSHR

Enable and configure handling of the DSENQSHR keyword when it is specified on the JCL job card, and when it is not specified on the job card.
Syntax
ES_DSENQSHR={ALLOW|AUTO|DISALLOW}
Parameters
ALLOW
For JCL jobs that have the DSENQSHR keyword specified on the JCL job card, sets DSENQSHR to the value specified on the job card. For jobs that do not have the DSENQSHR keyword specified on the JCL job card, sets DSENQSHR=ALLOW for each of those jobs.
AUTO
Use the value specified on the JCL Job card, which sets ES_DSENQSHR to ALLOW when that value is either ALLOW or USEJC, and DISALLOW otherwise.
DISALLOW
For jobs that do not have the DSENQSHR keyword specified on the JCL job card, sets DSENQSHR=DISALLOW for each of those jobs.
Default

When the job card does not specify the DSHQSHR keyword or when the job card sets DSENQSHR to USEJC:

ES_CAT_RETRY_WAIT=ES_DSENQSHR=DISALLOW

When the job card specifies the DSENQSHR keyword, the value of DSENQSHR is used.

Comments
When DSENQSHR is allowed on a job, exclusive dataset locks are downgraded to SHARED after performing the last step that requires an exclusive lock.

Exclusive locks resulting from a dynamic exclusive enque (for example an IDCAMS DELETE operation) are maintained as exclusive until the end of the job regardless of the DSENQSHR setting.

Use VSAM Share options with VSAM datasets. You can enable these by setting the ES_SHAREOPT environment variable to Y.

ES_ELAPSED_DISPATCH_SECONDS

Specifies how frequently casmgr checks for Jobs in the waiting state and then starts them.
Syntax
ES_ELAPSED_DISPATCH_SECONDS=wait-time
Parameter
wait-time
The number of seconds that casmgr waits before checking for Jobs in the waiting state and then starting them.
Default
ES_ELAPSED_DISPATCH_SECONDS=5

ES_EMP_EXIT_n

ES_EMP_EXIT_n
Specifies the number of Event Manager user exits for the region.
ES_EMP_EXIT_n=batch-component
Parameters
n
A single digit ranging from 1 through 9, depending on the number of Event Manager user exits for the region.
Note: This must be set to 1 when mfbsiemx is the only Event Manager user exit for the region.
batch-component
An event manager component.
Default
Not set.
Comments
You must set ES_EMP_EXIT once for each Event Manager used in the region.

When setting ES_EMP_EXIT multiple times, they must be set in numerical order.

Example
ES_EMP_EXIT_1=mfbsiemx
ES_EMP_EXIT_2=mfmonemx
ES_EMP_EXIT_3=...

ES_GLM

If this variable is set, it identifies the region as an Enterprise Server cluster Global Lock Manager (GLM).
Syntax
ES_GLM=ON
Parameter
ON
Identify the region as a GLM.
Default
Not set. The region is not identified as a GLM.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

ES_GLM_TIMEOUT

Sets the amount of time that can pass while a submit request to an Enterprise Server cluster Global Lock Manager (GLM) is retried and before permanently disabling the connection.
Syntax
ES_GLM_TIMEOUT=number
Parameter
number
The number of seconds during which a retry is attempted and before disabling the connection.
Default
ES_GLM_TIMEOUT=120
Comments
This variable only applies to the region within an Enterprise Server cluster designated as the GLM.

ES_HARD_KILL_PROCESS

Enables you to modify how Enterprise Server kills a process.
Syntax
ES_HARD_KILL_PROCESS={Y|N}
Parameters
Y
Issue a hard kill after a soft kill when the soft kill fails.
N
No hard kill is attempted after the soft kill.
Default
ES_HARD_KILL_PROCESS=Y
Comments
This variable only applies to the region within an Enterprise Server cluster designated as the Global Lock Manager (GLM).

ES_HOSTNAME_TO_USE

In an Enterprise Server Cluster, if a machine uses more than one network card, you might need to set this variable to identify the host MFCS should use.
Syntax
ES_HOSTNAME_TO_USE=host-name
Parameter
host-name
The host name that matches the network card you want to use.
Default
Not set. MFCS uses the local host.

ES_JES_BYTES

Maximum number of bytes to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_BYTES=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of bytes in thousands. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of bytes is reached.
CANCEL
Cancel the job when the specified maximum number of bytes is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of bytes is reached.
Default
Not set.
Example
In this example, each line is assumed to hold 132 bytes; therefore the job is automatically cancelled at 100000/132 lines, and the memory contents are dumped:
ES_JES_BYTES=(100,DUMP)

ES_JES_CARDS

Maximum number of cards to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_CARDS=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of cards. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of cards is reached.
CANCEL
Cancel the job when the specified maximum number of cards is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of cards is reached.
Default
Not set.
Example
In this example, each card is assumed to hold 25 lines; therefore at 750 lines (25×30) a warning message is issued the job continues.
ES_JES_CARDS=(30,WARNING)

ES_JES_CONSOLE_MESSAGES

Determines whether to lodge CASMG0001I messages in the splmsg.dat list for a job.
Syntax
ES_JES_CONSOLE_MESSAGES={Y|N}
Parameters
Y
Lodges CASMG0001I messages in the splmsg.dat list for a job.
N
Does not lodge CASMG0001I messages in the splmsg.dat list for a job.
Default
ES_JES_CONSOLE_MESSAGES=Y
Comments
CASMG0001I messages are produced when a program running in a JCL job does 'display upon console'. These messages, along with others, are lodged in the splmsg.dat file. When the job information is displayed in ESCWA/ESMAC, these messages are also shown.

There is a limit of 65535 messages per job. If that limit is exceeded, the last messages sent will overwrite the last message already lodged in splmsg.dat.

There is a way to work around this, if your program outputs a lot of messages. You can set ES_JES_CONSOLE_MESSAGES=N in order to avoid storing the messages in splmsg.dat. Whatever this setting, the CASMG0001I messages will still be included in the JESYSMSG for the job.

There is also a Job statement extension so that this can be configured on a job by job basis - see the line below. See JOB Statement Extensions for more details.

//*MFE:%CONSOLE_MSGS=Y|N

ES_JES_DELAY_MEM_ENQ

Determines whether to delays the exclusive enque of a new (not previously existing) PDS member until the file is opened.
Syntax
ES_JES_DELAY_MEM_ENQ={Y|N}
Parameters
Y
Delay the exclusive enque of a new (not previously existing) PDS member until the file is opened.
N
Do not delay the exclusive enque of a new (not previously existing) PDS member until the file is opened.
Default
ES_JES_DELAY_MEM_ENQ=N
Comments
PDS members are given an exclusive enque at step start.

When used with existing PDS members, the program abends with code S213 when it attempts to access a file and cannot get the exclusive enque.

ES_JES_DISABLE_RESTART_FLUSH

Indicates whether jobs in a specific enterprise server region are moved from the Active queue to the Complete queue when the region is restarted.
Syntax
ES_JES_DISABLE_RESTART_FLUSH={Y|N}
Parameters
Y
Move jobs in the region from the Active queue to the Complete queue when the region is restarted.
N
Do not move jobs in the region from the Active queue to the Complete queue when the region is restarted.
Default
ES_JES_DISABLE_RESTART_FLUSH=N

ES_JES_ENFORCE_EXPIRE_DATE

Determines whether or not to check the expiration date when deleting a catalogued dataset, and if expired, delete the dataset.

Syntax
ES_JES_ENFORCE_EXPIRE_DATE={Y|N}
Parameters
Y
Check the expiry date and delete expired datasets.
N
Do not check the expiration date.
Default
ES_JES_ENFORCE_EXPIRE_DATE=Y
Comments
Use the PURGE keyword to delete non-expired datasets.

ES_JES_FREE_SSTM_SYSOUT

Determines whether to free the memory assigned to store details about each CICS spool file that you create using the CICS Spool Write APIs, once the spool file has been created.
Syntax
ES_JES_FREE_SSTM_SYSOUT={Y|N}
Parameters
Y
Free the memory assigned to store details about each CICS spool file.
N
Do not free the memory assigned to store details about each CICS spool file.
Default
ES_JES_FREE_SSTM_SYSOUT=N
Comments

Setting ES_JES_FREE_SSTM_SYSOUT=Y helps to avoid problems with receiving out of memory errors when creating multiple new files.

CAUTION:
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.

ES_JES_HIGHER_SECURITY_LEVEL

Determines which programs are loaded based on checks made against the list of SYS1.LNKLIB entries.
Syntax
ES_JES_HIGHER_SECURITY_LEVEL={0|[1|NONE][2|BASIC][3|WARN][4|ENHANCED]}
Parameters
0
The behavior is unchanged with regard to JES enhanced security.
1|NONE
A value of 1 or NONE is the equivalent of not setting the value and maintains the behaviour of earlier versions of Enterprise Test Server. With a setting of 1 or no setting at all, warning messages about the number of SYS1.LNKLIB entries might be issued if none have been defined (JES000067W) and messages about programs not being loaded from certain locations (JES000069W) are also given. In addition, messages JCLCM0260W and JCLCM0308W might also be issued.
2|BASIC
A level of BASIC or 2 causes programs to be loaded from the list of SYS1.LNKLIB entries, STEPLIB, and JOBLIB locations. Programs in other locations are not loaded. The loading of programs from dynamic PDSs is also entirely disabled.
3|WARN
A level of WARN or 3 causes checks to be made against the PROGRAM and the PHYSFILE security classes. The PHYSFILE check is to make sure the PHYSFILE resource class is implemented. If these checks fail, a warning message (JCLCM0262W, JCLCM0263W or JCLCM0266W) is issued.
4|ENHANCED
A level of ENHANCED or 4 will cause the same PROGRAM and PHYSFILE checks to be made but if they fail then the job will abend with an S913 security error and a suitable message will be issued to indicate the failure.
Default
ES_JES_HIGHER_SECURITY_LEVEL=1

ES_JES_LINES

Maximum number of lines to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_LINES=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of lines in thousands. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of lines is reached.
CANCEL
Cancel the job when the specified maximum number of lines is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of lines is reached.
Default
Not set.
Example
In the following example, each card is assumed to hold 25 lines; therefore at 750 lines (25×30) a warning message is issued and the job continues. Limit the number of lines output to 100000. When this limit is reached, cancel the job. This produces an S722 Output limit exceeded system abend code:
ES_JES_LINES=(100,CANCEL)

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.
Syntax
ES_JES_OUTLIM=(max-lines[,{WARNING|CANCEL|DUMP}])
Parameters
max-lines
Maximum number of lines of output before taking action. The range is from 1-16777215.
WARNING
Issue a warning when the specified maximum number of lines of output is reached.
CANCEL
Cancel the job when the specified maximum number of lines of output is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of lines of output is reached.
Default
Not set.
Example
A warning is issued when 5000 lines of output is exceeded:
ES_JES_OUTLIM=5000

The job is canceled when 1000 lines of output are reached.

ES_JES_OUTLIM=(1000,CANCEL)
Comments
Individual OUTLIM values can be set on each SYSOUT dataset. For example:
//SYSPRINT DD SYSOUT=*,OUTLIM=500

ES_JES_PAGES

Maximum number of pages to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_PAGES=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of pages. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of pages is reached.
CANCEL
Cancel the job when the specified maximum number of pages is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of pages is reached.
Default
Not set. No limit to the number of pages output.
Example
In this example, each page is assumed to hold 60 lines; therefore when 600 lines (60×10) have been processed, a warning is issued and the job continues:
ES_JES_PAGES=10

ES_JES_PARM_INIT_LOW

Determines whether the parameter string passed to a program executed by JCL is initialized to low-values or to spaces.
Syntax
ES_JES_PARM_INIT_LOW={Y|N}
Parameters
Y
Initialize the parameter string to low-values.
N
Initialize the parameter string to spaces.
Default
ES_JES_PARM_INIT_LOW=N

ES_JES_RESTART

Determines whether JCL restart processing is enabled.
Syntax
ES_JES_RESTART={Y|N}
Parameters
Y
Enables JCL restart processing.
N
Disables JCL restart processing.
Default
ES_JES_RESTART=N

ES_JES_SORT_SPOOL_BY

Specifies which column is initially used to sort the spool records in casrdo41.
Syntax
ES_JES_SORT_SPOOL_BY={JOBNAME|SUBDATE|JOBUSER}
Parameters
JOBNAME
Sort by job name.
SUBDATE
Sort by sub date.
JOBUSER
Sort by job user.
Default
Not set.

ES_JES_SPOOL_ORDER

The order in which the spool list is displayed when you first open ESMAC.
Syntax
ES_JES_SPOOL_ORDER=1
Parameter
1
Displays the list in descending order by JOBID.
Default
Not set. Displays the list in ascending order by JOBID.

ES_JESYSMSG_OUTPUT

The status of the system messages spool files (JESYSMSG) is set to Output, rather than Out Hold.
Syntax
ES_JESYSMSG_OUTPUT={Y|N}
Parameters
Y
All job messages will have the status as Output, 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.
N
Messages are set to Out Hold.
Default
ES_JESYSMSG_OUTPUT=N

ES_JESYSMSG_RESTRICTED

Holds back spool files based on their class when the status of the system message spool files are set to Output.
Syntax
ES_JESYSMSG_RESTRICTED={class-name|class-number}[class-name|class-number][...]]
Parameters
class-name
The name of a class.
number
A number representing the class.
Default
Not set.
Example
The following:
ES_JESYSMSG_RESTRICTED=ABC123

Specifies classes A, B, C, 1, 2, and 3.

Comments
All job messages have an Output status, but print either physically or logically only when the MSGCLASS of the job matches one of the sysout classes defined to an active printer.

ES_OLD_DYN_PDS

Determines the resulting behavior of dynamic PDS members when specified in a JCL DD statement.
Syntax
ES_OLD_DYN_PDS={Y|N}
Parameters
Y
Enables previous default behavior of cataloging and creating the physical files for dynamic PDS when referenced in a JCL DD statement.
N
Physical files for dynamic PDS members are only created and cataloged when created using the JCL utility or by a user program.
Default
ES_OLD_DYN_PDS=N

ES_OPEN_CAT_ON_DEMAND

Determines if additional catalogs (as specified using MFUSERCAT_NODE) are opened when the system starts, or only opened when required.
Syntax
ES_OPEN_CAT_ON_DEMAND={Y|N}
Parameters
Y
When the enterprise server region starts, no attempt is made to open the catalogs specified in MFUSERCAT_NODE. Only the system catalog is opened initially, and the other nodes are opened when required.
N
When the enterprise server region starts, all nodes are opened.
Default
ES_OPEN_CAT_ON_DEMAND=N
Comments
When ES_OPEN_CAT_ON_DEMAND=N is set and there is a problem opening any of the nodes specified in MFUSERCAT_NODE, the JES system will not start.

ES_OLD_DYN_PDS

Determines the resulting behavior of dynamic PDS members when specified in a JCL DD statement.
Syntax
ES_OLD_DYN_PDS={Y|N}
Parameters
Y
Enables previous default behavior of cataloging and creating the physical files for dynamic PDS when referenced in a JCL DD statement.
N
Physical files for dynamic PDS members are only created and cataloged when created using the JCL utility or by a user program.
Default
ES_OLD_DYN_PDS=N

ES_PROG_PATH

Determines whether to display the program's load path in the JESYSMSG and SYSLOG datasets.
Note: Applies to native enterprise server regions only.
Syntax
ES_PROG_PATH={Y|N}
Parameters
Y
Display the program's load path in the JESYSMSG and SYSLOG datasets.
N
Do not display the program's load path in the JESYSMSG and SYSLOG datasets.
Default
Not set.

ES_SAM_ESDS

Under VSE and when opening the OUTPUT of a reusable ESDS file, determines whether the file is reset when the DISP is not specified in the DLBL statement.
Syntax
ES_SAM_ESDS={Y|N}
Parameters
Y
File is reset.
N
File is not reset.
Default
Not set.

ES_SSTM_CICS

Location of the JCL used to initialize the SSTM CICS environment.
Syntax
ES_SSTM_CICS=file-location
Parameter
file-location
The full path to the location of the SSTMCICS.JCL file used to initialize the SSTM CICS environment.
Default
Not set.

ES_SSTM_IMS

Location of the JCL used to initialize the SSTM IMS environment.
Syntax
ES_SSTM_IMS=file-location
Parameter
file-location
The full path to the location of the JCL used to initialize the SSTM IMS environment.
Default
Not set.

ES_SSTM_JOB_FLUSH_ACTIVE

Determines whether a CICS SSTM job is removed from the Active queue when the region shuts down.
Syntax
ES_SSTM_JOB_FLUSH_ACTIVE ={Y|N}
Parameters
Y
Remove the CICS SSTM job from the Active queue.
N
Do not remove the CICS SSTM job from the Active queue.
Default
ES_SSTM_JOB_FLUSH_ACTIVE=N

ES_SYSOUT_HOLD

Determines which SYSOUT files are sent to the Complete queue with an Out Hold status.
Syntax
ES_SYSOUT_HOLD={msg-class}[msg-class[...]]
Parameter
msg-class
A message class to send to the Complete queue with an Out Hold status.
Default
Not set. No specific message classes are sent to the Complete queue with an Out Hold status.
Example
Message classes A and B are sent to the Complete queue with an Out Hold status:
ES_SYSOUT_HOLD=AB

ES_USR_DFLT_JES

Allows you to override the default user when no user is logged on for JES authentication.
Syntax
ES_USR_DFLT_JES=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JES=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

GDG_RESTART_UCC11_ONLY

Determines when GDG restart information should be written.
Syntax
GDG_RESTART_UCC11_ONLY={Y|N}
Parameters
Y
GDG restart information is written, but only when ES_JES_RESTART=Y and MF_UCC11 is set (Y, YA, or M).
N
GDG restart information is written even if MF_UCC11=N or is not set. (ES_JES_RESTART=Y must still be set.)
Default
GDG_RESTART_UCC11_ONLY=Y

HOST_DISP

Determines whether JCL DISP is honored for DELETE on mainframe resident datasets.
Syntax
HOST_DISP={ON|OFF}
Parameters
ON
JCL DISP is honored for DELETE.
OFF
JCL DISP is not honored for DELETE.
Default
HOST_DISP=OFF

HOST_NEW

Determines whether JCL looks on the host for new datasets that are not cataloged locally.
Syntax
HOST_NEW={ON|OFF}
Parameters
ON
JCL looks on the host for new datasets not cataloged locally.
OFF
JCL does not look on the host for new datasets not cataloged locally.
Default
HOST_DISP=OFF

JCLTEMP_DIR

Enables you to specify a separate location for the JCLTEMP directory.
Syntax
JCLTEMP_DIR=path
Parameter
path
The full or relative path to the location of your JCLTEMP directory.
Default
Not set. Uses the directory specified by MFBSI_DIR.

JES_PRINT_SPOOL_MSG

Specifies the disposition of the spool data set printing message (JES000029I).
Syntax
JES_PRINT_SPOOL_MSG={CONSOLE|LOG|SILENT}
Parameters
CONSOLE
Send spool data to the console.log file.
LOG
Send spool data to 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 the spool files, and a new file is created every day.
SILENT
No messages. Use this option with caution, as it specifies that no audit log of your spool data sets is created.
Default
JES_PRINT_SPOOL_MSG=CONSOLE
Comments
This environment variable is intended for high-print-load users, meaning that a high number of print requests are sent to the console. This could affect system performance.

MF_ALIAS

Specifies program aliases.
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]
Parameters
program-name1...10
An eight-character program name.
Important: A program name shorter than eight characters must have trailing spaces extending its length to eight characters.
alias1...10
An eight-character alias.
Important: An alias shorter than eight characters must have trailing spaces extending its length to eight characters.
Default
Not set.
Comments
Each program-name/alias pair is 16 characters long — eight characters for the program-name, and eight characters for the alias. You can specify up to 10 pairs.

program-name/alias pairs are searched first in the order in which they appear and thus can potentially override the built-in list. If not found, the built-in alias table is searched.

Example
MF_ALIAS=IKJEFT1BIDAEFT01MYPROG  THEIRPRG
Adds:
Program-name | Alias
IKJEFT1B | IDAEFT01
MYPROG | THEIRPRG

MF_CHARSET

Specifies the system character set.
Syntax
MF_CHARSET={{A|ASCII}|{E|EBCDIC}}
Parameters
A|ASCII
Use the ASCII character set.
E|EBCDIC
Use the EBCDIC character set.
Default
MF_CHARSET=A

MF_DUPJOBS

Specifies whether jobs with duplicate names are allowed to run in parallel.
Syntax
MF_DUPJOBS={Y|N}
Parameters
Y
Jobs with duplicate names are allowed to run in parallel.
N
Jobs with duplicate names are not allowed to run in parallel.
Default
MF_DUPJOBS=N

MF_FALLTHRUCHECK

Specifies whether MSS is to check that the main COBOL program ends by executing a GOBACK or STOP RUN.
Syntax
MF_FALLTHRUCHECK={Y|N}
Parameters
Y
Check that the main COBOL program ends by executing a GOBACK or STOP RUN.
N
Do not check that the main COBOL program ends by executing a GOBACK or STOP RUN.
Default
MF_FALLTHRUCHECK=Y
Comments
If MF_FALLTHRUCHECK is set to Y and the check fails, MSS issues this message:
JCLCM0213S Main pgm xxxxxxxx did not issue GOBACK or STOP RUN.

MF_IKJEFT_KEEP_MAX

Determines whether IKJEFT01 uses the last return code from a command or the highest return code of all commands executed as the step COND CODE.
Syntax
MF_IKJEFT_KEEP_MAX={Y|N}
Parameters
Y
IKJEFT01 uses the highest return code of all commands executed as the step COND CODE.
N
IKJEFT01 uses the last return code from a command as the step COND CODE.
Default
MF_IKJEFT_KEEP_MAX=N

MF_JCL_AUDIT

Specifies that audit information is written to the audit log when a catalog entry is deleted.
Syntax
MF_JCL_AUDIT={DLET|DLEJ|DLET,DLEJ}
Parameters
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.
Default
Not set.
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

The following is an example of the audit event passed to SYSLOG:

mf.jcl 35500 5:5 [timeQuality tzKnown="1" isSynced="0"][origin ip="127.0.0.1" enterpriseID="********.5043"
software="Micro Focus Auditing" swVersion="API ver 1.2.2 syslog ver 1.0.0"][meta
sequenceId="88"][MFAuditPropertyList@5043 SYSTEM="AUDIT   "] userid=SYSAD    groupid=SYSADM
  jobnum=0000000 jobname=ESMAC    dsname=MFI01.ANF.TEST1
     member=         api=MVSCATIO apifunc=DLET

MF_JES_ABEND_CAF_COMMIT

Specify the outcome when a non-zero return code is received from the commit at the end of a DSNAL or IKJEFT** unit of work.
Syntax
MF_JES_ABEND_CAF_COMMIT={Yes|No|return-code}
Parameters
Yes
Generates an S482 abend.
No
Does not generate an abend.
return-code
A numeric value up to three digits to be used as the return code.
Default
MF_JES_ABEND_CAF_COMMIT=Yes

MF_JESPWR_EXIT

Passes JES2 and VSE PWR statements to the MFJESPWR user exit.
Syntax
MF_JESPWR_EXIT=Y
Parameter
Y
Pass JES2 and VSE PWR statements to the MFJESPWR user exit.
Default
Not set.
Comments
When set, the JCL execution engine calls the MFJESPWR exit program 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_LEX_API

Specifies whether the JES configuration uses single or multiple LEX files, and enables JES configuration to specify subdirectories for LEX files as necessary.
Syntax
MF_LEX_API={1|2|D}|1D|2D|D
Parameters
1
Use multiple LEX files.
2
Use a single LEX file. Disk-based access only.
D
Use directories to store LEX files.
Default
MF_LEX_API=1
Comments
Do mix these settings in a Region/PAC. They must be consistent for all.
Example
This example sets the JES configuration to use a single LEX file stored in directories.
MF_LEX_API=2D

MF_MFA

Specifies what data set catalogs are to be searched.
Syntax
MF_MFA={ALL|RJSE}
Parameters
ALL
Search for data sets first in the local catalog, and if not found, on the mainframe.
RJSE
Search for data sets in the local catalog only. No mainframe search is performed.
Default
MF_MFA= ALL

MF_SPLJNO_LOCK

Determines whether job number acquisition is enqueued to reduce file and disk access or handled with file locks to improve performance when running JCL jobs on multiple processes.
Syntax
MF_SPLJNO_LOCK=Y
Parameter
Y
Enqueue job number acquisition.
Default
Not set. Job number acquisition is handled with file locks, which can improve performance when running JCL jobs on multiple processes.
Comments
The parameter value is not case sensitive.

Setting MF_SPLJNO_LOCK to no value or any value other than Y or y results in the default behavior.

MF_MVSJOB

Sets the number at which a job starts and finishes.
Syntax
MF_MVSJOB=lower-value{-|+}upper-value
Parameters
lower-value
Number at which a job starts. Contains seven digits - for example, 0000001.
+
Reset the values to these new ones each time the region is started.
-
Sets the values but only on the first startup of the region.
upper-value
Upper job number. Contains seven digits - for example, 9999999.
Default
MF_MVSJOB=0001000+0099999
Comments

This environment variable can be used to enable a seven-digit Job number limit. If the upper-value is greater than 99999, then 6+ digit job number support is enabled. The maximum value that can be set is 9999999.

Tip: To revert to five-digit job number support, set:
 MF_MVSJOB=lower-limit+upper-limit

Where upper-limit is less than 0099999, and ensuring that the + sign is used to separate the low and high values.

Example
Resets the values to start with job number 10 and run through to job number 100:
MF_MVSJOB=0000010+0000100

When the upper limit has been reached, you receive a message:

All job numbers in the range 0000010:0000100 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_MVSP0034_LIMIT

Specifies the number of records in each exported catalog XML document.
Syntax
MF_MVSP0034_LIMIT=limit
Parameter
limit
A one- to six-digit number between 1 and 999999.
Default
Not set. All records are written to the catalog export XML file

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.
Default
MF_NODD=A

MF_PCRENAME_LAX

Determines whether physical files in other locations can be renamed if the cataloged name is changed.
Syntax
MF_PCRENAME_LAX={Y|N|D}
Parameters
Y
Enables physical files in other locations to be renamed if the cataloged name is changed.
N
When an MVS dataset is renamed, the associated physical file is normally renamed only if it is stored in a subdirectory of the of the catalog file location.
D
Creates a new directory structure and filename, and moves the existing file to the new location.
Properties
MF_PCRENAME_LAX=N

MF_RCCF

Determines whether to enable or disable Job Step Execution (RJSE).
Syntax
MF_RCCF={DELETEJOB|KEEPJOB}
Parameters
DELETEJOB
Disables RJSE.
KEEPJOB
Enables RJSE.
Default
MF_RCCF=DELETEJOB

MF_SMS

Enables support for IBM Storage Management Subsystem (SMS) data classes.
Syntax
MF_SMS={ON|OFF}
Parameters
ON
Turns on support for SMS data classes.
OFF
Turns off support for SMS data classes.
Default
MF_SMS=OFF
Comments
MSS provides emulation for SMS data classes only.

To enable DATACLAS support this variable needs to be ON in addition to setting MFUSERCAT_NODE=SYSMFE1.

MF_SPOOL_ARCHIVE_LOC

The base location for files archived as part of the spool housekeeping process, where the contents of the MVS SPOOL spool file are archived prior to deletion.
Syntax
MF_SPOOL_ARCHIVE_LOC=path-name
Parameter
path-name
The base location for files archived as part of the spool housekeeping process
Default
Not set.

MF_SPOOL_HK_LEX_SCAN

Determines if the MFELX* files associated with a job are also deleted when spool housekeeping is run.
Syntax
MF_SPOOL_HK_LEX_SCAN={Y|N}
Parameters
Y
The files are deleted.
N
The files are not deleted.
Default
MF_SPOOL_HK_LEX_SCAN=Y

MF_SPOOL_HK_TESTDATE

Overrides the normal date for the spool housekeeping.
Syntax
MF_SPOOL_HK_TESTDATE=YYYYMMDD
Parameters
The following are used to represent the date used to override the normal date
YYYY
Four-digit year.
MM
Two-digit month.
DD
Two-digit day.
Default
Not set. Uses the normal date for the spool housekeeping.

MF_SPOOL_HK_WRITE_PROFILES

Determines the creation of profile files (.PRO files) when a data set is archived.
Syntax
MF_SPOOL_HK_WRITE_PROFILES={Y|N}
Parameters
Y
Profile files are created.
N
Profile files are not created.
Default
MF_SPOOL_HK_WRITE_PROFILES=Y

MF_UCC11

Configures emulation of UCC11, which is the JCL job restart functionality.
Syntax
MF_UCC11={Y|YA|M|MA|MR|N}
Parameters
Y
When restarting a job with DISP=(NEW,CATLG), it will not result in job failure caused by the data set already being cataloged.
YA
When running a job with DISP=(NEW,CATLG), it will not result in job failure caused by the data set already being cataloged.
M, MA, MR
When restarting a job any data set that has an inital disposition of NEW is changed to MOD. Therefore, data will be appended to the data set if it already exists.
N
MF_UCC11 is not set so a data set with an initial disposition of NEW might cause an error when restarting the job if the data set already exists.
Default
MF_UCC11=N
Comments

This environment variable works independently of the JCL RESTART parameter.

The setting of the MF_UCC11 value can be made on a job-by-job basis using either the JCL user exit, MFJUXIT, or the Advanced Restart Functionality.

When set to Y or YA, if the job uses GDG data sets, the GDG generation is reset to the level used in the previous job, ensuring that the restart will automatically pick up the correct GDG generation.

GDG Restart information is usually only written when MF_UCC11=Y, YA or M and ES_JES_RESTART=Y. You can ensure that it is always written by setting ES_JES_RESTART=Y and GDG_RESTART_UCC11_ONLY=N - this will ensure that the restart information is available if a job is restarted at a later date.

When restarting a job with restart functionality enabled (that is, values Y, YA, or M), 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 set to YA or M and the disposition of the data set is DISP=NEW, if the DSORG of the data set is defined on the DD Card, it will be checked against the catalog record, if the latter exists. If there is a mismatch, or if the catalog record refers to a GDG base, the data set will not be replaced, and the JCLCM0200S error message is issued.

MF_UCC11_DYNCLEAN

When MF_UCC11 is enabled, controls whether dynamically allocated datasets (such as using SVC99) are cleaned when a job is restarted.
Syntax
MF_UCC11_DYNCLEAN={Y|N}
Parameters
Y
When a job is restarted, any dynamically allocated datasets are removed and replaced.
N
Prevents the cleaning of dynamically allocated datasets when restarting a job.
Default
MF_UCC11_DYNCLEAN=Y
Comments
Depandancies are valid only when MF_UCC11=Y or YA.

MF_USESCA7

Determines whether MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors.
Syntax
MF_USESCA7={ON|OFF}
Parameters
ON
Accepts CA7 Scheduler control statements as comments.
OFF
Diagnoses CA7 Scheduler control statements as errors.
Default
MF_USESCA7=ON

MFALLOC_DEF_VB_PCFILE

Determines whether a new PS VB file is defined in the catalog.
Syntax
MFALLOC_DEF_VB_PCFILE={Y|N}
Parameters
Y
A new PS VB file is defined in the catalog as a VB file with default settings of minimum length = 0, and maximum length = 32760.
N
Do not create a new PS VB file.
Default
MFALLOC_DEF_VB_PCFILE=Y
Comments
Valid only when the LRECL mfims imsdbu directive is not set or is set to 0 (zero).

MFALLOC_LOC

The default allocated dataset location.
Syntax
MFALLOC_LOC={path-name|SQL-URL}
Parameters
path-name
The full path to the dataset location.
SQL-URL
For a database-hosted dataset, the SQL URL to that location.
Default
Not set.
Example
Set the default allocated dataset to the sql://localhost/JCLTEST?folder=/JCLDEMO/data location:
MFALLOC_LOC=sql://localhost/JCLTEST?folder=/JCLDEMO/data

MFALLOC_PCFILE

Determines whether a catalogued file is created when DSORG=PS is provided in the DCB parameters.
Syntax
MFALLOC_PCFILE={Y|N}
Parameters
Y
A catalogued file is created when DSORG=PS is provided in the DCB parameters.
N
A catalogued file is not created.
Default
MFALLOC_PCFILE=Y
Comments
Valid only when DSORG=PS is provided in the DCB parameters.

MFBSI_DIR

Identifies the directory used by MFBSI to store MFBSIJCL log files, any semaphore files (JOBnnnnn.sem), and substituted JCL members.
Syntax
MFBSI_DIR=path-name
Parameter
path-name
The full path to the directory where MFBSI stores files.
Default
Not set.
Comments
For complete information about using MFBSI_DIR to configure your enterprise server region, see Configuring the Server.

MFCATMNTUE

Specifies the name of the MFCATMNT user exit program if not compiled to the default name of MFCATMNTUE.
Syntax
MFCATMNTUE=program-name
Parameter
program-name
Represents the name of the MFCATMNT user exit program if not compiled to the default name of MFCATMNTUE.
Default
Not set. User exit program is compiled using the default name of MFCATMNTUE.

MFJ_ALL_STEP_CHECK

Use this variable to prevent any steps after a restart step that have conditions that refer to any steps prior to the restart from running.
Syntax
MFJ_ALL_STEP_CHECK={Y|N}
Parameters
Y
Do not run any steps after a restart step that have conditions that refer to any steps prior to the restart.
N
Run the steps listed after a restart step that have conditions that refer to steps prior to the restart.
Default
MFJ_ALL_STEP_CHECK=N
Comments
The default behavior of this product is to not check COND CODES from steps prior to a restart step. This means that the steps after the restart step that have conditions that refer to any steps prior to the restart step might run. This is a change of behavior from releases 4.0 Patch Update 1 and earlier when these steps would have not run. Micro Focus recommends that you review and test the behavior before restarting the jobs.

Set this variable to Y to prevent steps after a restart step that have conditions that refer to any steps prior to the restart from running.

The setting of MFJ_ALL_STEP_CHECK is bypassed if the Abend and Cond Code Recover option of the Advanced Restart Functionality is used.

MFJ_INPUTDS_ERROR

Determines whether IEBDG, IEBGENER, IEBCOMPR, and DFSORT, and ICETOOL emulation treat missing input files as though they were present but empty.
Syntax
MFJ_INPUTDS_ERROR={Y|N}
Parameters
Y
Treats missing input files as missing.
N
Causes IEBDG, IEBGENER, IEBCOMPR, and DFSORT, and ICETOOL emulation to treat missing input files as though they were present but empty.
Default
MFJ_INPUTDS_ERROR=Y

MFJ_LEX_LOCATION

Specifies an alternative location for the storage of JCL lexigraphical files, which are created when a job is parsed, and are stored in the same directory as the job log by default.
Syntax
MFJ_LEX_LOCATION=path-name
Parameter
path-name
The full path to the alternative directory location in which to store JCL lexicographical files. The alternative directory location must be accessible by all enterprise server regions that both submit and run jobs.
Default
Not set.

MFJ_PTPCH_CODESET

When using a codeseet similar to but other than Japanese 9122, causes MFJPTPCH to match hexadecimal character values with those in Japanese code set 9122 to determine whether a character is printable or not.
Syntax
MFJ_PTPCH_CODESET=EXTJ
Parameter
EXTJ
MFJPTPCH attempts to match hexadecimal character values with those in Japanese code set 9122 to decide whether a character is printable or not.
Default
Not set. Hexadecimal character values are not evaluated for printability.
Comments
For use only when an extended Japanese code set other than 9122 is being used.

MFJ_REPORT_DATE_CHANGE

Determines whether date stamps are recorded in the JESYSMSG job log of when a is job started along with date changes date changes during execution.
Syntax
MFJ_REPORT_DATE_CHANGE={Y|N}
Parameters
Y
Date stamps are recorded in the JESYSMSG job log of when a is job started along with date changes during execution.
N
Switches off date stamps in the log.
Properties
MFJ_REPORT_DATE_CHANGE=Y

MFJ_REPRO_EMPTY

Determines whether the IDCAMS REPRO action can copy from a pristine VSAM file.
Syntax
MFJ_REPRO_EMPTY={Y|N}
Parameters
Y
Enables the IDCAMS REPRO action to copy from a pristine VSAM file. The resulting file is empty.
N
Prevents the IDCAMS REPRO action from copying from a pristine VSAM file, and produces a JCLAM0150S error when attempted.
Properties
MFJ_REPRO_EMPTY=Y

MFJ_STRICT_CASE

Determines the case to be maintained for physical file names passed to MVSCATIO by the catalog API and other utilities such as the mfcatxml utility for exporting and importing a catalog, and the mvspcrn utility for bulk updates.
Syntax
MFJ_STRICT_CASE={Y|N}
Parameters
Y
MVSCATIO honors the case of physical file names passed by the catalog API, and other utilities.
N
All physical file names are folded into upper case.
Default
MFJ_STRICT_CASE=N

MFJFAXIT

Specifies the user exit program that enables file action notifications.
Syntax
MFJFAXIT=path-name\file-name
Parameters
path-name
The full path to the location of the user exit program that enables file action notifications.
file-name
The name of the user exit program file.
Default
Not set. The MFJAXIT user exit is not enabled.
Comments
This user exit is called by the JCL engine whenever a JCL file is opened OUTPUT, I-O, or EXTEND, or when it is copied or renamed by the JCL engine.
Example
A sample user exit program (MFJFAXIT.cbl) is provided with your product, and is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits directory.

MFJSENGINE

Specifies which sort engine the utility MFJSORT is to emulate.
Syntax
MFJSENGINE={DFSORT|SYNCSORT}
Parameters
DFSORT
MFJFSORT emulates the mainframe DSORT utility.
SYNCSORT
MFJFSORT emulates the SYNCSORT utility.
Default
MFJSENGINE=DFSORT

MFREXX_CHARSET

Specifies the character set used by the REXX engine when working with hexadecimal strings or performing string comparisons.
Syntax
MFREXX_CHARSET={A|E}
Parameters
A
Use the ASCII character set.
E
Use the EBCDIC character set.
Default
MFREXX_CHARSET=E

MFREXX_CONCAT

Specifies one or more characters to be used for the CONCAT operator.
Syntax
MFREXX_CONCAT={"char-op"|char-hex}[{ |,}{"char-op"|char-hex}[...]]
Parameter
char-op
A character operator to use in addition to the default operator.
char-hex
A hexadecimal value that represents a character operator to use in addition to the default operator.
Default
Not set. The default character operator is ?.
Comments
Single quotes may be substituted for double quotes.

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.

Examples
Both examples set & (hex value 26) and # (hex value 23) as CONCAT operators in addition to ?:
MFREXX_CONCAT="&" 23
MFREXX_CONCAT=26,'#'

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
Parameter
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.
Default
MFREXX_LSEQ_RECSIZE_MAX=255

MFREXX_NO_PROCESS_STDIN

Determines whether to stop STDIN from being processed on an EXECIO command.
Syntax
MFREXX_NO_PROCESS_STDIN={Y|N}
Parameters
Y
Stops STDIN from being processed on an EXECIO command.
N
STDIN is processed on an EXECIO command.
Default
MFREXX_NO_PROCESS_STDIN=N

MFREXX_NOT

Specifies one or more characters to be used for the NOT operator in addition to the default.
Syntax
MFREXX_NOT={"char-op"|char-hex}[{ |,}{"char-op"|char-hex}[...]]
Parameters
char-op
A character operator to use in addition to the default operator. Each additional character must be defined within single or double quotes.
char-hex
A hexadecimal value that represents a character operator to use in addition to the default operator.
Default
Not set. The default character operator is ¬.
Comments
Single quotes may be substituted for double quotes.

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.

Examples
Both examples set & (hex value 26) and # (hex value 23) to be used as NOT operators in addition to ¬:
MFREXX_NOT="&" 23
MFREXX_NOT=26,'#'

MFREXX_OR

Specifies one or more characters to be used for the OR operator in addition to the default.
Syntax
MFREXX_OR={"char-op"|char-hex}[{ |,}{"char-op"|char-hex}[...]]
Parameters
char-op
A character operator to use in addition to the default operator.
char-hex
A hexadecimal value that represents a character operator to use in addition to the default operator.
Default
Not set. The default character operator is |.
Comments
Single quotes may be substituted for double quotes.

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

Examples
Both examples set & (hex value 26) and # (hex value 23) to be used as OR operators in addition to |:
MFREXX_NOT="&" 23
MFREXX_NOT=26,'#'

MFSYSCAT

The location and file name of the JES system catalog.
Syntax
MFSYSCAT={path-name\CATALOG.DAT|URL}
Parameters
path-name
The full path to the location of the CATALOG.DAT file.
URL
For a database-hosted system catalog, the full SQL URL that points to the CATALOG.DAT file.
Default
Not set. Uses the location specified in the JES > Configuration > System Catalog field in ESCWA.
Comments
See the data category in The dbfhdeploy Command Line Utility for full notation details if specifying a database-hosted system catalog.
Examples
MFSYSCAT=C:\MY\CATALOG\FOLDER\CATALOG.DAT
MFSYSCAT=sql://localhost/JCLTEST/catalog.dat?folder=/JCLDEMO

MFUSERCAT_BASE_LOC

If an entry in MFUSERCAT_LOC only specifies the file name of the user catalog rather than the full path and file name, use this environment variable to specify where these catalogs are located.
Syntax
MFUSERCAT_BASE_LOC=path-name
Parameter
path-name
The full path to the location of the file specified by the MFUSERCAT_LOC environment variable.
Default
Not set. If the path is not specified in MFUSERCAT_LOC, the current working directory is used.
Comments
If multiple user catalog files are in the same location - for example, C:\USERCATALOGS or $$MYFILESHARE - use this environment variable to store that location. Then, you only need to specify the file name of the catalog in MFUSERCAT_LOC.

Valid only when the value of MFUSERCAT_LOC is a file name only.

MFUSERCAT_NODE

MFUSERCAT_NODE
User catalog node.
Syntax
Parameters
SYSMFE1
Default
Comments
Example
Related information
MF_SMS

NEWJCL

Controls ISPF skeleton JCL processing.

SPOOL_TIMEOUT

Enables greater control over record-lock retries by setting timeout and interval durations.
Syntax
SPOOL_TIMEOUT=timeout:interval
Parameters
timeout
The amount of time in milliseconds to continue to retry the lock before ceasing the attempt.
interval
The amount of time in milliseconds before initiating a new lock retry attempt.
Default
SPOOL_TIMEOUT=500:100
Comments
Set this environment variable to resolve reported record-locked messages, which, depending on hardware performance, can occur especially during shutdown of an enterprise server instance with an SSTM job.

SSTM_WC_REFRESH

Determines how often the write count for the SSTM job is updated in SYSOUT or SYSPRINT.
Syntax
SSTM_WC_REFRESH={0|number-of-writes}
Parameters
0
The count is only updated when the file is closed.
number-of-writes
A value from 1 through 65535 to indicate the number of writes at which the count is updated.
Default
SSTM_WC_REFRESH=0
Comments
Any provided value outside of 0-65535 defaults to 65535.

VSE_STARTUP_CFG

The location of the VSE JCL configuration file.
Syntax
VSE_STARTUP_CFG=[path-name\]file-name
Parameters
path-name
The full path to the location of the VSE JCL configuration file. When not specified, Enterprise Server looks for the file in the current working directory.
file-name
The name of the VSE JCL configuration file.
Default
Not set. You must explicitly set VSE_STARTUP_CFG to use VSE JCL support.


Mainframe Access Environment Variables

Lists environment variables related to the Mainframe Access functionality.
Parent topic: Environment Variables by Groups

CCITIMEOUT

Sets a maximum time-out period used with non-data connect applications.
Syntax
CCITIMEOUT=wait-time
Parameter
wait-time
The number of seconds to wait before timing out times 10, up to a maximum value of 2,147,483,647.
Default
CCITIMEOUT=1200

(2 minutes)

Comments
Use this variable with non-data connect applications such as Drag and Drop, SourceConnect, and the Monitor.
Example
This example sets the wait time to 4 minutes:
CCITIMEOUT=2400

MAINFRAME_FLOATING_POINT

Specifies the format to use for floating point data items. Possible formats are IBM hexadecimal and IEEE.
Syntax
MAINFRAME_FLOATING_POINT={true|false}
Parameters
true
Use IBM hexadecimal-format floating-point data items.
false
Use IEEE-format floating-point data items.
Default
MAINFRAME_FLOATING_POINT=false
Comments
The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MFACLIENTINI

The complete path to the mfaclient.ini file, which contains mainframe logon credentials.
Syntax
MFACLIENTINI=path-name
Parameter
path-name
The complete path to the mfaclient.ini file.
Default
Not set. Uses the default location of the mfaclient.ini file, which is %APPDATA%\micro focus.
Comments
Used by mfdasmx.

MFAIMBEDDEDHEX

Determines whether the COBOL run-time system properly handles hex values embedded in source code.
Syntax
MFAIMBEDDEDHEX=COBOL
Parameter
COBOL
Enables the COBOL run-time system to properly handle hex values embedded in source code, meaning that all translated hex values less than x'1f' have a null character inserted before the hex value.
Default
Not set. The COBOL run-time system does not handle embedded hex values.
Comments
When set, hex values are handled in the same manner as when using the MDECONV application.

MFALLOC_DEF_VB_PCFILE

Determines whether a new PS VB file is defined in the catalog.
Syntax
MFALLOC_DEF_VB_PCFILE={Y|N}
Parameters
Y
A new PS VB file is defined in the catalog as a VB file with default settings of minimum length = 0, and maximum length = 32760.
N
Do not create a new PS VB file.
Default
MFALLOC_DEF_VB_PCFILE=Y
Comments
Valid only when the LRECL mfims imsdbu directive is not set or is set to 0 (zero).

MFALLOC_LOC

The default allocated dataset location.
Syntax
MFALLOC_LOC={path-name|SQL-URL}
Parameters
path-name
The full path to the dataset location.
SQL-URL
For a database-hosted dataset, the SQL URL to that location.
Default
Not set.
Example
Set the default allocated dataset to the sql://localhost/JCLTEST?folder=/JCLDEMO/data location:
MFALLOC_LOC=sql://localhost/JCLTEST?folder=/JCLDEMO/data

MFALLOC_PCFILE

Determines whether a catalogued file is created when DSORG=PS is provided in the DCB parameters.
Syntax
MFALLOC_PCFILE={Y|N}
Parameters
Y
A catalogued file is created when DSORG=PS is provided in the DCB parameters.
N
A catalogued file is not created.
Default
MFALLOC_PCFILE=Y
Comments
Valid only when DSORG=PS is provided in the DCB parameters.

MFAMAXHOTLINKS

MFAMAXHOTLINKS
Used only by the hot-link software from Micro Focus, routes all non-data connect application communication requests through this hot-link.
Syntax
MFAMAXHOTLINKS=number-of-simultaneous-links
Parameter
number-of-simultaneous-links
The maximum number of simultaneous links allowed, up to 10.
Default
MFAMAXHOTLINKS=4
Comments
The hot-link remains active to the mainframe until you shut down your workstation, or you enter the MFDAELSC CLOSE command.

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.

MFAMAXSENDLENGTH

Sets the maximum length of data that can be transmitted in a single communication packet to or from the mainframe.
Syntax
MFAMAXSENDLENGTH=max-data-length
Parameter
max-data-length
The number of bytes that represents the maximum length of data.
Default
Not set.
Comments
This is useful when there is a router that limits the transfer length of data to or from the mainframe, or when the allowable length of transferred data is restricted.

This setting 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.

Example
MFAMAXSENDLENGTH=4000


WebSphere MQ Environment Variables

Attention: 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 OpenText Support for Micro Focus Products.
Parent topic: Environment Variables by Groups

ES_MQ_1PC

Indicates whether the IBM WebSphere MQ switch module ESMQXA operate in one-phase commit mode.
CAUTION:
Set this environment variable only when advised to do so by OpenText Support for Micro Focus Products.
Syntax
ES_MQ_1PC={[Y|y|Yes|T|True]|[N|n|No|F|False}
Parameters
Y|y|Yes|T|True
The ESMQXA switch module operates in one-phase commit mode.
N|n|No|F|False
The ESMQXA switch module operates in two-phase commit mode.
Default
ES_MQ_1PC=F

ES_MQ_LIB

The full name including the path of the IBM WebSphere MQ client or server library. This should only be required if MQ was NOT installed in the default location.
Syntax
ES_MQ_LIB=path-name/library-name
Parameters
path-name
The full path to the library location.
library-name
The name of the library file.
Default
Not set. Enterprise Server looks for library files in the default location for your platform.
Comments
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_XA

The type of XA structure to use for the two-phase commit XA switch module.
Syntax
ES_MQ_XA={D|S}
Parameters
D
Use a dynamic XA structure
S
Use a static XA structure.
Default
ES_MQ_XA=D

MQSERVER

The names of one or more minimal channels.
Syntax
MQSERVER=channel-name/transport-type/{machine-name|ip-address(port-number)}
   [,{machine-name|ip-address}(port-number)][...]]
Parameters
channel-name
The name of a channel as defined on the server.
transport-type
The communications protocol, which can be any of the following:
  • TCP
  • LU62
  • NETBIOS
  • SPX
machine-name
The name of the server machine.
ip-address
The machine IP address.
port-number
The number of the port used.
Comments
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.

Examples
MQSERVER=CHANNEL3/TCP/QServer(1414)
MQSERVER=CHANNEL1/TCP/10.120.99.999(1414),10.120.98.888(1414)

TX_MQ_CONVERT

Sets the code set to overwrite the MQ Q manager CCSID. The value is used in the MD-codedcharsetid parameter.
Syntax
TX_MQ_CONVERT=codeset[,Force]
Parameters
codeset
The code that corresponds to that you want to use to overwrite MQ Q manager CCSID. See Installing CCSID translation tables for further details.
Force
Force the convert option for MQ even if the application does not set the option on the call.
Default
Not set. Enterprise Server uses the Q Manager CCSID.
Example
TX_MQ_CONVERT=037

To force the convert option for MQ even if the application does not set the option on the call, specify the code set followed by Force:

TX_MQ_CONVERT=037,Force

TX_MQTRACE

Enables tracing in dfh0mqis for WebSphere MQ calls.


PAC Environment Variables

Lists environment variables related to configuring a PAC in Enterprise Server..
Parent topic: Environment Variables by Groups

CICS_SIT

The name of the SIT used by the enterprise server region.
Syntax
CICS_SIT=sit-name
Parameter
sit-name
The name of the CICS SIT to use for the enterprise server region.
Default
Not set. The CICS SIT specified in ESCWA is used.

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.
Syntax
ES_ALLOC_OVERRIDE=path-name\rules-file
Parameters
path-name
The full path to the dataset rules file.
rules-file
The name of the dataset rules file.
Default
Not set.

ES_CICS_SINGLE

Configures CICS so that a user can only log on once when the enterprise server region is running in a PAC with CICS enabled.
Syntax
ES_CICS_SINGLE={Y|N}
Parameters
Y
A user can only log on once.
N
The same user may sign on to multiple terminals with CICS.
Default
ES_CICS_SINGLE=Y
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XCMD

Controls the CICS CMD resource class.
Syntax
ES_CLASS_XCMD={YES|NO|class-name}
Parameters
YES
CICS CMD is the default CMD class.
NO
Security for CMDs is bypassed.
class-name
The name of a class to override the default CMD CICSCMD class.
Default
ES_CLASS_XCMD=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XDCT

Controls the CICS DCT resource class.
Syntax
ES_CLASS_XDCT={YES|NO|class-name}
Parameters
YES
DCICSDCT is the default DCT class.
NO
Security for DCTs is bypassed.
class-name
The name of a class to override the default DCT DCICSDCT class.
Default
ES_CLASS_XDCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XFCT

Controls the CICS FCT resource class.
Syntax
ES_CLASS_XFCT={YES|NO|class-name}
Parameters
YES
FCICSFCT is the default FCT class.
NO
Security for FCTs is bypassed.
class-name
The name of a class to override the default PCT FCICSFCT class.
Default
ES_CLASS_XFCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XJCT

Controls the CICS JCT resource class.
Syntax
ES_CLASS_XJCT={YES|NO|class-name}
Parameters
YES
JCICSJCT is the default JCT class.
NO
Security for JCTs is bypassed.
class-name
The name of a class to override the default JCT JCICSJCT class.
Default
ES_CLASS_XJCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPCT

Controls the CICS PCT resource class.
Syntax
ES_CLASS_XPCT={YES|NO|class-name
Parameters
YES
ACICSPCT is the default PCT class.
NO
Security for PCTs is bypassed.
class-name
The name of a class to override the default PCT ACICSPCT class.
Default
ES_CLASS_XPCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPPT

Controls the CICS PPT resource class.
Syntax
ES_CLASS_XPPT={YES|NO|class-name}
Parameters
YES
MCICSPPT is the default PPT class.
NO
Security for PPTs is bypassed.
class-name
The name of a class to override the default PPT MCICSPPT class.
Default
ES_CLASS_XPPT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPSB

Controls the CICS PSB resource class.
Syntax
ES_CLASS_XPSB={YES|NO|class-name}
Parameters
YES
PCICSPSB is the default PSB class.
NO
Security for PSBs is bypassed.
class-name
The name of a class to override the default PSB PCICSPSB class.
Default
ES_CLASS_XPSB=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XRES

Controls the CICS DOCTEMPLATE resource class.
Syntax
ES_CLASS_XRES={YES|NO|class-name}
Parameters
YES
RCICSRES is the default RES class.
NO
Security for DOCTEMPLATEs is bypassed.
class-name
The name of a class to override the default RES RCISRES class.
Default
ES_CLASS_XRES=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XTST

Controls the CICS TST resource class.
Syntax
ES_CLASS_XTST={YES|NO|class-name}
Parameters
YES
SCITST is the default TST class.
NO
Security for TSTs is bypassed.
class-name
The name of a class to override the default TST SCITST class.
Default
ES_CLASS_XTST=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XTRAN

Controls the CICS TRAN resource class.
Syntax
ES_CLASS_XTRAN={YES|NO|class-name}
Parameters
YES
TCICSTRN is the default TRAN class.
NO
Security for TRANs is bypassed.
class-name
The name of a class to override the default TRAN TCICSTRN class.
Default
ES_CLASS_XTRAN=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_DISABLE_DFLTUSR_SIGNON

Disables the default user (mfuser) signon when invoking ES Monitor & Control (ESMAC).
Syntax
ES_DISABLE_DFLTUSR_SIGNON=Y
Parameter
Y
Disables the mfuser auto-logon after starting Enterprise Server administration via your MFDS internal security account.
Default
Not set. mfuser is signed in to ESMAC.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_EMP_EXIT_n

ES_EMP_EXIT_n
Specifies the number of Event Manager user exits for the region.
ES_EMP_EXIT_n=batch-component
Parameters
n
A single digit ranging from 1 through 9, depending on the number of Event Manager user exits for the region.
Note: This must be set to 1 when mfbsiemx is the only Event Manager user exit for the region.
batch-component
An event manager component.
Default
Not set.
Comments
You must set ES_EMP_EXIT once for each Event Manager used in the region.

When setting ES_EMP_EXIT multiple times, they must be set in numerical order.

Example
ES_EMP_EXIT_1=mfbsiemx
ES_EMP_EXIT_2=mfmonemx
ES_EMP_EXIT_3=...

ES_ESM_CMDSEC

Indicates whether CICS processing honors the CMDSEC option specified on a transaction's PLT definition.
Syntax
ES_ESM_CMDSEC=YES
Parameter
YES
CICS overrides the CMDSEC option, and always calls its command security checking routine to issue the appropriate call to the SAF interface.
Default
Not set. 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.

ES_ESM_PLTPIUSR

Specifies the user ID under which PLT programs run during CICS initialization.
Syntax
ES_ESM_PLTPIUSR=userid
Parameter
userid
The user ID for CICS to use for security checking for PLT programs that run during CICS initialization.
Default
Not set. The user specified when starting the CICS-enabled enterprise server region is used.
Comments

The user ID specified must have appropriate authorization to access all the resources used by the programs as determined by the ES_ESM_PLTPISEC environment variable.

ES_ESM_RESSEC

Indicates whether CICS processing honors the RLS security setting specified on a transaction definition (PCT).
Syntax
ES_ESM_RESSEC=ALWAYS
Parameter
ALWAYS
CICS processing always performs resource level security checking irrespective of the RLS security setting on the transaction definition.
Default
Not set. The RLS security setting of a transaction is honored. That is, resource-level security checking is performed only when the RLS security checkbox is marked in the PCT definition.

ES_ESM_SECPRFX

Indicates whether CICS processing adds a prefix to resource names when making security queries.
Syntax
ES_ESM_SECPRFX={NO|YES|prefix}
Parameters
NO
Use no prefixes.
YES
Uses prefix resource names with the CICS region user ID.
prefix
Define a prefix for resource names as an alphanumeric string that starts with an alphabetic character, and is one to eight upper-case characters in total.
Default
ES_ESM_SECPRFX=NO
Comments
This environment variable is applied only to CICS classes.

ES_ESM_XUSER

Indicates whether CICS processing performs surrogate user checks.
Syntax
ES_ESM_XUSER={NO|YES}
Parameters
NO
No surrogate user checking is performed.
YES
Perform surrogate user checking wherever such checks are permitted.
Default
ES_ESM_XUSER=YES

ES_PAC_NO_GLOBAL_LOG

Stops the messages in the console.log from being stored in the PAC Scale-out Repository (PSOR) CasPacLog.
Syntax
ES_PAC_NO_GLOBAL_LOG={Y|N}
Parameters
Y
Prevents console.log messages for PAC member regions from being stored in the PSOR.
N
console.log messages for PAC member regions are stored in the PSOR.
Default
ES_PAC_NO_GLOBAL_LOG=N
Comments
You can set ES_PAC_NO_GLOBAL_LOG=Y to improve performance if you are not monitoring messages from the PSOR.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_SCALE_OUT_REPOS_n

Specifies connection information for either Redis or Oracle Coherence data stores used by enterprise server regions that are part of a PAC.
Syntax
ES_SCALE_OUT_REPOS_n=sor-name=sor-Type,
   {redis-connection-details|oracle-connection-details}##[TMP#][models]
Parameters
n
Represents the SOR number. Valid values are 1 through 9.
sor-name
The name of the SOR. No spaces are allowed. In the context of using Redis, the SOR name is used to retrieve the Redis master from Redis.
sor-type
This is the type of data store. Valid values are:
redis | Regular connection to a Redis data store
redis_TLS | TLS -enabled connection to a Redis data store
coherence | Oracle Coherence connection to an Oracle data store
redis-connection-details
One or more host and port name pairs used for Redis connections as follows:
host-name:port-name[,host-name:port-name[...]]
host-name | The machine name or IP address of the host system where data stores are location
port-name | The port used to make the connection to the host specified by the corresponding host-name
oracle-connection-details
[userid@][path-name|URL][config-file]
   [,java-property[[=java-property-value]][…]]##[TMP#]
   [={TS=ts-model[:ts-model]|TD=td-model[:td-model]}]
   [[#{TS=ts-model[:ts-model]|TD=td-model[:td-model]}]][...]]
userid@ | The user ID to use when Oracle Coherence security is enabled.
path-name | The path to the configuration file represented by config-file. If omitted, defaults to the current working directory.
URL | A URL that contains the configuration content.
config-file | The name of the cache configuration file. If omitted, defaults to mfes-cache-config.xml.
java-property | The name of a Java property to set to the specified java-property-value, or is clear if java-property-value is unspecified.
java-property-value | The value of the property specified by java-property.
# Delimiter character.
TMP | Indicates that this PSOR stores active resources.
TS | Indicates temporary storage resource type.
TD | Indicates transient data resource type.
ts-model | An identifier for the corresponding TS consisting of either a character string no more than four bytes in length.1
td-model | An identifier for the corresponding TD consisting of a character string no more than 16 bytes in length.1
1 You may use the * wildcard character to represent any string, and the + character to represent any single character. Identifiers of a size smaller than the byte limit are automatically padded using + characters to extend the length to the limit.
Default
None. You must set ES_SCALE_OUT_REPOS_n for all enterprise server regions that are part of a PAC.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Examples
See PAC and SOR Environment Variables.

ES_SOR_RETRIES

Sets the number of attempts to access records in the PSOR before stopping.
Syntax
ES_SOR_RETRIES=integer
Parameter
integer
An integer value ranging from 1 through 1000 that represents the number of attempts to access records in the PSOR before stopping.
Default
ES_SOR_RETRIES=10
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_CICS

Allows you to override the default user when no user is logged on for CICS authentication.
Syntax
ES_USR_DFLT_CICS=userid
Parameter
userid
An alternative default user name.
Default
ES_USR_DFLT_CICS=CICSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_JCL

Enables you to override the default user when no user is logged on for JCL authentication.
Syntax
ES_USR_DFLT_JCL=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JCL=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_USR_DFLT_JES

Allows you to override the default user when no user is logged on for JES authentication.
Syntax
ES_USR_DFLT_JES=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JES=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_WORKING_MODE

The bitism of the server, 32- or 64-bit.
Syntax
ES_WORKING_MODE={32|64}
Parameters
32
Indicates that the server runs in 32-bit mode.
64
Indicates that the server runs in 64-bit mode.
Default
ES_WORKING_MODE=64
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_XA_%xaname%_OPTIONS

When set with ES_XA_RECONNECT=Y, configures the XA reconnect process to operate in a multi-attempt mode.
Syntax
ES_XA_%xaname%_OPTIONS={reconnect_attempts,wait-time|EX}
Parameters
%xaname%
The name of the RM as specified in MFDS or ESCWA.
reconnect_attempts
The number of reconnect attempts to the target RM. Maximum is 9999.
wait-time
The number of seconds to delay between each attempt.
EX
Exclude the target RM from XA reconnect processing.
Default
Not set.
Comments
ES_XA_%xaname%_OPTIONS must be set along with ES_XA_RECONNECT=Y.

You might need to set ES_XA_%xaname%_OPTIONS multiple times — once for each RM that you require to operate in a multiple-attempt mode.

Examples
Specify that an XA reconnect processing attempts to reconnect to MQPROD 100 times and waiting for 10 seconds between each reconnect attempt:
ES_XA_MQPROD_OPTIONS=100,10

Specify that the XA reconnect processing is to exclude MQPROD from the XA reconnect processing:

ES_XA_MQPROD_OPTIONS=EX

ES_XA_RECONNECT

Configures the XA reconnect process to operate in a single-attempt mode.
Syntax
ES_XA_RECONNECT=Y,wait-time[,retry_count]
Parameters
Y
Enables the reconnect process.
wait-time
The number of seconds to delay before triggering the XA recovery transaction after a two-phase commit failure and between each reschedule of the XA recovery transaction if the syncpoint phase 2 returns an RC 04. Maximum is 300.
retry_count
The number of recovery retries to attempt when the XA commit or rollback executed by the XA recovery transaction returns an RC-04. Default is 5.
Default
Not set. XA reconnect operates in multi-attempt mode.
Comments
In case of failure, the following messages are sent to the console:
CASXO0054W XA recovery error RC=4 on commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG           000000***********000010000000**        0000

When the maximum number of retries is reached, the following message is sent to the console:

CASXO0055S XA MAX recovery attempts, manually commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG       000000***********000010000000**        0000
Example
ES_XA_RECONNECT=Y,120,4

MFSYSCAT

The location and file name of the JES system catalog.
Syntax
MFSYSCAT={path-name\CATALOG.DAT|URL}
Parameters
path-name
The full path to the location of the CATALOG.DAT file.
URL
For a database-hosted system catalog, the full SQL URL that points to the CATALOG.DAT file.
Default
Not set. Uses the location specified in the JES > Configuration > System Catalog field in ESCWA.
Comments
See the data category in The dbfhdeploy Command Line Utility for full notation details if specifying a database-hosted system catalog.
Examples
MFSYSCAT=C:\MY\CATALOG\FOLDER\CATALOG.DAT
MFSYSCAT=sql://localhost/JCLTEST/catalog.dat?folder=/JCLDEMO

MFUSERCAT_BASE_LOC

If an entry in MFUSERCAT_LOC only specifies the file name of the user catalog rather than the full path and file name, use this environment variable to specify where these catalogs are located.
Syntax
MFUSERCAT_BASE_LOC=path-name
Parameter
path-name
The full path to the location of the file specified by the MFUSERCAT_LOC environment variable.
Default
Not set. If the path is not specified in MFUSERCAT_LOC, the current working directory is used.
Comments
If multiple user catalog files are in the same location - for example, C:\USERCATALOGS or $$MYFILESHARE - use this environment variable to store that location. Then, you only need to specify the file name of the catalog in MFUSERCAT_LOC.

Valid only when the value of MFUSERCAT_LOC is a file name only.

MFUSERCAT_LOC

Specifies the location and name of each additional catalog, matching the values provided in the MFUSERCAT_NODE value.
Syntax
MFUSERCAT_LOC={[path-name\]file-name}[;{[path-name\]file-name}[...]]
Parameters
path-name
The full path to a catalog file.
file-name
The name of the catalog file.
Default
Not set. No file names or locations are provided for additional catalogs specified by MFUSERCAT_NODE.
Comments
Parameter values are limited to a total of 4096 characters.

If multiple catalog files are in the same location, you can use the environment variable MFUSERCAT_LOC to store that location. If you do this, you only need to specify the file name of each catalog file in MFUSERCAT_LOC.

MFUSERCAT_NODE

Specifies additional SMS, SPOOL, and User catalogs.
Syntax
MFUSERCAT_NODE=node-name[,node-name[...]]
Parameter
node-name
A user catalog or special node name, including optional wildcards * for any number of characters and ? for a single character.
Default
Not set.
Comments
Use this variable to specify additional SMS, SPOOL and User catalogs. Up to 64 additional catalogs may be specified with semi-colon separated values. The physical file used for each catalog is stored in the environment variable MFUSERCAT_LOC.

The parameter specification is limited to 4096 characters.

In the parameter specification, you may optionally use the UNIX-style square bracket notation (part of the regular expression feature), to specify a list of permissible characters at a particular point within the node specification.

To enable support for the SMS entities DATACLAS and MGMTCLAS, this variable needs to be set in addition to setting MF_SMS=ON.

Each node-name entry in MFUSERCAT_NODE must have a corresponding entry in MFUSERCAT_LOC.

Use the ES_OPEN_CAT_ON_DEMAND variable to determine if these catalogs are opened when the region starts, or only opened when they are required.


Security and Auditing Environment Variables

Lists environment variables related to configuring the security and auditing environment.
Parent topic: Environment Variables by Groups

ES_CESN_NO_OS390

Overrides the default CESN transaction and the IMS sign-on screen response behavior for invalid user credentials.
Syntax
CESN_NO_OS390=ON
Parameter
ON
Override the default CESN transaction and IMS sign-on screen response behavior for invalid credentials, and instead produce an invalid credential message.
Default
Not set. CESN transaction and IMS sign-on screen response is Your userid is invalid or Your password is invalid.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XCMD

Controls the CICS CMD resource class.
Syntax
ES_CLASS_XCMD={YES|NO|class-name}
Parameters
YES
CICS CMD is the default CMD class.
NO
Security for CMDs is bypassed.
class-name
The name of a class to override the default CMD CICSCMD class.
Default
ES_CLASS_XCMD=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XDCT

Controls the CICS DCT resource class.
Syntax
ES_CLASS_XDCT={YES|NO|class-name}
Parameters
YES
DCICSDCT is the default DCT class.
NO
Security for DCTs is bypassed.
class-name
The name of a class to override the default DCT DCICSDCT class.
Default
ES_CLASS_XDCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XFCT

Controls the CICS FCT resource class.
Syntax
ES_CLASS_XFCT={YES|NO|class-name}
Parameters
YES
FCICSFCT is the default FCT class.
NO
Security for FCTs is bypassed.
class-name
The name of a class to override the default PCT FCICSFCT class.
Default
ES_CLASS_XFCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XJCT

Controls the CICS JCT resource class.
Syntax
ES_CLASS_XJCT={YES|NO|class-name}
Parameters
YES
JCICSJCT is the default JCT class.
NO
Security for JCTs is bypassed.
class-name
The name of a class to override the default JCT JCICSJCT class.
Default
ES_CLASS_XJCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPCT

Controls the CICS PCT resource class.
Syntax
ES_CLASS_XPCT={YES|NO|class-name
Parameters
YES
ACICSPCT is the default PCT class.
NO
Security for PCTs is bypassed.
class-name
The name of a class to override the default PCT ACICSPCT class.
Default
ES_CLASS_XPCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPPT

Controls the CICS PPT resource class.
Syntax
ES_CLASS_XPPT={YES|NO|class-name}
Parameters
YES
MCICSPPT is the default PPT class.
NO
Security for PPTs is bypassed.
class-name
The name of a class to override the default PPT MCICSPPT class.
Default
ES_CLASS_XPPT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XPSB

Controls the CICS PSB resource class.
Syntax
ES_CLASS_XPSB={YES|NO|class-name}
Parameters
YES
PCICSPSB is the default PSB class.
NO
Security for PSBs is bypassed.
class-name
The name of a class to override the default PSB PCICSPSB class.
Default
ES_CLASS_XPSB=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XRES

Controls the CICS DOCTEMPLATE resource class.
Syntax
ES_CLASS_XRES={YES|NO|class-name}
Parameters
YES
RCICSRES is the default RES class.
NO
Security for DOCTEMPLATEs is bypassed.
class-name
The name of a class to override the default RES RCISRES class.
Default
ES_CLASS_XRES=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XTRAN

Controls the CICS TRAN resource class.
Syntax
ES_CLASS_XTRAN={YES|NO|class-name}
Parameters
YES
TCICSTRN is the default TRAN class.
NO
Security for TRANs is bypassed.
class-name
The name of a class to override the default TRAN TCICSTRN class.
Default
ES_CLASS_XTRAN=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_CLASS_XTST

Controls the CICS TST resource class.
Syntax
ES_CLASS_XTST={YES|NO|class-name}
Parameters
YES
SCITST is the default TST class.
NO
Security for TSTs is bypassed.
class-name
The name of a class to override the default TST SCITST class.
Default
ES_CLASS_XTST=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_DISABLE_DFLTUSR_SIGNON

Disables the default user (mfuser) signon when invoking ES Monitor & Control (ESMAC).
Syntax
ES_DISABLE_DFLTUSR_SIGNON=Y
Parameter
Y
Disables the mfuser auto-logon after starting Enterprise Server administration via your MFDS internal security account.
Default
Not set. mfuser is signed in to ESMAC.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_ESM_CMDSEC

Indicates whether CICS processing honors the CMDSEC option specified on a transaction's PLT definition.
Syntax
ES_ESM_CMDSEC=YES
Parameter
YES
CICS overrides the CMDSEC option, and always calls its command security checking routine to issue the appropriate call to the SAF interface.
Default
Not set. 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.

ES_ESM_PLTPISEC

The level of security checking for PLTPI processing.
Syntax
ES_ESM_PLTPISEC={NONE|CMDSEC|RESSEC|ALL}
Parameters
NONE
No security checking is performed on PLT initialization programs.
CMDSEC
CICS performs command security checking only.
RESSEC
CICS performs resource security checking only.
ALL
CICS performs both command and resource security checking.
Default
ES_ESM_PLTPISEC=NONE

ES_ESM_RCF

Determines how RACF is used for command authorization.
Syntax
ES_ESM_RCF={A|C|N|S|T|Y}
Parameters
A
A combination of options T, C, and S.
C
Use RACF for ETO terminal command authorization.
N
RACF does not perform sign-on, transaction, or command authorization.
S
Use RACF for static and ETO terminal command authorization. Includes option C.
T
Use RACF for sign-on and transaction authorization.
Y
A combination of options T and C.
Default
ES_ESM_RCF=N

ES_ESM_SECPRFX

Indicates whether CICS processing adds a prefix to resource names when making security queries.
Syntax
ES_ESM_SECPRFX={NO|YES|prefix}
Parameters
NO
Use no prefixes.
YES
Uses prefix resource names with the CICS region user ID.
prefix
Define a prefix for resource names as an alphanumeric string that starts with an alphabetic character, and is one to eight upper-case characters in total.
Default
ES_ESM_SECPRFX=NO
Comments
This environment variable is applied only to CICS classes.

ES_ESM_XUSER

Indicates whether CICS processing performs surrogate user checks.
Syntax
ES_ESM_XUSER={NO|YES}
Parameters
NO
No surrogate user checking is performed.
YES
Perform surrogate user checking wherever such checks are permitted.
Default
ES_ESM_XUSER=YES

ES_OLD_SEC_TSTD

Prevents security being enforced for TS or TD queues that are not declared in the security repository.
Syntax
ES_OLD_SEC_TSTD=ON
Parameter
ON
Prevents security being enforced for TS or TD queues that are not declared in the security repository.
Default
Not set. security is enforced for TS or TD queues that are not declared in the security repository.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

ES_SURROGATE_JOB_USER

Associates a user ID with a job when submitting the job for processing through the internal reader from CICS.
Syntax
ES_SURROGATE_JOB_USER=ON
Parameter
ON
The user ID that started the enterprise server region is used in the job submission.
Default
Not set. The CICS default user CICSUSER, or as specified by ES_USR_DFLT_CICS, is used in the job submission.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

MF_ROOT_CERT

Enables the MF Directory Server process and any client applications to find the root certificate file.

MFAUDIT_LOGS

The location of audit files.

USSCONFIG

Points to the location of the SSL cipher suite specification file(s) used by the CIPHERS attribute in the CICS URIMAP or TCPIPSERVICE resource.
Syntax
USSCONFIG=cipher-path
Parameter
cipher-path
The absolute path to the cipher suite specification file or files.
Comments
For details about ciphers and cipher files, see the Security Attributes > Ciphers section of the Universal Resource Identifier Map topic.


SORT Engine Environment Variables

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

Parent topic: Environment Variables by Groups

MFJSENGINE

Specifies which sort engine the utility MFJSORT is to emulate.
Syntax
MFJSENGINE={DFSORT|SYNCSORT}
Parameters
DFSORT
MFJFSORT emulates the mainframe DSORT utility.
SYNCSORT
MFJFSORT emulates the SYNCSORT utility.
Default
MFJSENGINE=DFSORT

MFJSDCBOUTFIL

MFJSDCBOUTFIL
Determines whether the DCB's LRECL value is honored during an OUTFIL statement.
MFJSDCBOUTFIL={ON|OFF}
Parameters
ON
The LRECL specified in the DCB properties is used during an OUTFIL statement.
OFF
Emulates the ICE222A/ICE217A mainframe restriction.
Default
MFJSDCBOUTFIL=OFF
Comments
When MFJSDCBOUTFIL=ON is in effect, if the DCB LRECL value differs from that calculated by OUTFIL, records are either truncated or padded with space to match the DCB LRECL value.
Example
MFJSDCBOUTFIL=ON

MFJSTATS

For a COBOL sort not running under mainframe emulation, determines whether statistics are included in reports produced for the COBOL SORT operation.
Syntax
MFJSTATS={ON|OFF|switch}
Parameters
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.
OFF
No statistics are included in the report.
switch
Switches the inclusion of statistics in the report to ON when set to OFF, and to OFF when set to ON.
Default
MFJSTATS=OFF
Comments
If you are performing a COBOL sort using mainframe emulation, you can create a statistics report by modifying the JCL statement.

SORTCOMPRESS

Tells the system whether or not to execute a compression routine on each record to be sorted.
Syntax
SORTCOMPRESS={0|1}
Parameters
0
Disables compression.
1
Enables compression.
Default
SORTCOMPRESS=0
Comments
When compression is enabled, run-length encoding of sort records is enabled, resulting in much better performance when records contain multiple repeated characters.

Use this variable to improve memory usage and therefore sort performance when the sort records contain many single, repeated characters; for example, multiple spaces.

The behavior when set to any positive integer is equivalent to SORTCOMPRESS=1.

SORTSCHEME

Enables the SORTSPACE environment variable, which specifies an alternative memory allocation size for sort operations.
Syntax
SORTSCHEME=1
Parameter
1
Enables the SORTSPACE environment variable.
Default
Not set. The memory allocated for sort functions is 1 megabyte.

SORTSPACE

The amount of memory to be allocated to internal workspace for SORT operations, and the format for the allocated memory.
Important: To set SORTSPACE to a value other than the default, you must first enable it using the SORTSCHEME environment variable.
Syntax
SORTSPACE=memory-spec[K|M|G]
Parameter
memory-spec
A number that represents the amount of memory to allocate. When used without an optional parameter, this number represents memory in bytes; otherwise, it represents the units specified by an optional parameter.
K
memory-spec specifies memory allocation in kilobytes.
M
memory-spec specifies memory allocation in megabytes.
G
memory-spec specifies memory allocation in gigabytes.
Default
SORTSPACE=1M
Comments
A larger value for SORTSPACE generally results in a faster sort. However, if you specify a value that exceeds the capacity of main memory in your computer such that the operating system has to page memory in and out, performance is degraded.

Parameter values are not case sensitive.

Example
SORTSPACE=1024K

SORTTEMPSPACE

The amount of memory to be allocated to temporary workspace for SORT operations.
Syntax
SORTTEMPSPACE=memory-spec[K|M|G]
Parameters
Important: The value specified must be equivalent to 32M or greater, irrespective of the scheme used to specify the amount of memory.
memory-spec
A number that represents the amount of memory to allocate. When used without an optional parameter, this number represents memory in bytes; otherwise, it represents the units specified by an optional parameter.
K
memory-spec specifies memory allocation in kilobytes.
M
memory-spec specifies memory allocation in megabytes.
G
memory-spec specifies memory allocation in gigabytes.
Default
SORTTEMPSPACE=32M
Comments
Use this variable to adjust the memory allocation strategy used by SORT. This can generally improve performance in systems suffering from memory fragmentation.

Parameter values are not case sensitive.

Example
SORTTEMPSPACE=250M

SORTTYPE

Sets SORT operations to use the file handler.
Syntax
SORTTYPE=2
Parameter
2
Forces SORT to use the file handler, which picks up format modifications from the extfh.cfg file.
Default
Not set. SORT attempts to use CBL_ library routines to read and write files to improve performance.


Spool Housekeeping Environment Variables

Lists environment variables relatee to the configuration of the spool housekeeping processes.
Parent topic: Environment Variables by Groups

MF_SPOOL_ARCHIVE_LOC

The base location for files archived as part of the spool housekeeping process, where the contents of the MVS SPOOL spool file are archived prior to deletion.
Syntax
MF_SPOOL_ARCHIVE_LOC=path-name
Parameter
path-name
The base location for files archived as part of the spool housekeeping process
Default
Not set.

MF_SPOOL_HK_LEX_SCAN

Determines if the MFELX* files associated with a job are also deleted when spool housekeeping is run.
Syntax
MF_SPOOL_HK_LEX_SCAN={Y|N}
Parameters
Y
The files are deleted.
N
The files are not deleted.
Default
MF_SPOOL_HK_LEX_SCAN=Y

MF_SPOOL_HK_OUTPRT

Determines if files from the Complete queue with a status of Output or Printed are also deleted when spool housekeeping is run.
Syntax
MF_SPOOL_HK_OUTPRTC={Y|N}
Parameters
Y
Files from the Complete queue are deleted.
N
Files from the Complete queue are not deleted.
Default
MF_SPOOL_HK_OUTPRT=Y

MF_SPOOL_HK_TESTDATE

Overrides the normal date for the spool housekeeping.
Syntax
MF_SPOOL_HK_TESTDATE=YYYYMMDD
Parameters
The following are used to represent the date used to override the normal date
YYYY
Four-digit year.
MM
Two-digit month.
DD
Two-digit day.
Default
Not set. Uses the normal date for the spool housekeeping.

MF_SPOOL_HK_WRITE_PROFILES

Determines the creation of profile files (.PRO files) when a data set is archived.
Syntax
MF_SPOOL_HK_WRITE_PROFILES={Y|N}
Parameters
Y
Profile files are created.
N
Profile files are not created.
Default
MF_SPOOL_HK_WRITE_PROFILES=Y


Tracing and Debugging Environment Variables

Lists environment variables related to the tracing and debugging functionality.
Parent topic: Environment Variables by Groups

CCITRACE

Specifies the type of information to record using CCI tracing.
Syntax
CCITRACE={/|-}{F|P|D}[...]
Parameters
/
Turns on the specified option.
-
Turns off the specified option.
F
Logs the details of CCI API calls to CTF. This option is implied when either P or D is specified. You can override this using -F.
P
When turned on, logs the details of protocol-level calls to CTF, which could greatly increase function tracing. When not set, only the details of the CCI user-level API are traced.
D
Logs the contents of all buffers passed to and from the CCI functions.
Warning: Setting this option might not produce the desired results if the application has been coded to prohibit data tracing.
Default
Not set. CCI tracing is controlled via the ctf.cfg and CCI.INI trace options.
Comments
The ctf.cfg and the CCI.INI file ([ccitrace_base] section) can also be used to control trace options, but any values specified by the CCITRACE environment variable take precedence. For details, see Tracing Options for CTF.CFG and CCI.INI - The CCI Configuration File.
Example
CCITRACE=/F/D

DBG_MVSPSKEL

The skeleton JCL for debugging.

ES_DDBG_PORT_RANGE

A range of ports to use for dynamic debugging.
Syntax
ES_DDBG_PORT_RANGE={starting-port-number-ending-port-number |
   starting-port-number,number-of-ports
Parameters
starting-port-number
A port number that represents the start of the range.
ending-port-number
A port number that represents the end of the range. This number must be greater than the value of starting-port-number. All available ports within the range are used.
number-of-ports
The total number of ports. The ports used include those available, starting with the starting-port-number port and continuing with ports greater than the starting-port-number port, up to the total number specified.
Default
Not set. Dynamic debugging uses random ports.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Examples
The following specifies that all available ports from 8001 through 8040 are to be used:
ES_DDBG_PORT_RANGE=8001-8040

The following specifies using the next 40 available ports with a port number higher than the starting port number:

ES_DDBG_PORT_RANGE=8001,40

MFTRACE_ANNOTATIONS

The location of the trace files.

MFTRACE_CONFIG

The location of the CTF configuration file.
Syntax
MFTRACE_CONFIG=path-name\ctf.cfg
Parameter
path-name
The full path to the location of the ctf.cfg file.
Default
Not set.

MFTRACE_LOGS

The location in which to create CTF trace log files.
Syntax
MFTRACE_LOGS=path-name
Parameter
path-name
The full path to the directory used to store CTF trace log files.
Default
Not set. Uses the current working directory.

MFTSO_DEBUG

Controls the display of debug messages.

TX_MQTRACE

Enables tracing in dfh0mqis for WebSphere MQ calls.


Windows Environment variables

Lists environment variables related to configuring Enterprise Server for a Windows environment.
Parent topic: Environment Variables by Groups

COBPRFDIR

Location of .ipf files created by programs compiled with the PROFILE compiler directive.
Syntax
COBPRFDIR=path-name[[;path-name][...]]
Parameter
path-name
The full path of a directory to search.
Default
Not set. .ipf files are created in and expected to be in the current working directory.

COBPATH

Specifies the directory or directories that the run-time system searches for dynamically loadable .int and .gnt files, or callable shared objects.
Syntax
COBPATH=path-name[;path[...]]
Parameter
path-name
The full or relative path to a directory for the run-time system to search for a dynamically loadable program (.int, .gnt or callable shared object) file.
Default
None. Dynamically set based on enterprise server region configuration.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

When more than one path-name is specified, a null path name represents the current working directory.

Example
COBPATH=C:\mydir\srclib;;\otherlib

COBSW

Specifies the run-time system switch settings for the run-time system to observe when running an application.
Syntax
COBSW={+|-}switch[...]
Parameters
+
Sets the switch.
-
Unsets the switch.
switch
A run-time switch. See Run-time Switches for details.
Default
COBSW=-A
Example
This example enables run-time switch 0 and the ANSI COBOL debug switch:
COBSW=+0+D

DB2DBDFT

The default database against which the DB2 SQL preprocessor processes SQL statements.
Syntax
DB2DBDFT=path-name/database-name
Parameters
path-name
The location of the default database.
database-name
The name of the default database.
Default
Not set. Uses the database name specified in the project.

ENTRYNAMEMAP

Specifies the locations of entry-name map files to use.
Important: You must set the entry_point_mapper tunable to enable entry-point mapper support. See entry_point_mapper for details.
Syntax
ENTRYNAMEMAP={file-name|directory}[;...]
Parameters
file-name
The name of the entry-name map file.
directory
A directory containing an entry-name map file. The name of the entry-name map file must be mfentmap.dat.
Default
Not set. The run-time system searches for an entry-name map file called mfentmap.dat in each directory specified by the COBDIR environment variable.
Comments
If the run-time system finds more than one entry-name map file, and the same entry point is defined differently in different files, precedence is given to the definition in the entry-name map file that was found first. To change the order in which the run-time system finds entry name map files you need to change the order in which the files appear in the COBDIR or ENTRYNAMEMAP environment variable paths.

ES_CONSOLE_LOG (deprecated)

ES_CONSOLE_LOG (deprecated)
Sends console messages to the Windows Event Log.
Note: ES_CONSOLE_LOG is deprecated, and provided for backward compatibility only. We recommend that you use MFDS configuration options instead. For details, see the Windows Monitoring and Management section in the General Properties topic.
ES_CONSOLE_LOG={I|W|E|S}[...]
Parameters
I
Send informational messages to the Windows Event Log.
W
Send warning messages to the Windows Event Log.
E
Send error messages to the Windows Event Log.
S
Send severe messages to the Windows Event Log.
Default
Not set. No console messages are sent to the Windows Event log.

LANG

Specifies the locale.
Syntax
LANG=win-language[_territory[.code-page]]
Parameters
win-language
The spoken/written language in which your program is to run. This determines which message catalog is open so that if an error occurs, the error message is output in the selected language. win-language can take any of the following values:
Value | Language
1 | US English
2 | Canadian French
3 | Danish
4 | Dutch
5 | UK English
6 | Finnish
7 | French
8 | German
9 | Italian
10 | Norwegian
11 | Portuguese
12 | Spanish
13 | Swedish
territory
The country in which your program is to run.
code-page
The character set code to use for your program.
Default
Not set.
Example
LANG=7

MFLOGDIR

Specifies a directory to be used by Client/Server Binding for log files.
Syntax
MFLOGDIR=path-name
Parameter
path-name
The full path to the location of log files.
Default
Not set.
Example
MFLOGDIR=d:\mydir\logs

MFRU_NOINHERIT

Determines whether to skip registering processes in shared memory during initialization of the run-time system.
Syntax
MFRU_NOINHERIT={Y|TRUE}
Parameters
Y|TRUE
Do not register processes in shared memory during initialization of the run-time system.
Default
Not set. Processes are registered.
Comments
Consider setting this variable to avoid COBRT105 errors, which can occur during initialization if a very large number of COBOL processes are running and there are no available slots in the shared memory segment.

When set, various run-time settings such as switches, shared memory, console window settings, and so on, are no longer inherited by any child processes.

MFUSER

Enables you to change the user from the default User ID to an alternative ID.

OOSW

OO run-time switches.

XFHLOG

Determines the location of the log file when the LOG option is active.
Syntax
XFHLOG=DEFAULT
Parameter
DEFAULT
Generates the log file in the current working directory.
Default
Not set. The log file is generated in %ProgramData%\Micro Focus\File Handler\version-number, where version-number represents the version of your Micro Focus product.
Comments
The effect of this variable can be overridden by the LOGFILENAME configuration option.


Reserved Environment Variables

CAUTION:
These variables are for Micro Focus use only and must not be set unless advised to do so by OpenText Support for Micro Focus Products.
APPCLLU | ASLMFNET | BTRMAXREC
BTRPAGE | 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 |  | 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 | MFAUTOCTL_XREF_DSN
MF_ROOT_CERT | MF_SPPOOL_HK_TESTDATE | MFEDATA
MFDS_PORT | MFE.AMODE31ONLY | MFJCLHF
MFE-TRAP-IMS-AMP | MFIMS_DB_AUTOSTOP | MFJSENGINE
MFJCOMPARE.FILE | MFJDEBUG | MFMVSUSER
MFJSTATS | MFJUXITLOG | MFREXX_OR
MFREXX_LSEQ_RECSIZE_MAX | MFREXX_NOT | NLS_TIMESTAMP_FORMAT
MFUCC12 | NCG | TX_UNICLI_SESSIONS
TMF | XFH2BTR | XFHNODE
  • 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


Environment variables in alphabetical order

Tip: For information about how and where to set environment variables for Enterprise Server, see Setting Environment Variables, To set environment variables from ESCWA, and To set environment variables from the command line.
A | B | C | D | E | F | G | H | I | J | K | L | M
N | O | P | Q | R | S | T | U | V | W | X | Y | Z
Parent topic: Configuring Environment Variables
Related tasks
To edit an XA resource
Related information
To set environment variables from ESCWA
To set environment variables from the command line
Setting Environment Variables

A

AUTOCAT_IMP

Name of an input file name for automated catalog import using MFA Data Access Services.
AUTOCAT_IMP=[path-name\]file-name
Parameters
path-name
The full path to the location of the automatic catalog file name.
file-name
The name of the automated catalog import file.
Default
Not set.

C

CAS_SRV_CANCEL

Determines the cancel regime for service modules loaded by a SEP: the regime affects the request handler upon completion of the service module invocation.
Syntax
CAS_SRV_CANCEL={P|L|N|D}
Parameters
P
Physical cancel.
L
Logical cancel.
N
No cancel.
D
Deferred cancel.
Default
CAS_SRV_CANCEL=P
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Example
CAS_SRV_CANCEL=L
Related information
Advanced Region Properties

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.
Syntax
CASSPOOL_LOCK_RETRY_COUNT=retry-count
Parameter
retry-count
The number of retries made to obtain a record lock.
Default
CASSPOOL_LOCK_RETRY_COUNT=20

CCIERRLOG

Specifies the location of and filename for CCI error log output.
Syntax
CCIERRLOG=path-name\file-name
Parameters
path-name
The full path to the output location.
file-name
The name of the output file.
Default
Not set. The default path is the working directory of the application calling CCI, and the default filename is ccierr.log.
Comments
The CCI error log 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. See CCI.INI - The CCI Configuration File for more information.
Related information
CCI.INI - The CCI Configuration File

CCITCP2

Sets the TCP address of the machine running the MFDS (formerly CCITCP2) registration daemon.
Syntax
CCITCP2=host-name
Parameter
host-name
The TCP host name, IPv4 address, or IPv6 address of the machine running the MFDS daemon you want to contact from the session.
Default
Not set. The local system is used.
Comments
Use this environment variable to set the TCP address of the machine running the MFDS registration daemon, which holds the registration of the service you are contacting, or will hold the registration of the service you are starting.
Related information
Using CCITCP2
Open an Enterprise Server Data Set through ESMAC (deprecated)

CCITCP2_PORT

Sets the port used for the MFDS registration process.
Syntax
CCITCP2_PORT=port-number
Parameter
port-number
The number of the port on which the MFDS service is listening.
Default
Not set. Uses the port specified by the mfcobol service name in %WINDIR%\system32\drivers\etc\services . If not found there, uses the official Micro Focus directory port, which is 86.
Related information
mfds
mf-client.dat Configuration Options
Using CCITCP2

CCITCPS_service-name

Associates the name of a service being registered with a different service name, one or more ports, and/or one or more network interfaces.
Syntax
CCITCPS_old-service-name=[new-service-name],
   {MFNODE:node-name | MFPORT:port-number |
    MFNODE:node-name, MFPORT:port-number}
Parameters
old-service-name
The name of the CCI server.
new-service-name
The new name to use for the CCI server. If omitted, the old-service-name is used.
node-name
The host name or IP address on which to listen for connections.
port-number
The TCP port on which to listen for connections.
Default
Not set. A port is assigned by the operating system, and the server listens on all available network interfaces.
Comments
CCITCPS is set in the environment of a CCI server process, and changes how it listens for connections and how its service name is registered.
Example
CCITCPS_MYSERVICE=,MFPORT:3000

CCITCPT_service-name

Specifies the host, and/or port for a client to use when connecting to a service.
Syntax
CCITCPT_serice-name=[unused], MFNODE:node-name, MFPORT:port-number
Parameters
service-name
The name of the CCI service to which the client is to connect.
unused
The parameter before the comma is not used with CCITCPT, but supported for consistency with CCITCPS.
node-name
The host name or IP address to connect.
port-number
The TCP port to connect.
Default
Not set. The client attempts to look the service up in the MFDS directory.
Comments
Use this environment variable to instruct a CCI client to connect directly to the specified host and port rather than querying MFDS for the location of the named service.
Example
CCITCPT_MYSERVICE=,MFNODE:localhst.MFPORT:3000

CCITIMEOUT

Sets a maximum time-out period used with non-data connect applications.
Syntax
CCITIMEOUT=wait-time
Parameter
wait-time
The number of seconds to wait before timing out times 10, up to a maximum value of 2,147,483,647.
Default
CCITIMEOUT=1200

(2 minutes)

Comments
Use this variable with non-data connect applications such as Drag and Drop, SourceConnect, and the Monitor.
Example
This example sets the wait time to 4 minutes:
CCITIMEOUT=2400

CCITRACE

Specifies the type of information to record using CCI tracing.
Syntax
CCITRACE={/|-}{F|P|D}[...]
Parameters
/
Turns on the specified option.
-
Turns off the specified option.
F
Logs the details of CCI API calls to CTF. This option is implied when either P or D is specified. You can override this using -F.
P
When turned on, logs the details of protocol-level calls to CTF, which could greatly increase function tracing. When not set, only the details of the CCI user-level API are traced.
D
Logs the contents of all buffers passed to and from the CCI functions.
Warning: Setting this option might not produce the desired results if the application has been coded to prohibit data tracing.
Default
Not set. CCI tracing is controlled via the ctf.cfg and CCI.INI trace options.
Comments
The ctf.cfg and the CCI.INI file ([ccitrace_base] section) can also be used to control trace options, but any values specified by the CCITRACE environment variable take precedence. For details, see Tracing Options for CTF.CFG and CCI.INI - The CCI Configuration File.
Example
CCITRACE=/F/D
Related information
Tracing Options for CTF.CFG
CCI.INI - The CCI Configuration File

CICS_SIT

The name of the SIT used by the enterprise server region.
Syntax
CICS_SIT=sit-name
Parameter
sit-name
The name of the CICS SIT to use for the enterprise server region.
Default
Not set. The CICS SIT specified in ESCWA is used.
Related information
CICS Resources - SIT

CCITCPS_service-name

Associates the name of a service being registered with a different service name, one or more ports, and/or one or more network interfaces.
Syntax
CCITCPS_old-service-name=[new-service-name],
   {MFNODE:node-name | MFPORT:port-number |
    MFNODE:node-name, MFPORT:port-number}
Parameters
old-service-name
The name of the CCI server.
new-service-name
The new name to use for the CCI server. If omitted, the old-service-name is used.
node-name
The host name or IP address on which to listen for connections.
port-number
The TCP port on which to listen for connections.
Default
Not set. A port is assigned by the operating system, and the server listens on all available network interfaces.
Comments
CCITCPS is set in the environment of a CCI server process, and changes how it listens for connections and how its service name is registered.
Example
CCITCPS_MYSERVICE=,MFPORT:3000

COBCCSIDDIR

Specifies the location where the translation tables are installed for a deployed application that uses CCSID translation tables.
Syntax
COBCCSIDDIR=base-dir
Parameter
base-dir
The base directory containing sub-directories for each translation table.
Default
Not set. CCSID tables are installed by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer directory.

COBCONFIG

Specifies a run-time configuration file that tailors run-time configurable options in some way.
Syntax
COBCONFIG=path-name
Parameter
path-name
The directory that contains the COBOL configuration file, which tailors the run-time system.
Default
Not set. Enterprise Server searches for the file in $COBDIR/etc/cobconfig.
Example
COBCONFIG=C:\mydir\cobconfig
Related information
Run-time Configuration Tunables - Overview

COBCONFIG.BLOCK

The location of the application configuration file.
Syntax
COBCONFIG.BLOCK=path
Parameter
path
The full path to the location of the application configuration file.
Default
Not set.

COBCPY

Specifies the directory or directories that the Compiler and Animator should search for copybook files.
Syntax
COBCPY=path-name[[;path-name][...]]
Parameter
path-name
The full path to a directory that the Compiler and Animator are to search when looking for copybook files. When more than one path-name is present, a null path-name represents the current working directory.
Default
COBCPY=%COBCPY%;C:\Program Files (x86)\Micro Focus\Enterprise Developer\cpylib;
   C:\Program Files (x86)\Micro Focus\Enterprise Developer\cpylib\basecl;
   C:\Program Files (x86)\Micro Focus\Enterprise Developer\cpylibguicl;
   C:\Program Files (x86)\Micro Focus\Enterprise Developer\cpylibolecl
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.
Example

The following causes the Compiler to search for a copybook in C:\group\sharedcopy, then in the current directory, and finally in C:\mydir\mycpy until either the copybook is found or it can be considered not found.

COBCPY=C:\group\sharedcopy;.;C:\mydir\mycpy

COBDATA

Specifies the directory or directories that the run-time system is to search for data files.
Syntax
COBDATA=path-name[[;path-name][...]]
Parameter
path-name
The full path to a directory for the run-time system to search for application data files. When more than one path-name is present, a null path-name represents the current working directory.
Default
Not set. The run-time searches the current working directory.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

COBDATA provides you with the facility to map data files globally, thus enabling you to put working data files in a directory whose name is not known until run time.

COBDATA affects the compiler and other utilities. During compilation, for example, program source is regarded as a data file by the compiler. If you intend to use any COBOL development system utilities, we recommend that the COBDATA value starts with a colon (:).

COBDATA is considered set if there is an environment variable of this name in your environment space, and its value is non-empty.

The full mapping order for files is:

  1. Any dd_ environment mappings
  2. Any ASSIGN TO EXTERNAL mappings
  3. Any COBDATA environment variable mappings

For multiple directory paths specified either in the COBDATA environment variable or a dd_ environment variable, the system searches the first directory specified followed by a slash (/) as a prefix to the user name.

If the filename is not found, or is not readable, the search continues with the next directory until the final directory has been searched. If no file is found, the first directory is used if a file is to be created.

Any dd_ and COBDATA mappings are ignored for any filename that starts with a hyphen () or a slash (/). In addition, it is illegal to have a hyphen in an environment variable name.

When using this facility, you should not use a filename that starts with "COB... "(these are reserved for the COBOL system).

You can use the COBDATA environment variable for files open in any mode (including OUTPUT) and for fixed or variable length files. If you are using indexed files, both the data and index files must be in the same directory.

The COBDATA environment variable affects file deletes, using the rules given here, as well as file opens.

If you intend to use COBOL development system programs, we recommend that you first unset COBDATA, as many of these programs open data files and are thus affected by the value of COBDATA. If you have to set COBDATA, you should include the paths :$COBDIR/dynload/helptbox.lbr and :$COBDIR/dynload/check.lbr at the beginning of the COBDATA value. If you want to see the Animator Help pages, also include COBDIR/dynload/advanim.lbr.

Example

The following causes COBDATA to be set to instruct the run-time system to search for data files in the current directory, then in the current directory's demo subdirectory, and finally in the C:\data\progs directory.

COBDATA=.;.\demo;C:\data\progs

COBDIR

Specifies the directory where Enterprise Server is installed. Many system components and utilities require and use this information.
Syntax
COBDIR=path-name
Parameter
path-name
The directory that contains the required Micro Focus COBOL system software.
Default
Not set. The default path is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer /opt/microfocus/EnterpriseDeveloper .
Comments

The Micro Focus COBOL system is normally installed in the default COBOL system directory and so does not require COBDIR to be set. COBDIR only needs to be set when your COBOL system has been installed in a different directory such as when more than one version of the COBOL system is available at the same time.

Example

This example causes the compiler to search the directory C:\products\cobse20 for the Micro Focus COBOL system software:

COBDIR=C:\products\cobse20
Related information
ENTRYNAMEMAP

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.
Syntax
COBKEYTIMEOUT=trans-time
Parameter
trans-time
A number in the range 1 through 126 that represents the maximum elapsed time required for a terminal to transmit any valid escape sequence to the run-time system over the line or network connection.
Default
Not set.
Comments
On encountering a lone Escape character, the run-time system waits n tenths of a second before assuming that the character does not introduce an escape sequence.

The run-time system calculates an appropriate default value for n from the baud rate of the terminal.

When a terminal key is depressed, the terminal might send in response a single character or a group of characters to the run-time system. Typically, such a group of characters starts with an escape character and the group of characters is known as an escape sequence. A terminal might send an escape sequence for one depression of a function key. It might also send the same sequence of characters for a depression of the Escape key followed by the depression of one or more alphabetic or numeric data keys. The only difference apparent to the run-time system is the interval between the arrival of each character? the user cannot type as fast as the escape sequence is generated by the terminal.

If a terminal is connected over a network that sends the characters to the run-time system in discrete packets, then the network can alter the intervals between each character arriving at the run-time system. COBKEYTIMEOUT is available to help compensate for typical network delays so the run-time system identifies escape sequences correctly.

COBLANG

Sets the language environment in which your COBOL program runs.
Syntax
COBLANG=LE-option
Parameter
LE-option
A COBOL language environment (LE) option.
Default
Not set.

COBMAINSTACK

Specifies the size of the main stack.
Note: This variable applies to native COBOL applications on UNIX, and Enterprise Server on both Windows and UNIX.
Syntax
COBMAINSTACK=stack-size
Parameters
stack-size
The size of the main stack in bytes.
Default
Not set.
Comments
The main stack size defaults to three times the size of a threaded stack. The size of a threaded stack is either specified when the stack is created (using CBL_THREAD_CREATE), or it defaults to 160KB for a 32-bit application or 320KB for a 64-bit application.

You might need to set COBMAINSTACK in any of the following circumstances:

  • If you are deploying native OO COBOL Enterprise JavaBeans (EJBs) to WebSphere on the AIX platform.
  • If you are using the multi-threaded run-time system.
  • If you have IF STATEMENTS with a very large number of ELSE clauses.
  • If you have a large amount of local-storage data.

COBPATH

Specifies the directory or directories that the run-time system searches for dynamically loadable .int and .gnt files, or callable shared objects.
Syntax
COBPATH=path-name[;path[...]]
Parameter
path-name
The full or relative path to a directory for the run-time system to search for a dynamically loadable program (.int, .gnt or callable shared object) file.
Default
None. Dynamically set based on enterprise server region configuration.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

When more than one path-name is specified, a null path name represents the current working directory.

Example
COBPATH=C:\mydir\srclib;;\otherlib

COBPRFDIR

Location of .ipf files created by programs compiled with the PROFILE compiler directive.
Syntax
COBPRFDIR=path-name[[;path-name][...]]
Parameter
path-name
The full path of a directory to search.
Default
Not set. .ipf files are created in and expected to be in the current working directory.

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.
Syntax
COBPRINTER="command-line"
Parameter
command-line
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.
Default
Not set.
Comments
Each DISPLAY UPON PRINTER statement executed by your COBOL program causes a new invocation of command-line. Each invocation receives the data referenced in the DISPLAY statement, and is followed by a system end-of-file condition.
Example
COBPRINTER="myspooler -a %TMPDIR%\spoolfile"

COBSW

Specifies the run-time system switch settings for the run-time system to observe when running an application.
Syntax
COBSW={+|-}switch[...]
Parameters
+
Sets the switch.
-
Unsets the switch.
switch
A run-time switch. See Run-time Switches for details.
Default
COBSW=-A
Example
This example enables run-time switch 0 and the ANSI COBOL debug switch:
COBSW=+0+D
Related information
Run-time Switches

CTM_SPACE

Enables you to change the default MFBSI behavior for handling spaces in AutoEdit variable values to mimic the z/OS behavior.
Syntax
CTM_SPACE={[ON|YES]|[OFF|NO]}
Parameters
ON|YES
Handle spaces using the MFBSI behavior, meaning allow embedded spaces in CTM variables.
OFF|NO
Handle spaces using the z/OS behavior, meaning do not allow embedded spaces in CTM variables.
Default
CTM_SPACE=ON
Comments
Control-M (CTM) for z/OS does not support embedded spaces in variable values. The default CTM behavior of MFBSI supports spaces, and in the case of AutoEdit variable values, removes the spaces and assigns the rest of the value to the variable. To mimic the z/OS behavior for handling spaces in AutoEdit variables, set CTM_SPACE=OFF.

D

DB2DBDFT

The default database against which the DB2 SQL preprocessor processes SQL statements.
Syntax
DB2DBDFT=path-name/database-name
Parameters
path-name
The location of the default database.
database-name
The name of the default database.
Default
Not set. Uses the database name specified in the project.

DBG_MVSPSKEL

The skeleton JCL for debugging.

E

ENTRYNAMEMAP

Specifies the locations of entry-name map files to use.
Important: You must set the entry_point_mapper tunable to enable entry-point mapper support. See entry_point_mapper for details.
Syntax
ENTRYNAMEMAP={file-name|directory}[;...]
Parameters
file-name
The name of the entry-name map file.
directory
A directory containing an entry-name map file. The name of the entry-name map file must be mfentmap.dat.
Default
Not set. The run-time system searches for an entry-name map file called mfentmap.dat in each directory specified by the COBDIR environment variable.
Comments
If the run-time system finds more than one entry-name map file, and the same entry point is defined differently in different files, precedence is given to the definition in the entry-name map file that was found first. To change the order in which the run-time system finds entry name map files you need to change the order in which the files appear in the COBDIR or ENTRYNAMEMAP environment variable paths.
Related information
entry_point_mapper
COBDIR

ES_3270_REMOVE_NULL_COLOR_ATTRIB

Sets the extended color attribute to low-values and does not send it to the 3270 emulator.
Syntax
ES_3270_REMOVE_NULL_COLOR_ATTRIB=Y
Parameter
Y
Sets the extended color attribute to low-values and does not send it to the 3270 emulator.
Default
Not set. Enterprise Server uses the default screen size.
Comments
This fixes an IBM issue related to Personal Communications (PCOM) which is described at http://www-01.ibm.com/support/docview.wss?uid=swg21461404.

ES_ABORT_PLTPI_ERROR

Enables the user to set the error on which to abort PLTPI processing, bypassing the prompt.
Syntax
ES_ABORT_PLTPI_ERROR={YN|NY|YY}
Parameters
YN
Abort on PGMIDERR.
NY
Abort on ABEND.
YY
Abort on PGMIDERR or ABEND.
Default
Not set. When an error occurs during PLTPI processing, mainframe CICS enterprise servers display a prompt that enables the user to cancel the startup or ignore the error.
Comments
Set ES_ABORT_PLTPI_ERROR to bypass the prompt and automatically abort the initialization as dictated by the value provided.

ES_ACBLIB

Specifies the location of the IMS ACB files.
Syntax
ES_ACBLIB=path-name
Parameter
path-name
The path location of the IMS ACB files.
Default
Not set. ACB files are assumed to be in the project directory.
Related information
IMS Configuration

ES_ALLOC_EXPAND

Expands an environment variable when used to specify an allocation path, or overrides this behavior.
Syntax
ES_ALLOC_EXPAND={Y|N}
Parameters
Y
Expand the environment variable used to specify an allocation path.
N
Do not expand the variable used in the path.
Default
ES_ALLOC_EXPAND=Y

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.
Syntax
ES_ALLOC_OVERRIDE=path-name\rules-file
Parameters
path-name
The full path to the dataset rules file.
rules-file
The name of the dataset rules file.
Default
Not set.
Related information
Controlling where Datasets are Created

ES_CAT_RETRY_COUNT

Determines the number of attempts made to open a catalog file that has produced an error when the initial attempt to open it was made.
Syntax
ES_CAT_RETRY_COUNT=attempt-count
Parameter
attempt-count
The number of attempts made to open a catalog file.
Default
ES_CAT_RETRY_COUNT=0
Comments
Use this variable in conjunction with the ES_CAT_RETRY_WAIT variable, which determines how long to wait in between each attempt.

Take care when setting these variables as they could impact the time taken to report an error and therefore will delay processing of a job whilst the checks take place. These variables can be useful if you experience file access problems (for example, network connection drop-outs) that only last a second or two, so that it gives the system a chance to recover, before aborting.

Related information
ES_CAT_RETRY_WAIT

ES_CAT_RETRY_WAIT

Determines the amount of time (in seconds) to wait between attempts made to open a catalog file that has produced an error when the initial attempt to open it was made.
Syntax
ES_CAT_RETRY_WAIT=wait-time
Parameter
wait-time
The number of seconds to wait between attempts made to open a catalog file.
Default
ES_CAT_RETRY_WAIT=0
Comments
Use this variable in conjunction with the ES_CAT_RETRY_COUNT variable, which determines how many attempts to make to open a catalog file that initially failed to open.

Take care when setting these variables as they could impact the time taken to report an error and therefore will delay processing of a job whilst the checks take place. These variables can be useful if you experience file access problems (for example, network connection drop-outs) that only last a second or two, so that it gives the system a chance to recover, before aborting.

Related information
ES_CAT_RETRY_COUNT

ES_CERT_REG

Specifies the directory in which the cascertreg user certificate utility should store its registrations.
Syntax
ES_CERT_REG=path-name
Parameter
path-name
Full path to the directory where registrations are stored.
Default
None; however, if omitted, you must specify the directory using the cascertreg command.
Related information
cascertreg

ES_CESN_NO_OS390

Overrides the default CESN transaction and the IMS sign-on screen response behavior for invalid user credentials.
Syntax
CESN_NO_OS390=ON
Parameter
ON
Override the default CESN transaction and IMS sign-on screen response behavior for invalid credentials, and instead produce an invalid credential message.
Default
Not set. CESN transaction and IMS sign-on screen response is Your userid is invalid or Your password is invalid.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

Related information
Advanced Region Properties

ES_CICS_SINGLE

Configures CICS so that a user can only log on once when the enterprise server region is running in a PAC with CICS enabled.
Syntax
ES_CICS_SINGLE={Y|N}
Parameters
Y
A user can only log on once.
N
The same user may sign on to multiple terminals with CICS.
Default
ES_CICS_SINGLE=Y
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XCMD

Controls the CICS CMD resource class.
Syntax
ES_CLASS_XCMD={YES|NO|class-name}
Parameters
YES
CICS CMD is the default CMD class.
NO
Security for CMDs is bypassed.
class-name
The name of a class to override the default CMD CICSCMD class.
Default
ES_CLASS_XCMD=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XDCT

Controls the CICS DCT resource class.
Syntax
ES_CLASS_XDCT={YES|NO|class-name}
Parameters
YES
DCICSDCT is the default DCT class.
NO
Security for DCTs is bypassed.
class-name
The name of a class to override the default DCT DCICSDCT class.
Default
ES_CLASS_XDCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XFCT

Controls the CICS FCT resource class.
Syntax
ES_CLASS_XFCT={YES|NO|class-name}
Parameters
YES
FCICSFCT is the default FCT class.
NO
Security for FCTs is bypassed.
class-name
The name of a class to override the default PCT FCICSFCT class.
Default
ES_CLASS_XFCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XJCT

Controls the CICS JCT resource class.
Syntax
ES_CLASS_XJCT={YES|NO|class-name}
Parameters
YES
JCICSJCT is the default JCT class.
NO
Security for JCTs is bypassed.
class-name
The name of a class to override the default JCT JCICSJCT class.
Default
ES_CLASS_XJCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XPCT

Controls the CICS PCT resource class.
Syntax
ES_CLASS_XPCT={YES|NO|class-name
Parameters
YES
ACICSPCT is the default PCT class.
NO
Security for PCTs is bypassed.
class-name
The name of a class to override the default PCT ACICSPCT class.
Default
ES_CLASS_XPCT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XPPT

Controls the CICS PPT resource class.
Syntax
ES_CLASS_XPPT={YES|NO|class-name}
Parameters
YES
MCICSPPT is the default PPT class.
NO
Security for PPTs is bypassed.
class-name
The name of a class to override the default PPT MCICSPPT class.
Default
ES_CLASS_XPPT=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XPSB

Controls the CICS PSB resource class.
Syntax
ES_CLASS_XPSB={YES|NO|class-name}
Parameters
YES
PCICSPSB is the default PSB class.
NO
Security for PSBs is bypassed.
class-name
The name of a class to override the default PSB PCICSPSB class.
Default
ES_CLASS_XPSB=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XRES

Controls the CICS DOCTEMPLATE resource class.
Syntax
ES_CLASS_XRES={YES|NO|class-name}
Parameters
YES
RCICSRES is the default RES class.
NO
Security for DOCTEMPLATEs is bypassed.
class-name
The name of a class to override the default RES RCISRES class.
Default
ES_CLASS_XRES=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XTRAN

Controls the CICS TRAN resource class.
Syntax
ES_CLASS_XTRAN={YES|NO|class-name}
Parameters
YES
TCICSTRN is the default TRAN class.
NO
Security for TRANs is bypassed.
class-name
The name of a class to override the default TRAN TCICSTRN class.
Default
ES_CLASS_XTRAN=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLASS_XTST

Controls the CICS TST resource class.
Syntax
ES_CLASS_XTST={YES|NO|class-name}
Parameters
YES
SCITST is the default TST class.
NO
Security for TSTs is bypassed.
class-name
The name of a class to override the default TST SCITST class.
Default
ES_CLASS_XTST=YES
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CLUSTER

Identifies a region as participating in an Enterprise Server cluster.
Syntax
ES_CLUSTER=ON
Parameter
ON
Sets the region to participate in an Enterprise Server cluster.
Default
Not set. The enterprise server region does not participate in an Enterprise Server cluster.
Comments
Mandatory for all enterprise server regions in a cluster.

ES_CLUSTER_ISC_TRACE

Enables tracing on the Enterprise Server cluster ISC listeners.
Syntax
ES_CLUSTER_ISC_TRACE=ON
Parameter
ON
Tracing of ISC listeners for an Enterprise Server cluster is enabled.
Default
Not set. Enterprise Server cluster ISC listeners are not traced.

ES_CLUSTER_LISTENER_PORT_TO_USE

Sets a specific port for an Enterprise Server cluster listener.
Syntax
ES_CLUSTER_LISTENER_PORT_TO_USE=port-number
Parameter
port-number
The port number to assign to a cluster listener.
Default
Not set. The Enterprise Server cluster listener uses an ephemeral port.

ES_CLUSTER_SYSTEM_DIR (deprecated)

Sets the system directory for an Enterprise Server cluster listener.
Note: ES_CLUSTER_SYSTEM_DIR is deprecated, and provided for backward compatibility only.
Syntax
ES_CLUSTER_LISTENER_PORT_TO_USE=path-name
Parameter
path-name
The full path to the cluster system directory.
Default
ES_CLUSTER_SYSTEM_DIR=%PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CLUSTER\system

ES_CONSOLE_LOG (deprecated)

ES_CONSOLE_LOG (deprecated)
Sends console messages to the Windows Event Log.
Note: ES_CONSOLE_LOG is deprecated, and provided for backward compatibility only. We recommend that you use MFDS configuration options instead. For details, see the Windows Monitoring and Management section in the General Properties topic.
ES_CONSOLE_LOG={I|W|E|S}[...]
Parameters
I
Send informational messages to the Windows Event Log.
W
Send warning messages to the Windows Event Log.
E
Send error messages to the Windows Event Log.
S
Send severe messages to the Windows Event Log.
Default
Not set. No console messages are sent to the Windows Event log.
Related information
General Properties

ES_CSKL_NO_MSG_CONSOLE

Stops the EZ Sockets CICS listener (CSKL) from writing messages to console.log.
Syntax
ES_CSKL_NO_MSG_CONSOLE=ON
Parameter
ON
CSKL does not write message to console.log.
Default
Not set. CSKL writes messages to console.log.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_CWS_WSBIND_COMP

Enables support for CICS applications that use COMP declarations.
Syntax
ES_CWS_WSBIND_COMP={Y|N}
Parameters
Y
Enables support for COMP declarations in CICS applications.
N
Support for COMP declarations is disabled for CICS applications.
Default
ES_CWS_WSBIND_COMP=N

ES_DB_FH

Enables or disables database file handler support. This is required if your data files are stored in a datastore, or your enterprise server region stores some of its resources in a database; see Micro Focus Database File Handler and Enterprise Server Region Database Management for more information.
Syntax
ES_DB_FH={[Y|true]|[N|false]}
Parameters
Y|true
Use the Micro Focus Database File Handler (MFDBFH) to direct file handling.
N|false
Disable database file handling.
Default
ES_DB_FH=N
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Database File Handling and Enterprise Server Region Database Management
Advanced Region Properties

ES_DB_SERVER

Specify the name of the database server to be used for region database operations.
Important: The configuration file specified by the MFDBFH_CONFIG environment variable must contain a corresponding <server> entry for the database server. <dsn> entries for the region, cross-region, and master databases must also be specified in the configuration file to enable use of region database operations.
Syntax
ES_DB_SERVER=server-instance
Parameter
server-instance
The name of a valid database server instance.
Default
Not set.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Example
ES_DB_SERVER=MYSERVER

In this example, your database configuration file would need to contain something similar to the following:

<datastores usevault="false">
   <server name="MYSERVER" type="sqlserver" access="odbc">
       <dsn name="SS.MYMASTER" type="database" dbname="master"/>
       <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO"
          feature="all"/>
       <dsn name="SS.CAS.CROSSREGION" type="crossregion.cas"/>
   </server>
</datastores>
Related information
Advanced Region Properties
MFDBFH_CONFIG

ES_DDBG_PORT_RANGE

A range of ports to use for dynamic debugging.
Syntax
ES_DDBG_PORT_RANGE={starting-port-number-ending-port-number |
   starting-port-number,number-of-ports
Parameters
starting-port-number
A port number that represents the start of the range.
ending-port-number
A port number that represents the end of the range. This number must be greater than the value of starting-port-number. All available ports within the range are used.
number-of-ports
The total number of ports. The ports used include those available, starting with the starting-port-number port and continuing with ports greater than the starting-port-number port, up to the total number specified.
Default
Not set. Dynamic debugging uses random ports.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Examples
The following specifies that all available ports from 8001 through 8040 are to be used:
ES_DDBG_PORT_RANGE=8001-8040

The following specifies using the next 40 available ports with a port number higher than the starting port number:

ES_DDBG_PORT_RANGE=8001,40
Related information
Advanced Region Properties

ES_DFS3650

Specifies the default transaction to execute or the MOD file display after successfully signing onto IMS.
Syntax
ES_DFS3650={MOD|TRX}
Parameters
MOD
Set ES_MOD3650 to the name of the MOD you want to display.
TRX
Set ES_TRX3650 to the name of the transaction.
Default
Not set. No transaction or MOD executes after successfully signing onto IMS.
Comments
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_DISABLE_DFLTUSR_SIGNON

Disables the default user (mfuser) signon when invoking ES Monitor & Control (ESMAC).
Syntax
ES_DISABLE_DFLTUSR_SIGNON=Y
Parameter
Y
Disables the mfuser auto-logon after starting Enterprise Server administration via your MFDS internal security account.
Default
Not set. mfuser is signed in to ESMAC.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Restricting administrative access
Advanced Region Properties

ES_DSENQSHR

Enable and configure handling of the DSENQSHR keyword when it is specified on the JCL job card, and when it is not specified on the job card.
Syntax
ES_DSENQSHR={ALLOW|AUTO|DISALLOW}
Parameters
ALLOW
For JCL jobs that have the DSENQSHR keyword specified on the JCL job card, sets DSENQSHR to the value specified on the job card. For jobs that do not have the DSENQSHR keyword specified on the JCL job card, sets DSENQSHR=ALLOW for each of those jobs.
AUTO
Use the value specified on the JCL Job card, which sets ES_DSENQSHR to ALLOW when that value is either ALLOW or USEJC, and DISALLOW otherwise.
DISALLOW
For jobs that do not have the DSENQSHR keyword specified on the JCL job card, sets DSENQSHR=DISALLOW for each of those jobs.
Default

When the job card does not specify the DSHQSHR keyword or when the job card sets DSENQSHR to USEJC:

ES_CAT_RETRY_WAIT=ES_DSENQSHR=DISALLOW

When the job card specifies the DSENQSHR keyword, the value of DSENQSHR is used.

Comments
When DSENQSHR is allowed on a job, exclusive dataset locks are downgraded to SHARED after performing the last step that requires an exclusive lock.

Exclusive locks resulting from a dynamic exclusive enque (for example an IDCAMS DELETE operation) are maintained as exclusive until the end of the job regardless of the DSENQSHR setting.

Use VSAM Share options with VSAM datasets. You can enable these by setting the ES_SHAREOPT environment variable to Y.

ES_ECI_MAX_RESP

Specifies the maximum expected response size to use when using Micro Focus ECI support to invoke CICS programs.
Syntax
ES_ECI_MAX_RESP=resp-size
Parameter
resp-size
A decimal from 1 to 16777215 representing the maximum expected response size in bytes.
Default
Not set. The maximum expected response size is calculated dynamically by multiplying the size of the TIOA by 2.
Comments
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_EMP_EXIT_n

ES_EMP_EXIT_n
Specifies the number of Event Manager user exits for the region.
ES_EMP_EXIT_n=batch-component
Parameters
n
A single digit ranging from 1 through 9, depending on the number of Event Manager user exits for the region.
Note: This must be set to 1 when mfbsiemx is the only Event Manager user exit for the region.
batch-component
An event manager component.
Default
Not set.
Comments
You must set ES_EMP_EXIT once for each Event Manager used in the region.

When setting ES_EMP_EXIT multiple times, they must be set in numerical order.

Example
ES_EMP_EXIT_1=mfbsiemx
ES_EMP_EXIT_2=mfmonemx
ES_EMP_EXIT_3=...

ES_ESM_DISABLE_DFLTUSER_ESMAC

Allows you to disable the default ESMAC user to increase the security of your server.
Syntax
ES_ESM_DISABLE_DFLTUSER_ESMAC=Y
Parameter
Y
Disables the default ESMAC user, disables the DEFAULT button on the logon screen, and forces users to always enter a valid user ID and password.
Default
Not set. The ESMAC user is enabled.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Restricting administrative access
Advanced Region Properties

ES_ELAPSED_DISPATCH_SECONDS

Specifies how frequently casmgr checks for Jobs in the waiting state and then starts them.
Syntax
ES_ELAPSED_DISPATCH_SECONDS=wait-time
Parameter
wait-time
The number of seconds that casmgr waits before checking for Jobs in the waiting state and then starting them.
Default
ES_ELAPSED_DISPATCH_SECONDS=5

ES_ESM_CMDSEC

Indicates whether CICS processing honors the CMDSEC option specified on a transaction's PLT definition.
Syntax
ES_ESM_CMDSEC=YES
Parameter
YES
CICS overrides the CMDSEC option, and always calls its command security checking routine to issue the appropriate call to the SAF interface.
Default
Not set. 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.

ES_ESM_IDPW_CASE

Forces the case of user ID and password for a single attempt ESM authentication.
Syntax
ES_ESM_IDPW_CASE=xy
Parameters
x
Specifies the case for the user ID. Use one of the following:
U | All upper case
L | All lower case
M | Mixed case and case-sensitive
y
Specifies the case for the password. Use one of the following:
U | All upper case
L | All lower case
M | Mixed case and case-sensitive
Default
Not set. Uses legacy behavior.
Comments
When this environment variable is set, Enterprise Server makes only one attempt to identify a user presenting the user ID and password as is (M), folded to upper case (U), or folded to lower case (L).

For the legacy behavior for CICS, the user ID and the password are used as supplied possibly filtered by the upper-case translation configuration of the sign-on transaction.

For ESMAC and IMS, the legacy behavior is that, first, the user ID and password are used as supplied. If the authentication fails, the user ID is folded to upper case and used again. If this fails as well, both the user ID and the password are folded to upper case and then used.

Example
This example tries a single authentication with the user ID folded to upper case, and the password used as-is:
ES_ESM_IDPW_CASE=UM

ES_ESM_PLTPISEC

The level of security checking for PLTPI processing.
Syntax
ES_ESM_PLTPISEC={NONE|CMDSEC|RESSEC|ALL}
Parameters
NONE
No security checking is performed on PLT initialization programs.
CMDSEC
CICS performs command security checking only.
RESSEC
CICS performs resource security checking only.
ALL
CICS performs both command and resource security checking.
Default
ES_ESM_PLTPISEC=NONE
Related information
ES_ESM_PLTPIUSR

ES_ESM_PLTPIUSR

Specifies the user ID under which PLT programs run during CICS initialization.
Syntax
ES_ESM_PLTPIUSR=userid
Parameter
userid
The user ID for CICS to use for security checking for PLT programs that run during CICS initialization.
Default
Not set. The user specified when starting the CICS-enabled enterprise server region is used.
Comments

The user ID specified must have appropriate authorization to access all the resources used by the programs as determined by the ES_ESM_PLTPISEC environment variable.

Related information
ES_ESM_PLTPISEC

ES_ESM_RCF

Determines how RACF is used for command authorization.
Syntax
ES_ESM_RCF={A|C|N|S|T|Y}
Parameters
A
A combination of options T, C, and S.
C
Use RACF for ETO terminal command authorization.
N
RACF does not perform sign-on, transaction, or command authorization.
S
Use RACF for static and ETO terminal command authorization. Includes option C.
T
Use RACF for sign-on and transaction authorization.
Y
A combination of options T and C.
Default
ES_ESM_RCF=N

ES_ESM_RESSEC

Indicates whether CICS processing honors the RLS security setting specified on a transaction definition (PCT).
Syntax
ES_ESM_RESSEC=ALWAYS
Parameter
ALWAYS
CICS processing always performs resource level security checking irrespective of the RLS security setting on the transaction definition.
Default
Not set. The RLS security setting of a transaction is honored. That is, resource-level security checking is performed only when the RLS security checkbox is marked in the PCT definition.

ES_ESM_SECPRFX

Indicates whether CICS processing adds a prefix to resource names when making security queries.
Syntax
ES_ESM_SECPRFX={NO|YES|prefix}
Parameters
NO
Use no prefixes.
YES
Uses prefix resource names with the CICS region user ID.
prefix
Define a prefix for resource names as an alphanumeric string that starts with an alphabetic character, and is one to eight upper-case characters in total.
Default
ES_ESM_SECPRFX=NO
Comments
This environment variable is applied only to CICS classes.

ES_ESM_XUSER

Indicates whether CICS processing performs surrogate user checks.
Syntax
ES_ESM_XUSER={NO|YES}
Parameters
NO
No surrogate user checking is performed.
YES
Perform surrogate user checking wherever such checks are permitted.
Default
ES_ESM_XUSER=YES

ES_ESMAC_DISP_MAX_OVERRIDE

Limits the number of lines shown when viewing an individual catalog entry in the ESMAC catalog view or when viewing a SYSOUT file from the job list view.
Syntax
ES_ESMAC_DISP_MAX_OVERRIDE=value
Parameter
value
An integer denoting the number of lines to display to a maximum of 99999.
Default
ES_ESMAC_DISP_MAX_OVERRIDE=1000
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_EUSA_SIZE

Sets the size of the extended user storage area, allowing large memory allocations to be set using the GETMAIN SHARED command.
Syntax
ES_EUSA_SIZE=number
Parameter
number
A numeric value representing the number of MB to allocate for the extended user storage area.
Default
ES_EUSA_SIZE=16

ES_EZASOKET_SUPPORT (deprecated)

Switches on EZASOKET support.
Note: ES_EZASOKET_SUPPORT is deprecated, and provided for backward compatibility only. We recommend that you configure EZASOKET using ESCWA instead.
Syntax
ES_EZASOKET_SUPPORT=Y
Parameter
Y
Turns on EZASOCKET support.
Default
Not set. EZASOCKET is not supported.
Comments
Parameter value is not case sensitive.

ES_GLM

If this variable is set, it identifies the region as an Enterprise Server cluster Global Lock Manager (GLM).
Syntax
ES_GLM=ON
Parameter
ON
Identify the region as a GLM.
Default
Not set. The region is not identified as a GLM.
Comments
This environment variable is considered to be turned on when set to any value, including ON.
Related information
Configuration

ES_GLM_TIMEOUT

Sets the amount of time that can pass while a submit request to an Enterprise Server cluster Global Lock Manager (GLM) is retried and before permanently disabling the connection.
Syntax
ES_GLM_TIMEOUT=number
Parameter
number
The number of seconds during which a retry is attempted and before disabling the connection.
Default
ES_GLM_TIMEOUT=120
Comments
This variable only applies to the region within an Enterprise Server cluster designated as the GLM.
Related information
Configuration

ES_HARD_KILL_PROCESS

Enables you to modify how Enterprise Server kills a process.
Syntax
ES_HARD_KILL_PROCESS={Y|N}
Parameters
Y
Issue a hard kill after a soft kill when the soft kill fails.
N
No hard kill is attempted after the soft kill.
Default
ES_HARD_KILL_PROCESS=Y
Comments
This variable only applies to the region within an Enterprise Server cluster designated as the Global Lock Manager (GLM).

ES_HOSTNAME_TO_USE

In an Enterprise Server Cluster, if a machine uses more than one network card, you might need to set this variable to identify the host MFCS should use.
Syntax
ES_HOSTNAME_TO_USE=host-name
Parameter
host-name
The host name that matches the network card you want to use.
Default
Not set. MFCS uses the local host.

ES_HSF_CFG

Enables you to configure a number of additional fields to appear in the HSF record displayed in the cashsf-a.csv or cashsf-b.csv file.
Syntax
ES_HSF_CFG=cfg-option=value[;[cfg-option=value][...]]
Parameters
cfg-option=value
One or more of the following option/value pairs:
cfg-option | value range
CUSTOM | 0-5
CICSF | 0-20
TSQ | 0-20
TDQ | 0-20
Default
ES_HSF_CFG=CUSTOM=0;CICSF=5;TSQ=5;TDQ=5
Comments
If a field is not explicitly set, or the value specified is out of range, the default value for the field is used.

The ES_WRITE_CUSTOM_HSF library routine writes to the custom fields.

Example
The following generates two custom fields, ten CICS file fields, five TSQ fields, and five TDQ fields.
ES_HSF_CFG=CUSTOM=2;CICSF=10;TSQ=5;TDQ=5
Related information
Configuring and Starting Transaction Data Collection
Analyzing Aggregated HSF Data in .csv Files
Viewing HSF Information as a .csv File

ES_IEBGEN_TO_ICEGEN

Determines enablement of VSAM copy using the MFGENER utility.
Syntax
ES_IEBGEN_TO_ICEGEN={Y|N}
Parameters
Y
Enables VSAM copy using the MFGENER utility.
N
Disables VSAM copy using the MFGENER utility.
Default
ES_IEBGEN_TO_ICEGEN=N

ES_IMS_APARM_DLI

Determines whether APARMs use ASCII and a positional parameter set to 19 when obtained from EBCDIC applications, or use EBCDIC and a positional parameter set to 20 when obtained from EBCDIC applications.
Syntax
ES_IMS_APARM_DLI={Yes|1}
Parameters
Yes|1
Sets the APARM positional parameter for DLI to 19.
Default
Not set. The default behavior sets the APARM positional parameter for DLI to 20.
Comment
The APARM positional parameter for BMP applications remains at 19 regardless of the ES_IMS_APARM_DLI setting.

ES_IMS_BASIC_CHKP_OPT

Enables a basic checkpoint call to process as if a SYNC call had been issued.
Syntax
ES_IMS_BASIC_CHKP_OPT={0|1}
Parameters
1
Checkpoint calls process as a SYNC call.
0
Checkpoint calls process normally.
Default
ES_IMS_BASIC_CHKP_OPT=0

ES_IMS_BYPASS_OTMA_DEST_RES

By default, a CHNG call issued from an OTMA- or IMS Connect-submitted transaction assumes that the destination is the OTMA client.
Syntax
ES_IMS_BYPASS_OTMA_DEST_RES={Y|N}
Parameters
Y
The destination is the OTMA client.
N
Assumes a non-OTMA client.
Default
ES_IMS_BYPASS_OTMA_DEST_RES=N
Comments
In some circumstances, the behavior of assuming a non-OTMA client is desirable.
Example
ES_IMS_BYPASS_OTMA_DEST_RES=Y

ES_IMS_CANCEL_MODE

Controls the caching of IMS binaries.
Syntax
ES_IMS_CANCEL_MODE={P|L|D}
Parameters
P
Performs a physical cancel; every transaction will have new-copy behavior. This option is the default behavior, but is the poorest performing of the options.
L
Performs a logical cancel. This gives the best performance of the options, but can only be used it there is only one DLITCBL entry point in an MPR.
D
Performs a deferred cancel, which will yield the same behavior as a logical cancel when the MPR services the same MPP back-to-back. It will behave as P (physical cancel) when the transaction changes.
Default
ES_IMS_CANCEL_MODE=P

ES_IMS_CLIENTID_LTERM

Sets LTERM to the client ID instead of the port ID.
Syntax
ES_IMS_CLIENTID_LTERM={Y|N}
Parameters
Y
Sets LTERM to the client-ID instead of the port-ID.
N
Sets LTERM to the client ID when commit-mode is zero, and to the port-ID when commit-mode is one.
Default
ES_IMS_CLIENTID_LTERM=N
Comments
By default, an IMS Connect request sets LTERM (if not explicitly overridden) to the client-ID when commit-mode is zero, and to the port-ID when commit-mode is one.

ES_IMS_CONFIG

The IMS TM parameters.

ES_IMS_DB_COMMIT_FLUSH

Enables you to force the flushing of database buffers to disk on COMMIT only.
Syntax
ES_IMS_DB_COMMIT_FLUSH={0|1}
Parameters
0
Forces the flushing of database buffers to disk on CLOSE only.
1
Forces the flushing of database buffers to disk on COMMIT only.
Default
ES_IMS_DB_COMMIT_FLUSH=0
Related information
ES_IMS_TLOG_FLUSH (deprecated)

ES_IMS_DB_TLOG_WRITETHRU

Enables you to force the flushing of TLOG buffers to disk on all database I/O.
Syntax
ES_IMS_DB_TLOG_WRITETHRU={0|1}
Parameters
0
Forces the flushing of TLOG buffers to disk on COMMIT only.
1
Forces the flushing of TLOG buffers to disk on all database I/O.
Default
ES_IMS_DB_TLOG_WRITETHRU=0
Related information
ES_IMS_TLOG_FLUSH (deprecated)

ES_IMS_DEADLOCK_WAIT

Sets the time to wait before checking for a deadlock.
Syntax
ES_IMS_DEADLOCK_WAIT=wait-time
Parameter
wait-time
Time in milliseconds to wait before checking for a deadlock.
Default
ES_IMS_DEADLOCK_WAIT=1000

(1 second)

ES_IMS_DIAGNOSE

Marks IMS TM as diagnose mode only for IMSMSGQ.
Syntax
ES_IMS_DIAGNOSE={Y|N}
Parameter
Y
The Transaction Manager (TM) works in diagnostic mode only, and no activity key points are written to the message queue.
N
Transaction Manager writes activity key points to the message queue.
Default
ES_IMS_DIAGNOSE=N
Comments
CAUTION:
Do not set ES_IMS_DIAGNOSE=Y unless advised to do so by OpenText Support for Micro Focus Products.

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 the DFSNDMX0.cbl exit routine program and its compiled code, which contains segment, field, and/or print exits.
Syntax
ES_IMS_EXITPATH=path-name
Parameter
path-name
The full path to the directory that contains the DFSNDMX0.cbl exit routine program and its compiled code.
Default
Not set.

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_GOTO_CICS_ON_SIGNOFF

Sets the behavior after logging off or timing out to return to CICS.
Syntax
ES_IMS_GOTO_CICS_ON_SIGNOFF=
Parameter
Returns to CICS after logging off or timing out.
Default
Returns to the IMS sign-on screen after logging off or timing out.

ES_IMS_IBMPLATFORM

Sets the emulation for the IMS run-time.
Syntax
ES_IMS_IBMPLATFORM={M|D}
Parameter
M
Sets the IMS run time to MVS.
D
Sets the IMS run time to DOSVS.
Default
ES_IMS_IBMPLATFORM=M
Comment
This variable rarely requires a change from the 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

Allows the user to specify the IMS System ID returned to the AIBTDLI INQY ENVIRON call.

ES_IMS_IRLM

Enables Internal Lock Resource Manager (IRLM) locking.
Syntax
ES_IMS_IRLM={0|1}
Parameters
0
Disables IRLM locking.
1
Enables IRLM locking.
Default
ES_IMS_IRLM=0
Comments
IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock.
Related information
Internal Resource Lock Manager (IRLM)

ES_IMS_LINKAGE_NULL

When an IMS program passes more linkage addresses than there are PCBs in the PSB, sets each extraneous linkage address to a value of NULL.
Syntax
ES_IMS_LINKAGE_NULL={Y|N}
Parameter
Y
Sets each extraneous linkage address to a value of NULL.
N
Extraneous linkage addresses are invalid.
Default
ES_IMS_LINKAGE_NULL=N

ES_IMS_JES_DIRTY_ABEND

Determines whether IMS marks a JES container as dirty when an IMS application abends or is aborted.
Syntax
ES_IMS_JES_DIRTY_ABEND={Y|N}
Parameter
Y
IMS marks a JES container as dirty when an IMS application abends or is aborted.
N
Disables the IMS behavior of marking a JES container as dirty when an IMS application abends or is aborted.
Default
ES_IMS_JES_DIRTY_ABEND=Y

ES_IMS_LOCALDLI (deprecated)

Determines whether batch program execution processes all IMS DB calls entirely in the JES initiator.
Syntax
ES_IMS_LOCALDLI=1
Parameter
1
Directs batch program execution to process all IMS DB calls entirely in the JES initiator.
Disables the IMS behavior of marking a JES container as dirty when an IMS application abends or is aborted.
Default
ES_IMS_LOCALDLI=1
Comments
Deprecated. See IMS Database Locking.

Processing IMS DB calls in the JES initiator can significantly improve performance.

Stop all IMS DB control processes accessed from the batch program before execution because they become exclusively owned by JES until the program completes.

Related information
IMS Database Locking

ES_IMS_LOCK_RETRY_DELAY

Sets the wait time for retrying an IMS DB lock.
Syntax
ES_IMS_LOCK_RETRY_DELAY=wait-time
Parameter
wait-time
The amount of time in milliseconds to delay retrying the IMS DB lock.
Default
ES_IMS_LOCK_RETRY_DELAY=5

ES_IMS_LOCK_TIMEOUT

Sets the time duration during which IMS DB control continues to retry a locked record before timing out
Syntax
ES_IMS_LOCK_TIMEOUT={0|wait-time}
Parameter
0
Sets an indefinite wait time.
wait-time
A number from 1 through 65525 that represents the number of seconds during which IMS DB control continues to retry a locked record before timing out.
Default
ES_IMS_LOCK_TIMEOUT=30

ES_IMS_LTERM_PREFIX

Sets an LTERM prefix alternative to the default (OTMA) to use when the ES_IMS_SINGLE environment variable is set to N.
Syntax
ES_IMS_LTERM_PREFIX=prefix
Parameter
prefix
A one- to four-character string to use as the LTERM prefix when the ES_IMS_SINGLE environment variable is set to N.
Default
ES_IMS_LTERM_PREFIX=OTMA
Comments
Enterprise Server pads the value specified with numeric digits up to eight characters, enabling the LTERM pool to be expanded from 9999 up to 999999. The pool size is dictated by the number of characters used in the specified prefix. For example, the LTERM pool size for a four-character prefix is 9999; for a three-character prefix is 99999; and so on.

Using an alternative prefix to OTMA enables you to exercise control over name conflicts.

The default setting of this environment variable suggests that the LTERMS apply only to OTMA clients; however, this is not the case. LTERMS can also be applied to second and subsequent 3270 user connections.

Related information
ES_IMS_SINGLE

ES_IMS_LU_LTERM

Determines the value of the LTERM literal returned by the MFS system.
Syntax
ES_IMS_LU_LTERM={Y|N}
Parameters
Y
Returns the LU name.
N
Returns the user ID.
Default
ES_IMS_LU_LTERM=

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.
Syntax
ES_IMS_MESGQ=[ds-file-name;]max-blocks;buffer-count;start-control;[cushion-size]
Parameters
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).
Default
ES_IMS_MESGQ=IMSMESGQ.dat;4;2;Y;4
Comments
CAUTION:
Manually set this variable only when advised to do so by OpenText Support for Micro Focus Products.

ES_IMS_DISPLAY_NEW

Changes the timestamp format for /DISPLAY output.
Syntax
ES_IMS_DISPLAY_NEW={Y|N}
Parameters
Y
Timestamp output follows the current z/OS system style, YYDDD/HHMMSS.
N
Timestamp output follows the old z/OS system style, MM/DD/YYYY HH:MM:SS.
Default
ES_IMS_DISPLAY_NEW=N

ES_IMS_MFS_OPT2_LEGACY

Configures MFS input type option 2 to behave the same as MFS input type option 1.
Syntax
ES_IMS_MFS_OPT2_LEGACY={Y|N}
Parameters
Y
Enables legacy MFS input type option 2 behavior.
N
MFS input type option 2 behavior is the same as MFS on z/OS mainframes.
Default
ES_IMS_MFS_OPT2_LEGACY=N

ES_IMS_OPEN_TIMEOUT

Defines the time period during which IMS retries the opening of a database file that is in use by another task.
Syntax
ES_IMS_OPEN_TIMEOUT=wait-time
Parameter
wait-time
The number of seconds IMS waits before making a subsequent attempt to open a database file that is in use by another task.
Default
ES_IMS_OPEN_TIMEOUT=30

ES_IMS_OTMA_DEST

Defines one or more destinations to which data is redirected for IMS Connect (IMSCON), the MQ-IMS Bridge (MQ), or the IMS print exit (NONOTMA).
Syntax
IMS Connect
ES_IMS_OTMA_DEST={LTERM-name,IMSCON}[;...]
MQ-IMS Bridge
ES_IMS_OTMA_DEST={LTERM-name,MQ,MQ-queue-manager-name,MQ-queue-name}[;...]
IMS Print Exit
IMS_OTMA_DEST={printer-name,NONOTMA,{LU1|LU3}}[;...]
Parameters
LTERM-name
A destination name specified as a literal value for a single destination, or specified using a literal value followed by one or more asterisks to represent a series of multiple destinations. For example, an LTERM-name of TERM*** creates 1000 LTERM destinations named TERM000 through TERM999. Use this method to avoid defining each destination separately.
MQ-queue-manager-name
The name of the MQ queue manager.
MQ-queue-name
The name of the MQ queue.
printer-name
The printer name.
Default
Not set.

ES_IMS_PATH

The location of compiled COBOL applications.
Syntax
ES_IMS_PATH=path-name
Parameter
path-name
The full path to the location of compiled COBOL applications.

ES_IMS_RCLASS

Creates a set of newly-named IMS security resource classes, appending a value to the default character of each resource class.
Syntax
ES_IMS_RCLASS=value
Parameters
value
Up to seven alphabetic characters.
Default
Not set. No new resource classes are created.
Comments
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.

Related information
Resource Classes for IMS Security

ES_IMS_RELEASE

Specifies 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.
Syntax
ES_IMS_ROLLFORWARD={Y|N}
Parameters
Y
Enables forward recovery logging.
N
Disables forward recovery logging.
Default
ES_IMS_ROLLFORWARD=N
Related information
IMS Configuration

ES_IMS_SINGLE

Enables or disables functionality that allows a single user to sign on to multiple LUs simultaneously.
Syntax
ES_IMS_SINGLE={Y|N}
Parameters
Y
Disables multiple sign-on functionality.
N
When ES_IMS_SINGLE is set to N, and a user attempts to sign on to an LU using a sign-on that is currently active at another LU, IMS Transaction Manager (TM) assigns a temporary LTERM to the user and LU using a name constructed from the ES_IMS_LTERM_PREFIX setting followed by a numerical value totalling eight characters (see IMS_LTERM_PREFIX for details). The temporary LTERM is the destination for the user and LU irrespective of activity at other LUs controlled by the user. When a user disconnects from an LU that is served by a temporary LTERM, the LTERM is returned to the temporary pool for reuse.

Also when ES_IMS_SINGLE is set to N, the execution of /dis USER all returns a sub-list for each user that shows all active connections. These connections persist throughout a session, and are dynamically recreated during a warm start. See IMS Control for details.

Default
ES_IMS_SINGLE=Y
Comments
No KEYPOINT activity is associated with the use of ES_IMS_SINGLE.

If an enterprise server region is running in a PAC with the IMS features enabled, then single signon will be enforced for IMS. If you want to change the behavior then set ES_IMS_SINGLE=N to enable the same user to signon to multiple terminals for IMS.

Related information
ES_IMS_LTERM_PREFIX

ES_IMS_SPARSE_EXIT_LANG

Specifies the language for IMS DB secondary index sparse routines.
Syntax
ES_IMS_SPARSE_EXIT_LANG=C
Parameter
C
Sets the language for IMS DB secondary index sparse routines to COBOL.
Default
Not set. Sparse exits are disabled.

ES_IMS_SUPPORT

Enables IMS support.

ES_IMS_TLOG_COMPRESS

Determines whether Backward Recovery TLOG files are compressed or not compressed.
Syntax
ES_IMS_TLOG_COMPRESS={0|1}
Parameters
0
Disables compression of the Backward Recovery TLOG file. When not compressed, the file contains only the information required to recover databases.
1
The Backward Recovery TLOG file is compressed. Enterprise Test Server reclaims space in the file when information becomes obsolete.
Default
ES_IMS_TLOG_COMPRESS=1

ES_IMS_TLOG_FLUSH (deprecated)

Determines whether the frequent flushing of TLOG and database buffers to disk is forced.
Attention: This environment variable is deprecated and provided for backward compatibility only. Use ES_IMS_DB_TLOG_WRITETHRU to flush TLOG buffers and ES_IMS_DB_COMMIT_FLUSH to flush database buffers.
Syntax
ES_IMS_TLOG_FLUSH={0|1}
Parameters
0
Does not flush TLOG and database buffers to disk.
1
Forces the frequent flushing of TLOG and database buffers to disk.
Default
ES_IMS_TLOG_FLUSH=0
Comments
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.
Related information
ES_IMS_DB_TLOG_WRITETHRU
ES_IMS_DB_COMMIT_FLUSH

ES_IMS_TLOG_MAXSIZE

Specifies the maximum size of the IMS DB transaction logging file.
Syntax
ES_IMS_TLOG_MAXSIZE=hex-value
Parameter
hex-value
A hexadecimal value that represents the maximum size for the transaction logging file in bytes.
Default
ES_IMS_TLOG_MAXSIZE=h"FFF00000"

(4GB)

ES_IMS_TLOG_PATH

The location of IMS DB transaction logging (TLOG) files.
Syntax
ES_IMS_TLOG_PATH=path-name
Parameter
path-name
The full path to the location where TLOG files are stored.
Default
Not set. Uses the Enterprise Test Server system directory.
Comments
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_THRESHOLD

Sets the threshold size of the IMS DB transaction logging file. When the threshold is reached, the current TLOG file is closed and a new TLOG file created for subsequent transactions.
Syntax
ES_IMS_TLOG_THRESHOLD=hex-value
Parameter
hex-value
A hexadecimal value that represents the threshold size for the transaction logging file in bytes.
Default
ES_IMS_TLOG_THRESHOLD=h"7FFFFFFF"

(2GB)

ES_IMSCFG

The location of the IMSCONFG.DAT IMS configuration file.
Syntax
ES_IMSCFG=path-name
Parameters
path-name
The full path to the location of the IMSCONFG.DAT file.
Default
Not set.

ES_IMSDAT

The location of IMS DB data files.
Syntax
ES_IMSDAT=path-name
Parameters
path-name
The full path to the directory that stores IMS DB data files.
Default
Not set. Uses the current working directory.

ES_IMSLIB through ES_IMSLIB25

ES_IMSLIB specifies the location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files. You can use this same variable with a sequential number appended to search additional locations.
Syntax
ES_IMSLIB[1...25]=path-name
Parameters
path-name
The full path to the location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files.
Default
Not set. Looks for the .DAT files in the current working directory.
Comments
You may specify up to 25 locations.
Example
ES_IMSLIB=$BASEPATH\ED_SETS\IMSLIB		      /*sets the first location for IMSLIB objects */
ES_IMSLIB2=$BASEPATH \ED_SETS_SYS\IMSLIB  /* sets the next location to search */
ES_IMSLIB3=$BASEPATH \ED_SETS_QA\IMSLIB		 /* and the next */
ES_IMSLIB4=$BASEPATH \ED_SETS_PROD\IMSLIB	/* etc. */

ES_INQFILE_RETURN

Modifies EXEC CICS INQUIRE FILE behavior for cataloged files.
Syntax
ES_INQFILE_RETURN={DSN|PCN}
Parameters
DSN
The DSN is returned. For an alternative file, the BASEDSNAME is the DSNAME of the BASE file.
PCN
The PC name of the file (truncated at 44 characters) is returned if the file is open, or if FCT fix-up has been performed. Otherwise, the dataset name is returned.
Default
ES_INQFILE_RETURN=PCN

ES_JES_BYTES

Maximum number of bytes to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_BYTES=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of bytes in thousands. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of bytes is reached.
CANCEL
Cancel the job when the specified maximum number of bytes is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of bytes is reached.
Default
Not set.
Example
In this example, each line is assumed to hold 132 bytes; therefore the job is automatically cancelled at 100000/132 lines, and the memory contents are dumped:
ES_JES_BYTES=(100,DUMP)

ES_JES_CARDS

Maximum number of cards to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_CARDS=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of cards. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of cards is reached.
CANCEL
Cancel the job when the specified maximum number of cards is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of cards is reached.
Default
Not set.
Example
In this example, each card is assumed to hold 25 lines; therefore at 750 lines (25×30) a warning message is issued the job continues.
ES_JES_CARDS=(30,WARNING)

ES_JES_CONSOLE_MESSAGES

Determines whether to lodge CASMG0001I messages in the splmsg.dat list for a job.
Syntax
ES_JES_CONSOLE_MESSAGES={Y|N}
Parameters
Y
Lodges CASMG0001I messages in the splmsg.dat list for a job.
N
Does not lodge CASMG0001I messages in the splmsg.dat list for a job.
Default
ES_JES_CONSOLE_MESSAGES=Y
Comments
CASMG0001I messages are produced when a program running in a JCL job does 'display upon console'. These messages, along with others, are lodged in the splmsg.dat file. When the job information is displayed in ESCWA/ESMAC, these messages are also shown.

There is a limit of 65535 messages per job. If that limit is exceeded, the last messages sent will overwrite the last message already lodged in splmsg.dat.

There is a way to work around this, if your program outputs a lot of messages. You can set ES_JES_CONSOLE_MESSAGES=N in order to avoid storing the messages in splmsg.dat. Whatever this setting, the CASMG0001I messages will still be included in the JESYSMSG for the job.

There is also a Job statement extension so that this can be configured on a job by job basis - see the line below. See JOB Statement Extensions for more details.

//*MFE:%CONSOLE_MSGS=Y|N
Related information
JOB Statement Extensions

ES_JES_DELAY_MEM_ENQ

Determines whether to delays the exclusive enque of a new (not previously existing) PDS member until the file is opened.
Syntax
ES_JES_DELAY_MEM_ENQ={Y|N}
Parameters
Y
Delay the exclusive enque of a new (not previously existing) PDS member until the file is opened.
N
Do not delay the exclusive enque of a new (not previously existing) PDS member until the file is opened.
Default
ES_JES_DELAY_MEM_ENQ=N
Comments
PDS members are given an exclusive enque at step start.

When used with existing PDS members, the program abends with code S213 when it attempts to access a file and cannot get the exclusive enque.

ES_JES_DISABLE_RESTART_FLUSH

Indicates whether jobs in a specific enterprise server region are moved from the Active queue to the Complete queue when the region is restarted.
Syntax
ES_JES_DISABLE_RESTART_FLUSH={Y|N}
Parameters
Y
Move jobs in the region from the Active queue to the Complete queue when the region is restarted.
N
Do not move jobs in the region from the Active queue to the Complete queue when the region is restarted.
Default
ES_JES_DISABLE_RESTART_FLUSH=N
Related information
Active output jobs and server restarts

ES_JES_ENFORCE_EXPIRE_DATE

Determines whether or not to check the expiration date when deleting a catalogued dataset, and if expired, delete the dataset.

Syntax
ES_JES_ENFORCE_EXPIRE_DATE={Y|N}
Parameters
Y
Check the expiry date and delete expired datasets.
N
Do not check the expiration date.
Default
ES_JES_ENFORCE_EXPIRE_DATE=Y
Comments
Use the PURGE keyword to delete non-expired datasets.

ES_JES_FREE_SSTM_SYSOUT

Determines whether to free the memory assigned to store details about each CICS spool file that you create using the CICS Spool Write APIs, once the spool file has been created.
Syntax
ES_JES_FREE_SSTM_SYSOUT={Y|N}
Parameters
Y
Free the memory assigned to store details about each CICS spool file.
N
Do not free the memory assigned to store details about each CICS spool file.
Default
ES_JES_FREE_SSTM_SYSOUT=N
Comments

Setting ES_JES_FREE_SSTM_SYSOUT=Y helps to avoid problems with receiving out of memory errors when creating multiple new files.

CAUTION:
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.

ES_JES_HIGHER_SECURITY_LEVEL

Determines which programs are loaded based on checks made against the list of SYS1.LNKLIB entries.
Syntax
ES_JES_HIGHER_SECURITY_LEVEL={0|[1|NONE][2|BASIC][3|WARN][4|ENHANCED]}
Parameters
0
The behavior is unchanged with regard to JES enhanced security.
1|NONE
A value of 1 or NONE is the equivalent of not setting the value and maintains the behaviour of earlier versions of Enterprise Test Server. With a setting of 1 or no setting at all, warning messages about the number of SYS1.LNKLIB entries might be issued if none have been defined (JES000067W) and messages about programs not being loaded from certain locations (JES000069W) are also given. In addition, messages JCLCM0260W and JCLCM0308W might also be issued.
2|BASIC
A level of BASIC or 2 causes programs to be loaded from the list of SYS1.LNKLIB entries, STEPLIB, and JOBLIB locations. Programs in other locations are not loaded. The loading of programs from dynamic PDSs is also entirely disabled.
3|WARN
A level of WARN or 3 causes checks to be made against the PROGRAM and the PHYSFILE security classes. The PHYSFILE check is to make sure the PHYSFILE resource class is implemented. If these checks fail, a warning message (JCLCM0262W, JCLCM0263W or JCLCM0266W) is issued.
4|ENHANCED
A level of ENHANCED or 4 will cause the same PROGRAM and PHYSFILE checks to be made but if they fail then the job will abend with an S913 security error and a suitable message will be issued to indicate the failure.
Default
ES_JES_HIGHER_SECURITY_LEVEL=1

ES_JES_LEVEL

Sets the default JCL type on the JES Control page.
Syntax
ES_JES_LEVEL={VSE|JES2|JES3}
Parameters
VSE
Default JCL type of VSE.
JES2
Default JCL type of JES2.
JES3
Default JCL type of JES3.
Default
ES_JES_LEVEL=JES2

ES_JES_LINES

Maximum number of lines to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_LINES=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of lines in thousands. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of lines is reached.
CANCEL
Cancel the job when the specified maximum number of lines is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of lines is reached.
Default
Not set.
Example
In the following example, each card is assumed to hold 25 lines; therefore at 750 lines (25×30) a warning message is issued and the job continues. Limit the number of lines output to 100000. When this limit is reached, cancel the job. This produces an S722 Output limit exceeded system abend code:
ES_JES_LINES=(100,CANCEL)

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.
Syntax
ES_JES_OUTLIM=(max-lines[,{WARNING|CANCEL|DUMP}])
Parameters
max-lines
Maximum number of lines of output before taking action. The range is from 1-16777215.
WARNING
Issue a warning when the specified maximum number of lines of output is reached.
CANCEL
Cancel the job when the specified maximum number of lines of output is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of lines of output is reached.
Default
Not set.
Example
A warning is issued when 5000 lines of output is exceeded:
ES_JES_OUTLIM=5000

The job is canceled when 1000 lines of output are reached.

ES_JES_OUTLIM=(1000,CANCEL)
Comments
Individual OUTLIM values can be set on each SYSOUT dataset. For example:
//SYSPRINT DD SYSOUT=*,OUTLIM=500

ES_JES_PAGES

Maximum number of pages to output in a job before taking the action specified by cancelling the job, cancelling the job and dumping memory contents, or issuing a warning message.
Syntax
ES_JES_PAGES=(number[,{WARNING|CANCEL|DUMP}])
Parameters
number
Maximum number of pages. The range is from 0-99999999.
WARNING
Issue a warning when the specified maximum number of pages is reached.
CANCEL
Cancel the job when the specified maximum number of pages is reached.
DUMP
Cancel the job and dump the memory contents when the specified maximum number of pages is reached.
Default
Not set. No limit to the number of pages output.
Example
In this example, each page is assumed to hold 60 lines; therefore when 600 lines (60×10) have been processed, a warning is issued and the job continues:
ES_JES_PAGES=10

ES_JES_PARM_INIT_LOW

Determines whether the parameter string passed to a program executed by JCL is initialized to low-values or to spaces.
Syntax
ES_JES_PARM_INIT_LOW={Y|N}
Parameters
Y
Initialize the parameter string to low-values.
N
Initialize the parameter string to spaces.
Default
ES_JES_PARM_INIT_LOW=N

ES_JES_RESTART

Determines whether JCL restart processing is enabled.
Syntax
ES_JES_RESTART={Y|N}
Parameters
Y
Enables JCL restart processing.
N
Disables JCL restart processing.
Default
ES_JES_RESTART=N
Related information
GDG_RESTART_UCC11_ONLY
MF_UCC11

ES_JES_SORT_SPOOL_BY

Specifies which column is initially used to sort the spool records in casrdo41.
Syntax
ES_JES_SORT_SPOOL_BY={JOBNAME|SUBDATE|JOBUSER}
Parameters
JOBNAME
Sort by job name.
SUBDATE
Sort by sub date.
JOBUSER
Sort by job user.
Default
Not set.

ES_JES_SPOOL_ORDER

The order in which the spool list is displayed when you first open ESMAC.
Syntax
ES_JES_SPOOL_ORDER=1
Parameter
1
Displays the list in descending order by JOBID.
Default
Not set. Displays the list in ascending order by JOBID.

ES_JESYSMSG_OUTPUT

The status of the system messages spool files (JESYSMSG) is set to Output, rather than Out Hold.
Syntax
ES_JESYSMSG_OUTPUT={Y|N}
Parameters
Y
All job messages will have the status as Output, 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.
N
Messages are set to Out Hold.
Default
ES_JESYSMSG_OUTPUT=N

ES_JESYSMSG_RESTRICTED

Holds back spool files based on their class when the status of the system message spool files are set to Output.
Syntax
ES_JESYSMSG_RESTRICTED={class-name|class-number}[class-name|class-number][...]]
Parameters
class-name
The name of a class.
number
A number representing the class.
Default
Not set.
Example
The following:
ES_JESYSMSG_RESTRICTED=ABC123

Specifies classes A, B, C, 1, 2, and 3.

Comments
All job messages have an Output status, but print either physically or logically only when the MSGCLASS of the job matches one of the sysout classes defined to an active printer.

ES_LE370_SUPPORT

Enables support for Language Environment (LE) in CICS applications
Syntax
ES_LE370_SUPPORT=Y
Parameter
Y
Enables LE support.
Default
Not set. LE support is not enabled.
Comments
Parameter value is not case sensitive.

ES_LEGACY_ECI

Indicates that Enterprise Server must use Micro Focus ECI instead of IBM CTG.
Syntax
ES_LEGACY_ECI=Y
Parameter
Y
Micro Focus ECI is used.
Default
Not set. IBM CTG is used.
Comments
Parameter value is not case sensitive.

ES_LOCKDB

Specifies the region database that is to process resource locking (step- and system-scoped ENQs) for an enterprise server region within a cluster, where resources such as catalogs are deployed to a database.
Syntax
ES_LOCKDB=region-db
Parameter
region-db
The name of the region database responsible for processing step- and system-scoped ENQs.
Default
Not set.
Comments
This variable must be used in conjunction with ES_SERVER, in which ES_SERVER is set to the database server that houses the region database; see Resource Locking for more information.
Related information
ES_SERVER
Resource Locking
Enterprise Server LOCKDB

ES_MAX_CATALOG_LINES

Restricts the number of entries displayed in ESMAC catalog view.
Syntax
ES_MAX_CATALOG_LINES=number
Parameter
number
The number of lines to display up to a maximum of 99999.
Default
ES_MAX_CATALOG_LINES=5000
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

ES_MAX_HTTP_OUT

Specifies the maximum size of the HTTP response sent by Enterprise Server.
Syntax
ES_MAX_HTTP_OUT=value
Parameter
value
A number representing the maximum size of the HTTP response in bytes.
Default
ES_MAX_HTTP_OUT=
Comments
In earlier releases, the size of the HTTP response was controlled by the HTTP Out field on the ESCWA ES Control page.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

Related information
ES Control
Advanced Region Properties

ES_MEM_STRATEGY

Selects the types of memory processes supported.
Comments
Memory strategy can also be set via the memory_strategy run-time tunable.
Related information
Control
memory_strategy

ES_MFASM_SUPPORT

Enables Assembler support in a CICS enterprise server region.
ES_MFASM_SUPPORT={Y|N}
Parameters
Y
Assembler supported for CICS server regions.
N
No Assembler supported for CICS server regions.
Default
ES_MFASM_SUPPORT=N

ES_MFDS_ADDRESS

Specifies the server address is used by casstart when the /m parameter is not provided.

ES_MFSLIB

The location of the control blocks generated by the MFS generation program.
Syntax
ES_MFSLIB=path-name
Parameter
path-name
The path to the MFS directory.
Default
ES_MFSLIB=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ims

ES_MOD3650

Replaces the default MOD file displayed after a successful sign-on to IMS. See ES_DFS3650 for further details.
Syntax
ES_MOD3650=file-name
Parameter
file-name
The name of the replacement default MOD file.

ES_MQ_1PC

Indicates whether the IBM WebSphere MQ switch module ESMQXA operate in one-phase commit mode.
CAUTION:
Set this environment variable only when advised to do so by OpenText Support for Micro Focus Products.
Syntax
ES_MQ_1PC={[Y|y|Yes|T|True]|[N|n|No|F|False}
Parameters
Y|y|Yes|T|True
The ESMQXA switch module operates in one-phase commit mode.
N|n|No|F|False
The ESMQXA switch module operates in two-phase commit mode.
Default
ES_MQ_1PC=F
Related information
WebSphere MQ Switch Module

ES_MQ_LIB

The full name including the path of the IBM WebSphere MQ client or server library. This should only be required if MQ was NOT installed in the default location.
Syntax
ES_MQ_LIB=path-name/library-name
Parameters
path-name
The full path to the library location.
library-name
The name of the library file.
Default
Not set. Enterprise Server looks for library files in the default location for your platform.
Comments
In AIX environments the library is an object inside a shared object. For example:
ES_MQ_LIB="/usr/mqm/lib64/libmqmxa64.a(libmqm64.o)"
Related information
Configuring Enterprise Server for WebSphere MQ Trigger Monitors

ES_MQ_XA

The type of XA structure to use for the two-phase commit XA switch module.
Syntax
ES_MQ_XA={D|S}
Parameters
D
Use a dynamic XA structure
S
Use a static XA structure.
Default
ES_MQ_XA=D

ES_OLD_DYN_PDS

Determines the resulting behavior of dynamic PDS members when specified in a JCL DD statement.
Syntax
ES_OLD_DYN_PDS={Y|N}
Parameters
Y
Enables previous default behavior of cataloging and creating the physical files for dynamic PDS when referenced in a JCL DD statement.
N
Physical files for dynamic PDS members are only created and cataloged when created using the JCL utility or by a user program.
Default
ES_OLD_DYN_PDS=N

ES_OLD_SEC_TSTD

Prevents security being enforced for TS or TD queues that are not declared in the security repository.
Syntax
ES_OLD_SEC_TSTD=ON
Parameter
ON
Prevents security being enforced for TS or TD queues that are not declared in the security repository.
Default
Not set. security is enforced for TS or TD queues that are not declared in the security repository.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

ES_OPEN_CAT_ON_DEMAND

Determines if additional catalogs (as specified using MFUSERCAT_NODE) are opened when the system starts, or only opened when required.
Syntax
ES_OPEN_CAT_ON_DEMAND={Y|N}
Parameters
Y
When the enterprise server region starts, no attempt is made to open the catalogs specified in MFUSERCAT_NODE. Only the system catalog is opened initially, and the other nodes are opened when required.
N
When the enterprise server region starts, all nodes are opened.
Default
ES_OPEN_CAT_ON_DEMAND=N
Comments
When ES_OPEN_CAT_ON_DEMAND=N is set and there is a problem opening any of the nodes specified in MFUSERCAT_NODE, the JES system will not start.

ES_OTMA_TIMEOUT

The time in seconds that an OTMA client should wait for an answer.
Syntax
ES_OTMA_TIMEOUT=wait-time
Parameter
wait-time
The number of seconds to wait. The maximum is 43199.
Default
ES_OTMA_TIMEOUT=120

(2 minutes)

Related information
Open Transaction Manager Access (OTMA)

ES_PAC_NO_GLOBAL_LOG

Stops the messages in the console.log from being stored in the PAC Scale-out Repository (PSOR) CasPacLog.
Syntax
ES_PAC_NO_GLOBAL_LOG={Y|N}
Parameters
Y
Prevents console.log messages for PAC member regions from being stored in the PSOR.
N
console.log messages for PAC member regions are stored in the PSOR.
Default
ES_PAC_NO_GLOBAL_LOG=N
Comments
You can set ES_PAC_NO_GLOBAL_LOG=Y to improve performance if you are not monitoring messages from the PSOR.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

Related information
Configuration Options
Advanced Region Properties

ES_PRODUCTION

Prevents the initiation of a debugging session from the IDE.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_PROG_PATH

Determines whether to display the program's load path in the JESYSMSG and SYSLOG datasets.
Note: Applies to native enterprise server regions only.
Syntax
ES_PROG_PATH={Y|N}
Parameters
Y
Display the program's load path in the JESYSMSG and SYSLOG datasets.
N
Do not display the program's load path in the JESYSMSG and SYSLOG datasets.
Default
Not set.

ES_RDO_MAX_RESOURCES

Specifies the maximum number of records for CICS resource types that display in Enterprise Server Common Web Administration (ESCWA) or Enterprise Server Monitor and Control (ESMAC).
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_RLS_FILE_SUPPORT

If a record is locked because a program is doing a read for update, and the application needs to ensure that no other program can access that record, you can set this environment variable to avoid returning a dirty record until the program holding the lock has completed.
Syntax
ES_RLS_FILE_SUPPORT=Y
Parameter
Y
Stops dirty records being returned when a record is locked by another process.
Default
Not set. Dirty records are returned.
Comments
The timeout in fileshare also needs to be set to 0 using /t 0 in the fileshare configuration file. See Using a Fileshare Configuration File for details.

Parameter values are not case sensitive.

Related information
Using a Fileshare Configuration File

ES_RTLS_CERT_AUTH_FILEPATH

The absolute path to the certificate authority file used for a TLS-enabled Redis SOR.
Syntax
ES_RTLS_CERT_AUTH_FILEPATH=path-name
Parameter
path-name
The full path to the certificate authority file used for a TLS-enabled Redis SOR.

ES_RTLS_CERT_FILEPATH

Absolute file path to the certificate file used for a TLS-enabled Redis SOR.
Syntax
ES_RTLS_CERT_FILEPATH=path-name
Parameter
path-name
The full path to the certificate file used for a TLS-enabled Redis SOR
Default
Not set.

ES_RTLS_PRIVATE_KEY_FILEPATH

Absolute file path to the private key file used for a TLS-enabled Redis SOR.
Syntax
ES_RTLS_PRIVATE_KEY_FILEPATH=path-name
Parameter
path-name
The full path to the private key file used for a TLS-enabled Redis SOR.
Default
Not set.

ES_SAM_ESDS

Under VSE and when opening the OUTPUT of a reusable ESDS file, determines whether the file is reset when the DISP is not specified in the DLBL statement.
Syntax
ES_SAM_ESDS={Y|N}
Parameters
Y
File is reset.
N
File is not reset.
Default
Not set.

ES_SEP_DORMANT_TIME

Allows override of Transient SEP dormant time. Rather than automatically terminating transient SEPs on completion of a stateful request, the server manager allows a period of inactivity before scheduling their termination. This allows new requests to re-use the SEP rather than starting a new instance. This environment variable allows you to control the period of inactivity.
Syntax
ES_SEP_DORMANT_TIME=wait-time
Parameter
wait-time
The number of seconds that the Transient SEP is inactive.
Default
ES_SEP_DORMANT_TIME=2
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_SERVER

The default server name used if no -r switch is specified on casstart or casstop.
Syntax
ES_SERVER=server-name
Parameter
server-name
The server name.
Defaults
32-bit
ES_SERVER=ESDEMO
64-bit
ES_SERVER=ESDEMO64
Related information
ES_LOCKDB

ES_SNATRC_DIR

Specifies the location of the SNA traces written by the z/OS communication manager.
Syntax
ES_SNATRC_DIR=path-name
Parameter
path-name
The full path to the location of SNA traces.
Default
Not set.
Comments
You must set this environment variable before you start the region to ensure that the SNA trace files are written to a valid directory.

This directory is then used to set up the SNA environment variables SNAMSG and SNATRC to appropriate values.

ES_SCALE_OUT_REPOS_n

Specifies connection information for either Redis or Oracle Coherence data stores used by enterprise server regions that are part of a PAC.
Syntax
ES_SCALE_OUT_REPOS_n=sor-name=sor-Type,
   {redis-connection-details|oracle-connection-details}##[TMP#][models]
Parameters
n
Represents the SOR number. Valid values are 1 through 9.
sor-name
The name of the SOR. No spaces are allowed. In the context of using Redis, the SOR name is used to retrieve the Redis master from Redis.
sor-type
This is the type of data store. Valid values are:
redis | Regular connection to a Redis data store
redis_TLS | TLS -enabled connection to a Redis data store
coherence | Oracle Coherence connection to an Oracle data store
redis-connection-details
One or more host and port name pairs used for Redis connections as follows:
host-name:port-name[,host-name:port-name[...]]
host-name | The machine name or IP address of the host system where data stores are location
port-name | The port used to make the connection to the host specified by the corresponding host-name
oracle-connection-details
[userid@][path-name|URL][config-file]
   [,java-property[[=java-property-value]][…]]##[TMP#]
   [={TS=ts-model[:ts-model]|TD=td-model[:td-model]}]
   [[#{TS=ts-model[:ts-model]|TD=td-model[:td-model]}]][...]]
userid@ | The user ID to use when Oracle Coherence security is enabled.
path-name | The path to the configuration file represented by config-file. If omitted, defaults to the current working directory.
URL | A URL that contains the configuration content.
config-file | The name of the cache configuration file. If omitted, defaults to mfes-cache-config.xml.
java-property | The name of a Java property to set to the specified java-property-value, or is clear if java-property-value is unspecified.
java-property-value | The value of the property specified by java-property.
# Delimiter character.
TMP | Indicates that this PSOR stores active resources.
TS | Indicates temporary storage resource type.
TD | Indicates transient data resource type.
ts-model | An identifier for the corresponding TS consisting of either a character string no more than four bytes in length.1
td-model | An identifier for the corresponding TD consisting of a character string no more than 16 bytes in length.1
1 You may use the * wildcard character to represent any string, and the + character to represent any single character. Identifiers of a size smaller than the byte limit are automatically padded using + characters to extend the length to the limit.
Default
None. You must set ES_SCALE_OUT_REPOS_n for all enterprise server regions that are part of a PAC.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Examples
See PAC and SOR Environment Variables.
Related information
Oracle Coherence Requirements and Configuration as a Scale-Out Repository
PAC and SOR Environment Variables
Advanced Region Properties

ES_SOR_RETRIES

Sets the number of attempts to access records in the PSOR before stopping.
Syntax
ES_SOR_RETRIES=integer
Parameter
integer
An integer value ranging from 1 through 1000 that represents the number of attempts to access records in the PSOR before stopping.
Default
ES_SOR_RETRIES=10
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Configuration Options
Advanced Region Properties

ES_SSTM_CICS

Location of the JCL used to initialize the SSTM CICS environment.
Syntax
ES_SSTM_CICS=file-location
Parameter
file-location
The full path to the location of the SSTMCICS.JCL file used to initialize the SSTM CICS environment.
Default
Not set.

ES_SSTM_IMS

Location of the JCL used to initialize the SSTM IMS environment.
Syntax
ES_SSTM_IMS=file-location
Parameter
file-location
The full path to the location of the JCL used to initialize the SSTM IMS environment.
Default
Not set.

ES_SSTM_JOB_FLUSH_ACTIVE

Determines whether a CICS SSTM job is removed from the Active queue when the region shuts down.
Syntax
ES_SSTM_JOB_FLUSH_ACTIVE ={Y|N}
Parameters
Y
Remove the CICS SSTM job from the Active queue.
N
Do not remove the CICS SSTM job from the Active queue.
Default
ES_SSTM_JOB_FLUSH_ACTIVE=N

ES_SURROGATE_JOB_USER

Associates a user ID with a job when submitting the job for processing through the internal reader from CICS.
Syntax
ES_SURROGATE_JOB_USER=ON
Parameter
ON
The user ID that started the enterprise server region is used in the job submission.
Default
Not set. The CICS default user CICSUSER, or as specified by ES_USR_DFLT_CICS, is used in the job submission.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

Related information
ES_USR_DFLT_CICS
Advanced Region Properties

ES_SYSOUT_HOLD

Determines which SYSOUT files are sent to the Complete queue with an Out Hold status.
Syntax
ES_SYSOUT_HOLD={msg-class}[msg-class[...]]
Parameter
msg-class
A message class to send to the Complete queue with an Out Hold status.
Default
Not set. No specific message classes are sent to the Complete queue with an Out Hold status.
Example
Message classes A and B are sent to the Complete queue with an Out Hold status:
ES_SYSOUT_HOLD=AB

ES_TEST_TRANCLASS

Activates transaction class support.
Syntax
ES_TEST_TRANCLASS={Y|N}
Parameters
Y
Activate transaction class support.
N
Do not activate transaction class support.
Default
ES_TEST_TRANCLASS=N
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_TMC_AGGREGATE

Initializes performance settings for the IMS message queue, and enables dynamic performance tuning. 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.
Syntax
ES_TMC_AGGREGATE={[,N|,D]|nnn,Y}
Parameters
,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 ESCWA. 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.
Notes: To avoid unpredictable results when using this setting, Micro Focus recommends that you also set the static options as follows on ESCWA. Select enterprise server region you require, click IMS > Configuration and then click the TM tab:
  • Set the Cold start list to Everything.
  • Check Persist.

See Server Instance Properties: MSS IMS TM General for more information.

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.

Typically, when the message queue resides on a higher performance I/O subsystem such as one using SSDs, a smaller value, for example 1 or 2, produces the best results. A value of 10 or higher seldom improves performance.

Default
ES_TMC_AGGREGATE=,N
Related information
To dynamically tune IMS message queue performance
Server Instance Properties: MSS IMS TM General

ES_TN3270_FORCE_ALT

Enables you to use a screen size other than the default when using a TN3270 terminal emulator.
Syntax
ES_TN2370_FORCE_ALT=ON
Parameter
ON
Enables alternative screen size.
Default
Not set. The default screen size is used.
Comments
This environment variable is considered to be turned on when set to any value, including ON.

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.
Syntax
ES_TN3270_MODEL_LOG=Y
Parameter
Y
Model names are written to TSQ TN32MODL.
Default
Not set. Model names are not logged.

ES_TRANCLASS_CWI

For CICS Web Services, enables the prioritizing and limiting of Web requests in a TRANCLASS-enabled region.
Syntax
ES_TRANCLASS_CWI={TCPIPSERVICE|URIMAP}
Parameters
TCPIPSERVICE
Prioritize and limit TCPIPSERVICE transactions.
URIMAP
Prioritize and limit URIMAP transactions.
Default
ES_TRANCLASS_CWI=TCPIPSERVICE
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_TRX3650

The default transaction to run after a successful sign-on to IMS. See ES_DFS3650 for further details.
Syntax
ES_TRX3650=transaction
Parameter
transaction
The default transaction to run.
Default
Not set.

ES_TSC_AGGREGATE

Controls the performance environment for CICS TS/TD data stores.
Syntax
ES_TSC_AGGREGATE=wait-time,{Y|N|D}
Parameters
wait-time
The time in milliseconds to wait for additional flush requests to accumulate.
Y
Use aggregate data store flush-buffers-to-disk operations
N
Do not aggregate
D
Disable flush operations.

ES_USR_DFLT_CICS

Allows you to override the default user when no user is logged on for CICS authentication.
Syntax
ES_USR_DFLT_CICS=userid
Parameter
userid
An alternative default user name.
Default
ES_USR_DFLT_CICS=CICSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
ES_SURROGATE_JOB_USER
Advanced Region Properties

ES_USR_DFLT_ESMAC

Allows you to override the default user when no user is logged on for ESMAC authentication.
Syntax
ES_USR_DFLT_ESMAC=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_ESMAC=MFUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Configuring the Default ESMAC User (deprecated)
Advanced Region Properties

ES_USR_DFLT_IMS

Allows you to override the default user when no user is logged on for IMS authentication.
Syntax
ES_USR_DFLT_IMS=user-id
Parameter
user-id
The user name to override the default.
Default
ES_USR_DFLT_IMS=IMSUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_USR_DFLT_JCL

Enables you to override the default user when no user is logged on for JCL authentication.
Syntax
ES_USR_DFLT_JCL=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JCL=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_USR_DFLT_JES

Allows you to override the default user when no user is logged on for JES authentication.
Syntax
ES_USR_DFLT_JES=userid
Parameter
userid
The default user name.
Default
ES_USR_DFLT_JES=JESUSER
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_WORKING_MODE

The bitism of the server, 32- or 64-bit.
Syntax
ES_WORKING_MODE={32|64}
Parameters
32
Indicates that the server runs in 32-bit mode.
64
Indicates that the server runs in 64-bit mode.
Default
ES_WORKING_MODE=64
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Related information
Advanced Region Properties

ES_WS_RUNAWAY_TIMEOUT

Time that the client waits for a response from the Web service. Valid values are 0 to 65535 seconds.
Syntax
ES_WS_RUNAWAY_TIMEOUT=wait-time
Parameter
wait-time
Time in seconds that the client waits for a response from the Web service. Valid range is 0 through 65535.
Default
Not set.

ES_XA_%xaname%_OPTIONS

When set with ES_XA_RECONNECT=Y, configures the XA reconnect process to operate in a multi-attempt mode.
Syntax
ES_XA_%xaname%_OPTIONS={reconnect_attempts,wait-time|EX}
Parameters
%xaname%
The name of the RM as specified in MFDS or ESCWA.
reconnect_attempts
The number of reconnect attempts to the target RM. Maximum is 9999.
wait-time
The number of seconds to delay between each attempt.
EX
Exclude the target RM from XA reconnect processing.
Default
Not set.
Comments
ES_XA_%xaname%_OPTIONS must be set along with ES_XA_RECONNECT=Y.

You might need to set ES_XA_%xaname%_OPTIONS multiple times — once for each RM that you require to operate in a multiple-attempt mode.

Examples
Specify that an XA reconnect processing attempts to reconnect to MQPROD 100 times and waiting for 10 seconds between each reconnect attempt:
ES_XA_MQPROD_OPTIONS=100,10

Specify that the XA reconnect processing is to exclude MQPROD from the XA reconnect processing:

ES_XA_MQPROD_OPTIONS=EX
Related information
To edit an XA resource
Multiple mode reconnect for CICS

ES_XA_ABEND

Recycles non-batch SEPs when a severe error is returned by an xa-start by an Oracle switch.
Syntax
ES_XA_ABEND=RECYCLE
Parameter
RECYCLE
Recycles non-batch SEPs when a severe error is returned by an xa-start by an Oracle switch.
Default
Not set. Non-batch SEPs are not recycled.

ES_XA_LOG_SUPPRESS

Suppresses XA logging and the recovery of in-doubt XA transactions.
Syntax
ES_XA_LOG_SUPPRESS=Y
Parameter
Y
Default
Not set. XA logging is not suppressed.
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

Parameter value is not case sensitive.

Related information
Advanced Region Properties

ES_XA_RECONNECT

Configures the XA reconnect process to operate in a single-attempt mode.
Syntax
ES_XA_RECONNECT=Y,wait-time[,retry_count]
Parameters
Y
Enables the reconnect process.
wait-time
The number of seconds to delay before triggering the XA recovery transaction after a two-phase commit failure and between each reschedule of the XA recovery transaction if the syncpoint phase 2 returns an RC 04. Maximum is 300.
retry_count
The number of recovery retries to attempt when the XA commit or rollback executed by the XA recovery transaction returns an RC-04. Default is 5.
Default
Not set. XA reconnect operates in multi-attempt mode.
Comments
In case of failure, the following messages are sent to the console:
CASXO0054W XA recovery error RC=4 on commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG           000000***********000010000000**        0000

When the maximum number of retries is reached, the following message is sent to the console:

CASXO0055S XA MAX recovery attempts, manually commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG       000000***********000010000000**        0000
Example
ES_XA_RECONNECT=Y,120,4
Related information
Setting Up Application Reconnect in a Multi-instance Queue Manager
Single mode reconnect for CICS

ES_ZOS_SYSPRINT_DCB

Enables MFJAMS SYSPRINT to have the same DCB attributes as the IDCAMS SYSPRINT.
Syntax
ES_ZOS_SYSPRINT_DCB={Y|N}
Parameters
Y
Enable MFJAMS SYSPRINT to use the same DCB attributes as the IDCAMS SYSPRINT.
N
MFJAMS SYSPRINT is not enabled to use the same DCB attributes as the IDCAMS SYSPRINT.
Default
ES_ZOS_SYSPRINT_DCB=N

EXTFH

Specifies a configuration file for the Callable File Handler.
Syntax
EXTFH=file-name.cfg
Parameter
file-name
The prefix name of the configuration (.cfg) file.
Default
Not set. The default configuration file name prefix is extfh.
Example
EXTFH=c:\mydir\myconfig.cfg

F

FHREDIR

Specifies a configuration file to be used by the Fileshare Client.
Syntax
FHREDIR=[path-name\]prefix.cfg
Parameters
path-name
The full path to the location of the Fileshare Client configuration file.
prefix
The prefix name of the configuration (.cfg) file.
Default
Not set. Uses the fhredir.cfg file in the current working directory.
Example
FHREDIR=C:\mydir\myconfig.cfg
Related information
Configuring Fileshare
Specifying Fileshare Locations in the Fileshare Client Configuration File

FS

Specifies a configuration file to be used by the Fileshare Server.
Syntax
FS=file-name.cfg
Parameter
file-name
The prefix name of the configuration (.cfg) file.
Default
FS=fs.cfg
Example
FS=myfsconf.cfg

FSCOMMS

Specifies that the Fileshare system is to run in single user mode.
Syntax
FSCOMMS="\$local"
Parameter
$local
Run the Fileshare System in single user mode.
Default
Not set. Fileshare system runs in multi-user mode.

G

GDG.RECALL

Controls the recall of HSM archived datasets when accessing mainframe GDGs using MFA Data Access Services.

GDG_RESTART_UCC11_ONLY

Determines when GDG restart information should be written.
Syntax
GDG_RESTART_UCC11_ONLY={Y|N}
Parameters
Y
GDG restart information is written, but only when ES_JES_RESTART=Y and MF_UCC11 is set (Y, YA, or M).
N
GDG restart information is written even if MF_UCC11=N or is not set. (ES_JES_RESTART=Y must still be set.)
Default
GDG_RESTART_UCC11_ONLY=Y
Related information
ES_JES_RESTART
MF_UCC11

H

HCOBND (deprecated)

Specifies a directory to be used for bind files generated by the DB2 External Compiler Module (ECM).
Attention: HCOBND is deprecated and provided for backward compatibility only. We recommend that you use either the BIND or the BINDDIR compiler directive option instead.
Syntax
HCOBND=path-name
Parameter
path-name
The directory that the DB2 ECM is to use to store bind files.
Default
Not set. Looks only in the current working directory for bind files generated by the DB2 ECM.
Comments
The DB2 ECM uses the specified directory until the variable is unset or reset to a different directory. The DB2 Compiler directive option BIND overrides this environment variable.
Example
HCOBND=d:\mydir\binds

HOST_DISP

Determines whether JCL DISP is honored for DELETE on mainframe resident datasets.
Syntax
HOST_DISP={ON|OFF}
Parameters
ON
JCL DISP is honored for DELETE.
OFF
JCL DISP is not honored for DELETE.
Default
HOST_DISP=OFF

HOST_NEW

Determines whether JCL looks on the host for new datasets that are not cataloged locally.
Syntax
HOST_NEW={ON|OFF}
Parameters
ON
JCL looks on the host for new datasets not cataloged locally.
OFF
JCL does not look on the host for new datasets not cataloged locally.
Default
HOST_DISP=OFF

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.
Syntax
IMSCPY=path-name
Parameter
path-name
The full path to the location of compiled COBOL applications.

ISPPROF

The location of ISPF dialog profiles.

J

JAVA_HOME

Specifies the location of the JDK.
Syntax
JAVA_HOME=path-name
Parameter
path-name
The full path to the location of the JAVA_HOME location.

JCLTEMP_DIR

Enables you to specify a separate location for the JCLTEMP directory.
Syntax
JCLTEMP_DIR=path
Parameter
path
The full or relative path to the location of your JCLTEMP directory.
Default
Not set. Uses the directory specified by MFBSI_DIR.

JES_PRINT_SPOOL_MSG

Specifies the disposition of the spool data set printing message (JES000029I).
Syntax
JES_PRINT_SPOOL_MSG={CONSOLE|LOG|SILENT}
Parameters
CONSOLE
Send spool data to the console.log file.
LOG
Send spool data to 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 the spool files, and a new file is created every day.
SILENT
No messages. Use this option with caution, as it specifies that no audit log of your spool data sets is created.
Default
JES_PRINT_SPOOL_MSG=CONSOLE
Comments
This environment variable is intended for high-print-load users, meaning that a high number of print requests are sent to the console. This could affect system performance.
Related information
JES000029I xxxxxx on yyyyyy

L

LIB

The location of the DB2 LIB directory.
Syntax
LIB=path-name
Parameter
path-name
The path to your Windows SDK LIB directory (x86) containing .lib files such as odbc32.lib.
Comments
This environment variable is set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.
Related information
Build and configure the XA connector for the RDBMS

M

MAINFRAME_FLOATING_POINT

Specifies the format to use for floating point data items. Possible formats are IBM hexadecimal and IEEE.
Syntax
MAINFRAME_FLOATING_POINT={true|false}
Parameters
true
Use IBM hexadecimal-format floating-point data items.
false
Use IEEE-format floating-point data items.
Default
MAINFRAME_FLOATING_POINT=false
Comments
The setting of this environment variable can be overridden by the NATIVE-FLOATING-POINT directive.

MF_ALIAS

Specifies program aliases.
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]
Parameters
program-name1...10
An eight-character program name.
Important: A program name shorter than eight characters must have trailing spaces extending its length to eight characters.
alias1...10
An eight-character alias.
Important: An alias shorter than eight characters must have trailing spaces extending its length to eight characters.
Default
Not set.
Comments
Each program-name/alias pair is 16 characters long — eight characters for the program-name, and eight characters for the alias. You can specify up to 10 pairs.

program-name/alias pairs are searched first in the order in which they appear and thus can potentially override the built-in list. If not found, the built-in alias table is searched.

Example
MF_ALIAS=IKJEFT1BIDAEFT01MYPROG  THEIRPRG
Adds:
Program-name | Alias
IKJEFT1B | IDAEFT01
MYPROG | THEIRPRG

MF_AMODE31ONLY

Indicates that all programs are AMODE(31).

MF_CHARSET

Specifies the system character set.
Syntax
MF_CHARSET={{A|ASCII}|{E|EBCDIC}}
Parameters
A|ASCII
Use the ASCII character set.
E|EBCDIC
Use the EBCDIC character set.
Default
MF_CHARSET=A

MF_CBLQDA

Determines if QSAM files are dynamically allocated
Syntax
MF_CBLQDA={ON|OFF}
Parameters
ON
Dynamically allocate QUSAM files when processing an OPEN I-O or OPEN EXTEND statement for an optional file (i.e., a file opened using the SELECT OPTIONAL syntax in the FILE-CONTROL paragraph) or a file opened for OUTPUT, whether it is optional or not.
OFF
Dynamic allocation is not permitted.
Default
MF_CBLQDA=OFF
Comments
This is an emulation of the CBLQDA Language Environment (LE) run-time option.

When set to ON, and your JCL contains a misspelled or no DD statement for the file being opened, a temporary file is created as a result of the OPEN statement, and then deleted after the program has run. For optional files opened for I-O or for EXTEND, you receive a return code of 05; for files opened for OUTPUT, you receive a return code of 00.

This variable has no effect on VSAM applications or the JCL utility programs.

For programs that use ESDS files and have this variable set ON, ensure that FILETYPE is set to 15 or 16; otherwise these files will be affected by the variable, and treated as QSAM files.

MF_DUPJOBS

Specifies whether jobs with duplicate names are allowed to run in parallel.
Syntax
MF_DUPJOBS={Y|N}
Parameters
Y
Jobs with duplicate names are allowed to run in parallel.
N
Jobs with duplicate names are not allowed to run in parallel.
Default
MF_DUPJOBS=N

MF_FALLTHRUCHECK

Specifies whether MSS is to check that the main COBOL program ends by executing a GOBACK or STOP RUN.
Syntax
MF_FALLTHRUCHECK={Y|N}
Parameters
Y
Check that the main COBOL program ends by executing a GOBACK or STOP RUN.
N
Do not check that the main COBOL program ends by executing a GOBACK or STOP RUN.
Default
MF_FALLTHRUCHECK=Y
Comments
If MF_FALLTHRUCHECK is set to Y and the check fails, MSS issues this message:
JCLCM0213S Main pgm xxxxxxxx did not issue GOBACK or STOP RUN.

MF_IKJEFT_KEEP_MAX

Determines whether IKJEFT01 uses the last return code from a command or the highest return code of all commands executed as the step COND CODE.
Syntax
MF_IKJEFT_KEEP_MAX={Y|N}
Parameters
Y
IKJEFT01 uses the highest return code of all commands executed as the step COND CODE.
N
IKJEFT01 uses the last return code from a command as the step COND CODE.
Default
MF_IKJEFT_KEEP_MAX=N

MF_JCL_AUDIT

Specifies that audit information is written to the audit log when a catalog entry is deleted.
Syntax
MF_JCL_AUDIT={DLET|DLEJ|DLET,DLEJ}
Parameters
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.
Default
Not set.
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

The following is an example of the audit event passed to SYSLOG:

mf.jcl 35500 5:5 [timeQuality tzKnown="1" isSynced="0"][origin ip="127.0.0.1" enterpriseID="********.5043"
software="Micro Focus Auditing" swVersion="API ver 1.2.2 syslog ver 1.0.0"][meta
sequenceId="88"][MFAuditPropertyList@5043 SYSTEM="AUDIT   "] userid=SYSAD    groupid=SYSADM
  jobnum=0000000 jobname=ESMAC    dsname=MFI01.ANF.TEST1
     member=         api=MVSCATIO apifunc=DLET

MF_JES_ABEND_CAF_COMMIT

Specify the outcome when a non-zero return code is received from the commit at the end of a DSNAL or IKJEFT** unit of work.
Syntax
MF_JES_ABEND_CAF_COMMIT={Yes|No|return-code}
Parameters
Yes
Generates an S482 abend.
No
Does not generate an abend.
return-code
A numeric value up to three digits to be used as the return code.
Default
MF_JES_ABEND_CAF_COMMIT=Yes

MF_JESPWR_EXIT

Passes JES2 and VSE PWR statements to the MFJESPWR user exit.
Syntax
MF_JESPWR_EXIT=Y
Parameter
Y
Pass JES2 and VSE PWR statements to the MFJESPWR user exit.
Default
Not set.
Comments
When set, the JCL execution engine calls the MFJESPWR exit program 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_LE_CBLOPTS

Specifies whether classic COBOL style options are in effect.
Syntax
MF_LE_CBLOPTS={Y|N}
Parameters
Y
Enables classic COBOL style options.
N
Disables classic COBOL style options.
Default
MF_LE_CBLOPTS=N
Comments
When disabled, or when the dialect is ENTCOBOL, or when the language is not COBOL, PARM syntax is of the following form:
[run-time-options] [/program-options];

Otherwise, the syntax is of the form:

[program-options] [/run-time-options]

MF_LEX_API

Specifies whether the JES configuration uses single or multiple LEX files, and enables JES configuration to specify subdirectories for LEX files as necessary.
Syntax
MF_LEX_API={1|2|D}|1D|2D|D
Parameters
1
Use multiple LEX files.
2
Use a single LEX file. Disk-based access only.
D
Use directories to store LEX files.
Default
MF_LEX_API=1
Comments
Do mix these settings in a Region/PAC. They must be consistent for all.
Example
This example sets the JES configuration to use a single LEX file stored in directories.
MF_LEX_API=2D

MF_MFA

Specifies what data set catalogs are to be searched.
Syntax
MF_MFA={ALL|RJSE}
Parameters
ALL
Search for data sets first in the local catalog, and if not found, on the mainframe.
RJSE
Search for data sets in the local catalog only. No mainframe search is performed.
Default
MF_MFA= ALL

MF_MVSJOB

Sets the number at which a job starts and finishes.
Syntax
MF_MVSJOB=lower-value{-|+}upper-value
Parameters
lower-value
Number at which a job starts. Contains seven digits - for example, 0000001.
+
Reset the values to these new ones each time the region is started.
-
Sets the values but only on the first startup of the region.
upper-value
Upper job number. Contains seven digits - for example, 9999999.
Default
MF_MVSJOB=0001000+0099999
Comments

This environment variable can be used to enable a seven-digit Job number limit. If the upper-value is greater than 99999, then 6+ digit job number support is enabled. The maximum value that can be set is 9999999.

Tip: To revert to five-digit job number support, set:
 MF_MVSJOB=lower-limit+upper-limit

Where upper-limit is less than 0099999, and ensuring that the + sign is used to separate the low and high values.

Example
Resets the values to start with job number 10 and run through to job number 100:
MF_MVSJOB=0000010+0000100

When the upper limit has been reached, you receive a message:

All job numbers in the range 0000010:0000100 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.

Related information
Spool Housekeeping

MF_MVSP0034_LIMIT

Specifies the number of records in each exported catalog XML document.
Syntax
MF_MVSP0034_LIMIT=limit
Parameter
limit
A one- to six-digit number between 1 and 999999.
Default
Not set. All records are written to the catalog export XML file

MF_NEWSPACE

Indicates whether SPACE is required for NEW datasets.

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.
Default
MF_NODD=A

MF_PCRENAME_LAX

Determines whether physical files in other locations can be renamed if the cataloged name is changed.
Syntax
MF_PCRENAME_LAX={Y|N|D}
Parameters
Y
Enables physical files in other locations to be renamed if the cataloged name is changed.
N
When an MVS dataset is renamed, the associated physical file is normally renamed only if it is stored in a subdirectory of the of the catalog file location.
D
Creates a new directory structure and filename, and moves the existing file to the new location.
Properties
MF_PCRENAME_LAX=N

MF_RCCF

Determines whether to enable or disable Job Step Execution (RJSE).
Syntax
MF_RCCF={DELETEJOB|KEEPJOB}
Parameters
DELETEJOB
Disables RJSE.
KEEPJOB
Enables RJSE.
Default
MF_RCCF=DELETEJOB

MF_ROOT_CERT

Enables the MF Directory Server process and any client applications to find the root certificate file.
Related information
Securing Communications Process to MF Directory Server using TLS
MF Directory Server Security

MF_SET_USERID

Sets the default user ID.
Syntax
MF_SET_USERID=userid
Parameter
userid
The user ID to set as the default.
Default
Not set. The default user ID is mfuser.

MF_SMS

Enables support for IBM Storage Management Subsystem (SMS) data classes.
Syntax
MF_SMS={ON|OFF}
Parameters
ON
Turns on support for SMS data classes.
OFF
Turns off support for SMS data classes.
Default
MF_SMS=OFF
Comments
MSS provides emulation for SMS data classes only.

To enable DATACLAS support this variable needs to be ON in addition to setting MFUSERCAT_NODE=SYSMFE1.

Related information
MFUSERCAT_NODE

MF_SPLJNO_LOCK

Determines whether job number acquisition is enqueued to reduce file and disk access or handled with file locks to improve performance when running JCL jobs on multiple processes.
Syntax
MF_SPLJNO_LOCK=Y
Parameter
Y
Enqueue job number acquisition.
Default
Not set. Job number acquisition is handled with file locks, which can improve performance when running JCL jobs on multiple processes.
Comments
The parameter value is not case sensitive.

Setting MF_SPLJNO_LOCK to no value or any value other than Y or y results in the default behavior.

MF_SPOOL_ARCHIVE_LOC

The base location for files archived as part of the spool housekeeping process, where the contents of the MVS SPOOL spool file are archived prior to deletion.
Syntax
MF_SPOOL_ARCHIVE_LOC=path-name
Parameter
path-name
The base location for files archived as part of the spool housekeeping process
Default
Not set.

MF_SPOOL_HK_LEX_SCAN

Determines if the MFELX* files associated with a job are also deleted when spool housekeeping is run.
Syntax
MF_SPOOL_HK_LEX_SCAN={Y|N}
Parameters
Y
The files are deleted.
N
The files are not deleted.
Default
MF_SPOOL_HK_LEX_SCAN=Y

MF_SPOOL_HK_OUTPRT

Determines if files from the Complete queue with a status of Output or Printed are also deleted when spool housekeeping is run.
Syntax
MF_SPOOL_HK_OUTPRTC={Y|N}
Parameters
Y
Files from the Complete queue are deleted.
N
Files from the Complete queue are not deleted.
Default
MF_SPOOL_HK_OUTPRT=Y

MF_SPOOL_HK_TESTDATE

Overrides the normal date for the spool housekeeping.
Syntax
MF_SPOOL_HK_TESTDATE=YYYYMMDD
Parameters
The following are used to represent the date used to override the normal date
YYYY
Four-digit year.
MM
Two-digit month.
DD
Two-digit day.
Default
Not set. Uses the normal date for the spool housekeeping.

MF_SPOOL_HK_WRITE_PROFILES

Determines the creation of profile files (.PRO files) when a data set is archived.
Syntax
MF_SPOOL_HK_WRITE_PROFILES={Y|N}
Parameters
Y
Profile files are created.
N
Profile files are not created.
Default
MF_SPOOL_HK_WRITE_PROFILES=Y

MF_SYSLOGDSN

The Syslog Dataset name.

MF_UCC11

Configures emulation of UCC11, which is the JCL job restart functionality.
Syntax
MF_UCC11={Y|YA|M|MA|MR|N}
Parameters
Y
When restarting a job with DISP=(NEW,CATLG), it will not result in job failure caused by the data set already being cataloged.
YA
When running a job with DISP=(NEW,CATLG), it will not result in job failure caused by the data set already being cataloged.
M, MA, MR
When restarting a job any data set that has an inital disposition of NEW is changed to MOD. Therefore, data will be appended to the data set if it already exists.
N
MF_UCC11 is not set so a data set with an initial disposition of NEW might cause an error when restarting the job if the data set already exists.
Default
MF_UCC11=N
Comments

This environment variable works independently of the JCL RESTART parameter.

The setting of the MF_UCC11 value can be made on a job-by-job basis using either the JCL user exit, MFJUXIT, or the Advanced Restart Functionality.

When set to Y or YA, if the job uses GDG data sets, the GDG generation is reset to the level used in the previous job, ensuring that the restart will automatically pick up the correct GDG generation.

GDG Restart information is usually only written when MF_UCC11=Y, YA or M and ES_JES_RESTART=Y. You can ensure that it is always written by setting ES_JES_RESTART=Y and GDG_RESTART_UCC11_ONLY=N - this will ensure that the restart information is available if a job is restarted at a later date.

When restarting a job with restart functionality enabled (that is, values Y, YA, or M), 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 set to YA or M and the disposition of the data set is DISP=NEW, if the DSORG of the data set is defined on the DD Card, it will be checked against the catalog record, if the latter exists. If there is a mismatch, or if the catalog record refers to a GDG base, the data set will not be replaced, and the JCLCM0200S error message is issued.

Related concepts
Advanced Restart Functionality
Related information
GDG_RESTART_UCC11_ONLY
ES_JES_RESTART
JCLCM0200S job-number job-name DISP=NEW, DATASET EXISTS - DDNAME
MF_UCC11_DYNCLEAN

MF_UCC11_DYNCLEAN

When MF_UCC11 is enabled, controls whether dynamically allocated datasets (such as using SVC99) are cleaned when a job is restarted.
Syntax
MF_UCC11_DYNCLEAN={Y|N}
Parameters
Y
When a job is restarted, any dynamically allocated datasets are removed and replaced.
N
Prevents the cleaning of dynamically allocated datasets when restarting a job.
Default
MF_UCC11_DYNCLEAN=Y
Comments
Depandancies are valid only when MF_UCC11=Y or YA.
Related information
MF_UCC11

MF_USESCA5

Specifies that the server should use version 5 of the Open Service Component Architecture (Open SCA).
Syntax
MF_USESCA5={ON|OFF}
Parameters
ON
The server uses version 5 of the Open SCA.
OFF
The server uses the default version of Open SCA.
Default
MF_USESCA5=ON

MF_USESCA7

Determines whether MSS accepts CA7 Scheduler control statements as comments rather than diagnosing them as errors.
Syntax
MF_USESCA7={ON|OFF}
Parameters
ON
Accepts CA7 Scheduler control statements as comments.
OFF
Diagnoses CA7 Scheduler control statements as errors.
Default
MF_USESCA7=ON

MFACCCGI_CHARSET

Specifies the charset used in the HTTP header returned by ESMAC.
Syntax
MFACCCGI_CHARSET=iana-string
Parameter
iana-string
An IANA-defined charset string.
Default
MFACCCGI_CHARSET=windows-1252

MFACLIENTINI

The complete path to the mfaclient.ini file, which contains mainframe logon credentials.
Syntax
MFACLIENTINI=path-name
Parameter
path-name
The complete path to the mfaclient.ini file.
Default
Not set. Uses the default location of the mfaclient.ini file, which is %APPDATA%\micro focus.
Comments
Used by mfdasmx.

MFALLOC_DEF_VB_PCFILE

Determines whether a new PS VB file is defined in the catalog.
Syntax
MFALLOC_DEF_VB_PCFILE={Y|N}
Parameters
Y
A new PS VB file is defined in the catalog as a VB file with default settings of minimum length = 0, and maximum length = 32760.
N
Do not create a new PS VB file.
Default
MFALLOC_DEF_VB_PCFILE=Y
Comments
Valid only when the LRECL mfims imsdbu directive is not set or is set to 0 (zero).

MFALLOC_LOC

The default allocated dataset location.
Syntax
MFALLOC_LOC={path-name|SQL-URL}
Parameters
path-name
The full path to the dataset location.
SQL-URL
For a database-hosted dataset, the SQL URL to that location.
Default
Not set.
Example
Set the default allocated dataset to the sql://localhost/JCLTEST?folder=/JCLDEMO/data location:
MFALLOC_LOC=sql://localhost/JCLTEST?folder=/JCLDEMO/data

MFALLOC_PCFILE

Determines whether a catalogued file is created when DSORG=PS is provided in the DCB parameters.
Syntax
MFALLOC_PCFILE={Y|N}
Parameters
Y
A catalogued file is created when DSORG=PS is provided in the DCB parameters.
N
A catalogued file is not created.
Default
MFALLOC_PCFILE=Y
Comments
Valid only when DSORG=PS is provided in the DCB parameters.

MFALLOC_PROP

Rules for generated PC dataset names on allocation (that is, the default catalog PC DSN format).

MFACLIENTINI

The complete path to the mfaclient.ini file, which contains mainframe logon credentials.
Syntax
MFACLIENTINI=path-name
Parameter
path-name
The complete path to the mfaclient.ini file.
Default
Not set. Uses the default location of the mfaclient.ini file, which is %APPDATA%\micro focus.
Comments
Used by mfdasmx.

MFAIMBEDDEDHEX

Determines whether the COBOL run-time system properly handles hex values embedded in source code.
Syntax
MFAIMBEDDEDHEX=COBOL
Parameter
COBOL
Enables the COBOL run-time system to properly handle hex values embedded in source code, meaning that all translated hex values less than x'1f' have a null character inserted before the hex value.
Default
Not set. The COBOL run-time system does not handle embedded hex values.
Comments
When set, hex values are handled in the same manner as when using the MDECONV application.

MFAMAXSENDLENGTH

Sets the maximum length of data that can be transmitted in a single communication packet to or from the mainframe.
Syntax
MFAMAXSENDLENGTH=max-data-length
Parameter
max-data-length
The number of bytes that represents the maximum length of data.
Default
Not set.
Comments
This is useful when there is a router that limits the transfer length of data to or from the mainframe, or when the allowable length of transferred data is restricted.

This setting 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.

Example
MFAMAXSENDLENGTH=4000

MFASERV

Controls how Mainframe Access checks for a dataset name (DSN).
Syntax
MFASERV=ON
Parameter
ON
If a DSN is not found in the local catalog, then the catalog API calls MFA to check the mainframe for the DSN.
Default
Not set. The catalog API does not call MFA to check the mainframe for the DSN.

MFAUDIT_LOGS

The location of audit files.

MFBSI_DIR

Identifies the directory used by MFBSI to store MFBSIJCL log files, any semaphore files (JOBnnnnn.sem), and substituted JCL members.
Syntax
MFBSI_DIR=path-name
Parameter
path-name
The full path to the directory where MFBSI stores files.
Default
Not set.
Comments
For complete information about using MFBSI_DIR to configure your enterprise server region, see Configuring the Server.

MFCATMNTUE

Specifies the name of the MFCATMNT user exit program if not compiled to the default name of MFCATMNTUE.
Syntax
MFCATMNTUE=program-name
Parameter
program-name
Represents the name of the MFCATMNT user exit program if not compiled to the default name of MFCATMNTUE.
Default
Not set. User exit program is compiled using the default name of MFCATMNTUE.

MFCODESET

Specifies which translation tables to use.
Syntax
MFCODESET=country-code
Parameter
country-code
The country code required for translation. See Supported Country Codes for a list of countries and codes.
Default
Not set. Uses the country code returned from the CBL_GET_OS_INFO routine.
Comments
If you are not using UK or US language settings, you must also set MFCODESET as a Windows system variable. See your Windows documentation for details.
Related information
Code set translation
Supported country codes

MFCODESET_DBCSDIR

The location of a set of mapping files (.E2A and .A2E files) required for an application to perform ASCII/EBCDIC conversions of certain double-byte character sets.
Syntax
MFCODESET_DBCSDIR=path-name
Parameter
path-name
The full path to the location of .E2A and .A2E files.
Default
Not set. The application looks in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\codeset directory to locate the files required for the inbuilt support.
Comments
The support covers codesets 81, 82, 86, 886, and 941.

Certain deployed applications do not require a full Enterprise Test Server product to be available (for example, .NET COBOL applications, and native self-contained applications), and so cannot utilize the inbuilt translation support provided by a full product. In these cases, you must deploy the mapping files with the application, and use this variable to locate the files at run time. You only need to deploy the .E2A and .A2E files appropriate to the codeset(s) you require.

Related information
To install a supported country code for deployed applications
Code set translation

MFCROW_DISABLE

Turn off common directives, preventing compilers from using directives found in directives.mf files.
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.
Syntax
MFCROW_DISABLE={Y|N}
Parameters
Y
Compilers do not use directives in directives.mf files.
N
Compilers use directives in directives.mf files.
Default
MFCROW_DISABLE=N

MFCSCFG

Specifies a configuration file to be used by the Client/Server Binding client program.
Syntax
MFCSCFG=[path-name\]file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The name of the configuration file.
Default
MFCSCFG=mfclisrv.cfg
The default path-name is the current working directory, and if not found, the default settings for the configuration entries are used.
Comments
The value of MFCSCFG is overridden by any value defined in the command line.
Example
MFCSCFG=d:\mydir\mfclisrv.cfg

MFDBFH_CONFIG

Specifies the location and the name of the configuration file that defines the database server instances and associated databases.
Syntax
MFDBFH_CONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the configuration file.
file-name
The file name of the configuration file.
Default
Not set. Uses the mfdbfh.cfg file found in the current working directory.
Comments
You can also set MFDBFH_CONFIG as a system environment variable.
Related information
ES_DB_SERVER
Database File Handling and Enterprise Server Region Database Management

MFDBFH_GRANT_USER_PERMISSIONS

Grants execute privileges to specific users or roles, for types and procedures that are created when configuring an Oracle database for MFDBFH access.
Syntax
MFDBFH_GRANT_USER_PERMISSIONS={user|role}[{user|role}[...]]
Parameters
user
A user granted execute privileges for types and procedures created by MFDBFH.
role
A role granted execute privileges for types and procedures created by MFDBFH.
Default
Not set. Oracle default permissions are applied, which are to grant execute permissions to the schema owner of that type/procedure only.
Comments
This variable has no effect on permissions for any other database provider used with MFDBFH.

MFDBFH_RECORD_LOCKING

Specifies the type of record locking that it is to be used when the database file handler is in effect.

Syntax
MFDBFH_RECORD_LOCKING={table|database}
Parameters
table
A file's record locks are held in a seperate lock table. (When using this locking mode, the behavior of record locking COBOL file operations closely follows the same behavior when using Fileshare.)
database
The native record locking mechanism of the database engine is used to establish and test locks on the data file records. This method improves performance, but at the cost of the locking behavior not exactly matching that of traditional COBOL record locking; see Record Locking Strategies for more information.
Default
MFDBFH_RECORD_LOCKING=table
Related information
Record Locking Strategies

MFDBFH_SCRIPT_DIR

Specifies the location of the scripts and stored procedures required when the database file handler is in effect.
Syntax
MFDBFH_SCRIPT_DIR=path-name
Parameter
path-name
The full path to the directory containing the required resources.
Default
MFDBFH_SCRIPT_DIR=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mfdbfh\scripts

MFDBFH_VAULT

Specifies the name of a secrets vault.
Syntax
MFDBFH_VAULT=vault-name
Parameter
vault-name
The name of a vault that is defined in the product's secrets.cfg file.
Default
Not set. Uses the default vault as defined in secrets.cfg.
Comments
For more information on secrets vaults, see Vault Facility.
Related information
Vault Facility

MFE.FALLTHRUCHECK

Enables messages to be issued if the user program does not return from a main program via GOBACK or STOP RUN.

MFE.SMS

Enables SMS support.

MFEXTMAP

Location of a mapper file.

MFFTP_ASCII_CMD_XLATE

For EBCDIC datasets, translates from EBCDIC to ASCII using a PUT, and ASCII to EBCDIC using a GET.
Syntax
MFFTP_ASCII_CMD_XLATE={Y|N}
Parameters
Y
Converts from EBCDIC to ASCII in PUTs and from ASCII to EBCDIC in GETs, for files cataloged as EBCDIC when TYPE A or ASCII sub command is also issued.
N
Standard conversion.
Default
MFFTP_ASCII_CMD_XLATE=N

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.

MFJ_ALL_STEP_CHECK

Use this variable to prevent any steps after a restart step that have conditions that refer to any steps prior to the restart from running.
Syntax
MFJ_ALL_STEP_CHECK={Y|N}
Parameters
Y
Do not run any steps after a restart step that have conditions that refer to any steps prior to the restart.
N
Run the steps listed after a restart step that have conditions that refer to steps prior to the restart.
Default
MFJ_ALL_STEP_CHECK=N
Comments
The default behavior of this product is to not check COND CODES from steps prior to a restart step. This means that the steps after the restart step that have conditions that refer to any steps prior to the restart step might run. This is a change of behavior from releases 4.0 Patch Update 1 and earlier when these steps would have not run. Micro Focus recommends that you review and test the behavior before restarting the jobs.

Set this variable to Y to prevent steps after a restart step that have conditions that refer to any steps prior to the restart from running.

The setting of MFJ_ALL_STEP_CHECK is bypassed if the Abend and Cond Code Recover option of the Advanced Restart Functionality is used.

MFJ_INPUTDS_ERROR

Determines whether IEBDG, IEBGENER, IEBCOMPR, and DFSORT, and ICETOOL emulation treat missing input files as though they were present but empty.
Syntax
MFJ_INPUTDS_ERROR={Y|N}
Parameters
Y
Treats missing input files as missing.
N
Causes IEBDG, IEBGENER, IEBCOMPR, and DFSORT, and ICETOOL emulation to treat missing input files as though they were present but empty.
Default
MFJ_INPUTDS_ERROR=Y

MFJ_LEX_LOCATION

Specifies an alternative location for the storage of JCL lexigraphical files, which are created when a job is parsed, and are stored in the same directory as the job log by default.
Syntax
MFJ_LEX_LOCATION=path-name
Parameter
path-name
The full path to the alternative directory location in which to store JCL lexicographical files. The alternative directory location must be accessible by all enterprise server regions that both submit and run jobs.
Default
Not set.

MFJ_PTPCH_CODESET

When using a codeseet similar to but other than Japanese 9122, causes MFJPTPCH to match hexadecimal character values with those in Japanese code set 9122 to determine whether a character is printable or not.
Syntax
MFJ_PTPCH_CODESET=EXTJ
Parameter
EXTJ
MFJPTPCH attempts to match hexadecimal character values with those in Japanese code set 9122 to decide whether a character is printable or not.
Default
Not set. Hexadecimal character values are not evaluated for printability.
Comments
For use only when an extended Japanese code set other than 9122 is being used.

MFJ_REPORT_DATE_CHANGE_2

Determines whether date stamps are recorded in the JESYSMSG job log of when a is job started along with date changes date changes during execution.
Syntax
MFJ_REPORT_DATE_CHANGE={Y|N}
Parameters
Y
Date stamps are recorded in the JESYSMSG job log of when a is job started along with date changes during execution.
N
Switches off date stamps in the log.
Properties
MFJ_REPORT_DATE_CHANGE=Y

MFJ_REPRO_EMPTY

Determines whether the IDCAMS REPRO action can copy from a pristine VSAM file.
Syntax
MFJ_REPRO_EMPTY={Y|N}
Parameters
Y
Enables the IDCAMS REPRO action to copy from a pristine VSAM file. The resulting file is empty.
N
Prevents the IDCAMS REPRO action from copying from a pristine VSAM file, and produces a JCLAM0150S error when attempted.
Properties
MFJ_REPRO_EMPTY=Y

MFJ_STRICT_CASE

Determines the case to be maintained for physical file names passed to MVSCATIO by the catalog API and other utilities such as the mfcatxml utility for exporting and importing a catalog, and the mvspcrn utility for bulk updates.
Syntax
MFJ_STRICT_CASE={Y|N}
Parameters
Y
MVSCATIO honors the case of physical file names passed by the catalog API, and other utilities.
N
All physical file names are folded into upper case.
Default
MFJ_STRICT_CASE=N
Related information
Importing and Exporting a Catalog: import export utility
Bulk Update of Catalog

MFJFAXIT

Specifies the user exit program that enables file action notifications.
Syntax
MFJFAXIT=path-name\file-name
Parameters
path-name
The full path to the location of the user exit program that enables file action notifications.
file-name
The name of the user exit program file.
Default
Not set. The MFJAXIT user exit is not enabled.
Comments
This user exit is called by the JCL engine whenever a JCL file is opened OUTPUT, I-O, or EXTEND, or when it is copied or renamed by the JCL engine.
Example
A sample user exit program (MFJFAXIT.cbl) is provided with your product, and is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits directory.

MFJSABCODE

Determines the abend code issued when MFJSERET=ABEND is in effect.
Syntax
MFJSABCODE=abend-code
Parameter
abend-code
A decimal value between 1 and 99 representing the abend code to issue.
Default
Not set. When MFJSERET=ABEND is in effect, an abend S00D (decimal code 16) is issued when a Sort or Merge operation fails with an unrecoverable error. Otherwise, the program terminates with an unrecoverable error.
Comments
If a Sort or Merge operation fails with an unrecoverable error, it will abend with a code between S001 and S063.
Example
This example results in abend code S04D being issued:
MFJSABCODE=77
Related information
MFJSERET

MFJSDCBOUTFIL

MFJSDCBOUTFIL
Determines whether the DCB's LRECL value is honored during an OUTFIL statement.
MFJSDCBOUTFIL={ON|OFF}
Parameters
ON
The LRECL specified in the DCB properties is used during an OUTFIL statement.
OFF
Emulates the ICE222A/ICE217A mainframe restriction.
Default
MFJSDCBOUTFIL=OFF
Comments
When MFJSDCBOUTFIL=ON is in effect, if the DCB LRECL value differs from that calculated by OUTFIL, records are either truncated or padded with space to match the DCB LRECL value.
Example
MFJSDCBOUTFIL=ON

MFJSENGINE

Specifies which sort engine the utility MFJSORT is to emulate.
Syntax
MFJSENGINE={DFSORT|SYNCSORT}
Parameters
DFSORT
MFJFSORT emulates the mainframe DSORT utility.
SYNCSORT
MFJFSORT emulates the SYNCSORT utility.
Default
MFJSENGINE=DFSORT
Related information
Introduction
SYNCSORT Emulation

MFJSERET

Allows an unsuccessful operation to abend, but prevents this from terminating the program with an unrecoverable error.
Syntax
MFJSERET=ABEND
Parameter
ABEND
The operation will abend and its program will continue instead of terminating with an unrecoverable error (return code 16)
Default
Not set. An unsuccessful operation and its program terminate with an unrecoverable error (return code 16). See also MFJSABCODE.

MFJSSTRICTSORT

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.
Syntax
MFJSSTRICTSORT={ON|OFF}
Parameters
ON
Disables the mainframe behavior described above.
OFF
Enables the mainframe behavior described above.
Default
MFJSSTRICTSORT=OFF

MFJSTATS

For a COBOL sort not running under mainframe emulation, determines whether statistics are included in reports produced for the COBOL SORT operation.
Syntax
MFJSTATS={ON|OFF|switch}
Parameters
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.
OFF
No statistics are included in the report.
switch
Switches the inclusion of statistics in the report to ON when set to OFF, and to OFF when set to ON.
Default
MFJSTATS=OFF
Comments
If you are performing a COBOL sort using mainframe emulation, you can create a statistics report by modifying the JCL statement.

MFJSWINDOW

Determines the sliding or fixed century window.
Syntax
MFJSWINDOW={sliding-century|fixed-century}
Parameters
0
A century window that starts with the current year.
sliding-century
A number from 1 through 100. This sets the century window based on the current year, determining the starting year by subtracting the number specified from the current year. If unchanged from year to year, the starting year slides forward each year.
fixed-century
A year from 1000 through 3000. This sets the century window to start on the year specified.
Defaults
When emulating DFSORT, a sliding window set to 80:
MFJSWINDOW=80

When emulating SYNCSORT:

MFJSWINDOW=0
Comments
You can use this environment variable instead of the Y2PAST sort option.

Use this environment variable for Y2K compatibility when two-digit year values are used.

Examples
In the year 2020, set a sliding window to start in 1990 and end in 2090:
MFJSWINDOW=30

In the year 2020, set a fixed window to start in 1990 and end in 2090:

MFJSWINDOW=1990

MFLECONFIG

Specifies a configuration file for Language Environment (LE) run-time options.
Syntax
MFLECONFIG=path-name\file-name
Parameters
path-name
The full path to the location of the ile containing the LE run-time options you want to use.
file-name
The name of the file containing the LE run-time options you want to use.
Default
Not set. No LE run-time options are used.

MFLOCKING

Enables Locking Support.

MFLOGDIR

Specifies a directory to be used by Client/Server Binding for log files.
Syntax
MFLOGDIR=path-name
Parameter
path-name
The full path to the location of log files.
Default
Not set.
Example
MFLOGDIR=d:\mydir\logs

MFPRELOAD_USE

Calls MFPRELOAD to improve performance.

MFREXX_CHARSET

Specifies the character set used by the REXX engine when working with hexadecimal strings or performing string comparisons.
Syntax
MFREXX_CHARSET={A|E}
Parameters
A
Use the ASCII character set.
E
Use the EBCDIC character set.
Default
MFREXX_CHARSET=E

MFREXX_CONCAT

Specifies one or more characters to be used for the CONCAT operator.
Syntax
MFREXX_CONCAT={"char-op"|char-hex}[{ |,}{"char-op"|char-hex}[...]]
Parameter
char-op
A character operator to use in addition to the default operator.
char-hex
A hexadecimal value that represents a character operator to use in addition to the default operator.
Default
Not set. The default character operator is ?.
Comments
Single quotes may be substituted for double quotes.

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.

Examples
Both examples set & (hex value 26) and # (hex value 23) as CONCAT operators in addition to ?:
MFREXX_CONCAT="&" 23
MFREXX_CONCAT=26,'#'

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
Parameter
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.
Default
MFREXX_LSEQ_RECSIZE_MAX=255

MFREXX_NO_PROCESS_STDIN

Determines whether to stop STDIN from being processed on an EXECIO command.
Syntax
MFREXX_NO_PROCESS_STDIN={Y|N}
Parameters
Y
Stops STDIN from being processed on an EXECIO command.
N
STDIN is processed on an EXECIO command.
Default
MFREXX_NO_PROCESS_STDIN=N

MFREXX_NOT

Specifies one or more characters to be used for the NOT operator in addition to the default.
Syntax
MFREXX_NOT={"char-op"|char-hex}[{ |,}{"char-op"|char-hex}[...]]
Parameters
char-op
A character operator to use in addition to the default operator. Each additional character must be defined within single or double quotes.
char-hex
A hexadecimal value that represents a character operator to use in addition to the default operator.
Default
Not set. The default character operator is ¬.
Comments
Single quotes may be substituted for double quotes.

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.

Examples
Both examples set & (hex value 26) and # (hex value 23) to be used as NOT operators in addition to ¬:
MFREXX_NOT="&" 23
MFREXX_NOT=26,'#'

MFREXX_OR

Specifies one or more characters to be used for the OR operator in addition to the default.
Syntax
MFREXX_OR={"char-op"|char-hex}[{ |,}{"char-op"|char-hex}[...]]
Parameters
char-op
A character operator to use in addition to the default operator.
char-hex
A hexadecimal value that represents a character operator to use in addition to the default operator.
Default
Not set. The default character operator is |.
Comments
Single quotes may be substituted for double quotes.

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

Examples
Both examples set & (hex value 26) and # (hex value 23) to be used as OR operators in addition to |:
MFREXX_NOT="&" 23
MFREXX_NOT=26,'#'

MFRU_NOINHERIT

Determines whether to skip registering processes in shared memory during initialization of the run-time system.
Syntax
MFRU_NOINHERIT={Y|TRUE}
Parameters
Y|TRUE
Do not register processes in shared memory during initialization of the run-time system.
Default
Not set. Processes are registered.
Comments
Consider setting this variable to avoid COBRT105 errors, which can occur during initialization if a very large number of COBOL processes are running and there are no available slots in the shared memory segment.

When set, various run-time settings such as switches, shared memory, console window settings, and so on, are no longer inherited by any child processes.

MFSUB

Specifies whether to use SUBI or ASUBI.
Syntax
MFSUB={SUBI|ASUBI}

MFSYSCAT

The location and file name of the JES system catalog.
Syntax
MFSYSCAT={path-name\CATALOG.DAT|URL}
Parameters
path-name
The full path to the location of the CATALOG.DAT file.
URL
For a database-hosted system catalog, the full SQL URL that points to the CATALOG.DAT file.
Default
Not set. Uses the location specified in the JES > Configuration > System Catalog field in ESCWA.
Comments
See the data category in The dbfhdeploy Command Line Utility for full notation details if specifying a database-hosted system catalog.
Examples
MFSYSCAT=C:\MY\CATALOG\FOLDER\CATALOG.DAT
MFSYSCAT=sql://localhost/JCLTEST/catalog.dat?folder=/JCLDEMO
Related information
mfsplcnv Spool Conversion Utility

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.
Syntax
MFTRACE_CONFIG=path-name\ctf.cfg
Parameter
path-name
The full path to the location of the ctf.cfg file.
Default
Not set.
Related information
RM Switch Module Diagnostics

MFTRACE_LOGS

The location in which to create CTF trace log files.
Syntax
MFTRACE_LOGS=path-name
Parameter
path-name
The full path to the directory used to store CTF trace log files.
Default
Not set. Uses the current working directory.

MFTSO_DEBUG

Controls the display of debug messages.

MFUSER

Enables you to change the user from the default User ID to an alternative ID.

MFUSERCAT_BASE_LOC

If an entry in MFUSERCAT_LOC only specifies the file name of the user catalog rather than the full path and file name, use this environment variable to specify where these catalogs are located.
Syntax
MFUSERCAT_BASE_LOC=path-name
Parameter
path-name
The full path to the location of the file specified by the MFUSERCAT_LOC environment variable.
Default
Not set. If the path is not specified in MFUSERCAT_LOC, the current working directory is used.
Comments
If multiple user catalog files are in the same location - for example, C:\USERCATALOGS or $$MYFILESHARE - use this environment variable to store that location. Then, you only need to specify the file name of the catalog in MFUSERCAT_LOC.

Valid only when the value of MFUSERCAT_LOC is a file name only.

MFUSERCAT_LOC

Specifies the location and name of each additional catalog, matching the values provided in the MFUSERCAT_NODE value.
Syntax
MFUSERCAT_LOC={[path-name\]file-name}[;{[path-name\]file-name}[...]]
Parameters
path-name
The full path to a catalog file.
file-name
The name of the catalog file.
Default
Not set. No file names or locations are provided for additional catalogs specified by MFUSERCAT_NODE.
Comments
Parameter values are limited to a total of 4096 characters.

If multiple catalog files are in the same location, you can use the environment variable MFUSERCAT_LOC to store that location. If you do this, you only need to specify the file name of each catalog file in MFUSERCAT_LOC.

Related information
MFUSERCAT_NODE

MFUSERCAT_NODE

Specifies additional SMS, SPOOL, and User catalogs.
Syntax
MFUSERCAT_NODE=node-name[,node-name[...]]
Parameter
node-name
A user catalog or special node name, including optional wildcards * for any number of characters and ? for a single character.
Default
Not set.
Comments
Use this variable to specify additional SMS, SPOOL and User catalogs. Up to 64 additional catalogs may be specified with semi-colon separated values. The physical file used for each catalog is stored in the environment variable MFUSERCAT_LOC.

The parameter specification is limited to 4096 characters.

In the parameter specification, you may optionally use the UNIX-style square bracket notation (part of the regular expression feature), to specify a list of permissible characters at a particular point within the node specification.

To enable support for the SMS entities DATACLAS and MGMTCLAS, this variable needs to be set in addition to setting MF_SMS=ON.

Each node-name entry in MFUSERCAT_NODE must have a corresponding entry in MFUSERCAT_LOC.

Use the ES_OPEN_CAT_ON_DEMAND variable to determine if these catalogs are opened when the region starts, or only opened when they are required.

Related information
MFUSERCAT_LOC

MQSERVER

The names of one or more minimal channels.
Syntax
MQSERVER=channel-name/transport-type/{machine-name|ip-address(port-number)}
   [,{machine-name|ip-address}(port-number)][...]]
Parameters
channel-name
The name of a channel as defined on the server.
transport-type
The communications protocol, which can be any of the following:
  • TCP
  • LU62
  • NETBIOS
  • SPX
machine-name
The name of the server machine.
ip-address
The machine IP address.
port-number
The number of the port used.
Comments
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.

Examples
MQSERVER=CHANNEL3/TCP/QServer(1414)
MQSERVER=CHANNEL1/TCP/10.120.99.999(1414),10.120.98.888(1414)
Related information
Enterprise Server Batch Reconnect for MQ Batch Programs Running in a Multi-instance Queue Manager
XAR for WebSphere MQ

MULTIMFENTMAP

Specifies whether special characters such as < and & are replaced with the equivalent HTML entities such as &lt; and &amp;.

N

NEWJCL

Controls ISPF skeleton JCL processing.

O

OOSW

OO run-time switches.

P

PROCLIB

Under a mainframe emulation, determines whether a status of 37 is returned.
Syntax
PROCLIB={ON|OFF}
Parameters
ON
Under a mainframe emulation, returns a file status of 37 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.
OFF
No file status is returned.
Default
PROCLIB=OFF

S

SHOW_CATALOG_WAIT

Displays a message when the enterprise server is waiting for a response from the catalog server.
Default
Not set. No message is displayed when the enterprise server is waiting.

SORTCOMPRESS

Tells the system whether or not to execute a compression routine on each record to be sorted.
Syntax
SORTCOMPRESS={0|1}
Parameters
0
Disables compression.
1
Enables compression.
Default
SORTCOMPRESS=0
Comments
When compression is enabled, run-length encoding of sort records is enabled, resulting in much better performance when records contain multiple repeated characters.

Use this variable to improve memory usage and therefore sort performance when the sort records contain many single, repeated characters; for example, multiple spaces.

The behavior when set to any positive integer is equivalent to SORTCOMPRESS=1.

SORTEXITREENTRY

Determines whether E15 user exits will be called after the SORTIN data set has been exhausted. [1]
Syntax
SORTEXITREENTRY={ON|OFF}
Parameter
ON
Within Enterprise Server, MFJSORT will continue to call E15 user exit programs until a return code of 8 has been returned, even after the SORTIN data set has been fully read.
OFF
E15 user exit programs are not called once the SORTIN data set has been read.
Default
SORTEXITREENTRY=OFF

SORTSCHEME

Enables the SORTSPACE environment variable, which specifies an alternative memory allocation size for sort operations.
Syntax
SORTSCHEME=1
Parameter
1
Enables the SORTSPACE environment variable.
Default
Not set. The memory allocated for sort functions is 1 megabyte.
Related information
SORTSPACE

SORTSPACE

The amount of memory to be allocated to internal workspace for SORT operations, and the format for the allocated memory.
Important: To set SORTSPACE to a value other than the default, you must first enable it using the SORTSCHEME environment variable.
Syntax
SORTSPACE=memory-spec[K|M|G]
Parameter
memory-spec
A number that represents the amount of memory to allocate. When used without an optional parameter, this number represents memory in bytes; otherwise, it represents the units specified by an optional parameter.
K
memory-spec specifies memory allocation in kilobytes.
M
memory-spec specifies memory allocation in megabytes.
G
memory-spec specifies memory allocation in gigabytes.
Default
SORTSPACE=1M
Comments
A larger value for SORTSPACE generally results in a faster sort. However, if you specify a value that exceeds the capacity of main memory in your computer such that the operating system has to page memory in and out, performance is degraded.

Parameter values are not case sensitive.

Example
SORTSPACE=1024K
Related information
SORTSCHEME

SORTTEMPSPACE

The amount of memory to be allocated to temporary workspace for SORT operations.
Syntax
SORTTEMPSPACE=memory-spec[K|M|G]
Parameters
Important: The value specified must be equivalent to 32M or greater, irrespective of the scheme used to specify the amount of memory.
memory-spec
A number that represents the amount of memory to allocate. When used without an optional parameter, this number represents memory in bytes; otherwise, it represents the units specified by an optional parameter.
K
memory-spec specifies memory allocation in kilobytes.
M
memory-spec specifies memory allocation in megabytes.
G
memory-spec specifies memory allocation in gigabytes.
Default
SORTTEMPSPACE=32M
Comments
Use this variable to adjust the memory allocation strategy used by SORT. This can generally improve performance in systems suffering from memory fragmentation.

Parameter values are not case sensitive.

Example
SORTTEMPSPACE=250M

SORTTYPE

Sets SORT operations to use the file handler.
Syntax
SORTTYPE=2
Parameter
2
Forces SORT to use the file handler, which picks up format modifications from the extfh.cfg file.
Default
Not set. SORT attempts to use CBL_ library routines to read and write files to improve performance.

SPOOL_TIMEOUT

Enables greater control over record-lock retries by setting timeout and interval durations.
Syntax
SPOOL_TIMEOUT=timeout:interval
Parameters
timeout
The amount of time in milliseconds to continue to retry the lock before ceasing the attempt.
interval
The amount of time in milliseconds before initiating a new lock retry attempt.
Default
SPOOL_TIMEOUT=500:100
Comments
Set this environment variable to resolve reported record-locked messages, which, depending on hardware performance, can occur especially during shutdown of an enterprise server instance with an SSTM job.

SSTM_WC_REFRESH

Determines how often the write count for the SSTM job is updated in SYSOUT or SYSPRINT.
Syntax
SSTM_WC_REFRESH={0|number-of-writes}
Parameters
0
The count is only updated when the file is closed.
number-of-writes
A value from 1 through 65535 to indicate the number of writes at which the count is updated.
Default
SSTM_WC_REFRESH=0
Comments
Any provided value outside of 0-65535 defaults to 65535.

STEPLIB

The path or paths to search for Loader input-load member .390 files.
STEPLIB=path-name[;path-name[...]]
Parameter
path-name
The full path to a location containing input-load member .390 files.
Comments
.390 files must contain SYSLMOD.

STRICTVSAM

Specifies strict mainframe emulation during file processing of VSAM files.
Syntax
STRICTVSAM={ON|OFF}
Parameters
ON
File status 37 is returned when an existing VSAM file is opened for OUTPUT if the file has data or previously had data written to it, or the file is of a different format to the file on disk.
OFF
File status 0 is returned and a new file is created when an existing VSAM file is opened for OUTPUT.
Default
STRICTVSAM=OFF

SYSIN

The path for macro input .MLC files.
SYSIN=path-name
Parameter
path-name
The full path to the location that contains macro input .MLC files.

SYSLIST

The path for Assemble and Link listing files.
SYSLIST=path-name
Parameter
path-name
The full path to the location that contains Assemble and Link listing files, including .MAT, .PRN, and .LST files.

SYSWORK

The path to Assemble, Link and Animator/370 work files.
SYSWORK=path-name
Parameter
path-name
The full path to the location that contains Assemble, Link, and Animator/370 work files, including .BAL, and .IDF/.IDX files.

SYSPUNCH

The path to Assemble output files for PUNCH statements.
SYSPUNCH=path-name
Parameter
path-name
The full path to the location that contains Assemble output files for PUNCH statements, including .PCH files.

SYSMPC

The path to Assemble input precompiled macros.
SYSMPC=path-name
Parameter
path-name
The full path to the location that contains Assemble input precompiled macros, including .MPC.

SYSLIB

The paths for Assemble input macro and copy files.
Syntax
SYSLIB=path-name[;path-name[...]]
Parameter
path-name
The full path to a location containing Assemble input macro and copy files, including .MAC and .CPY files.

SYSLIN

The path to Link input and Assemble output files.
SYSLIN=path-name
Parameter
path-name
The path to Link input (.LIN) files and Assemble output (.OBJ) files.

SYSLMOD

The path for Link output load-member (.390) files.
Syntax
SYSLMOD=path-name
Parameter
path-name
The path to Link output load-member (.390) files.

SYSPARM

The path for the Macro input SYSPARM value.
SYSPARM=path-name
Parameter
path-name
The path to the Macro input SYSPARM value.

T

TX_MQ_CONVERT

Sets the code set to overwrite the MQ Q manager CCSID. The value is used in the MD-codedcharsetid parameter.
Syntax
TX_MQ_CONVERT=codeset[,Force]
Parameters
codeset
The code that corresponds to that you want to use to overwrite MQ Q manager CCSID. See Installing CCSID translation tables for further details.
Force
Force the convert option for MQ even if the application does not set the option on the call.
Default
Not set. Enterprise Server uses the Q Manager CCSID.
Example
TX_MQ_CONVERT=037

To force the convert option for MQ even if the application does not set the option on the call, specify the code set followed by Force:

TX_MQ_CONVERT=037,Force
Related information
Installing CCSID translation tables

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.
Syntax
TXFILEP={path-name|datastore-location}
Parameters
path-name
The full path to the VSAM files on disk.
datastore-location
For database-hosted files, the location of the datastore containing the VSAM files. Use the notation described in the The dbfhdeploy Command Line Utility topic under Category > data.
Related information
The dbfhdeploy Command Line Utility

TXMAPP

The location of the BMS load module.
Syntax
TXMAPP=path-name
Parameter
path-name
The full path to the location of the BMS load module.

TXRDTP

The location of MSS resource definition (RDO) files.
Syntax
TXRDTP=path-name
Parameter
path-name
The full path to the MSS resource definition (RDO) files.

TXTRANP

The location of the CICS application object files.
Syntax
TXTRANP=path-name
Parameter
path-name
The full path to the location of the CICS application object files.

U

USSCONFIG

Points to the location of the SSL cipher suite specification file(s) used by the CIPHERS attribute in the CICS URIMAP or TCPIPSERVICE resource.
Syntax
USSCONFIG=cipher-path
Parameter
cipher-path
The absolute path to the cipher suite specification file or files.
Comments
For details about ciphers and cipher files, see the Security Attributes > Ciphers section of the Universal Resource Identifier Map topic.
Related information
Active Universal Resource Identifier Map
Universal Resource Identifier Map

V

VSE_STARTUP_CFG

The location of the VSE JCL configuration file.
Syntax
VSE_STARTUP_CFG=[path-name\]file-name
Parameters
path-name
The full path to the location of the VSE JCL configuration file. When not specified, Enterprise Server looks for the file in the current working directory.
file-name
The name of the VSE JCL configuration file.
Default
Not set. You must explicitly set VSE_STARTUP_CFG to use VSE JCL support.

X

XFHLOG

Determines the location of the log file when the LOG option is active.
Syntax
XFHLOG=DEFAULT
Parameter
DEFAULT
Generates the log file in the current working directory.
Default
Not set. The log file is generated in %ProgramData%\Micro Focus\File Handler\version-number, where version-number represents the version of your Micro Focus product.
Comments
The effect of this variable can be overridden by the LOGFILENAME configuration option.


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
Related information
FHREDIR


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
  • PostgreSQL
  • ODBC (generic one-phase commit)
  • DB2 LUW
  • Oracle
  • XDB

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 Enterprise Server-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.
  • Defining XA Resource Entries
  • RM Switch Modules
  • XA Resource and Security
  • Enterprise Server XA Reconnect
  • Reconnecting to an MQ Server in a Multi-instance Queue Manager
    Enterprise Server transaction processing and batch systems can now reconnect to the standby MQ Queue Manager in a Multi-Instance Queue Manager (MIQM) when connection to the active queue manager is lost.
  • XA Recovery
  • XA Troubleshooting
Parent topic: Configuring the Server Instance Environment


Planning and Designing XARs

Note: This topic does not apply to XDB or 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 in Enterprise 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
  • PostgreSQL

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

Is the application using MFDBFH datastore(s) with transactional files but no embedded SQL?
If your application does not use any embedded SQL, you are ready to define your MFDBFH XAR(s) as described in Micro Focus Native Database File Handling and Enterprise Server Region Database Management.
Does the application require more than one XAR?
This depends on what database(es) the application accesses, and how the application interacts with it.
Does the application use MFDBFH with DB2 and embedded SQL with DB2?
In this case, you must compile your embedded SQL code using the XAID compiler directive for, for example, online CICS or Web Services applications and batch processing. This applies whether MFDBFH CICS transactional files are used or not.
Does the application use MFDBFH datastore(s) with transactional files and/or have embedded SQL code that requires 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, and it does not use MFDBFH transactional files, 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 CICS, IMS, or IMTK container-managed service interface types that require embedded SQL database access. In another scenario, you might be using MFDBFH to store COBOL transactional files in a database along with executing embedded SQL applications. This likely requires recompilation of application source code. See Working with Multiple XARs for more information.

Is the embedded SQL application coded to use distinct XARs?
Typically, the SQL code is 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 only batch jobs, and you are not using MFDBFH?
If so, consider identifying these XARs as batch-only resources, which can save considerable overhead, and eliminate the need to recompile using the XAID compiler directive option. For more information, see the BatchOnly=(T|F) section in SQL xa_open string Configuration Options.
How do Enterprise Server Service Execution Processes (SEPs) work with XARs?
Each CICS, IMS MPP, or IMTK container-managed SEP implicitly establishes a connection to each enabled XAR in the region; however, when an XAR definition contains BatchOnly=T, these SEPs do not interact with that XAR. For more information, see the BatchOnly=(T|F) section in SQL xa_open string Configuration Options.

Generally, batch SEPs are explicitly provided XAR connections with some variations possible, depending on the batch application. See Emulations of Mainframe Utilities for more information on IKJEFT01 jobs or other batch utilities. See MVS Emulation for more information on DSNALI or DSNRLI applications.

With IMS BMPs, you can get similar behavior if the DFSRRC00 PARM names a preferred XAR. In this case, IMS BMPs connect only to that XAR; otherwise, the application implicitly establishes a connection to each enabled XAR in the region.

How do the SEPs monitor the connection to the XA Resource Managers?
Each time a transaction is triggered, each SEP will verify the connection to all active XA resources unless they are excluded from the monitoring processing. If the connection is lost, the XA reconnect process attempts to reconnect a number of specified times at specified time intervals. If the connection is not reestablished after the set number of retries the XA entry is disabled. You can use Dynamic XA to re-enable the resource manager. See Enterprise Server XA Reconnect for more information.

For more information about configuring an XAR, see To define an XA Resource (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
Database File Handling and Enterprise Server Region Database Management
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.

Note: When using dynamic registration with Oracle or DB2, you might need to use the XAID directive when you compile your embedded SQL code. See SQL xa_open string Configuration Options for details.

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 XA Resource Entries


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. When building CICS and Oracle DSNRLI applications, specify the XAID compiler directive option; however, this is not required for other DB2 or Oracle batch processing.
  • One-phase commit for ODBC - UserP=T is supported only for SQL Server on Windows and Linux platforms only.
  • 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.
LNAME={T|F}
Determines how the XAR handles long user names during user impersonation.
T
The associated long user names of the current Enterprise Server user for each CICS transaction or batch job is used for establishing connection during user impersonation. See Long Usernames and Passwords for more information.
F
Default. The current Enterprise Server user for each CICS transaction or batch job is used for establishing connection during user impersonation.
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.
Note: DB2 and Oracle - When LocalTX =T is set for a DB2 or an Oracle XAR that uses dynamic registration, you must specify the XAID compiler directive option when building your CICS DSNRLI applications; however, this is not required for other DB2 or Oracle batch processing.
ISOLEVEL={CR|RO|RR|SS|SZ|UR}
Determines the isolation level of transactions for a specific XAR.
Parameter | Description
CR | Committed Read (default)
RO | Read Only (Oracle only)
RR | Repeatable Read (not supported on Oracle)
SS | Snapshot (SQL Server only)
SZ | Serializable
UR | Uncommitted Read (not supported on Oracle)
Note: DB2 and Oracle - When ISOLEVEL is set for a DB2 or an Oracle XAR that uses dynamic registration, you must specify the XAID compiler directive option when building your CICS DSNRLI applications; however, this is not required for other DB2 or Oracle batch processing.
ESLOGGING=0001
Provides additional RM switch module diagnostics in the Enterprise Server console log, including JCL connection or database API errors.
PACKAGEPATH=schema1[+schema2+...schemaN]
DB2 only. You can use the following substitution markers to enable customization based on the current JCL or CICS user name, XA resource name, enterprise server region name, or a combination:
%REGION%
The current enterprise server region name.
%XARN%
The current XA resource name.
%ESUSER%
The current CICS or JCL user name.
Notes:
  • When used with UserP, the PACKAGEPATH value changes when the user for the connection changes.
  • When PACKAGEPATH is set for a DB2 XAR that uses dynamic registration, you must build the module in Enterprise Developer. When building CICS applications, specify the XAID compiler directive option. This is not required for other batch processing.

Parent topic: Planning and Designing XARs
Related concepts
Planning and Designing XARs
Working with Multiple XARs
Generic one-phase commit for ODBC xa_open string
IBM DB2 xa_open string
Oracle xa_open string
PostgreSQL xa_open string


Defining XA Resource Entries

You can add, edit, or delete XA resources dynamically (that is, whilst an enterprise server region is running). Any changes made come into effect after any in-flight transactions have completed. You can also update these resources whilst the region is stopped, where changes become effective the next time you start the region.

The ability to make these changes in a live environment comes under the control of the existing enterprise server permissions.

  • 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. Open the ESCWA Administration page, and then select the enterprise server region that references the transactional data file from the left pane.
  2. In the right pane, click General > XA Resources.
  3. Click NEW.
  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. 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.
    Enabled
    Check this to enable the XAR. It is checked by default.
    Reconnection attempts
    Type or select the number of reconnection attempts to make following an initial connection error.
    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.
    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. If you add an XAR while the region is running, you can connect to it as soon as the XAR is enabled.
  • SQL Server xa_open string
  • PostgreSQL xa_open string
  • Generic one-phase commit for ODBC xa_open string
  • IBM DB2 xa_open string
  • Oracle xa_open string
  • XDB xa_open string
  • XAR for WebSphere MQ
  • MQ XA switch modules support the BATCHONLY option
Parent topic: Defining XA Resource Entries
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][,TM=tmname]
   [,RMRECOVERYGUID=guid][,TIMEOUT=timeoutvalue]
   [,USERP={T|F}][,LNAME={T|F}][,BATCHONLY={T|F}][,LOCALTX={T|F}]
   [,ISOLEVEL={CR|RR|SS|SZ|UR}][,ESLOGGING={0001|0002}]
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.1
password
The password required to connect the user ID to the data source.1
tmname
Restriction: Windows environment only.
The transaction manager name used for diagnostics by the Microsoft Distributed Transaction Coordinator (MSDTC). Micro Focus recommends that you specify the transaction manager name as a string that uniquely identifies the host machine and enterprise server instance. The tmname value is restricted to 40 characters. If not specified, the TM value defaults to Micro Focus Enterprise Server.
guid
Restriction: Windows environment only.
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, LNAME, BATCHONLY, LOCALTX, ISOLEVEL, and ESLOGGING
See SQL xa_open string Configuration Options for more information.

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.

Note:
  • If you specify any parameter other than those listed here, the switch module returns an error to Enterprise Server.
  • Restriction: Windows environment only.
    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 more information.

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

To configure 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


PostgreSQL xa_open string

To complete the definition of an PostgreSQL XAR, add the following values in the Open string field:

DSN=odbc_dsn[,USRPASS=userid.password]
   [,USERP={T|F}][,LNAME={T|F}][,BATCHONLY={T|F}][,LOCALTX={T|F}]
   [,ISOLEVEL={CR|RR|SS|SZ|UR}][,ESLOGGING={0001|0002}]
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.1
password
The password required to connect the user ID to the data source.1
USERP, LNAME, BATCHONLY, LOCALTX, ISOLEVEL, and ESLOGGING
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 ESPGSQLXA.cbl source. This can be helpful if you want to ease security. To do this, search for CUSTOMIZE within ESPGSQLXA.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


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}][,LNAME={T|F}][,BATCHONLY={T|F}]
   [,LOCALTX={T|F}][,ISOLEVEL={CR|RR|SZ|UR}][,ESLOGGING={0001|0002}]
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. 1
password
The password required to connect the user ID to the data source. 1
USERP, LNAME, BATCHONLY, LOCALTX, ISOLEVEL, and ESLOGGING
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 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}][,LNAME={T|F}][,BATCHONLY={T|F}]
   [,LOCALTX={T|F}][,ISOLEVEL={CR|RR|SZ|UR}][,ESLOGGING={0001|0002}]
   [,PACKAGEPATH=schema1[+schema2+...schemaN]]
Note: The open string format is defined by IBM. We strongly recommend that you become familiar with 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 name of the library that contains the transaction manager's ax_reg and ax_unreg functions.
For Windows:
If the %PATH% environment variable includes the directory that contains the axlib library, set AXLIB to CASAXLIB.dll.

If the %PATH% environment variable does not include the directory that contains the axlib library, set AXLIB to include the absolute path of the axlib library. For example, set AXLIB to either %COBDIR%\bin\CASAXLIB.dll (32bit) or %COBDIR%\bin64\CASAXLIB.dll (64bit).

Note: In all cases, specification of the .dll file extension is optional.
For UNIX:
If the $LD_LIBRARY_PATH or $LIBPATH environment variable includes the directory that contains the axlib library, set AXLIB to either casaxlib.so or casaxlib64.so.

If the $LD_LIBRARY_PATH or $LIBPATH environment variable does not include the directory that contains the axlib library, set AXLIB to include the absolute path of the axlib library. For example, set AXLIB to either $COBDIR/lib/casaxlib.so (32bit) or $COBDIR/lib/casaxlib64.so (64bit).

Note: In all cases, specification of the .so file extension is required.
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 to 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, LNAME, BATCHONLY, LOCALTX, ISOLEVEL, ESLOGGING, and PACKAGEPATH
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}][+LNAME={T|F}][+BATCHONLY={T|F}][+LOCALTX={T|F}][+ISOLEVEL={CR|RO|SZ}]
   [+ESLOGGING={0001|0002}]
Important: The open string format is defined by Oracle. We strongly recommend that you become familiar with 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, LNAME, BATCHONLY, LOCALTX, ISOLEVEL, and ESLOGGING
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


XDB xa_open string

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

[{SERVER | SRV}=["]server-name["],] [{LOCATION | LOC | DB}=["]location-name["],]
     [{USERID | UID}=["]userid["],] {PASSWORD | PWD}=["]password["]
The parameters are:
server-name
The name of your XDB Server. The default is the value set in the Server Name field of the XDB Client Options dialog box in the Options Utility. Optional.
location-name
Your XDB location. The default is the value set in the Locations field of the XDB Client Options dialog box in the Options Utility. Optional.
Note: If you want to use multiple locations within a singleenterprise server instance with a single XA resource definition, you can omit the location-name from the XA Open string and configure the location to use for that transaction by modifying the XDB Client Options dialog box before each transaction executes. To use this feature, edit the xdb.ini file and add the XDBIniReread variable to the [Client] section as follows:
[CLIENT]
XDBCFG=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\
XDBIniReread=Yes

When XDBIniReread=Yes, the switch module rereads the settings in the XDB Client Options dialog box each time it connects.

userid
The user ID required to connect to the XDB server. The default is the value set in the AuthID field of the Options Utility. Optional.
password
The password required to connect the user ID to the XDB Server. Required.
Note: You can access the Options Utility from Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2 > Configuration > Client Options.
Parent topic: To define an XA resource (XAR) for an enterprise server region
Related concepts
Options Utility


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=channel_name,TRPTYPE=trp_type,CONNAME=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
    The network address of the queue manager (connection name). The valid values of this parameter depend on the value of the TRPTYPE parameter. CONNAME is mandatory when multiple MQ listeners are defined to make an MQ connection from the Micro Focus Directory Server, and optional when connecting using a single MQ listener.
    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:

    channel=MARS.SVR,trptype=tcp,conname=MARS(1415),qmname=MARS,tpm=cics
    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 tasks
To create an XA resource for a trigger monitor
Related reference
WebSphere MQ Environment Variables
Related information
MQSERVER


MQ XA switch modules support the BATCHONLY option

The BATCHONLY option ensures that only batch modules can execute XA operations on that BATCHONLY XA entry. Use this option to target several MQ XA entries and switch from one to another. A DNSRLI job is able to connect to an MQ XA entry, disconnect, and connect to a different MQ XA entry within the same batch program.

Note:
  • Any SWITCH verb must be terminated using a TERMINATE THREAD before establishing a new connection.
  • The following limitations apply:
    • Only one MQ XA entry can be active at a time in a CICS region.
    • Different MQ XA resource cannot target the same QUEUE MANAGER.
where:
BATCHONLY={T|F}
T
True
F
False (default value)

Example xa open string:

QMNAME=MTOMQ32.QM,TPM=CICS,AXLIB=casaxlib,BATCHONLY=T
Parent topic: To define an XA resource (XAR) for an enterprise server region


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: If you delete an XA resource whilst the region is running, any in-flight transactions are completed before your changes take effect.
Parent topic: Defining XA Resource Entries
Parent topic: Work with Servers


To edit an XA resource

  1. Open Enterprise Server Administration, and then select an enterprise server region from the list in the left pane.
  2. In the right pane, click General > XA Resources.
  3. On the list of XA resources, click Edit Edit on the line representing the XA resource you want to edit.
    Warning: If you edit the ID of an enabled resource, it effectively creates a new resource whilst leaving the previously-named resource active in memory. To create a resource with the intended ID, the recommended action is to delete the enabled resource, and add a new one using the new ID.
  4. Update the attributes on the page as required.
  5. Click Save.
Note: If you have edited the resource whilst the region is running, any in-flight transactions are processed using the previous details, then the changes come into effect for the next available connection.

To set the number of XA resource reconnect attempts following an error

To configure an XA resource module (RM) to a single reconnect attempt, set the ES_XA_RECONNECT environment variable. For details, see the Single mode reconnect.

To configure an RM to attempt multiple reconnects, set the ES_XA_%xaname%_OPTIONS environment variable. For details, see Multiple mode reconnect.

Parent topic: Defining XA Resource Entries
Parent topic: Work with Servers
Related concepts
Single mode reconnect for CICS
Multiple mode reconnect for CICS
Related reference
Environment variables in alphabetical order
Related information
ES_XA_%xaname%_OPTIONS


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.
Note: If you disable the XA resource whilst the region is running, any in-flight transactions are completed before your changes take effect.
Parent topic: Defining XA Resource Entries
Parent topic: Work with Servers


RM Switch Modules

  • Building RM Switch Modules
    Describes the build process for each supported RM switch module.
  • WebSphere MQ Switch Module
    Describes the provided WebSphere MQ switch module.
Parent topic: Using XA-compliant Resources (XARs)


Building RM Switch Modules

Note: Source code for RM switch modules is not installed with Enterprise Server.

You can build one or more RM switch modules of each switch module type. A switch module type is determined by its corresponding database type:

  • SQL Server RM Switch Module
    Provides the information required to build the SQL Server RM switch module.
  • PostgreSQL RM Switch Module
    Provides the information required to build the PostgreSQL RM switch module.
  • Generic One-phase Commit for ODBC RM Switch Module
    Provides the information required to build the generic one-phase commit for ODBC RM switch module.
  • IBM DB2 RM Switch Module
    Provides the information required to build the IBM DB2 RM switch module.
  • Oracle RM Switch Module
    Provides the information required to build an Oracle RM switch module.
  • XDB RM Switch Module
    Provides the information required to build the XDB RM switch module.
Parent topic: RM Switch Modules


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 to ensure that any database connections made using this switch module all participate in a single XA transaction.

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.
Note: If you prefer to supply user credentials programmatically rather than in the xa_open string, instructions for doing so are provided in the COBOL source file in the Customization section.
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.

Before building this switch module, ensure that your LIB environment variable contains the path to the odbc32.lib file, located in a subdirectory under your Windows SDK LIB directory.

Some OpenESQL directives are process-based, and typically need to be set in within the code of the program that makes the database connection.

If you are executing services under Enterprise Server that are deployed as container-managed applications, 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
Important: Beginning with the SQL Server ODBC 17.3 driver, Microsoft has changed their XA protocol. Use the MSSQL17 build option if you are using ODBC 17.3 or later. Currently, later Microsoft ODBC 17 versioned drivers will work with SQL Server 2017 and later only. For SQL Server 2016 and earlier, you must use the MSSQL build option and an earlier version of the SQL Server ODBC driver.
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
    Important: For ODBC Driver 17 for SQL Server versions 17.3 and later, enter build mssql17 instead.
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
    Important: For ODBC Driver 17 for SQL Server versions 17.3 and later, enter build mssql17 instead.
Build Output
The build process produces two binary switch module files from the ESMSSQL.CBL COBOL source file:
Binary File | Type
ESMSSQL.DLL | static
ESMSSQL_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. Micro Focus recommends 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
See SQL Server xa_open string for more information on using the SQL Server RM switch module xa_open string.
Parent topic: Building RM Switch Modules


PostgreSQL RM Switch Module

Provides the information required to build the PostgreSQL RM switch module.

The PostgreSQL module provides two-phase commit support using PostgreSQL-provided SQL calls, and ensures that any database connections made using this switch module all participate in a single XA transaction.

PostgreSQL Server configuration for XA

Important: Before you can use the PostgreSQL RM Switch Module, you must configure the PostgreSQL Server by changing the value of the max_prepared_transactions property from its default value of 0 (zero) to a value greater than 0. After making this change, you must restart the server before proceeding. For additional details about the max_prepared_transactions configuration property, see your PostgreSQL documentation.
Source Code
The PostgreSQL RM switch module COBOL source file, ESPGSQLXA.CBL is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Note: If you prefer to supply user credentials programmatically rather than in the xa_open string, instructions for doing so are provided in the COBOL source file in the Customization section.
Build Requirements
To build the PostgreSQL RM switch module, you must have the Windows Software Development Kit (SDK) installed for your version of Windows.

Before building this switch module, ensure that your LIB environment variable contains the path to the odbc32.lib file, located in a subdirectory under your Windows SDK LIB directory.

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 pg
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 pg
Build Output
The build process produces two binary switch module files from the ESPGSQLXA.CBL COBOL source file:
Binary File | Type
ESPGSQLXA_S.DLL | static
ESPGSQLXA.DLL | dynamic

You can register an RM switch module with Enterprise Server dynamically, or register it statically depending on which binary file you use. Micro Focus recommends 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 PostgreSQL RM switch module, including the xa_open string definition, see PostgreSQL xa_open string.
Parent topic: Building RM Switch Modules


Generic One-phase Commit for ODBC RM Switch Module

Provides the information required to build the generic one-phase commit for ODBC RM switch module.
Source Code
The generic one-phase commit for ODBC RM switch module COBOL source file, ESODBCXA.CBL is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Note: If you prefer to supply user credentials programmatically rather than in the xa_open string, instructions for doing so are provided in the COBOL source file in the Customization section.
Build Requirements
To build the ODBC RM switch module, you must have the Windows Software Development Kit (SDK) installed for your version of Windows.

Before building this switch module, ensure that your LIB environment variable contains the path to the odbc32.lib file, located in a subdirectory under your Windows SDK LIB directory.

Some OpenESQL directives are process-based, and typically need to be set in within the code of the program that makes the database connection.

If you are executing services under Enterprise Server that are deployed as container-managed applications, 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 odbc
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 odbc
Build Output
The build process produces two binary RM switch module files from the ESODBCXA.CBL COBOL source file:
File | Type
ESODBCXA.DLL | static
ESODBCXA_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. Micro Focus recommends 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.

Limitations
The ODBC module supports only a one-phase commit, therefore the following SQL operations are not supported in the source for your deployed container-managed service:
  • CONNECT
  • DISCONNECT
  • BEGIN TRANSACTION
  • COMMIT
  • ROLLBACK
Additional Resources
For more information on using the ODBC RM switch module, including the xa_open string definition, see Generic One-phase Commit for ODBC RM xa_open string.
Parent topic: Building RM Switch Modules


IBM DB2 RM Switch Module

Provides the information required to build the IBM DB2 RM switch module.
Source Code
The IBM DB2 RM switch module COBOL source file, ESDB2XA.CBL is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Note: If you prefer to supply user credentials programmatically rather than in the xa_open string, instructions for doing so are provided in the COBOL source file in the Customization section.
Building the Switch Module
You can use either of the following methods to build the IBM DB2 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 db2
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 db2
Build Output
The build process produces two binary files from the ESDB2XA.CBL COBOL source file:
Binary File | Type
ESDB2XA_S.DLL | static
ESDB2XA.DLL | dynamic

You can register an RM switch module with Enterprise Server dynamically, or register it statically depending on which binary file you use. Micro Focus recommends 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 IBM DB2 RM switch module, including the open string definition and details of supported SQL operations, see the following:
  • The Database Access - DB2 ECM topic under Additional Software Requirements
  • The Transaction Managers help topic available in the IBM RDBMS documentation.
  • DB2 9.1 - The X/Open XA Interface programming considerations help topic available in the IBM RDBMS documentation.
Parent topic: Building RM Switch Modules


Oracle RM Switch Module

Provides the information required to build an Oracle RM switch module.

We support Oracle RM switch modules for both Oracle 18 and Oracle 19 databases.

Source Code
The Oracle RM switch module COBOL source file, ESORAXA.CBL is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Note: If you prefer to supply user credentials programmatically rather than in the xa_open string, instructions for doing so are provided in the COBOL source file in the Customization section.
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 switch-module

    Where switch-module is either ora19 for Oracle 19 databases, or ora21 for Oracle 21 databases.

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 switch-module

    Where switch-module is either ora19 for Oracle 19 databases, or ora21 for Oracle 21 databases.

Build Output
The build process produces two binary RM switch module files from the ESORAXA.CBL COBOL source file:
Binary File | Type
ESORAXA.DLL | static
ESORAXA_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. Micro Focus recommends 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 Oracle RM switch module, including the open string definition and details of supported SQL operations, see the following:
  • The Database Access - COBSQL (Pro*COBOL) section of the Additional Software Requirements topic.
  • The Developing Applications with Oracle XA help topic available in the Oracle RDBMS documentation.
Parent topic: Building RM Switch Modules


XDB RM Switch Module

Source Code
The XDB RM switch module COBOL source file, ESXDBXA.CBL, is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Building the Switch Module
You can use either of the following methods to build the XDB switch module:
Method 1
  1. Start an Enterprise Developer command prompt, 32 bit, running as an administrator.
  2. Change to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory (default location).
  3. Enter build xdb
Method 2
  1. Start an Enterprise Developer command prompt, 32 bit.
  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 xdb
Build Output
The build process produces a binary file from each COBOL source file:
COBOL Source | Binary File
ESXDBXA.CBL | ESXDBXA.DLL
ESXDBOPC.CBL | ESXDBOPC.DLL
Parent topic: Building RM Switch Modules


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 Test Server\bin
esmqxa.dll | %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin64

By default, these switch modules operate in two-phase commit mode. If instructed by OpenText Support for Micro Focus Products 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: RM Switch Modules
Related concepts
ES_MQ_1PC


XA Resource and Security

  • Using the Vault Facility with the XA Open String
    Describes using the Vault Facility to hide sensitive information.
  • User Impersonation for CICS and JCL
    Describes using user impersonation to provide credentials other than those specified in the xa_open string.
Parent topic: Using XA-compliant Resources (XARs)


Using the Vault Facility with the XA Open String

The XA open string required to connect to a database instance might contain sensitive information. When it does, you can hide that sensitive information using the Micro Focus Vault Facility, which enables the storage of data in a secure external source. You can use the vault facility to securely hide entire open strings, or pieces of an open string.

Note: For complete details on using the Micro Focus Vault Facility, see Vault Facility.

The ESXAEXTCFG COBOL program

We provide the ESXAEXTCFG.CBL COBOL program and writeSecrets.bat batch file to use with the vault facility and RM switch modules to obfuscate XA open strings. These files are located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.

The steps required are as follows:

  1. Start an Enterprise Server command prompt.
  2. Copy ESXAEXTCFG.CBL and writeSecrets.bat from the default location to any location where you have WRITE permission.
  3. From the directory containing the copied ESXAEXTCFG.CBL and writeSecrets.bat files, insert the data into the vault by editing writeSecrets.bat, replacing canned values with those used on your system, and then running the batch file.

    WriteSecrets.bat runs a series of mfsecretsadmin commands that populate the vault. For more information, see The mfsecretsadmin Utility .

  4. Edit ESXAEXTCFG.cbl to use the secret name that was inserted into the vault. Examples for common configurations have been included in the program.
  5. Compile the ESXAEXTCFG.cbl program using the following command to create an external configuration module:
    build ext

    This generates the ESXAEXTCFG.dll switch module.

  6. Copy the new ESXAEXTCFG module to a directory on your Windows PATH.
  7. Update the XA open string and start the region.

The ESXAEXTCFG.CBL file contains examples for common usage scenarios such as storing the entire XA string in the vault, storing only the password, or storing a combination of the user ID and password. It also documents return code values on entry and on exit, the initial name/value pair table used on entry, and the use of placeholders.

XA open string placeholders

For replacing pieces of the open string with data from the vault, use placeholders to identify the data to be replaced. For example, within the open string, use &PWD& as the placeholder for a password, or &NAME& as a placeholder elsewhere in the open string, where the text between ampersands (&) matches the text in the name/value pair table. Examples of both XA open strings and corresponding configurations have been provided in the ESXAEXTCFG COBOL program.

Note: When pulling the entire XA string from the vault, placeholders are not recognized because the XA string you provide in the Enterprise Server console is overridden by what is pulled from the vault, meaning it can be any value, including blank.
Parent topic: XA Resource and Security
Related concepts
Vault Facility
The mfsecretsadmin Utility


User Impersonation for CICS and JCL

Note: This topic does not apply to the XDB RM switch module.

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.
  • PostgreSQL User Impersonation Configuration
    Describes the setup required to use PostgreSQL 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: XA Resource and Security
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


PostgreSQL User Impersonation Configuration

To find the appropriate database user credentials for CICS transactions or batch jobs, the PostgreSQL XA switch module executes a SET SESSION AUTHORIZATION statement. For this call to work properly, your xa_open string user must be a superuser. 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 PostgreSQL documentation on this and other related topics before implementing your solution:

  1. Create the user cited in the xa_open string:
    CREATE ROLE XAOPENUSER SUPERUSER LOGIN PASSWORD 'xxxxxx'
  2. Create the user FRITZ to execute CICS or JCL:
    CREATE ROLE FRITZ LOGIN PASSWORD 'xxxxxx'
  3. Create a schema for FRITZ:
    CREATE SCHEMA FRITZ AUTHORIZATION FRITZ
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


Enterprise Server XA Reconnect

The XA reconnect CICS transaction, CRCN, has been replaced by XA reconnect code executed in a Service Execution Process (SEP). The XA reconnect processing is invoked before each new transaction by executing an xa-ping to test and verify the connection to the target resource manager. If the ping fails, the XA reconnect code attempts an XA reconnect using the XA APIs.

Note: The XA reconnect mechanism attempts to reconnect to all XA entries marked as enabled at the start up of the enterprise server region.

To prevent the reconnect attempts:

  • Remove the XA manager from the enterprise server region definition.

Alternatively:

  • Set the XA manager as disabled before starting the enterprise server region.

XA reconnect can operate in single or multiple reconnect modes depending on the configuration of the ES_XA_RECONNECT and the ES_XA_%xaname%_OPTIONS environment variables:

  • Single mode reconnect for CICS
    To configure the XA reconnect process to operate in a single attempt mode, set the ES_XA_RECONNECT environment variable.
  • Multiple mode reconnect for CICS
    For enterprise server regions configured to run CICS applications, you can configure the XA reconnect process to operate in a multiple attempt mode by setting the ES_XA_%xaname%_OPTIONS environment variable.
Parent topic: Using XA-compliant Resources (XARs)


Single mode reconnect for CICS

To configure the XA reconnect process to operate in a single attempt mode, set the ES_XA_RECONNECT environment variable.

In this configuration, each time a transaction is about to execute, an xa-ping is attempted. If this fails an xa-close and xa-open followed by an xa-ping are executed. If these fail, an error message is sent to the console indicating that the connection to the Resource Manager (RM) has been lost. The RM is not disabled.

On each attempt to execute a transaction, the same processing takes place until the connection to the RM is re-established. If the connection to the target RM is lost and the transaction requires the target RM, then the application program determines if action to recover the error is required, such as ABEND or rollback, or to display a message to the console. If the RM is not disabled, all XA error messages are displayed in the console. When the connection is re-established, a message is displayed in the console.

Configures the XA reconnect process to operate in a single-attempt mode.
Syntax
ES_XA_RECONNECT=Y,wait-time[,retry_count]
Parameters
Y
Enables the reconnect process.
wait-time
The number of seconds to delay before triggering the XA recovery transaction after a two-phase commit failure and between each reschedule of the XA recovery transaction if the syncpoint phase 2 returns an RC 04. Maximum is 300.
retry_count
The number of recovery retries to attempt when the XA commit or rollback executed by the XA recovery transaction returns an RC-04. Default is 5.
Default
Not set. XA reconnect operates in multi-attempt mode.
Comments
In case of failure, the following messages are sent to the console:
CASXO0054W XA recovery error RC=4 on commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG           000000***********000010000000**        0000

When the maximum number of retries is reached, the following message is sent to the console:

CASXO0055S XA MAX recovery attempts, manually commit in-doubt transaction RM: RM01 RC:  00004 XID: MF_CAS  DEMOMYREG       000000***********000010000000**        0000
Example
ES_XA_RECONNECT=Y,120,4
Parent topic: Enterprise Server XA Reconnect
Related tasks
To edit an XA resource
Related reference
Environment variables
Related information
ES_XA_RECONNECT


Multiple mode reconnect for CICS

For enterprise server regions configured to run CICS applications, you can configure the XA reconnect process to operate in a multiple attempt mode by setting the ES_XA_%xaname%_OPTIONS environment variable.

When the ES_XA_%xaname%_OPTIONS environment variable specifies an RM and a wait time, each time a transaction is about to be executed an xa-ping is attempted. If it fails the XA reconnect processing will loop on the xa-close, xa-open, and xa-ping. Waiting a specified duration, in seconds, before repeating until the xa-ping receives a return code of 0. If at the end of the loops, the connection has not been re-established, the RM will be disabled and a severe error will be sent to the console to indicate that the RM has been disabled.

To re-enable the target RM, Dynamic XA should be used. Dynamic XA provides the ability to disable and re-enable an XA RM during the life of a region.

When set with ES_XA_RECONNECT=Y, configures the XA reconnect process to operate in a multi-attempt mode.
Syntax
ES_XA_%xaname%_OPTIONS={reconnect_attempts,wait-time|EX}
Parameters
%xaname%
The name of the RM as specified in MFDS or ESCWA.
reconnect_attempts
The number of reconnect attempts to the target RM. Maximum is 9999.
wait-time
The number of seconds to delay between each attempt.
EX
Exclude the target RM from XA reconnect processing.
Default
Not set.
Comments
ES_XA_%xaname%_OPTIONS must be set along with ES_XA_RECONNECT=Y.

You might need to set ES_XA_%xaname%_OPTIONS multiple times — once for each RM that you require to operate in a multiple-attempt mode.

Examples
Specify that an XA reconnect processing attempts to reconnect to MQPROD 100 times and waiting for 10 seconds between each reconnect attempt:
ES_XA_MQPROD_OPTIONS=100,10

Specify that the XA reconnect processing is to exclude MQPROD from the XA reconnect processing:

ES_XA_MQPROD_OPTIONS=EX
Parent topic: Enterprise Server XA Reconnect
Related tasks
To edit an XA resource
Related reference
Environment variables
Related information
ES_XA_%xaname%_OPTIONS


Reconnecting to an MQ Server in a Multi-instance Queue Manager

Enterprise Server transaction processing and batch systems can now reconnect to the standby MQ Queue Manager in a Multi-Instance Queue Manager (MIQM) when connection to the active queue manager is lost.
  • Setting Up Application Reconnect in a Multi-instance Queue Manager
    XA reconnect enables reconnection to the standby MQ Queue Manager in a Multi-Instance Queue Manager (MIQM) when connection to the active queue manager is lost in both transaction processing and batch programs.
  • Enterprise Server Batch Reconnect for MQ Batch Programs Running in a Multi-instance Queue Manager
    If MQ is configured as a Multi-Instance Queue Manager (MIQM), batch programs will automatically reconnect to the active queue manager. This is enabled by setting the MQCNO-RECONNECT option in the MQCONNX IBM MQ API.
Parent topic: Using XA-compliant Resources (XARs)


Setting Up Application Reconnect in a Multi-instance Queue Manager

XA reconnect enables reconnection to the standby MQ Queue Manager in a Multi-Instance Queue Manager (MIQM) when connection to the active queue manager is lost in both transaction processing and batch programs.

XA Reconnect

The XA reconnect is performed as part of the processing in the SEP. See Enterprise Server SEP XA Reconnect for more information. If the environment variable ES_XA_RECONNECT is set to any value, the system will attempt to reconnect to an XA resource when the connection is lost. In the context of a MIQM configuration where connection to the active instance is lost, if the ES_XA_MQ is set to MIQM then the XA reconnect processing in the SEP will attempt to switch to the newly active MQ instance.

Configuring XA Reconnect for an Multi-instance Queue Manager

To further configure XA reconnect for an MIQM, you must specify three environment variable ES_XA_RECONNECT, ES_XA_MQ, and MQSERVER.

The environment variable ES_XA_MQ is used to enable the reconnection to the standby queue manager when the connection to the active queue manager is lost:

ES_XA_MQ=MIQM

In addition, the environment variable MQSERVER must be set so that the system can verify that at least 2 connections are listed. For example:

MQSERVER=CHANNEL1/TCP/10.120.99.999(1414),10.120.98.888(1414)

XA Entry Definition

To enable the system to connect to the active queue manager in an MIQM at region startup, an XA entry must be created that will point to the first address listed in the MQSERVER environment variable.

Important: You cannot use the MQ related entries in the SIT to configure MQ. The XA connection must be specified as part of the XA resources of your region using Micro Focus Directory Server (MFDS) or Enterprise Server Common Web Administration (ESCWA).

The following is an example XA entry for an active MIQM MQ instance:

ID:
MQPROD
Open string
TPM=ESCICS,AXLIB=casaxlib,QMNAME=MIQM001,uid=mq01@MYCORPDOM,pwd=MQadmin,CHANNEL=CHANNEL1,TRPTYPE=TCP,CONNAME=10.120.99.999(1414)

At the point XA entries are installed, the system will create an XA entry for the standby entry which will be identical to the active definition except for the name and the CONNAME.

If the example MQPROD is already specified then the dynamically created instance entry will be:

ID:
MQPRO#
Open string
TPM=ESCICS,AXLIB=casaxlib,QMNAME=MIQM001,uid=mq01@MYCORPDOM,pwd=MQadmin,CHANNEL=CHANNEL1,TRPTYPE=TCP,CONNAME=10.120.88.888(1414)

Where the ID and the CONNAME is different. This entry will be installed but will not be activated until the connection to the first active instance is lost. When this connection loss takes place, the active connection will be replaced with that of the standby MQ instance which now becomes active and the previously active instance become the standby instance.

Both connections appear active but only the active one is enrolled in the XA transaction.

Note: To switch back to the initial queue manager, stop the currently active queue manager, the enterprise server will then regain the connection to the original queue manager.
Note: The hostname or IP address specified in the CONNAME option of the XA open string must be consistent with the hostname or IP address in MQSERVER.
Parent topic: Reconnecting to an MQ Server in a Multi-instance Queue Manager
Related information
ES_XA_RECONNECT


Enterprise Server Batch Reconnect for MQ Batch Programs Running in a Multi-instance Queue Manager

If MQ is configured as a Multi-Instance Queue Manager (MIQM), batch programs will automatically reconnect to the active queue manager. This is enabled by setting the MQCNO-RECONNECT option in the MQCONNX IBM MQ API.

In Enterprise Server, if an application program uses the MQCONN API and the reconnect in an MIQM, the system will redirect the MQCONN API to the MQCONNX API. The system will also set the MQCNO-RECONNECT option on the MQCONNX API invocation.

Note: You might experience security issues when using the MQCONN API. To resolve this ensure that you pass user credentials. See Passing user credentials when connecting to an MQSeries queue manager for more information.

Configuring a Batch Reconnect

Set the environment variable ES_XA_MQ to enable reconnection to the standby queue manager when the connection to the active queue manager is lost:

ES_XA_MQ=MIQM

In addition, the environment variable MQSERVER can be set to enable Enterprise Server to verify that at least 2 connections are listed. For example:

MQSERVER=CHANNEL1/TCP/10.120.99.999(1414),10.120.98.888(1414)
where each connection is separated by a comma.
Parent topic: Reconnecting to an MQ Server in a Multi-instance Queue Manager
Related information
MQSERVER


XA Recovery

Some events (such as connection loss, process death, resource manager failure, etc.) might result in the creation of 'in-doubt' XA transactions. Such transactions are created when one or more RMs enlisted in an XA transaction have not completed or have failed on the second phase of a syncpoint (either commit or a rollback). When this happens, the XA transaction left in the resource manager in a "prepared" state is called an in-doubt transaction. It is the role of the XA transaction manager such as Enterprise Test Server to resolve these in-doubt transactions.

In order to recover XA transactions, the transaction manager logs the outcome of the syncpoint-related XA verbs. It uses this information to make a decision on how to syncpoint an in-doubt transactions if one is left in one or more resource managers. During region startup, on SEP abend, on XA errors RMFAIL and RMERR returned on phase 2 of a syncpoint, the XA recovery transaction will be triggered. Using the information contained in the XA log, this system transaction will then commit or rollback the XA transactions returned by the resource manager.

When an XA transaction is recovered, you receive the following type of messages:

CASXO0027I XA recovery committed in-doubt transaction 177969 branch 1 on RM XADB2
CASXO0027I XA recovery committed in-doubt transaction 249152 branch 3 on RM ESMQXA4
CASXO0027I XA recovery committed in-doubt transaction 1539000001 branch 3 on RM DB51

At region start up, if in-doubt transactions were created during the last region run, you receive the following type of messages:

CASXO0029I XA log reported in-doubt transaction 1443000001 branch 3
CASXO0029I XA log reported in-doubt transaction 03456 branch 1

It is possible that some of these XA transactions were resolved or recovered during the previous region run. If not they should be recovered shortly after these messages are displayed. Another message should then be displayed and it confirms the XA recovery at startup:

CASXO0027I XA recovery committed in-doubt transaction 03456 branch 1 on RM XADB2

XA logging

XA logging is the mechanism underpinning the recovery of in-doubt transactions. By default, XA logging is enabled for RMs that present a xa_recover entry point. XA logging is bypassed for an RM which does not present the xa_recover() capability.

Depending upon your environment, logging might degrade performance. You can disable XA logging by setting the following environment variable:

ES_XA_LOG_SUPPRESS=Y

XA protocol optimization

For the two-phase commit batch program DSNRLI, XA processing is optimised when only one RM participates in the XA transaction.

Parent topic: Using XA-compliant Resources (XARs)


XA Troubleshooting

  • XA Troubleshooting
  • XA Return Codes
  • RM Switch Module Diagnostics
  • XDB 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 occurred
  • -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.

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. For example:

Example 1
This trace shows a successful 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


RM Switch Module Diagnostics

SQL Server, DB2, Oracle, XDB, PostgreSQL, and ODBC
The SQL Server, DB2, Oracle,, XDB, PostgreSQL, and ODBC switch modules have been coded to use the Consolidated Trace Facility (CTF) to aid in debugging any errors returned during operation. The CTF component name for tracing RM switch modules is mf.esxa. Our Enterprise Developer product provides a configuration file, ctf.cfg, located by default 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.

For more information, see The Consolidated Trace Facility and Components Traced by CTF.

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 concepts
Consolidated Tracing Facility
Components Traced by CTF
Related information
MFTRACE_CONFIG


XDB Diagnostics

You can configure the XDB XA Switch module to trace error conditions by enabling the XATrace option in the xdb.ini file as follows:

 [Trace]
XATrace=filename

Where filename is the full path to and filename of a file used to collect trace information. Each entry in this file contains a timestamp, the error message generated at that time, and possibly some diagnostic information. For example, following entry might be produced by an incorrect XA open string:

 XA PID = 7336 : 2011-08-29 15:27:04.247000 :
Error parsing connection string :
LOC = MYLOC, UID=MFIABC, XDBPWD='xxxxxxxx'
Reason = Invalid token XDBPWD at position 26
Parent topic: XA Troubleshooting


Scale-Out Performance and Availability Clusters

The Performance and Availability Cluster (Performance and Availability Cluster (PAC)) architecture is designed to improve the scaling and availability of Enterprise Server deployed in a multi-system configuration. The PAC architecture minimizes single points of failure (SPOF).

  • Performance and Availability Clusters Rationale
    This topic outlines the concept of the scale-out enterprise server architecture and its use as a high availability platform.
  • Performance and Availability Clusters Topology
    This chapter describes a performance and availability cluster's components and their function.
  • Prerequisites
    Details the supported operating systems, software prerequisites, and configuration prerequisites for using a PAC.
  • Supported Configurations
    Details the supported configurations and limitations when using a PAC.
  • Configuring a PAC
    Details the mandatory and optional configuration requirements for a PAC.
  • Administering a PAC
    The following details tasks, best practices, and utilities to help administer your PAC.
  • Troubleshooting a PAC
    The following describes how to diagnose common problems that can occur when working with a PAC.
  • Reference
    Reference information for configuring and administering your PAC.
Parent topic: Enterprise Server configuration and administration
Related concepts
Performance Availability Clusters (PACs)
Related reference
Supported Configurations
Types of Database
Providing Credentials for your Scale-Out Repository using Secrets
PAC and SOR Environment Variables


Performance and Availability Clusters Rationale

Enterprise server instances, also referred to as regions, are typically deployed in a scale-up configuration. Capacity is increased by adding or replacing hardware components such as cores/vCPUs. Increasing the number of cores/vCPU increases overall capacity but scaling is not linear.

A Performance and Availability Cluster (PAC) enables you to configure regions in a scale-out architecture. In a PAC, multiple regions work together as a single logical entity, improving the linearity of capacity scaling. A PAC that utilizes distributed regions improves resilience to hardware or network issues. Therefore, the region is no longer a SPOF, improving the availability of the configuration.

User and system data files can also be a SPOF. Files can be replicated across drives for improved resilience. VSAM and transactional file updates are made up of multiple physical file input/output operations. If an issue occurs which prevents a file operation completing, then the file can be corrupted, and the replication process will propagate the corrupted file. For improved availability and scaling, files can now be managed and stored in an RDBMS.

Parent topic: Scale-Out Performance and Availability Clusters


Performance and Availability Clusters Topology

There are a number of mandatory components that must be configured to support the core function of a Performance and Availability Cluster (PAC). There are additional optional components that can be configured depending on the required function of your PAC.

The following diagram presents both mandatory and optional components of the PAC architecture:

The following sections describe the functions of the key components of the PAC and recommend when optional components should be considered.

  • Mandatory: Region Availability
  • Mandatory: System Data Availability
  • Recommended: System and User Data File Availability
  • Recommended: System Security
  • Optional: Scale-Out Repository
Parent topic: Scale-Out Performance and Availability Clusters


Mandatory: Region Availability

At the core of a Performance and Availability Cluster (PAC) are the regions, a PAC can contain two or more regions

  • These regions can be distributed across hardware to improve PAC resilience.
  • All participating regions must be the same bitism, on the same OS and version, and have the same product version installed.
Note: Micro Focus recommends that you create a PAC with at least three regions. This enables instances within the PAC to be temporarily suspended for maintenance without compromising the availability of the PAC.
Mandatory Region Availability

The PAC Scale-Out Repository (PSOR) enables the PAC to be administered and operated as a single system image:

  • Synchronization of key CICS and system resource definitions. See CICS Resources section in the Supported Configurations topic for more information.
  • Providing operational support for JCL job submission, scheduling, monitoring, and control.
  • Abstraction of where Jobs are run.
  • Reply and job kill capabilities.
  • Recovery processes, such as release ENQs, closing, and database hosted files left open.
  • Mechanisms to update and deploy new load modules using CICS NEWCOPY and JCL batch.
Note: A PAC must have only one PSOR.

The following are examples of how a Scale-Out Repository (Scale-Out Repository (SOR)) reduces the administrative burden and minimizes the risks that might normally be part of managing a scale-out configuration of enterprise server instances:

  • Switching from online to batch; without the SOR, as the CICS application starts in each region, the FCTs for the files it uses will be marked as open. Switching to batch would require the administrator to go to each region in turn and perform an FCT close on the file. With the SOR, the first region to run the CICS application would mark the file open in the FCT and the SOR will apply this to all the instances in the PAC. To switch to batch, the administrator simply goes to any single instance in the PAC, close the FCT, and the action will be applied for all instances in the PAC.
  • Administering a batch job; if a batch job is submitted to any enterprise server instance in a PAC where the PAC is sharing a catalog and spool files. The job gets added to the queues and the first enterprise server instance in the PAC available to submit that job will pick it up. The job might run on a different enterprise server instance than the one it was submitted on. If you wanted to administer that job without the SOR, you would need to go to each enterprise server instance, in turn, to determine which one was running that Job. With the SOR, the job can be administered from any region in the PAC.
  • Updating a library used across the PAC; without the PAC, the administrator would need to go to each enterprise server instance, in turn, and install the library. With the SOR, the library can be loaded into the SOR which will then manage its publication to all the enterprise server instance in the PAC.
Note: Over time as more capabilities are added to the PAC, then more supporting actions will be added to the function of the SOR to minimize administration requirements.
Parent topic: Performance and Availability Clusters Topology


Mandatory: System Data Availability

A Performance and Availability Cluster (PAC) is defined and administered as a single system image for common attributes using a region and cross-region database:

Mandatory: System Data Availability
  • A region database is required for SYSTEM scope ENQs.
  • A cross-region database is required to provide recovery for the region database and SYSTEMS scope ENQs.
  • This method of ENQ processing is a direct replacement for the capabilities provided by the Global Lock Manager (GLM).
  • As well as ENQ support, all the GLM capabilities are now provided by a PAC.

The Databases are configured using the Micro Focus Database File Handler (MFDBFH) using the mfdbfh.cfg configuration file.

The location of the mfdbfh.cfg must be specified in the Configuration Information field by the environment variable MFDBFH_CONFIG. This environment variable must be specified for each of the regions that are members of the PAC.

The two supported RDBMS connection methods are:

  • ODBC Drivers.
  • Database Connection Strings.

See Types of Database for more information on region and cross-region databases.

Parent topic: Performance and Availability Clusters Topology


Recommended: System and User Data File Availability

Micro Focus recommends using a datastore database to store system-critical files to improve the availability of this data:

Recommended: System and User Data File Availability
Note: Micro Focus recommends that you store catalog, user catalogs, spool files (spljob, spldsn, splmsg, spljno), and CICS resource definition files in the datastore.
Attention: Any Field Developed Solution (FDS) or scripts that directly access these files needs to be modified for the new URI and utilities to load and unload files. The potential impact on access latency can be mitigated by concurrent/parallel access.

A datastore can be created to store user files in the RDBMS, providing support for:

  • Transactional and non-transactional files.
  • VSAM, sequential, and line sequential files.
  • Improved availability of data.
  • Improved scaling for transactional files.

Micro Focus recommends that you move all VSAM or transactional files that are critical to the availability of the system to a datastore.

Parent topic: Performance and Availability Clusters Topology


Recommended: System Security

Access to the PAC Scale-Out Repository (PSOR) and Scale-Out Repository (SOR) can be configured to require authentication when a client connects to it. If this is the case, you can store the password in the Micro Focus Secrets Vault. See Providing Credentials for your Scale-Out Repository using Secrets for more information.

Recommended: System Security

Micro Focus recommends you secure access to the PSOR and any additional SOR using the Secrets Vault to store the credentials.

Parent topic: Performance and Availability Clusters Topology
Related reference
Providing Credentials for your Scale-Out Repository using Secrets


Optional: Scale-Out Repository

You can configure one or more Scale-Out Repository (SOR) to store specific types of user data, currently limited to non-recoverable TS and TD queues. You can choose which instances of user data are stored in a SOR using a SOR Model. For example, if only a subset of TSQs need to be shared, then a SOR Model can be used to specify which TSQs are directed to the SOR. Instance data that does not match a SOR Model rule continues to be stored on its local enterprise server instance. See PAC and SOR Environment Variables for more information.

Optional: Scale-Out Repository
Note: Any user data that can be stored in a SOR can also be stored in the PAC Scale-Out Repository (PSOR).

Micro Focus recommends that you use additional SORs to distribute the load and improved performance.

Parent topic: Performance and Availability Clusters Topology


Prerequisites

Details the supported operating systems, software prerequisites, and configuration prerequisites for using a PAC.

Supported Operating Systems

The following platforms are supported:

  • Windows
  • x86-64 running Red Hat Linux 7, 8, or 9
  • x86-64 running on SUSE 12

Operating System Dependencies

On Linux platforms, the scale-out features require the latest version of the libuuid library.

To install on SUSE, at the command prompt, type the following:

zypper search libuuid

Follow the prompts and only install the non-development packages.

To install on Red Hat, at the command prompt, type the following:

yum search libuuid

Follow the prompts to install the packages.

RDBMS Support

The PAC requires a supported RDBMS to manage the following databases:

  • Region database (mandatory)
  • Cross-region database (mandatory)
  • Datastore database(s) (optional)
A datastore database should be used to manage VSAM files using the Micro Focus Database File Handler support.
Windows
Database | ODBC Driver
Microsoft SQL Server 2008 (including Express editions) R2 and later | ODBC 13.1 for SQL Server
PostgreSQL 10.x (incl. Amazon Aurora Postgres) and later | psqlodbc 11
DB2 10.5 and later | n/a
Oracle 19c | n/a
Note: These are databases supported for database hosted VSAM files. See Additional Software Requirements on Windows and Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components for more information on CICS SQL supported databases.
UNIX
Database | ODBC Driver
Microsoft SQL Server 2017 (including Express editions) and later ODBC 13.1 for SQL Server
Note: SQL Server 2017 installs versions 13 and 17 (x64 only)
PostgreSQL 10.x and later | psqlodbc 11
DB2 10.5 and later | n/a
Oracle 19c | n/a
Note: The Micro Focus Native Database File Handler is only supported on x86-64 running Red Hat Linux 7.3 or 7.4 or x86-64 running on SUSE v12 SP2 as these are also the minimum requirements for Microsoft SQL Server 2017.

In addition, there are minimum requirements for the following components:

Component | Version
Driver manager (MSSQL and PostgreSQL installations only) | unixODBC 2.3.2
Current Limitations
  • The order in which duplicate keys are returned is not guaranteed for indexed files. For files stored on disk, duplicate keys are always returned in the order they were written in.
  • The supported key types are currently limited to alphanumeric, binary, and numeric.
  • PostgreSQL does not support EBCDIC collating sequences. See Configure Datastores for Db2 for more information.
  • MFDBFH does not support COBOL programs compiled with NOFCD3.

NoSQL Support for Scale-Out Repository

Enterprise Server must use a NoSQL database as a Scale-Out Repository (SOR), a requirement to maintain PAC integrity. Enterprise Server supports the following NoSQL databases:

Redis
An open source in-memory data structure store.
Redis Cluster
A distributed implementation of Redis with performance, scalability, and availability as part of its design. See Configuring Redis Cluster for more information about configuring Redis cluster.
Redis Sentinel
Provides Redis high availability.
Oracle Coherence
An in-memory data grid solution.
  • Redis Requirements and Configuration as a Scale-Out Repository
  • Oracle Coherence Requirements and Configuration as a Scale-Out Repository
Parent topic: Scale-Out Performance and Availability Clusters
Related reference
Configure Datastores for Db2


Redis Requirements and Configuration as a Scale-Out Repository

In general, you can store CICS tables in REDIS as well as TSQ and TDQ data. These will contain application data. For more information on Redis and the data types it can store, refer to its documentation here.

For a production environment, Micro Focus recommends using an enterprise-ready Redis server that supports Redis 5.0.3 to 6.2.6. However, you will require version 6.0 and later to support TLS connections.

Note: Redis high availability can be achieved by using Redis Sentinel.

Redis Communication Configuration Requirements

You can configure communication with Redis by setting the environment variable MFREDIS_CONFIG to point to a configuration file. This configuration file can contain the following variables:

RD_KEEPALIVE_INTERVAL
Specifies the keepalive interval in seconds used for Redis connections. The default value is 15.
RD_LUA_LOG
This variable enables logging on the Redis server.
Note: The Redis server must be started with --log-level set to warning as a minimum.
ON
Enables logging.
OFF
Disables logging.

The default value is OFF.

RD_RETRY_INTERVAL
Specifies how long, in milliseconds, the Redis client should wait before reattempting to connect and perform the last failed request.

The default value is 2000 (2 seconds).

RD_RETRY_ATTEMPTS
Specify the number of attempts the Redis client should try to perform the last failed request.

The default value is 1.

Additional Configuration for Redis Sentinel

The following additional configuration is required for Redis Sentinel.

In Redis, you need to specify a Redis master and as many Redis replicas as you require. An odd number of Redis Sentinel is required to make a quorum.

The following is an example of how to start and configure a Redis Sentinel that has a master on port 6741, 1 replica on port 6742 and 3 sentinels on ports 6800, 6801, and 6802.

To start the Redis master, on a command prompt, type:

redis-server.exe --port 6741 --protected-mode no --bind 0.0.0.0

To start the Redis replica, on a command prompt, type:

redis-server.exe redis_replica.conf

To start the 3 Redis sentinels, on a command prompt, type:

redis-server.exe sentinel-1.conf –-sentinel
redis-server.exe sentinel-2.conf –-sentinel
redis-server.exe sentinel-3.conf –-sentinel

In this case, your Redis master will be called MY_MASTER, this needs to be in uppercase. The following is an example of the content for the redis_replica.conf file. In the following configuration files, ensure that the text in bold is modified to reflect your requirements:

bind 0.0.0.0
port 6742   ## The port used by the replica.
tcp-backlog 511
timeout 0
tcp-keepalive 0
loglevel notice
logfile ""
databases 16
save 900 1
save 300 10
save 60 10000
stop-writes-on-bgsave-error yes
rdbcompression yes
rdbchecksum yes
dbfilename "dump.rdb"
replicaof 127.0.0.1 6741    ## The port and IP used by the master
replica-serve-stale-data yes
replica-read-only yes
repl-diskless-sync no
repl-diskless-sync-delay 5
repl-disable-tcp-nodelay no
replica-priority 100
appendonly no
appendfilename "appendonly.aof"
appendfsync everysec
no-appendfsync-on-rewrite no
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb
aof-load-truncated yes
lua-time-limit 5000
slowlog-log-slower-than 10000
slowlog-max-len 128
latency-monitor-threshold 0
notify-keyspace-events ""
hash-max-ziplist-entries 512
hash-max-ziplist-value 64
set-max-intset-entries 512
zset-max-ziplist-entries 128
zset-max-ziplist-value 64
hll-sparse-max-bytes 3000
activerehashing yes
client-output-buffer-limit normal 0 0 0
client-output-buffer-limit replica 256mb 64mb 60
client-output-buffer-limit pubsub 32mb 8mb 60
hz 10
aof-rewrite-incremental-fsync yes

The content of the sentinel-1.conf, sentinel-2.conf, and sentinel-3.conf are the same except for the port. Modify the port to correspond to the port used by the appropriate sentinel:

port 6800     ## The port used by the sentinel
sentinel monitor MY_MASTER 127.0.0.1 6741  ## The name, IP, and port used by the master.
sentinel down-after-milliseconds MY_MASTER 5000
sentinel failover-timeout MY_MASTER 60000
sentinel parallel-syncs MY_MASTER 1

For the PAC configuration, in ESCWA, the SOR name must match the Redis master name MY_MASTER followed by all the sentinel IP and ports, for example:

set ES_SCALE_OUT_REPOS_1=MY_MASTER=redis,127.0.0.1:6800,127.0.0.1:6801,127.0.0.1:6802##TMP

Configuring a TLS Enabled Redis Connection

You can configure a TLS enabled Redis connection by specifying redis_TLS for the sorType parameter of the ES_SCALE_OUT_REPOS environment variable. For example:
ES_SCALE_OUT_REPOS_1=MySOR=redis_TLS,127.0.0.1:6379##TMP#
In addition to this you must also specify the ES_RTLS_CERT_AUTH_FILEPATH , ES_RTLS_CERT_FILEPATH, and ES_RTLS_PRIVATE_KEY_FILEPATH environment variables for each enterprise server region that is a member of the PAC. Alternatively, in ESCWA, you can specify the Certificate Authority Filepath, Certificate Filepath, and Private Key Filepath properties on the Advanced Region Properties page for all enterprise server region that are members of a PAC which has a TLS enabled Redis Scale-Out Repository (SOR).
Parent topic: Prerequisites


Oracle Coherence Requirements and Configuration as a Scale-Out Repository

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

For a production environment, you must use Oracle Coherence version 14.1.1 or later.

Note: Micro Focus recommends that you use either Java 8 with Remote clients or Java 11 with Direct or Remote clients to avoid an issue with high CPU usage when used in a PAC environment. On UNIX platforms, Coherence is only supported on 64-bit machines.

For more information on Oracle Coherence click here.

You will require the Coherence file coherence.jar, and if you are configuring security you will also require the coherence-login.jar file.

Coherence clients and servers are configured using a combination of xml configuration files and Java system properties.

The Enterprise Server support file mfescache.jar is shipped with Enterprise Developer, and can be located at %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin. The Enterprise Server configuration file mfescache.cfg is also supplied and can be located at %ProgramFiles(x86)%\Micro Focus\Enterprise Server\etc. These are suitable for production use, provided that system properties are configured for items such as the cluster name. If the cluster name is not configured one is automatically generated based on the OS username running the client or server, for example, "User's cluster". When using the default configuration files, the cluster name must always be configured via the coherence.cluster property. The default configuration filename is mfes-cache-config.xml and it is located along the CLASSPATH within the mfescache.jar file. The configuration file can be extracted and modified if required.

The Coherence clients and servers can discover each other by multicasting or unicasting using a list of well-known addresses and will attempt to join to form a single cluster using a specified cluster name. The cluster name can be configured using the Java property coherence.cluster. See Oracle Coherence documentation for more information on cluster formation and configuration.

Note: Cluster names are limited in length to 64 characters.

The mfescache.cfg configuration file and well-known addresses

The configuration file mfescache.cfg defines the Java Virtual Machine environment created by Enterprise Server to enable it to utilize Coherence clients. This file can be modified by a text editor to add additional properties such as CLASSPATH entries or well-known addresses. The default cache configuration file (mfes-cache-config.xml) uses well-known addresses. The well-known addresses are specified as a comma-separated list of endpoints enclosed within curly parentheses {} using a Java property named mfescache.wka.CLUSTERNAME, for example:
mfescache.wka.MYPAC_cluster={192.168.11.12:7574,192.168.11.14:7574}
A Coherence server at one of the specified endpoints must be contactable to enable members to join or access the cluster. If the endpoint is not specified, then the port is set to the value of the coherence.clusterport value, the default value is the IANA registered port 7574. In environments where the network DNS can be configured to return multiple addresses for a network name then that facility can be used to simplify the configuration. If you are specifying a single endpoint address then the enclosing curly parentheses {} can be omitted.

Starting a Coherence server

To start a Coherence server for use with Enterprise Server you will require the following:

  • Java 1.8 or later.
  • The coherence.jar file from Oracle Coherence version 14.1.1 or later.
  • The Enterprise Server mfescache.jar support file.
  • Access to a Coherence cache configuration file, and/or Coherence operational override configuration file.
Note: The Enterprise Server Coherence feature does not support using alternative Scale-Out Repository (SOR) models. So just a single SOR should be configured.

Both the Oracle Coherence coherence.jar file, and the Enterprise Server mfescache.jar files must be on the Java CLASSPATH when running the server.

Unless the default cache configuration filename is being used, the location should be specified using the coherence.cacheconfig system property. This can be the name of a file on CLASSPATH, a path to a local file, or a URL providing the configuration content.

Each server cluster is started using a command similar to one of the following, assuming that the two jar files are in the current directory. Use a suitable cluster name in place of MYPAC_cluster; the class listed is a wrapper around the Coherence server, setting the following properties:

tangosol.pof.enabled=true,
coherence.pof.config=es-pof-config.xml,
coherence.role=server,
coherence.cacheconfig=mfes-cache-config.xml
Note: If the properties are already set they will not be overridden, with the exception of tangosol.pof.enabled.

Micro Focus recommends that you use a minimum of 3 servers for a production environment, this will support data redundancy and recovery in case a server were to fail or require maintenance. For testing purposes, a single server is sufficient.

In Coherence, the minimum number of service members that are required in a cluster before a service action is allowed or disallowed is referred to as a quorum. You can configure a quorum policy to control when specific service actions are allowed in a cluster ensuring that a cluster is adequately provisioned. See Oracles Coherence documentation for more information. To assist you configuring of a quorum policy the supplied operational override file defaults the coherence.role to "es-client" and defaults the cluster-survivor-quorum timeout-survivor-quorum elements to require at least one "es-client" and one "server".

Other than log settings, the servers can typically be started using the same configuration, for example:

java -cp coherence.jar:mfescache.jar -Dcoherence.cluster=MYPAC_cluster -Dmfescache.wka.MYPAC_cluster={192.168.11.12:7574,192.168.11.14:7574} com.microfocus.es.cache.coherence.ESCacheServer

To send output to a file using the default port:

java -cp coherence.jar:mfescache.jar -Dcoherence.cluster=MYPAC_cluster -Dmfescache.wka.MYPAC_cluster={192.168.11.12,192.168.11.14} -Dcoherence.log=/tmp/coherence.log com.microfocus.es.cache.coherence.ESCacheServer

To specify an alternative cache configuration file:

java -cp coherence.jar:mfescache.jar -Dcoherence.cluster=MYPAC_cluster -Dmfescache.wka.MYPAC_cluster={192.168.11.12,192.168.11.14} -Dcoherence.cacheconfig=mycacheconfig.xml com.microfocus.es.cache.coherence.ESCacheServer

Logging

Coherence logging is specified using the properties coherence.log=<location> and coherence.log.level=n where n can be between 0 to 9. See Oracle Coherence for more information on the log level. In addition to the standard Coherence behaviour, if @PID@ is included within the <location> it will be replaced with a process specific identifier which is useful when logging Enterprise Server processes. For example:
coherence.log=/logs/coherence_@PID@.log
Would set the log to be /logs/coherence_1234@mymachine.log.

By default, for Enterprise Server clients the coherence.log.level property is set to 0 but this can be overridden by specifying it as part of the SOR configuration, for example:

ES_SCALE_OUT_REPOS_1=MYSOR=coherence,,coherence.cluster=MYPAC_cluster,,mfescache.wka.MYPAC_cluster=127.0.0.1,coherence.log.level=9,coherence.log=/tmp/coherence.log##TMP#

Security

If security is enabled for the Coherence server, the user-id to use for access must be specified with an at character (@) as a suffix followed with the rest of the connection string, for example:

ES_SCALE_OUT_REPOS_1=MYSOR=coherence,MYUSER@mfes-cache-config.xml,coherence.cluster=MYPAC_cluster,mfescache.wka.MYPAC_cluster=127.0.0.1##TMP#

Micro Focus recommends that you store the password in the Vault Facility. See Vault Facility for more information.

Coherence security is configured using an "operational override" configuration file, this can be called tangosol-coherence-override.xml and is found on CLASSPATH or specified using the coherence.override system property. You must specify a corresponding Java security policy. A tangosol.coherence.override.xml file is included in the mfescache.jar, which by default does not specify any security settings.

Parent topic: Prerequisites
Related reference
PAC and SOR Environment Variables
Related information
ES_SCALE_OUT_REPOS_n


Supported Configurations

Details the supported configurations and limitations when using a PAC.
Note: Configuring internal Fileshare for an enterprise server region that is participating in a PAC, is invalid.
  • System
  • JCL support
  • IMS support
  • CICS Support
  • Lock Support
Parent topic: Scale-Out Performance and Availability Clusters


System

System-specific supported configurations:

  • Trace flags
  • VSAM share options
Parent topic: Supported Configurations


Trace flags

Switching on trace flags in any single region will cause those flags to be applied to all regions in the Performance and Availability Cluster (PAC).

Parent topic: System


VSAM share options

VSAM share options are supported.

Parent topic: System


JCL support

JCL is supported in a Performance and Availability Cluster (PAC), with the following exceptions:

  • The MVSPCRN utility does not support files that are being moved into a MFDBFH environment.
  • Any libraries accessing MFDBFH hosted files must be compiled using the FCD3 directive.
Parent topic: Supported Configurations


IMS support

IMS is not currently supported in a Performance and Availability Cluster (PAC).

Parent topic: Supported Configurations


CICS Support

Currently only a limited number of the CICS resource types can be managed in a Performance and Availability Cluster (PAC). Each of these resources might need specific processing in the PAC. For example, to open and close an FCT, or to copy an executable across the PAC. This topic describe the specific requirements for each resource type.

  • Temporary Storage and Transient Data Queues
  • Indirect Queues
  • Triggering
  • Extra-partition Queues
  • Internal Reader
  • Temporary Storage Queue (TSQ)
  • Browsing
  • EXEC CICS START @ TERMID
  • CICS Resources
Parent topic: Supported Configurations


Temporary Storage and Transient Data Queues

Temporary Storage (TS) and Transient Data (TD) queues can be directed to any Scale-Out Repository (SOR); they do not need to be directed to the PAC Scale-Out Repository (PSOR).

Parent topic: CICS Support


Indirect Queues

Model prefixes work on the target queue only:

Model prefix = MYQ

TDQ Name | Indirect Name | Storage location
MYQ1 | TDQ1 | Disk
TDQ1 | MYQ1 | SOR
Parent topic: CICS Support


Triggering

Triggering is supported.

Parent topic: CICS Support


Extra-partition Queues

The use of extra-partition queues is unsupported in a Performance and Availability Cluster (PAC).

Parent topic: CICS Support


Internal Reader

The internal reader is supported.

CICS applications can direct a JCL jobstream to these queues for execution by the JCL engine. These queues are a special type of extra-partition queue.

Parent topic: CICS Support


Temporary Storage Queue (TSQ)

The Temporary Storage Queue (TSQ) is supported.

Parent topic: CICS Support


Browsing

TSQ browsing is supported.

Parent topic: CICS Support


EXEC CICS START @ TERMID

Exec CICS START with a termid specified is supported in a Performance and Availability Cluster (PAC).

Note: START CHANNEL is currently unsupported.
Parent topic: CICS Support


CICS Resources

The following CICS resources are stored in the PAC Scale-Out Repository (PSOR) when configured and operating:

DCT
Although the DCT resources themselves are stored in the PSOR, the actual queue must be one of the following DCT types in order for it to be stored in a Performance and Availability Cluster (PAC) by a Scale-Out Repository (SOR) Model:
  • Non-recoverable.
  • Intra-partition - which includes triggers.
  • Indirect - model prefixes work only on the target DCT.
Note: Recoverable, internal reader, and extra-partition types cannot be stored in a SOR.

You can still have recoverable TD queues in a PAC by configuring the SIT to store the recoverable TDQ file in a database this is the same for recoverable TS queues.

When viewing information about TD queues in ESMAC, the following apply:

  • Information regarding SOR stored queues, such as number of items and depth, can be viewed by any enterprise server instance.
  • Information regarding queues stored on disk is only available to the local enterprise server instance.
ENQMODEL
An ENQMODEL is used to elect named resources for which ENQ/DEQ commands use a SYSTEMs wide scope (SYSTEMs vs SYSTEM).

By default, CICS ENQs in a PAC will be stored in the region database (scope SYSTEM).

ENQs are directed to the cross-region database if they match an ENQMODEL that has an ENQSCOPE value that is not equal to spaces (scope SYSTEMS). This enables ENQs to be shared outside of the PAC.

An ENQMODEL can be configured to send matching ENQs to shared memory. The purpose of this would be to gain a performance improvement over storing them in a database.

CAUTION:
It should only be used if the resource in question is being accessed in a single region. If the ENQ is taken in multiple regions, then the resource will not be protected.
FCT
The VSAM file referred to by the resource of this type can be stored in an RDBMS. See the MFDBFH configuration for requirements. Whether or not in MFDBFH, issuing a file close command in any enterprise server instance results in the file being closed by all instances in the PAC.
PCT
Since the Active PCT is stored in the PSOR, changing the status (enabled/disabled) in any region will result in the status being changed for the entire PAC.
PPT
Each enterprise server instance will load user applications from the location specified in its configured transaction path.

If you need to modify a program while a PAC is active, you need to uploaded the new binary file to the PSOR and then issue a caspac New Copy command.

For example, the process to install a new version of the program myprog.dll is as follows:

  1. Load the new version of myprog.dll into the PSOR with the following command:
    caspac -aLoad="C:\new files\myprog.dll" -sredis,127.0.0.1:6379
  2. Issue the New Copy command via one of the following methods:
    • Using the CICS castran command:
      castran –rinstanceName  -nmyprog
    • Using the CICS CPMT transaction:
      CPMT NE MYPROG
    • Using an EXEC CICS SET PROGRAM command:
      EXEC CICS SET PROGRAM(MYPROG) NEWCOPY
Note:
  • Enterprise server instances will pick up all binaries that have been loaded into the PSOR at start time. If there are a large number of binaries in the PSOR it might take some time to acquire them all. This might result in programs not being immediately available at start up.
  • Binaries can get out of synchronization between enterprise server instances if a new instance joins the PAC after programs have been loaded into the PSOR and before a new copy command is issued. In this case, the new enterprise server instance will use the newer binary version. To synchronize the enterprise server instances in the PAC, issue a new copy command.
RNL
Both JCL and CICS use the RNLs list to determine which resource to ENQ/DEQ require SYSTEMS or SYSTEM scope:
  • JCL ENQ scope is determined by the RNLs definitions only.
  • CICS ENQ scope is derived from ENQMODELs. If scope is set in the ENQMODEL and NQRNL=YES is set in the SIT then the RNL LIST is checked.
TSMODEL
This is used to determine generic properties to apply to a set of TS queues.
TST
Only non recoverable queues can be stored in a SOR. If recoverable queues are required, the file that contains recoverable queues can be stored in a database.
TRANCLASS
  • MaxActive is supported.
  • Priority is NOT supported.
Note: As a result of the additional workload overhead created in the PSOR, Micro Focus recommends that you do not use TRANCLASS in a PAC environment. If possible, application design should be modified to remove any dependency on TRANCLASS.
Parent topic: CICS Support


Lock Support

You can use the caslock command to view a list of locks for enterprise server regions that are members of a PAC. See Lock Processing for more information.

Note: You cannot use caslock to remove locks in a PAC.
Parent topic: Supported Configurations


Configuring a PAC

Details the mandatory and optional configuration requirements for a PAC.
  • PAC Requirements
    Your PAC must conform to the following requirements.
  • Configuring the Mandatory Components of a PAC
    The following provides step-by-step instructions to set up and configure a PAC and its mandatory components.
  • Configuring the Recommended Components of a PAC
    The following provides step-by-step instructions to set up and configure the recommended components of a PAC.
  • Configuration Options
    Provides information on PAC configuration options.
Parent topic: Scale-Out Performance and Availability Clusters
Related reference
Reference


PAC Requirements

Your Performance and Availability Cluster (PAC) must conform to the following requirements:

  • All enterprise server instances in a PAC must be the same bitism.
  • All machines participating in the PAC must have the same product version installed.

    This will avoid using inconsistent program versions between enterprise server instances.

  • All machines participating in the PAC must be using the same version of the same operating system.
    Note: This is enforced when an enterprise server instance in a PAC is cold started, it determines the operating system version for the rest of the PAC members. If any enterprise server instance attempts to warm start and the version does not match it will be rejected.

    This minimizes the chance of a user programs failing to run on some of the enterprise server instances due to differences in OS-related functionality support.

  • Set configuration files and environment variables that are used within a PAC. See Reference chapter for more information.
  • Recommended PAC Configuration
Parent topic: Configuring a PAC


Recommended PAC Configuration

  • Instances
  • System and User Data
  • Load Balancer
  • Data File Editor in a PAC Environment
Parent topic: PAC Requirements


Instances

Micro Focus recommends that the Performance and Availability Cluster (PAC) should consist of at least three regions so that availability is not compromised in the event a region failing or requiring maintenance.

Parent topic: Recommended PAC Configuration


System and User Data

Micro Focus recommends that you store catalog, user catalogs, spool files (spljob, spldsn, splmsg, spljno) and the CICS resource definition file in a datastore.

If VSAM or transactional files are critical to the availability of the system, it is recommended that they are moved to a datastore.

Remember: Any Field Developed Solution (FDS) or scripts that directly access these files need to be modified for the new URI and utilities to load/unload files.
Parent topic: Recommended PAC Configuration


Load Balancer

Micro Focus strongly recommends that you ensure that traffic to your PAC is managed by a load balancer. This will enable you to perform any future product upgrades in a way that minimizes PAC downtime and loss of data.

Parent topic: Recommended PAC Configuration


Data File Editor in a PAC Environment

You must configure a TS model to ensure that Data File Editor correctly honors file locking across all enterprise server regions in a PAC. See PAC and SOR Environment Variables for more information.

Parent topic: Recommended PAC Configuration


Configuring the Mandatory Components of a PAC

The following provides step-by-step instructions to set up and configure a PAC and its mandatory components.

The following instructions are for a Windows environment with PostgreSQL for the RDBMS and Redis for the SOR. The instructions assume familiarity of the mandatory PAC architecture. See Scale-Out Performance and Availability Clusters for more information.

Before you begin

Before you begin the set up and configuration of a PAC and its mandatory components, the following assumptions have been made:

  1. Third-party software. You must install the required prerequisites. See Prerequisites for more information.
  2. Install ODBC drivers 64bit.
  3. ESCWA has been installed and configured. See Enterprise Server Common Web Administration for more information.
  • Configuring the PSOR in ESCWA
  • Creating the PAC and Attaching the PSOR
  • Create the Regions to go in the PAC
  • Installing the PAC Definition into the Regions
  • Configuring Database Connections
  • Creating the MFDBFH Configuration File
  • Specifying the Mandatory Environment Variables
  • Creating the Region Database
  • Creating the Cross-Region Database
  • Cold Starting the First Region in the PAC
  • Warm Starting the Second Region in the PAC
Parent topic: Configuring a PAC
Related reference
Scale-Out Performance and Availability Clusters
Prerequisites
Enterprise Server Common Web Administration


Configuring the PSOR in ESCWA

To configure a PAC you first need to configure a PAC Scale-Out Repository (PSOR) which it will use:

  1. In the top menu bar, click Native.
  2. In the navigation pane, click SORs.
  3. On the Scale-Out Repositories page, click + Add.

    This opens the Scale-Out Repository Configuration dialog box.

  4. In the Name field, type MyPSOR.
  5. You now need to specify the NoSQL database to be used as the SOR.

    In the Type field, select Redis.

  6. In the Description field, type a description to your PSOR. In this case, My PAC SOR.
  7. You need to specify the connection path to the NoSQL database. In this case, we are using Redis on its default port.

    In the Connection Path(s) field, type localhost:6379.

  8. Click Save.
Parent topic: Configuring the Mandatory Components of a PAC


Creating the PAC and Attaching the PSOR

To create the PAC:

  1. In the navigation pane, click Groups > PACs.
  2. On the Performance and Availability Clusters page, click * New.

    This takes you to the New Performance and Availability Cluster page.

  3. In the Name field, type MYPAC.
    Note: The name of the PAC must be in uppercase and no more than 8 characters long.
  4. In the Description field, type My PAC.
  5. In the PAC SOR list, select MyPSOR.
  6. Click Save.
Parent topic: Configuring the Mandatory Components of a PAC


Create the Regions to go in the PAC

To create the two enterprise server regions that are going to be members of your PAC:

  1. In the navigation pane, click Directory Servers > Default.
    Note: Regions are created and hosted under the selected directory server. Micro Focus recommends that the regions in a PAC should reside on different machines to avoid single points of failure.
  2. On the Region and Server List page, click * New.

    This opens the New Region dialog box.

  3. In the Name field, type REGION1.
  4. In the Description field, type PAC Region 1.
  5. Check 64-Bit Working Mode.
    Note: The PAC and MFDBFH can support both 32 or 64-bit working modes, as long as the RDBMS, ODBC, and NoSQL also support it.

    All regions in a PAC must use the same bitism.

  6. Click Save.
  7. Repeat steps 2 through 6 but this time, type REGION2 in step 3 and PAC Region 2 in step 4.
Parent topic: Configuring the Mandatory Components of a PAC


Installing the PAC Definition into the Regions

You now need to install the PAC definition into the two enterprise server regions:

  1. In the navigation pane, click Groups > PACs > MYPAC.
  2. Click Install.

    This opens the Install PAC Definition to Regions dialog box.

  3. Check REGION1@Default.
  4. Check REGION2@Default.
  5. Click Add.
Parent topic: Configuring the Mandatory Components of a PAC


Configuring Database Connections

There are two methods for connecting to the RDBMS; connection strings and using ODBC drivers. See Database Connections for more information.

For this example you will use ODBC drivers to connect to PostgreSQL:

  1. In the search field next to the start icon, type ODBC and click ODBC Data Sources (64-bit).

    This opens the ODBC Data Source Administrator (64-bit) application.

  2. Click System DNS tab.
  3. Click Add.

    This opens the Create New Data Source dialog box.

  4. Click PostgreSQL ODBC Driver(ANSI).
  5. Click Finish.

    This opens the PostgreSQL ANSI ODBC Driver (psqlODBC) Setup dialog box.

  6. Repeat the above steps and complete the details for the three databases listed below:

See the Configuration Requirements chapter for more configuration information.

  • Region Database
  • Cross-Region Database
  • Postgres Database
Parent topic: Configuring the Mandatory Components of a PAC
Related reference
Database Connections
Configuration Requirements


Region Database

Specify the ODBC driver setup for the region database which in this case, acts for the PAC:

  1. In the Data Source field, type MYPAC.
  2. In the Description field, type a description for your region database. In this case, type PAC Database.
  3. In the Database field, type MYPAC.
  4. In the SSL Mode field, select disable.
  5. In the Server field, type the location of the PostgreSQL server. In this case, type localhost.
  6. In the Port field, type the port number to connect to the PostgreSQL server. In this case, it will be the default port, type 5432.
  7. In the User Name field, type postgres.
  8. In the Password field, type the postgres user's password.
  9. Click Save.
Parent topic: Configuring Database Connections


Cross-Region Database

A cross-region database facilitates functionality that is used across more than one enterprise server region.

Specify the ODBC driver setup for the cross-region database:

  1. In the Data Source field, type CrossRegion.
  2. In the Description field, type a description for your cross-region database. In this case, type Cross Region Database.
  3. In the Database field, type $XREGN$.
  4. In the SSL Mode field, select disable.
  5. In the Server field, type the location of the PostgreSQL server. In this case, type localhost.
  6. In the Port field, type the port number to connect to the PostgreSQL server. In this case, it will be the default port, type 5432.
  7. In the User Name field, type postgres.
  8. In the Password field, type the postgres user's password.
  9. Click Save.
Parent topic: Configuring Database Connections


Postgres Database

For MSSQL or PostgreSQL installations, each connection to a database server instance requires a data source connection to either the master database (MSSQL) or the postgres database (PostgreSQL).

Specify the ODBC driver setup for the postgres database:

  1. In the Data Source field, type Database.
  2. In the Description field, type a description for your cross-region database. In this case, type Postgres Database.
  3. In the Database field, type postgres.
  4. In the SSL Mode field, select disable.
  5. In the Server field, type the location of the PostgreSQL server. In this case, type localhost.
  6. In the Port field, type the port number to connect to the PostgreSQL server. In this case, it will be the default port, type 5432.
  7. In the User Name field, type postgres.
  8. In the Password field, type the postgres user's password.
  9. Click Save.
Parent topic: Configuring Database Connections


Creating the MFDBFH Configuration File

To create a PAC MFDBFH configuration file (mfdbfh.cfg):

  1. Create the following folder C:\PAC_Config.
  2. In the folder, create a file called mfdbfh.cfg.
  3. Copy and paste the following content into the file, substituting your postgres password as appropriate:
    <datastores>
     <server name="MYPAC" type="postgresql" access="odbc">
          <dsn name="Database" type="database" dbname="postgres" userid="postgres" password="xxxxxxxx"/>
          <dsn name="MYPAC" type="region.cas" region="MYPAC" feature="all" userid="postgres" password="xxxxxxxx"/>
          <dsn name="CrossRegion" type="crossregion.cas" userid="postgres" password="xxxxxxxx"/>
     </server>
</datastores>
Note: Micro Focus recommends that you create and edit the mfdbfh.cfg file using the dbfhconfig utility. See The dbfhconfig Command Line Utility for more information.
Parent topic: Configuring the Mandatory Components of a PAC


Specifying the Mandatory Environment Variables

For both enterprise server regions, you need to specify the mandatory environment variables:

  1. In the navigation pane, click Directory Servers > Default > REGION1.
  2. In the menu bar, click General > Properties.
  3. In the Configuration Information field, type the following:
    [ES-Environment]
MFDBFH_CONFIG=C:\PAC_Config\mfdbfh.cfg
  4. Click Apply.

Optionally, you might want to specify a directory for the system work files including the console log:

  1. In the System Directory field, type a path to a folder where the system work files can be stored. If the folder does not exist, then create it. In this case, type C:\ESCWA\System\REGION1.
  2. Click Apply.
Note: The system directory path must be different for each of the enterprise server regions in the PAC.
Parent topic: Configuring the Mandatory Components of a PAC


Creating the Region Database

Because database creation can be slow for some RDBMS, Micro Focus recommends that you create the region database before you start the PAC:

  1. At the Enterprise Developer command prompt, type the following:
    dbfhadmin -script -type:region -provider:pg -name:MYPAC -file:create_region_db.sql

    This creates a file containing the PostgreSQL statements to create the region database.

  2. At the Enterprise Developer command prompt, type the following to create the region database:
    dbfhadmin -createdb -provider:pg -type:region -name:MYPAC -file:create_region_db.sql -user:postgres
Note: Ensure that the PostgreSQL server is running and that the folder containing the psql PostgreSQL utility has been added to your PATH environment variable. Typically, you can find this located at C:\Program Files\PostgreSQL\10\bin.

When using the dbfhadmin -createdb -provider:pg -user:postgres ... command, it is assumed that an entry for the postgress user has been created in a password file, located at %APPDATA%\postgresql\pgpass.conf. See Configure Region and Cross-Region Databases in PostgreSQL for more information.

If the PostgreSQL server is running on a remote machine, the first field in the PostgreSQL password file must the hostname, and the dbfhadmin -host option must also be included.

The password file takes the form:

#hostname:port:database:username:password
localhost:5432:postgres:postgres:xxxxxxxxxx
Parent topic: Configuring the Mandatory Components of a PAC
Related reference
Configure Region and Cross-Region Databases in PostgreSQL


Creating the Cross-Region Database

Micro Focus recommends that you create the cross-region database before you start the PAC:

  1. At the Enterprise Developer command prompt, type the following:
    dbfhadmin -script -type:crossregion -provider:pg -name:MYPAC -file:create_crossregion_db.sql

    This creates a file containing the PostgreSQL statements to create the cross-region database.

  2. At the Enterprise Developer command prompt, type the following to create the cross-region database:
    dbfhadmin -createdb -provider:pg -type:crossregion -name:MYPAC -file:create_crossregion_db.sql -user:postgres
    Note: If the PostgreSQL server is running on a remote machine, the first field in the PostgreSQL password file must be hostname, and the dbfhadmin -host option must also be included.
Parent topic: Configuring the Mandatory Components of a PAC


Cold Starting the First Region in the PAC

You can now cold start the first enterprise server region in the PAC:

  1. In the navigation pane, click Directory Servers > Default > REGION1 .
  2. In the menu bar, click General > Control.
  3. Click Start.

    This opens the Region Start Options dialog box.

  4. Check Cold Start.
  5. Check Use current user credentials.
  6. Click Start.
    On a successful start, the following message with be displayed:
     MDS3801I Server started successfully
Parent topic: Configuring the Mandatory Components of a PAC


Warm Starting the Second Region in the PAC

You can now warm start the second enterprise server region in the PAC:

  1. In the navigation pane, click Directory Servers > Default > REGION2 .
  2. In the menu bar, click General > Control.
  3. Click Start.

    This opens the Region Start Options dialog box.

  4. Leave Cold Start unchecked.
  5. Check Use current user credentials.
  6. Click Start.
    On a successful start, the following message with be displayed:
     MDS3801I Server started successfully
  7. Validate that the enterprise server regions have joined the PAC. You will be able to see a list of PAC members under Groups > PACs > MYPAC in the Located members of PAC list.
Parent topic: Configuring the Mandatory Components of a PAC


Configuring the Recommended Components of a PAC

The following instructions are for Windows environments with PostgreSQL for the RDBMS and Redis for the SOR. The instructions assume familiarity of the mandatory PAC architecture and that you have completed the configuration of the mandatory PAC components. See Configuring the Mandatory Components of a PAC for more information.

  • Datastore Database
    The following topic provides information on the ODBC driver setup for the datastore database.
  • Adding Datastore to the MFDBFH Configuration File
    The following provides information on adding a datastore configuration to the mfdbfh.cfg.
  • Create a Datastore and Upload a File for PostgreSQL
    The following provides information on creating the datastore database structure in the RDBMS.
  • Configuring Redis Cluster
  • Configuring the JCL Environment for Database File Handling
    The following topic details the necessary modifications required to your JCL environment to use the Micro Focus Database File Handler (MFDBFH) in the context of a Performance and Availability Cluster (PAC).
  • Configuring CICS Applications for Micro Focus Database File Handling
    The following details the necessary modifications required to your CICS environment to use the Micro Focus Database File Handler (MFDBFH) in the context of a PAC.
  • Configuring CICS resources for Database File Handling
    The following shows you how to configure CICS to use a datastore.
  • Build and configure the XA connector for the RDBMS
    Provides the information required to build the PostgreSQL RM switch module.
  • Configuring TS and TD Queues for SOR Storage
    You can use the TSTDSRUE exit to direct queues to a Scale-Out Repository (SOR) instead of defining SOR models.
Parent topic: Configuring a PAC
Related reference
Configuring the Mandatory Components of a PAC


Datastore Database

Specify the ODBC driver setup for the datastore database which in this case, will store your VSAM files:

  1. In the search field next to the start icon, type ODBC and click ODBC Data Sources (64-bit).

    This opens the ODBC Data Source Administrator (64-bit) application.

  2. Click System DNS tab.
  3. Click Add.

    This opens the Create New Data Source dialog box.

  4. Click PostgreSQL ODBC Driver(ANSI).
  5. Click Finish.

    This opens the PostgreSQL ANSI ODBC Driver (psqlODBC) Setup dialog box.

  6. In the Data Source field, type VSAM.
  7. In the Description field, type a description for your datastore database. In this case, type VSAM Datastore.
  8. In the Database field, type VSAM.
  9. In the SSL Mode field, select disable.
  10. In the Server field, type the location of the PostgreSQL server. In this case, type localhost.
  11. In the Port field, type the port number to connect to the PostgreSQL server. In this case, it will be the default port, type 5432.
  12. In the User Name field, type postgres.
  13. In the Password field, type the postgres user's password.
  14. Click Save.

See the Configuration Requirements chapter for more configuration information.

Parent topic: Configuring the Recommended Components of a PAC
Related reference
Configuration Requirements


Adding Datastore to the MFDBFH Configuration File

Add the following entry in bold to your mfdbfh.cfg:

<datastores>
    <server name="MYPAC" type="postgresql" access="odbc">
        <dsn name="Database" type="database" dbname="postgres" userid="postgres" password="xxxxxxxx"/>
        <dsn name="MYPAC" type="region.cas" region="MYPAC" feature="all" userid="postgres" password="xxxxxxxx"/>
        <dsn name="CrossRegion" type="crossregion.cas" userid="postgres" password="xxxxxxxx"/>
        <dsn name="VSAM" type="datastore" dsname="VSAM" userid="postgres" password="xxxxxxxx"/>
    </server>
</datastores>
Note: The dsn name attribute value needs to match the data source name. This is how the VSAM database is located.

Micro Focus recommends that you create and edit the mfdbfh.cfg file using the dbfhconfig utility. See The dbfhconfig Command Line Utility for more information.

See the Configuration Requirements chapter for more configuration information.

Parent topic: Configuring the Recommended Components of a PAC
Related reference
Configuration Requirements


Create a Datastore and Upload a File for PostgreSQL

The following steps are required to create the datastore database structure in the RDBMS:

  1. At the Enterprise Developer command prompt, specify the MFDBFH_CONFIG to point at your mfdbfh.cfg file:
    set MFDBFH_CONFIG=C:\path\to\config\mfdbfh.cfg
  2. At the Enterprise Developer command prompt, type the following:
    dbfhdeploy create sql://MYPAC/VSAM
    Note: This URL needs to match the server instance name in mfdbfh.cfg.

See Upload Files to a PostgreSQL Datastore and the Configuration Requirements chapter for more configuration information.

Parent topic: Configuring the Recommended Components of a PAC
Related reference
Upload Files to a PostgreSQL Datastore
Configuration Requirements


Configuring Redis Cluster

Note: If you are using Enterprise Redis, this needs to be configured to use a custom hashing policy, with the following regular expression as rule one:
^[^{]*?\{(?<tag>[^}]+?)\}.*$
See the Database clustering page of the Redis Enterprise documentation for more information on the custom hashing policy.

Enterprise Server supports Redis Cluster as a Scale-Out Repository (SOR). Redis Cluster is a distributed implementation of Redis with performance, scalability, and availability as part of its design. You can configure communication with Redis Cluster by setting the environment variable MFREDIS_CONFIG to point to a configuration file. This configuration file can contain the following variables:

RD_LUA_LOG
This variable enables logging of Lua scripts on the Redis server.
Note: The Redis server must be started with --log-level set to warning as a minimum.
ON
Enables logging.
OFF
Disables logging.

The default value is OFF.

RD_RETRY_INTERVAL
Specifies how long, in milliseconds, the Redis client should wait before reattempting to connect and perform the last failed request.

The default value is 2000 (2 seconds).

RD_RETRY_ATTEMPTS
Specify the number of attempts the Redis client should try to perform the last failed request.

The default value is 1.

Parent topic: Configuring the Recommended Components of a PAC


Configuring the JCL Environment for Database File Handling

The following topic details the necessary modifications required to your JCL environment to use the Micro Focus Database File Handler (MFDBFH) in the context of a Performance and Availability Cluster (PAC).

You can configure your JCL environment to use the native database file handler, where catalog.dat and catalog files can be stored in a database.

This requires setting a number of environment variables within the JES region, and then configuring JES Mainframe System Support to use the datastore(s) you configured. Use the dbfhdeploy to move the catalog files from disk to the database.

You need to set the following environment variables in the Configuration Information field, for each of the enterprise server regions in the PAC:

Variable setting | Description
ES_DB_FH=Y | Enables the Micro Focus Database File Handler
MFDBFH_CONFIG=<path-filename-config-file> | Locates the configuration file containing the list of data sources and their database types
MFDBFH_SCRIPT_DIR=<path-to-scripts> | Locates the stored procedures required for Enterprise Server to interact with a database

If you are configuring a JCL environment from scratch, that is, the catalog is currently empty, then the required catalog file and specified folder structure is created on completion of the first job that is run.

The following example configures an enterprise server region in Enterprise Server Common Web Administration (ESCWA). It creates a catalog.dat file, if one does not already exist, within the CAT folder in the PGJCLCAT datastore:

  1. In the menu bar, click Native.
  2. In the navigation pane, expand Directory Servers.
  3. Click the enterprise server region you want to configure.
  4. Click General > Properties.
  5. In the Regions Feature group, check MSS Enabled.
  6. Check JES Enabled.
  7. Click Apply.
  8. Click JES > Configuration.
  9. In the System Catalog field, type the full name (including the path) of your system catalog file, such as sql://MYPAC/VSAM/catalog.dat?folder=/CAT.
  10. In the Default Allocated Dataset Location field, type the default directory to be used for the creation of new data sets, such as sql://MYPAC/VSAM?type=folder;folder=/CAT/data.

Repeat steps 3 through 10 for each enterprise server region in the PAC.

The Default Allocated Dataset Location field, specifies the creation of a sub-folder from the location of the catalog file for any cataloged data sets. The two options specified form the values of the MFSYSCAT and MFALLOC_LOC environment variables respectively.

If you are moving an existing catalog, the method of data set storage will determine which files you move to the database. If the data sets are stored relative to the catalog, you should move catalog.dat and all its data sets from disk to the same datastore. You can use the dbfhdeploy command line utility to upload the files and create the required folder structure to ensure that the relative file locations are maintained; that way, no changes to the catalog are necessary.

If an existing catalog contains absolute paths to its data sets, or the default data set allocation method (for example, when using ES_ALLOC_OVERRIDE) is different to or not relative to the catalog folder, you can either keep the data sets stored on disk, or you can move data sets to the database. If you do move a data set cataloged with an absolute path, you are required to re-catalog the entry, updating it with its new physical file location within the database.

Micro Focus recommends that both the catalog.dat and all its data sets reside in the same datastore.

You do not need to make any code changes to your batch application's source code to use files within a datastore.

If the enterprise server region running your JES environment terminates abnormally whilst any data files are open, Enterprise Server attempts to recover the files automatically. If you continue to receive errors accessing files (for example, file locked statuses), run the dbfhadmin command line utility to recover the files.

Parent topic: Configuring the Recommended Components of a PAC


Configuring CICS Applications for Micro Focus Database File Handling

The following details the necessary modifications required to your CICS environment to use the Micro Focus Database File Handler (MFDBFH) in the context of a Performance and Availability Cluster (PAC).

To move your existing data files from disk to a database, you need to use the dbfhdeploy command line utility to deploy them to a datastore. Once deployed, you need to configure your CICS environment to locate them within the datastore.

Whether you are creating a new resource or updating an existing one, the database file handling-specific changes are the same: you need to update the file path within the FCT that details the file, to point at the new datastore location. The following example configures an enterprise server region in Enterprise Server Common Web Administration (ESCWA) is using the ACCTFIL file, which is stored in the VSAM folder within the CICS datastore:

  1. In the menu bar, click Native.
  2. In the navigation pane, expand Directory Servers.
  3. Click the enterprise server region you want to configure.
  4. Click CICS > Resources.
  5. Select the By Type.
  6. Expand FCT.
  7. Click ACCTFIL.
  8. In the File Path field, type the path to the datastore, for example, sql://MYPAC/MYPAC/?type=folder;folder=/VSAM
  9. Click Install.

See the Category parameter in the The dbfhdeploy Command Line Utility for more information on the notation used in the File Path field.

As the data is transactional, ensure that the Backward Recovery field is checked. This indicates that the file is a protected resource, changes to which can be backed out. To support this you must configure an XA resource within the enterprise server region that points to the datastore in which the file is stored. See Create an XA Resource in the Configuring Datastores chapter that correspond to the database type you are using.

Note: You do not need to make any code changes to your CICS applications' source code to use files within a datastore.

If the enterprise server region running your CICS environment terminates abnormally whilst any data files are open, Enterprise Server attempts to recover the files automatically. If you continue to receive errors accessing files, for example, file locked statuses, run the dbfhadmin command line utility to recover the files.

Parent topic: Configuring the Recommended Components of a PAC
Related reference
The dbfhdeploy Command Line Utility
Create an XA Resource


Configuring CICS resources for Database File Handling

The following steps sets the CICS Resource Definition File Path field, so that you can use a datastore:

  1. In the menu bar, click Native.
  2. In the navigation pane, expand Directory Servers.
  3. Click the enterprise server region you want to configure.
  4. Click CICS > Resources.
  5. In the Resources Definition File Path field, type the full path of the resource definition file for this Enterprise Server. For example sql://MYPAC/VSAM/RDEF?type=folder

If a CICS resource definition file already exists and you want to use this with the Performance and Availability Cluster (PAC) then import the file to the database using dbfhdeploy and the path specified in the CICS Resource Definition File Path. For example:

dbfhdeploy -quiet data add <PATH>\dfhdrdat sql://MYPAC/VSAM/dfhdrdat?folder=/RDEF
Parent topic: Configuring the Recommended Components of a PAC


Build and configure the XA connector for the RDBMS

The PostgreSQL module provides two-phase commit support using PostgreSQL-provided SQL calls, and ensures that any database connections made using this switch module all participate in a single XA transaction.

PostgreSQL Server configuration for XA

Important: Before you can use the PostgreSQL RM Switch Module, you must configure the PostgreSQL Server by changing the value of the max_prepared_transactions property from its default value of 0 (zero) to a value greater than 0. After making this change, you must restart the postgresql server before proceeding. For additional details about the max_prepared_transactions configuration property, see your PostgreSQL product documentation.
Source Code
The PostgreSQL RM switch module COBOL source file, ESPGSQLXA.CBL is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
Note: If you prefer to supply user credentials programmatically rather than in the xa_open string, instructions for doing so are provided in the COBOL source file in the Customization section.
Build Requirements
To build the PostgreSQL RM switch module, you must have the Windows Software Development Kit (SDK) installed for your version of Windows.

Before building this switch module, ensure that your LIB environment variable contains the path to the odbc32.lib file, located in a subdirectory under your Windows SDK LIB directory.

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 pg
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 pg
Build Output
The build process produces two binary switch module files from the ESPGSQLXA.CBL COBOL source file:
Binary File | Type
ESPGSQLXA_S.DLL | static
ESPGSQLXA.DLL | dynamic

You can register an RM switch module with Enterprise Server dynamically, or register it statically depending on which binary file you use. Micro Focus recommends 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 PostgreSQL RM switch module, including the xa_open string definition, see PostgreSQL xa_open string.

Creating an XA Resource

Your enterprise server region requires an XA resource for each datastore that contains one or more transactional files. If the database containing the datastore is also used by other COBOL applications, additional XA resources are required. Refer to Working with Multiple XARs for details on how to handle such situations.

  1. Open the ESCWA Administration page, and then select the enterprise server region that references the transactional data file from the left pane.
  2. In the right pane, click General > XA Resources.
  3. Click NEW.
  4. Specify the following XAR details:
    Option | Description
    ID | Unique ID for the XAR.
    Name | Unique name for the XAR.
    Module | Specify the location of the RM switch module executable file (.dll). This is database specific: esmssql.dll for MSSQL and Azure SQL, ESPGSQLXA.dll for PostgreSQL, and ESDB2XA.dll for Db2. Refer to Building RM Switch Modules for more information.
    Open string DSN=<datastore-dsn>

    where <datastore-dsn> is the ODBC data source name of the datastore you are configuring.

    Note: These are only the mandatory options required, with the addition of USRPASS=userid.password if you are using a PostgreSQL database. You can also specify further options as required, as detailed in To Define an XA Resource (XAR) for an Enterprise Server Region.
  5. Click SAVE.

    The XA resource should be effective immediately.

See Configuration Requirements for more configuration information.

Parent topic: Configuring the Recommended Components of a PAC
Related tasks
To define an XA resource (XAR) for an enterprise server region
Related reference
Configuration Requirements
Related information
LIB


Configuring TS and TD Queues for SOR Storage

The TSTDSRUE exit is called at queue access time with the following information:

  • Queue name
  • Queue type (TS|TD)
  • Scale-Out Repository (SOR) name
Note: The SOR name will be in upper case.

The exit needs to return whether or not to direct the queue to the input SOR:

0
Do not send to the SOR.
1
Send to the SOR.

A sample exit is provided with Enterprise Developer and can be found in the following location src\enterpriseserver\exits\TSTDSRUE.CBL.

The compiled program should be placed in the bin and\or bin64.

If this exit is used, any SOR models which have been defined will be ignored.

Note: If a TS or TD queue name contains x'00' and that queue is to be written to a SOR, the name will be truncated from (and including) the x'00'. For example, x'AABB00CCDD' would be written with the name x'AABB'.

You must configure a TS model to ensure that Data File Editor correctly honors file locking across all enterprise server regions in a PAC.

Parent topic: Configuring the Recommended Components of a PAC


Configuration Options

The following environment variable can be specified on the command line or in the Configuration Information field, for the regions in a Performance and Availability Cluster (PAC):

Stops the messages in the console.log from being stored in the PAC Scale-out Repository (PSOR) CasPacLog.
Syntax
ES_PAC_NO_GLOBAL_LOG={Y|N}
Parameters
Y
Prevents console.log messages for PAC member regions from being stored in the PSOR.
N
console.log messages for PAC member regions are stored in the PSOR.
Default
ES_PAC_NO_GLOBAL_LOG=N
Comments
You can set ES_PAC_NO_GLOBAL_LOG=Y to improve performance if you are not monitoring messages from the PSOR.

Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.

Sets the number of attempts to access records in the PSOR before stopping.
Syntax
ES_SOR_RETRIES=integer
Parameter
integer
An integer value ranging from 1 through 1000 that represents the number of attempts to access records in the PSOR before stopping.
Default
ES_SOR_RETRIES=10
Comments
Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
Parent topic: Configuring a PAC
Related information
ES_PAC_NO_GLOBAL_LOG
ES_SOR_RETRIES


Administering a PAC

The following details tasks, best practices, and utilities to help administer your PAC.
  • PAC Best Practices
  • General Administration
  • Performing a Product Upgrade to a PAC Environment
  • SQL Administration
  • JCL Administration
  • CICS Administration
Parent topic: Scale-Out Performance and Availability Clusters


PAC Best Practices

Micro Focus recommends you use the following best practice guidelines when configuring and using Performance and Availability Cluster (PAC)s:

  • Ensure that traffic to your PAC is managed by a load balancer. This will enable you to perform any future product upgrades in a way that minimizes PAC downtime and loss of data.
  • TSQs and TDQs should be stored in their own SOR and not in the PSOR. This is for performance reasons and to facilitate the product upgrade process.
  • Each enterprise server instance requires its own resource definition file (dfhdrdat). Only a subset of resources are stored in the PAC Scale-Out Repository (PSOR). An enterprise server instance still require resources that are not available from the PSOR. The same dfhdrdat file should be used in every enterprise server instance in the PAC.

    Micro Focus recommends that you store the dfhdrdat file in your DATASTORE so that it is shared by all the enterprise server region in your PAC. Instead of pointing to a local folder location you will point to an sql:// location.

  • The same SIT and startup list should be used for every enterprise server region in the PAC.
    Note: SIT information should be the same, except for the SYSID if it is used for CICS inter-system communication (ISC).

    The APPLID should also be unique as this becomes the nodes netname, and the SYSID which is used internally to uniquely identify the connected systems within the other enterprise server regions.

  • Use the same program and file paths across a PAC.
  • Only use the caspac command to modify entries in the Scale-Out Repository (SOR). Removing entries manually might lead to unexpected behavior.
  • Prior to cold starting a PAC on the command line, ensure that you have run the caspac command to initialize the PAC.
  • Do not use Redis to permanently store all applications. Micro Focus recommends that you only store applications that are to be modified whilst a PAC is active and those changes need to be deployed throughout the PAC.
Parent topic: Administering a PAC


General Administration

  • Starting a PAC using ESCWA
  • Starting a PAC using the Command Line
  • Providing Credentials for your Scale-Out Repository using Secrets
  • Removing a Region from a PAC
  • Shutting Down an Unresponsive Region
  • Using a PAC with Autoscaling
Parent topic: Administering a PAC
Related reference
caspac


Starting a PAC using ESCWA

A Performance and Availability Cluster (PAC) cannot be started with a single action. All enterprise server regions within the PAC need to be started individually. The first region to be started must be cold started:

  1. In the navigation pane, click Directory Servers > DirectoryServer > FirstRegion .
  2. In the menu bar, click General > Control.
  3. Click Start.

    This opens the Region Start Options dialog box.

  4. Check Cold Start.
  5. Check Use current user credentials.
  6. Click Start.
    On a successful start, the following message with be displayed:
     MDS3801I Server started successfully

Subsequent regions in the PAC can be warm started:

  1. In the navigation pane, click Directory Servers > DirectoryServer > SubsequentRegion .
  2. In the menu bar, click General > Control.
  3. Click Start.

    This opens the Region Start Options dialog box.

  4. Leave Cold Start uncheck.
  5. Check Use current user credentials.
  6. Click Start.
    On a successful start, the following message is displayed:
     MDS3801I Server started successfully

Repeat the warm start steps for any remaining regions in the PAC.

Parent topic: General Administration


Starting a PAC using the Command Line

You can start a Performance and Availability Cluster (PAC) using the command line utility casstart. You can use it to script the actions to automate starting a PAC.

Micro Focus recommends that you only remove items from a Scale-Out Repository (SOR) using the caspac utility. See caspac for more information.

In a PAC, you must use either /s:c (cold start) or /s:w (warm start) options when starting an instance. These options will override whatever the SIT settings are for TS or TD. Using the /s:c option will result in all queues being removed along with other data. Using the /s:w option will leave existing queues intact.

Note: If you omit the /s option, then the SIT settings for TS and TD are applied.

The process of cold starting a PAC will remove all existing data from each SOR in the PAC.

To start a PAC, perform the following steps:

  1. Ensure that all regions that are part of the PAC are stopped.
  2. Ensure that a Redis instance is started for each SOR that is referenced by the PAC. Only one Redis instance for the PAC Scale-Out Repository (PSOR) and one for each additional SOR models.
  3. Cold start an enterprise server instance that is in the PAC1 by specifying /s:c on the casstart command:
    casstart /rregionName /s:c
    Note: If you are unable to perform a cold start using casstart then you might need to use the caspac utility with the InitPac option. See caspac for more information.
  4. You can start additional regions that are part of the PAC by performing a warm start:
    casstart /rregionName /s:w

If an enterprise server instance is cold started and another instance is already running in the same PAC, then the start will be changed to a warm start. In this case, the following message will be written:

CASSI9027W Region initializing in Warm startup mode because PAC <PAC_NAME> is already active.

If this message occurs but there are no active regions in the PAC, then caspac should be used with the -aInitPac option to initialize the PAC.

A warm start leaves all data in the SOR intact. A warm start is the default start mode. You must specify /s:w in the casstart command to override SIT settings for TS and TD.

An enterprise server instance that has been cold started will read the CICS resources from its local resource definition file. At resource installation time, PSOR-supported resources, will be placed in the PSOR. See Configuration Restrictions for more information. Regions that are part of the PAC and are subsequently warm started will read those resources from the PSOR.

Resources that are not yet supported in the PSOR will be read from the local resource definition.

If an enterprise server instance is warm started after the PAC has been initialized and there are no other instances in the PAC running, then it will automatically cold start.

1 This will remove all TSQs and TDQs from all SORs in the PAC; caspac only removes those in the PSOR.

Parent topic: General Administration
Related reference
caspac


Providing Credentials for your Scale-Out Repository using Secrets

If your Scale-Out Repository (SOR) is configured to request credentials when being connected to, then you can store the credentials using the vault facility.

Use the mfsecretsadmin utility to write the SOR's credential to the vault. Give the credential a name that identifies it for the SOR it relates to. The name must conform to the following standard:

microfocus/CAS/SOR-sorName-Pass

where:

microfocus/CAS/SOR-
Identifying prefix, specifies that this secret is used by a SOR.
sorName
This is the name of the SOR specified in the ES_SCALE_OUT_REPOS environment variable.
Note: The sorName must be specified in uppercase. The sorName can be specified in the SOR Configuration field, in the region's General Properties page of the Enterprise Server Common Web Administration interface.
-Pass
Identifying suffix, specifies that this is a password or credential.

See The mfsecretsadmin Utility for more information.

Example

For example, if you have the following configuration for your ES_SCALE_OUT_REPOS environment variable:

ES_SCALE_OUT_REPOS_1=RedisLocal=redis,127.0.0.1:12345##TMP#TD=AC*:TD*:RTDQ:SOR1#TS=A*:B+A:NRQSOR1
You would create an entry in your vault using the following mfsecretsadmin command:
mfsecretsadmin write microfocus/CAS/SOR-RedisLocal-Pass password
See Vault Facility for more information.
Parent topic: General Administration
Related reference
The mfsecretsadmin Utility
Vault Facility


Removing a Region from a PAC

You can temporarily remove a region from a Performance and Availability Cluster (PAC) by stopping the region.

To remove a region from a PAC:

  1. Remove the region from your load balancer, so there is no more work being sent to the region.
  2. Stop the region, the region will complete all transactions and/or batches currently being processed, and then the region will shutdown.

Micro Focus recommends that you use Enterprise Server Common Web Administration (ESCWA) when stopping and starting a region. Alternatively, you can use the casstop or casstart utilities.

The region will automatically rejoin the PAC when the region is restarted.

Parent topic: General Administration


Shutting Down an Unresponsive Region

If using either ESCWA or casstop fail to shut down a region, then you can kill the casmgr process. This will enable cascd to clean all connections and recover files in mfdbfh.

Parent topic: General Administration


Using a PAC with Autoscaling

When using a PAC within a container, you should use autoscaling to ensure that scaling down your application's resources does not result in the unexpected termination of Enterprise Server work, particularly in the case of long-running batch jobs. By using autoscaling you can prevent new work from being allocated to a PAC, and also guarantee that the PAC and its member regions will remain running until it has completed its current workload. The auto-scaling rules that you specify should contain a grace period during which this shutdown procedure will be allowed to run before the host container is terminated. In the case where a PAC is running batch jobs, this grace period should be at least the expected duration of time for the batch job to complete.

Parent topic: General Administration


Performing a Product Upgrade to a PAC Environment

Introduction

A PAC environment is typically required to provide continuous uninterrupted operation. Performing a product upgrade, maintenance, or other system upgrades can present a challenge for PAC management.

This document describes best practice you should adopt when performing a product upgrade to your PAC environment.

Characteristics of a PAC environment

A Performance and Availability Cluster (PAC) environment, regardless of its use to support CICS or JES services, has some characteristics that must be understood before attempting any upgrade to the PAC.

A PAC environment can be described as two or more enterprise server regions configured in a scale-out architecture and potentially distributed over multiple machines working together as a single logical entity.

Each enterprise server region accesses information from shared resources that manage locking and synchronization of the information.

The shared PAC resources are:

  • A PAC region database accessed by the Micro Focus Database File Handler (MFDBFH). This database holds locks and shares information used by the enterprise server regions in the PAC.
  • A cross-region database accessed by the Micro Focus Database File Handler (MFDBFH). The cross-region database holds resource locks that can be used to control resource access across enterprise server regions in the PAC.
  • A PAC Scale-Out Repository (PSOR) stored in a NoSQL database, typically Redis.
  • Optional, one of more additional Scale-Out Repositories (SORs) for storing TSQs and TDQs.
    Important: For performance reasons and to facilitate upgrades, TSQs and TDQs should not be stored in the PSOR.
  • One or more datastore databases. Datastores are used to store an application's VSAM data files, providing transactional support. Datastores are also used to store files that do not require recovery services, such as spool files, loadlibs, and configuration files.

It is when one or more of these shared components change or when record structures stored in some of these components change that risk is introduced when performing an update or patch process.

Upgrade types

Any update or patch applied to the system can potentially change its behavior. It is important to identify the changes being introduced by the upgrade or patch and determine the best way to apply the changes that mitigates risk and maintains PAC availability. Micro Focus strongly recommends that you review the Patch Update ReadMe prior to planning its installation.

There are three possible upgrade types, their suitability depends on the compatibility of the components being changed:

  1. If the upgrade or patch changes shared PAC resources but are compatible. In this case, the coexistence of different versions in the same PAC is possible and you can follow the steps described in the Compatible Upgrade Process topic.
  2. If the upgrade or patch impact or change one or more of the current shared PAC resources but they are incompatible. For example, changes to the PAC region database, changes to the PSOR layout, or changes to other PAC mechanisms that are incompatible with the existing PAC. In this case, you can follow the steps described in the Incompatible Upgrade Process topic.
  3. If the upgrade requires you to change the fundamental infrastructure of the PAC. For example, the existing RDBMS or SOR vendor must be changed then you will need to create a new PAC. In this case, you can follow the steps described in Configuring a PAC chapter. You can then migrate the data from your existing PAC into the new PAC. However, the migration of data might require downtime or the loss of some data.

If there is ever any question as to which approach should be taken then the Incompatible Upgrade Process should be followed.

When an in-place upgrade is not possible

You can contact OpenText Support for Micro Focus Products for assistance with an in-place upgrade of a PAC. In the unlikely event that an in-place upgrade is not possible the Patch Update ReadMe will provide information on how best to proceed. In-place upgrades might not be possible when moving to a new major product version.

Pre-production testing

Micro Focus strongly recommends that you test the update and update process in a staging environment before deployment to production. The staging environment should mirror your production environment as closely as possible while remaining separate. In addition to being able to replicate the update process, a pre-production environment also enables application code to be recompiled and tested. Pre-production testing gives you the opportunity to encounter and resolve any potential issues before they can impact your production system.

Upgrading PAC machines in groups

Both the Compatible and Incompatible PAC upgrade processes aim to maintain PAC availability during the upgrade steps. However, each enterprise server region must be stopped at some point, to be upgraded. It is inevitable that some connected or connecting clients will be impacted. The extent of the impact depends on the nature of the client sessions and when each enterprise server is stopped.

Consider a client that connects to a TN3270 listener and expects to maintain a long-lived connection while it submits transactions over a long period of time. The client will be disconnected from the enterprise server region when it is stopped to be upgraded. The client will have to reconnect and will likely connect to a different enterprise server region in the PAC. If that new enterprise server region is next to be stopped and upgraded, the same client might be disconnected multiple times. This situation is undesirable for any connecting client.

The impact can be minimized by upgrading the machines in groups, rather than one at a time. Provided that client traffic can be handled temporarily by a proportion of the enterprise server regions, Micro Focus recommends that the other instances are shut down, upgraded, and restarted in groups. This approach can then be repeated until all of the regions have been upgraded.

Managing client connections during a PAC upgrade

Before a running enterprise server region is stopped to be upgraded, Micro Focus recommends you first prevent new client connections, and if possible, enable existing client connections to complete. In addition, any scheduled work, such as Micro Focus Batch Scheduler Integration (MFBSI), cassub, and MQ triggered transactions should be suspended or rescheduled to occur after the upgrade process has been completed.

When a user changes the state of an enterprise server listener to "Disabled" (or "Stopped"), the listener will stop listening on the designated port number. Most load balancers can be configured to recognize this and automatically update their pool of live connection endpoints, to prevent new client connections while maintaining any existing connections. Ideally, the load balancer also provides the ability to manually manage the pool of live connection endpoints. This has the added benefit that the listeners can be manually re-enabled for testing prior to enabling traffic again from the load balancer. Setting the listener state to "Disabled", rather than "Stopped", ensures that the listener will not start automatically after the enterprise server region is restarted. Changing the state from "Disabled" to "Started" will enable new client connections again.
Note: This will only work if there are no existing client connections.

Micro Focus recommends that preparations for a PAC upgrade include verifying the impact of disabling the enterprise server listeners on a load balancer sitting in front of the PAC. Any existing long-lived client connections (for example, to a TN3270 listener) will be unavoidably terminated when the enterprise server region is stopped and errors are reported in the communications log. The list of active client connections can be viewed using Enterprise Server Common Web Administration (ESCWA), in the navigation tab click the required enterprise server region and then click MONITOR > Client to view the region's CLIENT LIST table.

Backing up the Micro Focus Directory Server (MFDS) configurations

Micro Focus recommends that you backup each enterprise server instance that is running a PAC if it is on a version of Enterprise Developer earlier than 6.0.

Backing up your enterprise server instance is not essential for Enterprise Developer 6.0 and later. This is because the Patch Update installer will automatically preserve the MFDS configuration.

See To Export the Repository for more information on how to back up the MFDS configuration. Select the option to export all the server definitions and all the related security configuration information. See To Import a Repository for more information on how to restore the configuration backup.

Backing up the Enterprise Server Common Web Administration (ESCWA) configuration

Micro Focus recommends using ESCWA to configure and administer your PAC. An instance of ESCWA running on a single host is typically chosen to manage the PAC and store the PAC and SOR configuration. All of the enterprise server instances in the PAC are then managed from this single ESCWA instance. In order to do this, the remote Directory Server under which each enterprise server region runs must be added to the ESCWA configuration. See Enterprise Server Common Web Administration for more information.

Micro Focus recommends that your ESCWA instance runs on a machine that is not part of your PAC. This configuration simplifies the PAC product upgrade process and means that the version of the product running ESCWA does not need to be same version as the machines running the enterprise server regions that make up the PAC.

Note: For product versions prior to Enterprise Developer 6.0, the ESCWA configuration is stored in the application configuration file commonwebadmin.json. The application configuration file is located in C:\ProgramData\Micro Focus\Enterprise Developer\ESCWA. This file must be manually backed up and restored.

The compatible and incompatible PAC upgrade processes

To illustrate both the compatible and incompatible PAC update processes, we can consider the following PAC configuration. A PAC with the named MYPAC, which has a PSOR named MYPSOR. The PAC consists of two enterprise server regions named Region 1 and Region 2. The enterprise server regions run on separate machines named Host 1 and Host 2:

In this example, the PAC consists of two enterprise server instances running on two separate machines. If the PAC consists of more than two enterprise server instance, Micro Focus strongly recommends that you consider upgrading the machines in groups rather than one at a time. Group updates minimizes the impact on connecting clients. See Upgrading PAC machines in groups for more information.

In this case, we can assume that the Enterprise Server Common Web Administration (ESCWA) service is running on a separate machine and does not need to be backed up and restored as part of this example.

We also assume that the Directory Server configuration for each enterprise server machine has already been backed up. This is not required for Enterprise Developer 6.0 and later, as the Patch Update installer will automatically preserve the MFDS configuration.

  • Compatible Upgrade Process
  • Incompatible Upgrade Process
Parent topic: Administering a PAC


Compatible Upgrade Process

Important: Ensure that you have read the corresponding Patch Update ReadMe to confirm that the compatible upgrade process is appropriate.

For the compatible upgrade process, enterprise server regions running with different product versions can temporarily coexist while the update is being applied. This avoids the need to completely stop the PAC from running.

  1. Stop new client connections to Region 1. This can be done by disabling the enterprise server listeners and/or modifying the load balancer configuration. See Managing client connections during a PAC upgrade for more information.
  2. Stop Region 1. Use ESCWA or casstop to gracefully stop enterprise server region. This will terminate any existing client connections. You can check active client connections on the CLIENT LIST page. In the navigation tab, click the required enterprise server region and then click MONITOR > Client.
    Note: It can take some time to stop an enterprise server region which has active client connections. This can result in a Not Responding message being displayed before it is reported as Stopped. Stopping an enterprise server region with active client connections might result in errors in the communications log.
  3. Apply the product upgrade to the Region 1 machine.
  4. Restore the Micro Focus Directory Server (MFDS) configuration backup to the Region 1 machine.
    Note: This is not required for Enterprise Developer 6.0 and later, as the Patch Update installer will automatically preserve the MFDS configuration.
  5. Start Region 1 in warm mode. In the ESCWA Region Start Options dialog box, uncheck Cold Start before starting the enterprise server region. Once started, ensure that the enterprise server region joins the PAC. You will see the following or similar message in the console log:
    CASSI1432I Joining PAC MYPAC. 14:46:19

    Record layout compatibility checks are preformed and if incompatible records are found the enterprise server region is unable to start. The following console message is displayed:

    PA2105S Region cannot be started because an incompatible record <record type> was found in the PSOR

    Where <record type> can be TST, CSA, DCT, PCT, FCT and so on.

    Compatible Upgrade Process - Region 1 Upgrade
  6. Enable client connections for Region 1 via the load balancer and/or the enterprise server listeners. See Managing client connections during a PAC upgrade for more information.
    Note: You might not want to perform this step at this point if you are upgrading the enterprise server regions in groups. This is to minimize disruption to connecting clients.
  7. Repeat steps 1 through 6 for Region 2.

    Both enterprise server regions have now been upgraded.

    Compatible Upgrade Process - Region 2 Upgrade
Note: At this point, all enterprise server regions in the PAC are upgraded and running. However, the PAC is running with the environment variable ES_PAC_MIN_COMP_CHECK=YES which reduces the checking of version levels being used. This is not an ideal long-term state for the PAC. If this is the case, you might want to upgrade using steps specified in the Incompatible Upgrade Process topic.
Parent topic: Performing a Product Upgrade to a PAC Environment


Incompatible Upgrade Process

The Patch Update ReadMe publication will indicate if you need to use the incompatible upgrade process. You will perform the upgrade process on each enterprise server region as they are moved to the new PAC. During this process both PACs will share the same region and cross-region databases and datastores.

Note: TSQs and TDQs must be stored in separate SORs and not in the PSOR.

In this example, the enterprise server regions are members of a PAC named MyPAC. There are two enterprise server regions called Region 1 and Region 2 that are hosted on separate machines, host 1 and host 2 respectively:

  1. Stop new client connections to Region 1. This can be performed by disabling the enterprise server listeners and/or by modifying the load balancer configuration. See Managing client connections during a PAC upgrade for more information.
  2. Stop Region 1 on host 1. Use ESCWA or casstop -r<region_name> to gracefully stop an enterprise server region. This will terminate any existing client connections. You can check for active client connections in ESCWA on the Client List page. In the navigation tab, click the required enterprise server region and then click Monitor > Clients.
  3. Apply the update or patch to host 1.
  4. Restore the Micro Focus Directory Server (MFDS) configuration backup to host 1.
    Note: This is not required for Enterprise Developer 6.0 and later, as the Patch Update installer will automatically preserve the MFDS configuration.
  5. Check the compatibility of the updated enterprise server instance version on host 1 against the PSOR. From an Enterprise Server command prompt on host 1, type:
    caspac -aCheckCompat=MyPAC -sredis,<psor_host_name>:<port>
    If the output indicates that the new updated product is incompatible with the current version then continue with the steps for an incompatible upgrade listed below. Otherwise, refer to the Compatible Upgrade Process topic.
  6. Start Region 1 using the new updated product in upgrade mode. In the ESCWA Region Start Options dialog box, check Upgrade before starting the enterprise server region. Alternatively, from a an Enterprise Server command prompt, type:
    casstart /r<region_name> /s:u
    Starting the enterprise server region will initialize the new PAC and create new stores in the PSOR that are prefixed with the PAC name and the new version number. At this point, the new PAC is running in parallel with the existing PAC. However, the enterprise server region is not enabled to receive client connections and, because the PAC is in upgrade mode, batch jobs will not be executed.
    Incompatible Upgrade Process - Upgraded Region 1
  7. If your PAC contains multiple enterprise server region then you will need to perform a warm start for the remaining enterprise server regions that reside on host 1. This can be performed from the ESCWA Region Start Options dialog box by checking Warm prior to starting. Alternatively, from an Enterprise Server command prompt, type:
    casstart /r<region_name> /s:w
  8. Repeat steps 1 through 4 for host 2.
  9. Warm start all enterprise server regions that reside on host 2, in this case Region 2, using one of the two methods specified in step 7.
  10. Enable the new PAC to accept batch work from an enterprise server region that has the new upgraded product. From an Enterprise Server command prompt, type:
    caspac -aSetMode=Running -sredis,<psor_host_name>:<port>
  11. Enable client connections for Region 1 on host 1 via the load balancer and/or the enterprise server listeners. See Managing client connections during a PAC upgrade for more information.
  12. Stop batch work in the old PAC from an enterprise server region that has the old product version. From an Enterprise Server command prompt, type:
    caspac -aSetMode=Quiesce -sredis,<psor_host_name>:<port>

    Incompatible Upgrade Process - Upgraded Region 2
  13. If your PAC contains multiple enterprise server region then you will need shut down any remaining enterprise server regions in the old PAC and upgrade the product on those hosts.
  14. Once all enterprise server regions in the old PAC have been shut down, what remains of the original PAC in the PSOR is no longer required. After the final enterprise server region from the old PAC has been stopped you can remove the old PAC stores.

    From an Enterprise Server command prompt on the new updated product, type:

    caspac -aRemOldPAC=MyPAC -sredis,<psor_host_name>:<port>
Parent topic: Performing a Product Upgrade to a PAC Environment


SQL Administration

  • XA Resources
Parent topic: Administering a PAC


XA Resources

If you specify an XA resource for MFDBFH and another XA resource for the user application, you will need to specify the XAID directive when compiling the applications. This will ensure they are able to determine which XA resource to connect to.

Parent topic: SQL Administration


JCL Administration

  • JOB Administration
  • Updating library, user exit, and printer exit
Parent topic: Administering a PAC


JOB Administration

A Job can be monitored and administered from any region in the Performance and Availability Cluster (PAC), regardless of where the JOB is running.

Note: When running in a PAC or with the MFDBFH database locking for multiple regions, active jobs are not flushed at region start-up. This is to avoid incorrectly removing jobs that are currently active in another region with the same name as the one starting up. See Active output jobs and server restarts for more information.
Parent topic: JCL Administration


Updating library, user exit, and printer exit

Updates to load libraries, printer exit, and user exist can be made with a single caspac command. For example:

caspac -aLoadJes="c:\new files\*.*" -sredis,127.0.0.1:6741 –npsorName

Once the command is executed the files will automatically be synchronized across all the regions within the Performance and Availability Cluster (PAC).

See caspac for more information.

Parent topic: JCL Administration


CICS Administration

  • CICS NEWCOPY
Parent topic: Administering a PAC


CICS NEWCOPY

When a CICS NEWCOPY command is executed in a Performance and Availability Cluster (PAC), the PAC will issue the command to all the enterprise server region in the PAC. The new program is added to the Scale-Out Repository (SOR). When the enterprise server instance executes the CICS NEWCOPY, it takes the new program from the SOR. Programs and files can be added, removed, and listed in the SOR using the caspac utility.

For example, the following loads acct.dll into the SOR represented by the Redis server located at 127.0.0.1 on port 6741. The acct.dll can then be deployed to all active enterprise server region in the PAC using the CICS NEWCOPY command:

caspac -pMyPAC -aLoadCICS="c:\new files\acct.dll" -sredis,127.0.0.1:6741

The following loads all files under C:\new_files into the SOR represented by the Redis server located at 127.0.0.1 on port 6741. All programs that were uploaded can be deployed to all active enterprise server region in the PAC using a CICS NEWCOPY command:

caspac -pMyPAC -aLoadCICS="c:\new files\*.*" -sredis,127.0.0.1:6741

The following removes acct.dll from the SOR represented by the Redis server located at 127.0.0.1 on port 6741:

caspac -pMyPAC -aDelete=CICS@acct.dll -sredis,127.0.0.1:6741

The following lists user programs that have been uploaded into the SOR:

caspac -pMyPAC -aList=* -sredis,127.0.0.1:6741
Note: Do not use Redis to permanently store all applications. Micro Focus recommends that you only store applications that are to be modified whilst a PAC is active and those changes need to be deployed throughout the PAC.

See caspac for more information.

Parent topic: CICS Administration


Troubleshooting a PAC

The following describes how to diagnose common problems that can occur when working with a PAC.
  • Cold start failure
  • File locking due to terminated process
  • Reporting issues
  • Error and Warning Messages
  • Scale-Out Repository availability at process start up
Parent topic: Scale-Out Performance and Availability Clusters


Cold start failure

If you attempt to cold start a region in a PAC which already has at least one region already running, then the cold start request will be executed as a warm start. This ensures that data is not accidently removed from the PSOR while a PAC is active.

If this occurs, the following console message will be displayed in the region you attempted to cold start:

CASSI9027W Region initializing in Warm startup
mode because PAC MYPAC is already active

If you receive this message when no other regions are running then this indicates that one or more regions failed to remove themselves from the PSOR before leaving the PAC. This can result in enterprise server incorrectly interpreting that the PAC is still active. If this scenario occurs then you can run the following command to initialize the PAC:

caspac -aInitPac=PAC_NAME -sredis,host:port
Note: You must ensure that there are no regions running in the PAC before issuing this command.
Parent topic: Troubleshooting a PAC


File locking due to terminated process

If the cascd process has not shut down cleanly, you might need to use the dbfhadmin utility to remove all closed handles:

To list all open handles:

dbfhadmin -openfiles -list -datastore:sql://localhost/VSAM

To force close the handles:

dbfhadmin -openfiles -recover -datastore:sql://localhost/VSAM
-host:nwb-xyz
Parent topic: Troubleshooting a PAC


Reporting issues

Use MFESdiags script to gather diagnostics files from all the regions in the PAC. This provides a lot of additional information, such as region exports, and so on.

Note: If you need to collect CTF or Aux tracing, then you need to set and collect this in each region of the PAC. Once you have collected the CTF or Aux tracing then you should stop this to avoid degrading performance.

If there are issues with dbfhdeploy, dbfhadmin, or configuration problems with getting files extracted, deployed, and you cannot recognize definitions in MFDBFH.cfg, then you can enable CTF using the config below:

# MFTRACE configuration file
mftrace.dest                      = textfile, binfile

mftrace.emitter.textfile#Location = .
mftrace.emitter.textfile#Format   = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)

mftrace.emitter.binfile#Location  = .
mftrace.emitter.binfile#Format    = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)

## Enable all tracing
## To enable tracing on specific switch, comment out #all line
## and uncomment the desired switch(es) below.

mftrace.level.mf.mfdbfh           = debug
mftrace.comp.mf.mfdbfh#all=true
mftrace.comp.mf.mfdbfh#api=true
mftrace.comp.mf.mfdbfh#config=true
mftrace.comp.mf.mfdbfh#database=true
mftrace.comp.mf.mfdbfh#datastore=true
mftrace.comp.mf.mfdbfh#fh=true
mftrace.comp.mf.mfdbfh#region=true
mftrace.comp.mf.mfdbfh#resource_locking=true

The resulting trace will contain information on any problem.

Note: You might need to use the annotations file located in $COBDIR/etc/mftrace/MF.MFDBFH.xml to interpret the trace.

If there are issues with loading files or with routines or calls failing, then you can enable RTS CTF in combination with CTF tracing. This will highlight what the routine is doing, that is, if your application is failing on a CBL_ routine, you could enable CTF tracing with RTS CTF to provide additional information on why the CBL_ routine is failing and whether it is accessing the database.

If the issues are occurring once a region has started, then in addition to the above you can use MFDBFH CTF, ES dumps/aux trace to investigate as any errors. If you are still unable to determine the cause, then capture mfesdiags and provide it to OpenText Support for Micro Focus Products.

Sometimes the MFDBFH CTF does not show up any immediate problems, or there might be issues on the database side that results an error code being thrown. In this cases, you can use third-party tracing in the form of ODBC tracing.

Note: You can only perform this type of tracing if you are using ODBC drivers to make the connection.

If you are using a direct connection to the database then you can look at the database trace.

For ODBC tracing, you can add the following to your odbc.ini for your main database connection:

Trace=1
TraceFile=/tmp/odbc.trace
Debug=1
DebugFile=/tmp/odbc.debug

Or you could add the following to your specific datastore connection definition, if you want to limit what is traced:

Debug=1
DebugFile=/tmp/odbc.debug

If you wanted to trace the ODBC connection to a specific datastore, you can use the following entry:

[PG.ASHNEW]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = MicroFocus$SEE$Files$ASHNEW
Debug=1
DebugFile=/tmp/odbc.debug

This logs information on what the ODBC driver is doing and whether it is failing.

Sometimes this does not necessarily show any problems as the issue may be on the database itself. In this case, you would need to investigate database diagnostic techniques specific to the RDBMS being used. This might be anything from low-level database tracing, such as SQL servers own trace, or investigating whether databases/tables have been created.

You can use the above techniques to find out which sql statements that are being made and specifically which are causing the issue. You can then run those in isolation on the database, that is, you can remove the Micro Focus elements from the scenario. If the dbfhdeploy is failing, you can use the MFDBFH scripts to determine the SQL statements and run them directly on the database.

Note: See Reporting a Problem for complete details on raising a support case with OpenText Support for Micro Focus Products.
Parent topic: Troubleshooting a PAC


Error and Warning Messages

When running in a PAC, administration operations might require synchronization across multiple regions in the PAC. For example, when closing an FCT or deploying a new version of a program, it is possible some regions could fail to process a synchronization request. Instructions for handling some of these situations are detailed below:

  • Message CASPA2104E
  • Message CASPA2102W
  • Scale-Out Repository availability at enterprise server region start up
Parent topic: Troubleshooting a PAC


Message CASPA2104E

If the SEP that processes the initial request detects that one of the regions in the PAC has not been communicating with the PSOR, it will not notify that region of the request (this is to prevent blocking the SEP indefinitely). If this happens, then the SEP will write a CASPA2104E message to the console and continue. The message includes the name of the target region, the type of operation, and the resource on which the operation was to be applied.

This means that the region that was not notified will not process the operation. When this message occurs, an administrator might need to take specific action depending on the results.

If the region is no longer active then the PAC will continue operating. If the region is active but not responding to any requests then it could be holding locks that will affect other regions in the PAC. In this case, you should first collect diagnostic information before performing a forced shutdown of the region to remove any remaining locks.

If the operation is an FCT close, you might receive a message like the following:

CASPA2104E FCT close error for VSO23RW: ITR not sent to RAS2(ras2machine) because it has not pinged the PAC SOR for 0000000482 seconds. 10:55:52

In this case, the FCT VSO23RW will be marked as closed in the PAC and all processes in all regions that successfully processed the close request will have physically closed the file if they had it open and removed any related locks.

The region referenced in the message, in this case RAS2, might not have reconnected to the PAC's SOR. This can be checked using the caspac utility, for example:

caspac -aStatus=<PacName> -sredis,<IP of PSOR>:<Port of PSOR> -n<PAC SOR Name|Sentinel Master Name>

This will output content similar to the following:

Connected to Redis server at 127.0.0.1 port 06741
Region Heartbeat status for endpoint: 127.0.0.1:06741
RAS1(ras1machine)@****::****:****:****:****: 04/03/2020@UTC:11:55:41.088
RAS2(ras2machine)@****::****:****:****:****: 04/03/2020@UTC:10:50:33.044

From this message you can see that RAS2 is no longer sending a heartbeat message to the PAC SOR. If the FCT references a catalogued file and any processes in RAS2 have opened the file, then there will be a shared lock left in the system (where the resource name is the data set name and the queue name is SYSZDSN). This would stop any batch jobs that need to access the same file from running. RAS2 might also interpret that CICS still has the FCT open.

If the region in question is still able to process requests, then check the FCT status in that region:

  • If it displays an FCT status of open and the other regions in the PAC see it as closed, then send a request to close the FCT directly to that region rather than via the load balancer (where the request might get routed to a different region). This will ensure that the region removes any SYSZDSN locks that it has in place (related to the FCT), and that its local copy of the FCT is marked as closed.
  • If it displays an FCT status of closed, then the region must have subsequently refreshed its status which means it has reconnected to the PSOR. This could mean that SYSZDSN locks are still held by that region. To resolve this, send a request to the region to open the FCT and then another request to close it.

If the operation is a CICS NEWCOPY or PHASEIN command, then the new copy of the program will not be deployed to the region referenced in the message. If that region regains communication with the PAC, then the command can be reissued directly to that region.

Parent topic: Error and Warning Messages


Message CASPA2102W

If you receive a CASPA2102W error message, of the type:

CASPA2102W PAC ITR wait fail on OperationType for ResourceName: At least one process failed to process the ITR. Check other regions in PAC for ITR failures.

The OperationType that it is related to could be a file close, a CICS NEWCOPY of a program, or a program cancel. The following is an example of the full message:

CASPA2102W PAC ITR wait fail on Close for VSO23R: At least one process failed to process the ITR. Check other regions in PAC for ITR failures.

As suggested by the message, the console.log for each region in the PAC should be checked for any reported a problem. Typically, at least one message like the following will be found:

CASPA2068W Region received an ITR but at least one SEP failed to process it. Type=File, Action=Close, Resource=VSO23R

If a SEP failed to process the operation then it could be out of synchronization with other SEPs in the PAC.

If the SEP exited whilst processing the operation, then there will be no need for any further action because recovery processing will ensure that any locks that were owned by the process will have been released. It would be apparent if this is the case because there would be console messages showing that a SEP exited around the time of the CASPA2068W message.

If the SEP is still active then there might be other console messages or traces which could help identify which process failed. You might need to intervene depending on which operation was issued. See Message CASPA2104E for more information. Typically, this would involve reissuing the command directly to the region which experienced the problem.

Parent topic: Error and Warning Messages


Scale-Out Repository availability at enterprise server region start up

When starting the enterprise server regions in a PAC, and a region(s) is unable to connect with their associated Scale-Out Repositories (SORs), then:

  • The region(s) will fail to start. If the region(s) were able to start then they would be in an inconsistent state with respect to the other region(s) in the PAC.
  • The messages, CASSI1430E and CASSI9047E, will be displayed in the console indicating the SOR that could not be connected to and its connection details.

In this case, you must ensure that the specified SOR is running and can be connected to from the machine hosting the region(s). You can then restart the region(s).

Parent topic: Error and Warning Messages


Scale-Out Repository availability at process start up

If a process starts whilst the regions are active and it cannot connect to a SOR, then:

  • The message CASPA1000W will be displayed in the console indicating that it was not possible to connect and the reason for the failure.

In this case, you must ensure that the specified SOR is running and can be connected to from the machine hosting the region(s).

If the SOR is not the PSOR; that is, the SOR is only being used for temporary storage and/or transient data, then:

  • The process will start and operate normally.
  • If the SEP receives a request to access a queue whose target is that SOR, then an attempt will be made to reconnect to the SOR prior to the access attempt:
    • If this attempt is successful then the message CASPA1001I will be displayed in the console and the queue will be accessed as normal.
    • If the attempt fails then the CICS command will receive an IOERR.

In this case, you must ensure that the specified SOR is running and can be connected to from the machine hosting the region. Connection will be established automatically when required.

If the SOR being connected to is the PSOR, then:

  • The process will be blocked and retry the connection.
  • The message CASPA1002E will be displayed in the console.

If the process is a SEP, initiator or MPR, then it will repeatedly try to connect with increasing intervals between retries, eventually stopping and shutting down if it fails to connect.

If the process is one of the auxiliary process, such as casras, castrc, castsc, and so on, then the process will retry indefinitely or until it connects or the region(s) is shutdown.

In these cases, you must ensure that the specified SOR is running and can be connected to from the machine hosting the region(s).

A successful connection will be indicated by the message CASSI1466I being displayed in the console by the process.
Note: If the reason for the connection failure to the PSOR is that the PSOR is no longer running, that is, all PSOR data has been lost, then the PAC will need to be restarted. Micro Focus recommends you use an HA solution for the PSOR to prevent this scenario.
Parent topic: Troubleshooting a PAC


Reference

Reference information for configuring and administering your PAC.
  • PAC Considerations
    The following considerations should be taken when configuring and running your PAC.
  • PAC Utilities
    Utilities for administering your PAC.
  • PAC and SOR Environment Variables
    The following PAC and SOR environment variables are provided for reference purposes only.
Parent topic: Scale-Out Performance and Availability Clusters


PAC Considerations

The following considerations should be taken when configuring and running your PAC.
  • Third-party software
  • Load libraries and user exits
  • SQL
  • Configuration files
  • Environment variables
Parent topic: Reference


Third-party software

You must ensure that any third-party software used by your PAC is consistent for all member regions.

Parent topic: PAC Considerations


Load libraries and user exits

You must ensure that all load libraries and user exits used by your PAC are consistent for all member regions.

Parent topic: PAC Considerations


SQL

You must ensure that all XA resources used by your PAC are consistent for all member regions.

Parent topic: PAC Considerations


Configuration files

You must ensure that all configuration files used by your PAC are consistent for all member regions.

The following table lists some of the configuration files that should be considered:

File Name | Component
Handler Modules | CICS
Package Modules & IDTs | CICS
Switch Modules | CICS
dfhdrdat | CICS
CICS Loadlib Modules | CICS
MFDBFH.cfg | File Handling
EXTFH.CFG | File Handling
allocation.cfg | JCL
SPLDSN.dat | JCL
SPLJOB.dat | JCL
SPLMSG.dat | JCL
SPLOUT.dat | JCL
SPLSUB.dat | JCL
JES Loadlib Modules | JCL
catalog.dat | JCL & CICS
Certificates & Keys | MFCRYPTLIB
ESM Modules | System Authorization Facility (SAF)
Note: This is not an exhaustive list. You should consider all configuration files that your PAC uses.
Parent topic: PAC Considerations


Environment variables

The following is a list of some of the more common environment variables that you can configure for your PAC. These must be consistent for all member regions:

Name | Description | Component
CICS_SIT | Specifies the name of the SIT used by the region. | CICS
ES_ALLOC_OVERRIDE | Specifies 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 | JCL
ES_CICS_SINGLE | Configures CICS so that a user can only log on once. | CICS
ES_CLASS_XCMD | Overrides the default CICS CMD resource class. | CICS
ES_CLASS_XDCT | Overrides the default CICS DCT resource class. | CICS
ES_CLASS_XFCT | Overrides the default CICS FCT resource class. | CICS
ES_CLASS_XJCT | Overrides the default CICS JCT resource class. | CICS
ES_CLASS_XPCT | Overrides the default CICS PCT resource class. | CICS
ES_CLASS_XPPT | Overrides the default CICS PPT resource class. | CICS
ES_CLASS_XPSB | Overrides the default CICS PSB resource class. | CICS
ES_CLASS_XRES | Overrides the default CICS DOCTEMPLATE resource class. | CICS
ES_CLASS_XTRAN | Overrides the default CICS TRAN resource class. | CICS
ES_CLASS_XTST | Overrides the default CICS TST resource class. | CICS
ES_DISABLE_DFLTUSR_SIGNON | Disables the default user (mfuser) signon when invoking ES Monitor & Control. | CICS
ES_EMP_EXIT_n | Specifies the number of Event Manager user exits for the region. | JCL
ES_ESM_CMDSEC | Indicates whether CICS processing honors the CMDSEC option specified on a transaction's PLT definition. | CICS
ES_ESM_PLTPIUSR | The user id under which PLT programs run during CICS initialization. | CICS
ES_ESM_RESSEC | Indicates whether CICS processing honors the RLS security setting specified on a transaction definition (PCT). | CICS
ES_ESM_SECPRFX | Indicates whether CICS processing prefixes the resource names when making security queries. Note: The environment variable ES_ESM_SECPRFX is only applied to CICS classes. | CICS
ES_ESM_XUSER | Indicates whether CICS processing performs surrogate user checks. | CICS
ES_PAC_NO_GLOBAL_LOG | Stops the messages in the console.log from being stored in the PSOR. | PAC
ES_SOR_RETRIES | Sets the number of attempts to access records in the PSOR before stopping. | PAC
ES_USR_DFLT_CICS | Enables you to override the default user when no user is logged on for CICS authentication. | CICS
ES_USR_DFLT_JCL | Enables you to override the default user when no user is logged on for JCL authentication. | JCL
ES_USR_DFLT_JES | Enables you to override the default user when no user is logged on for JES authentication. | JCL
ES_WORKING_MODE | The working mode of the server. This indicates whether the server is to run 32-bit or 64-bit applications |
ES_XA_%xaname%_OPTIONS | Set for each RM that you require to operate in a multiple attempt mode. See ES_XA_%xaname%_OPTIONS in Environment variables in alphabetical order for details. Dependency: Must be set along with ES_XA_RECONNECT=Y. | CICS
ES_XA_RECONNECT | Set this to configure the XA reconnect process to operate in a single attempt mode. See ES_XA_RECONNECT in Environment variables in alphabetical order for details. | CICS
MFSYSCAT | The location of the JES system catalog. | JCL
MFUSERCAT_BASE_LOC | If an entry in MFUSERCAT_LOC only specifies the file name of a user catalog rather than the full path and file name, use this environment variable to specify where these catalogs are located | JCL
MFUSERCAT_LOC | The location of the node(s) set in MFUSERCAT_NODE, separated by semi-colons if more than one is specified. | JCL
MFUSERCAT_NODE | Sets additional SMS, SPOOL and User catalogs. To enable support for the SMS entities DATACLAS and MGMTCLAS, this variable needs to be set in addition to setting MF_SMS=ON. | JCL
Note: This is not an exhaustive list. You should consider all environment variables your PAC uses.
Parent topic: PAC Considerations
Related concepts
Single mode reconnect for CICS
Multiple mode reconnect for CICS


PAC Utilities

Utilities for administering your PAC.
  • caspac
Parent topic: Reference
Related reference
caspac


caspac

You can use the caspac utility for the following PAC administration tasks:

  • Loading programs into a SOR ready for deployment using the CICS NEWCOPY command.
  • Removing programs from the SOR.
  • Listing user programs that are stored in the SOR.
  • Initializing the PAC ready for a cold start.
  • Querying the status of a PAC.
  • Creating a dump of the PAC.
  • Restoring a PAC from a dump file.
  • Writing a PAC log file.

Start an Enterprise Server command prompt and then run the caspac utility to see a list of the available options. See caspac for more information.

Parent topic: PAC Utilities


PAC and SOR Environment Variables

The following PAC and SOR environment variables are provided for reference purposes only.
Note: Micro Focus recommends that you configure your Performance and Availability Cluster (PAC) and Scale-Out Repository (SOR) using ESCWA. If you are configuring a SOR using Oracle Coherence you will not be able to use ESCWA for the configuration.

All enterprise server instances that are part of a PAC need to have the following environment variable set:

ES_PAC=pacname

Each SOR within a PAC needs a specific environment variable set:

ES_SCALE_OUT_REPOS_n=sorName=sorType,connectionDetails##[TMP#][models]
Note: The same environment variable must be specified on each region that joins a PAC. Only one environment variable can reference the PAC Scale-Out Repository (PSOR), as only one PSOR can be associated with any given PAC.

where:

n

This is the SOR number and can be a value 1 to 9.

sorName
This is the name of the SOR and must not contain spaces.

In the context of using Redis, the sorName is used to retrieve the Redis master from Redis.

sorType
This is the type of data store being used and can be:
  • redis
  • redis_TLS
  • coherence

Use redis_TLS for TLS enabled connections to a Redis data store. See Redis Requirements and Configuration as a Scale-Out Repository for more information.

connectionDetails
For Redis this is the host name and port number of the scale out repository, in the form host:port. For example, localhost:6379. You can specify multiple connections by using a comma as a delimiter between each connection.

For Oracle Coherence the connection string is limited to 1024 characters and takes the form:

[userid@][configfile][,property=[value]]…

where:

userid
This is the optional user to use when Oracle Coherence security is enabled.
configfile
This is the name, location, URL of the cache configuration file. If this is omitted it defaults to mfes-cache-config.xml.
property
This is the name of a Java property to set to the value or is clear if value is unspecified.
value
This is the value of the Java property to set.

The configuration used by the Enterprise Server clients should match the server configuration. So where for a Redis you might have:

ES_SCALE_OUT_REPOS_1=MySOR=redis,127.0.0.1:6379##TMP#

For Oracle Coherence you might have:

ES_SCALE_OUT_REPOS_1=MySOR=coherence,mfes-cache-config.xml,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1:7574##TMP#

If you are using the default mfes-cache-config.xml filename you can omit its name and just specify the properties. For example:

ES_SCALE_OUT_REPOS_1=MySOR=coherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1##TMP#
Note: There are two adjacent comma characters where the configuration file name is missing.

The configuration file mfescache.cfg is used to specify options when Enterprise Server is starting the Java Virtual Machine (JVM). This file can be modified to specify properties in addition to the connection string properties, if specified in both, then the connection string property will override the configuration file value.

TMP
Indicates that this is a PSOR that stores active resources.
Note: You must specify exactly one PSOR for each enterprise server instance within a PAC and each enterprise server instance in the PAC must use the same PSOR.
models
Take the form:
=ResourceType=model[:model][#ResourceType=model[:model]]

where:

#
Delimits the set of models for a model type.
ResourceType
The resource type can be Temporary Storage (TS) or Transient Data (TD). Permitted values are TS and TD.
model
Specified as a string between 0-16 bytes long. TD names can only be four characters long. TS names can be up to 16 characters long. The string names support the use of the following wildcards:
*
Matches any string of characters.
+
Matches any one character.
Note: Trailing + wildcards are used to pad missing characters appropriate for the resource type. For example, if you are specifying a model for a TD resource type and only specify a single letter "A" then it is treated as "A+++".
:
Delimits between each model.
x'hex string'
A hexadecimal prefix can be specified in a SOR model by enclosing the hex string in quotes and preceding it with an x, for example, x'ABAB' or x'AABBCC'.

You can use 2B as a generic matching character, for example, x'AA2BAA' would match queues that begin with x'AAAAAA', x'AABBAA', and x'AACCAA' and so on.

Examples

The following is an example of the ES_SCALE_OUT_REPOS_n environment variable using Redis as the SOR:

ES_SCALE_OUT_REPOS_1=RedisLocal=redis,127.0.0.1:12345##TMP#TD=AC*:TD*:RTDQ:SOR1#TS=A*:B+A:NRQSOR1

where:

RedisLocal
This specifies the name that will be used by Redis to identify the Redis master in a sentinel configuration.
redis
This specifies that Redis is the type of SOR being used.
127.0.0.1:12345
This specifies the Redis server connection details: ip address and port for this SOR.
##TMP#
This specifies that this SOR is the mandatory PSOR.
TD=AC*:TD*:RTDQ:SOR1#TS=A*:B+A:NRQSOR1

This specifies that the SOR will contain TDs starting with AC, TD, and a TD called RTDQ as well as all TSs starting with an A, those starting with a B followed by any character and ending with an A, and a TS called NRQSOR1.

The following is an example of how you can specify more Redis SORs on a PAC:

ES_SCALE_OUT_REPOS_2=RedisLocal2=redis,127.0.0.1:67891##TD=ATD#TS=T*R2:R*R2

where:

RedisLocal2
This specifies the name that will be used by Redis to identify the Redis master.
redis
This specifies that Redis is the type of SOR being used.
127.0.0.1:67891
This specifies the connection details for a second Redis server: ip address and port for this SOR.
##TD=ATD#TS=T*R2:R*R2
This specifies that the SOR will contain a TD called ATD, as well as TS that start with T and end with R2, and that start with R and end with R2.
Parent topic: Reference
Related concepts
Oracle Coherence Requirements and Configuration as a Scale-Out Repository
Related information
ES_SCALE_OUT_REPOS_n


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.

A full example of ESCERTPAS.CBL is provided in %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\src\enterpriseserver\exits.

Note: The example provided contains keyfile passwords in plain text. However, this is not recommended; the exit should acquire the password securely.

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 TLS/SSL authentication for CWI
    To set up server-side TLS 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
    Provides troubleshooting guidance for CWI SSL failures.
Parent topic: Enterprise Server configuration and administration


Setting up server-side TLS/SSL authentication for CWI

To set up server-side TLS 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 TLS authentication for CWI is as follows:
  1. Obtain a server private key and certificate. For development and test purposes, you can use the Demo CA. See Using the Demonstration Certificate Authority for more information. For production use, you must use an organizational or public CA. Put the certificate and private key in separate PEM-format files. The key file must have the same name as the certificate file, with _key appended to it. For example, if the certificate is in srvcert.pem, the key should be in 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 as follows:
    [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\EC_CAcollection.pem’ to lk-CARoot-to-be-used
  8. Start your enterprise 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.
  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. See User Certificate Registration for CICS Web Interface Servers for more information on associating client certificates with CICS user IDs.
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 are no 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 does not 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 /proc/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.

CCI Tracing can also be used to collect some SSL traces by adding the following to the CCI.INI file:

[ccitcp-base]
# Display the negotiated cipher
ssl_display_cipher=yes
# Display details of the peer certificate (if any)
ssl_display_cert=yes
# Display why the certificate content failed its trust test.
ssl_display_cert_fail_report=yes
# Display all details available about the offered certificate.
ssl_display_cert_connection_details=yes
# Switch on or off the SSL options above
ssl_display_options_on=yes
# Where to save the certificate information
ssl_display_destination=/home/diags/tls.txt
Parent topic: SSL Support for CICS Web Interface Servers


User Certificate Registration for CICS Web Interface Servers and DCAS

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, then your CWI server uses the Enterprise Server user certificate registration mechanism. This section explains user certificate registration and what you can do with it.

DCAS (Digital Certificate Access Server) listeners also use user certificate registration. DCAS and CWI can use the same collection of certificate registrations, or separate ones. The cascertreg utility is used to administer DCAS certificate registrations. See Multi-Factor Authentication, DCAS Security, and DCAS conversation type for more information.

  • Understanding User Certificate Registration
    In SSL, clients and servers can identify themselves using X.509 certificates.
  • User Certificates for CICS Web Interface
    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.
Parent topic: Enterprise Server configuration and administration
Related concepts
DCAS Security
Multi-Factor Authentication


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 and DCAS
Related concepts
Configuring a region for Express Logon Feature


User Certificates for CICS Web Interface

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.

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. 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 accepts (following the rules listed below), and that certificate can be associated with a user ID.

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 remains associated with that user even if security is subsequently switched on, and from that point there is no further validation for that user/certificate combination.

Registrations can be deleted 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 is a digitally-signed document.
  • It must be signed by a certification authority (CA) that is recognized by CICS, so that CICS can verify the certificate's signature.
  • It must be created using cryptographic algorithms recognized by CICS. Enterprise Developer 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 provides 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 is prompted to provide a passphrase before the certificate can be used.

Client certificates can be purchased from a commercial CA such as Verisign. They can also be generated using a variety of tools, including the DemoCA utilities included with some Enterprise Developer products.

Parent topic: User Certificate Registration for CICS Web Interface Servers and DCAS


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 Enterprise Developer 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 validates it and then checks to see if it is registered. If it is, the user ID associated with it is used for the CWI transaction and no further input from the user is required. If the certificate is not registered, CWI prompts the user to sign in - using the standard HTTP mechanism, so with a browser, you typically see a username/password dialog. If the user supplies a valid CICS user ID and password, the certificate is 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 and DCAS


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. Within that section are one or more name=value pairs. The supported names and their corresponding values are:

Name | Value | Comments
user | user ID associated with the certificate | Required. Provides the user ID to which the certificate is mapped.
cwi | "yes" or "no" | If present and set to "no", the mapping cannot be used by the CICS Web Interface feature.
dcas | "yes" or "no" | If present and set to "no", the mapping cannot be used by the Digital Certificate Authentication Service. Typically DCAS would be used for this purpose as part of TN3270 automatic signon through the ELF feature.

The optional cwi and dcas settings let you restrict how a certificate mapping is used. These settings take effect the first time the mapping is used after the region has been started.

Some comment lines might also be included. These begin with a semicolon (";") character. The cascertreg utility inserts comments that state when the file was created, and (for cascertreg version 1.3 or later) the issuer and subject distinguished names of the certificate, for reference.

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 forces 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 and DCAS


IPv6 Support

Enterprise Server 6.0 included partial support for Internet Protocol version 6 (IPv6). This support lets you configure, and programs use, IPv6 addresses and hostnames that resolve to IPv6 addresses, in addition to the existing support for IPv4 addresses.

Starting with Enterprise Server 7.0, by default, MFDS and MFCS listen on all configured IPv4 and IPv6 addresses, and can be configured to listen on a combination of specific IPv4 and IPv6 addresses.

Micro Focus recommends that you refer to your operating system documentation for more information about IPv6.

  • Components and features which support IPv6
  • Restrictions on IPv6 support
  • Specifying IPv6 Addresses
Parent topic: Enterprise Server configuration and administration


Components and features which support IPv6

The following components and features support IPv6:

  • Client programs which use the Micro Focus Common Client technology can generally use IPv6:
    • COBOL web service proxy programs.
    • CAS utilities such as casfile and cassub.
  • Enterprise Server communications processes and listeners.
  • Enterprise Server listener conversation filtering rules.
  • The Micro Focus Directory Server (MFDS), Enterprise Server Monitor and Control (ESMAC), and Enterprise Server Common Web Administration (ESCWA) user interfaces.
Parent topic: IPv6 Support


Restrictions on IPv6 support

The following restrictions apply to components and features when using IPv6:

  • CAS support for IPv6 is limited. Some features, such as CICS Web Interface, might not work with IPv6.
  • The Mainframe Subsystem EZ Sockets APIs (EZASOKET and EZACICAL) do not support IPv6.
  • IPv6 has not been tested with traditional CCI clients and servers such as Fileshare.
  • IPv6 address zone indexes, also known as scope IDs, are ignored by Enterprise Server. These appear in IPv6 addresses as a percent sign followed by a number or string, appended to the main part of the address, and are used to identify a network interface when an address is not globally unique.
  • There are cosmetic issues with IPv6 addresses in some contexts, such as in ESMAC.

IPv6 support for Enterprise Server for .NET is unchanged since 5.0.

Parent topic: IPv6 Support
Related reference
Specifying IPv6 Addresses


Specifying IPv6 Addresses

IPv6 addresses contain the colon (:) character. This can be ambiguous in contexts where a colon is used to separate an address and port. For example, in a URL, or in an Enterprise Server listener's configured endpoint.

In those contexts, Enterprise Server follows the standard convention used in URLs of enclosing the IPv6 address in square brackets.

For example, to configure an Enterprise Server listener to listen on the IPv6 address fe80::1ff:fe23:4567:890a and port 12000, you would configure the listener's endpoint as [fe80::1ff:fe23:4567:890a]:12000 .

Similarly, the URL for an HTTPS resource on port 9000 on the local system might begin with https://[::1]:9000/.

Parent topic: IPv6 Support
Related concepts
Restrictions on IPv6 support


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 CICS Web Interface Communications Options
  • Configuring Communications Processes
  • Configuring Listener Conversation Types
  • Conversation Filtering
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+ Desktop, 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 communications processes and listeners for a specific enterprise server region by clicking GENERAL > Listeners.

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 - list 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.
  • Actual Address - displays the network address or addresses used by the communications process to accept incoming client requests. The format is:
    protocol:hostname or ip-address:port
    where:
    protocol
    This can be tcp or tcpssl.
    hostname or ip-address
    This can be a single hostname or multiple IP addresses that can be either IPv4 or IPv6.
    port
    This must be a valid port or an asterisk * which indicates that the address is dynamically assigned for the communications process when it starts.
  • Status - 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.

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
  • Actual Address - displays the network address or addresses used by the listener to accept incoming client requests. The format is:
    protocol:hostname or ip-address:port
    where:
    protocol
    This can be tcp or tcpssl.
    hostname or ip-address
    This can be a single hostname or multiple IP addresses that can be either IPv4 or IPv6.
    port
    This must be a valid port or an asterisk * which indicates that the address is dynamically assigned for the listener when it starts.
  • Status - 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 - See Configuration Information for more information.
  • Description

See Listeners for more information.

Parent topic: Configuring Client-Server Communications


Securing Communications

There are a number of additional configuration options, for logging and setting a TLS (SSL) passphrase, that can be set in the file mf-server.dat, located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin . These are mostly options that require setting before the Micro Focus Communications 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 Securing Communications chapter and the To Create a Secure Communications Process topic for more information.

Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This can be specified in the mf-server.dat file and takes the following form:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
Parent topic: Configuring Client-Server Communications


Configuring CICS Web Interface Communications Options

There are a number of optional settings for the Micro Focus Communications Server that affect CICS Web Interface (CWI) processing.

These options apply to all CWI listeners and conversations belonging to an enterprise server instance. They are applied at enterprise server startup, and changes take effect when the enterprise server instance is restarted.

  • Setting Options
Parent topic: Configuring Client-Server Communications


Setting Options

All of the options are configured in Enterprise Server Common Web Administration (ESCWA) in the Configuration Information field, using "ini" format of name-value pairs within sections, under the [CWI] section. Options can be set in the Custom Configuration field of the first Communications Process, and/or the Configuration Information field of the enterprise server region that owns the Communications Process. If there are conflicting settings in the Server and the Communications Process, those in the Communications Process take precedence.

The [CWI] section can appear multiple times. If the same option is specified more than once, the last setting takes effect.

Note: Option names and values are case-insensitive.

[CWI] Section Options

The following options are recognized in the [CWI] section:

Default timeout=seconds
For client CWI conversations, the default timeout to use when waiting to receive a response from the server after sending an HTTP request. This can be overridden by the application or CICS resources.

The value is specified in seconds. The default value is 2147483648, or about 68 years.

Default connect timeout=seconds
For client CWI conversations, the default timeout to use when trying to connect to a web server. This timeout only applies until the TCP conversation has been established. This can be overridden by the application or CICS resources.

The value is specified in seconds. The default value is 30 seconds.

Tracing=integer-value
Enable CWI tracing. Trace messages describe aspects of CWI processing and are written to the Communications Server log.

The value is an integer. 0 disables tracing; larger values enable progressively more-detailed tracing. Currently the largest value that enables any additional messages is 6. The default value is 0 (no tracing).

Relax URL rules=yes|no
For client CWI conversations, allow non-standard characters in URLs for HTTP requests.

By default, the Communications Server imposes restrictions on the path portion of a URL for an HTTP request. This may cause some CICS WEB OPEN commands to fail if the URL contains characters not permitted by Communications Server. The permitted characters are letters, digits, the forward slash, characters allowed in well-formed URL query-strings, and the "unreserved" and "subdelim" characters defined by RFC 3986 section 3.3. Also permitted are canonical UTF-8 multi-byte character sequences, URL hex escape sequences, and square brackets around the host portion of the URL.

If this option is set to yes, only URLs with malformed hex escape or UTF-8 sequences are rejected. The default value is no.

Reconnect if server closes=yes|no
Enable automatic reconnection for client CWI conversations.

Communications Server can attempt to automatically reconnect to the server if necessary before sending a request. This avoids the application getting an error from CICS WEB SEND and having to do another CICS WEB OPEN. This option is disabled by default to more closely emulate the behavior of CWI on the mainframe. The attempt to reopen may not happen under all conditions and is not guaranteed to succeed; it is for application convenience only.

If this option is set to yes, CICS WEB SEND and WEB CONVERSE will attempt to reopen the conversation if necessary. The default value is no.

Log client certificates=yes|no
For CWI servers using TLS (SSL), log information about certificates received by clients.

If this is set to yes, and a client sends a certificate, some information about the certificate will be written to the Communications Server log. The default value is no.

Sleep time=milliseconds
Configure how long to wait between checks for session availability.

The CWI implementation provides thread safety by serializing operations on each CWI session. If a session is currently in use (some CWI operation is in progress), attempts to use that session will be blocked. Communications Server uses a polling mechanism to detect when the session is available. To avoid excessive CPU use ("busy-waiting"), each waiting thread will sleep between checking the session status. Note this is a rare condition and only applies to applications that attempt to use the same CWI session from multiple threads or processes. There is rarely any reason to change this setting.

This setting controls how long the threads sleep between checks, in milliseconds. The default value is 200 milliseconds.

Note: Smaller values can reduce latency but increase CPU load.
Always send options=yes|no
For CWI client conversations, controls whether an HTTP OPTIONS request is always sent after establishing a connection.

Older versions of Enterprise Server CWI always sent an HTTP OPTIONS request to a server after establishing a connection. This let the CWI implementation verify the state of the connection, confirm there was an HTTP server on the other end, and determine the server's HTTP version. This option can be used to disable this behavior.

This information is not required by the CICS WEB OPEN command unless one or both of the return parameters HTTPVNUM and HTTPRNUM is specified. Mainframe CWI does not make the OPTIONS request if neither of those parameters is used on WEB OPEN. When this option is disabled, Enterprise Server CWI emulates the mainframe and uses OPTIONS only if it is required.

The advantage of enabling this option is faster detection of an incorrect or unavailable server, since the error will be returned by WEB OPEN without waiting for a WEB SEND or WEB CONVERSE. The disadvantages are reduced mainframe compatibility, an extra request/response flow with the server, and potential (rare) issues with servers, proxies, or firewalls that do not handle OPTIONS requests correctly.

If this option is set to no, the OPTIONS request will only be sent by CICS WEB OPEN if HTTPVNUM and/or HTTPRNUM is specified. The default value is yes.

Example

For example, the Configuration Information field for the enterprise server region might contain the following:

# Communications options for CICS Web Interface
[CWI]
# Wait no more than 10 minutes for the response to a web request
Default timeout=600
# Log information about client certificates
Log client certificates=yes
# Set this to a value 1-6 to turn on tracing
Tracing=0
This could also be typed in the Custom Configuration field belonging to the region's Communications Process.
Parent topic: Configuring CICS Web Interface Communications Options


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 Custom Configuration field on the ESCWA COMMUNICATIONS PROCESSES page to edit configuration data specific to a communications process or a listener.
  • Editing Communications Settings
Parent topic: Configuring Client-Server Communications


Editing Communications Settings

The Custom Configuration field on the ESCWA COMMUNICATIONS PROCESSES 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
trace buffer size=number-of-events
trace file=path
trace on error=trace-option
tracing=trace-setting
[HTTP]
maximum header value length=bytes
[ISC]
listener-wait=listener-wait-number-of-seconds
[listeners]
logging=logging-level
[logging]
closed during initial receive=enable-logging
[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
[idle check]
interval=seconds
error=error-check-setting
readable=readable-check-setting
trace=trace-level

The sections, settings, and their parameters are explained below.

  • [CCI] section
  • [ezasoket] Section
  • [HTTP] Section
  • [idle check] Section
  • [ISC] Section
  • [listeners] Section
  • [logging] Section
  • [MFCC] Section
  • [tasks] Section
  • [threading] Section
  • Idle conversation check
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
  • trace buffer size
    Enables buffered tracing and sets the number of trace entries to buffer.
  • trace file
    Enables tracing to a specific file, rather than the MFCS log.
  • trace on error
    Enables the writing of trace entries only after an error occurs.
  • tracing
    Sets the (optional) tracing level.
  • trace error filter
    Restricts which error conditions trigger tracing.
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


trace buffer size

Enables buffered tracing and sets the number of trace entries to buffer.
Restriction: These options apply only when the Enterprise Server feature is enabled.

There are three buffering modes. If the trace on error configuration option is enabled, circular buffering is used: MFCS will store the most recent n entries, where n is the number specified with this option (or a default; see trace on error). Otherwise, if this option is specified with a value greater than zero, MFCS will buffer the specified number of trace entries and write them to the log or trace file when the buffer fills or when the region is shutting down. If neither option is specified, MFCS will not buffer trace entries, but instead write them immediately to the log or trace file.

Syntax:

trace buffer size=<number-of-entries>

Parameters:

<number-of-entries>
A number (at least 1) of trace entries to buffer before writing them to the MFCS log or the trace file. This reduces overhead on a busy system.

Properties:

Default: 0 (50 if trace on error is enabled)
Parent topic: [ezasoket] Section


trace file

Enables tracing to a specific file, rather than the MFCS log.
Restriction: These options apply only when the Enterprise Server feature is enabled.

If this is not specified or the value is empty, trace messages go to the Communications Server log. If it is specified, the file is opened in append mode. The trace messages will be written as plain ASCII text, one per line, with a timestamp.

Syntax:

trace file=path/to/file

Parameters:

path/to/file
The path to the trace file.

Properties:

Default: Not set
Parent topic: [ezasoket] Section


trace on error

Restriction: These options apply only when the Enterprise Server feature is enabled.

If this option is enabled, MFCS will keep the most recent trace entries in memory until an EZ Sockets API call returns with a non-zero MFCS return code, a RETCODE value of -1, or a non-zero ERRNO value; or as specified in the optional trace error filter configuration option; then it will write those entries to the log or trace file. See trace error filter for more information.

The number of entries stored is 50 unless overridden by the trace buffer size option.

Syntax:

trace on error=yes|no

Parameters:

Yes
Trace entries are written only after an error occurs.
No
Trace entries are written according to the trace buffer size setting (if set), or written immediately (if trace buffer size is not set).

Properties:

Default: No
Parent topic: [ezasoket] Section
Related reference
trace error filter


tracing

Restriction: These options apply only when the Enterprise Server feature is enabled.

Enables tracing of the EZ Sockets API calls (EZASOKET and EZCICAL) in the Communications Server.

Syntax:

tracing=yes|no|<number>

Parameters:

Yes
Enable tracing at level 2.
No
Disable tracing.
<number>
Set the tracing level. 0 disables tracing. Higher values enable more trace points. Currently there are no additional trace points after level 3.

Properties:

Default: No (tracing disabled)
Parent topic: [ezasoket] Section


trace error filter

Restriction: These options apply only when the Enterprise Server feature is enabled.

If the trace on error option is specified, this option can be used to control which error conditions cause MFCS to write the trace output. If it is not specified, trace output is written on every error condition, as described in the topic trace on error.

Syntax:

trace error filter=token-list

Parameters:

token-list
A list of one or more tokens, separated by spaces and/or commas. Tokens can be any of:
FAIL
This special token will cause errors to be reported if MFCS returns a non-zero value to CAS. This typically indicates a severe processing failure, such as, an invalid request from CAS or the failure to allocate storage.
RETCODE
This special token will cause errors to be reported if the EZ Sockets API parameter RETCODE is -1 on returning from an EZ Sockets function. Many EZ Sockets APIs (though not all) use -1 to indicate that some error occurred.
ERRNO
Any valid numeric value, per the IBM EZ Sockets documentation. Currently these include the values 4-121, 1002-1036, 10101-10999, and 20000-20002. See IBM documentation for the meanings of these values.
mnemonic name
The mnemonic name for any ERRNO value, such as EBADF, EIBMSOCKOUTOFRANGE, or EBADRDLEN. See IBM documentation for the names and their meanings.

The default is to trace on all errors.

Parent topic: [ezasoket] Section
Related reference
trace on error


[HTTP] Section

  • maximum header value length
    Sets the maximum size in bytes of the value of an HTTP header, for HTTP conversations using the new MFCS HTTP parser.
Parent topic: Editing Communications Settings


maximum header value length

Sets the maximum size in bytes of the value of an HTTP header, for HTTP conversations using the new MFCS HTTP parser.

This includes COBOL Web Services (when using the Web Services and J2EE conversation type for the listener), and CICS Web Services.

Syntax:

maximum header value length=bytes

Properties:

Default: 1024

Comments:

Most clients do not need the server to support values longer than the default, but some applications may make use of HTTP headers with unusually long values.

Parent topic: [HTTP] Section


[idle check] Section

This section enables you customize how MFCS periodically checks the state of idle conversations. Idle conversations are ones which are blocked waiting for processing by Enterprise Server, such as conversations waiting for the reply to a queued administration request.

  • interval
    Sets the time between idle-conversation checks after the first.
  • error
    Enables or disables the idle-conversation error check.
  • readable
    Enables or disables the idle-conversation readability check.
  • trace
    Enables tracing of idle-conversation processing.
Parent topic: Editing Communications Settings
Related reference
Idle conversation check


interval

Sets the time between idle-conversation checks after the first.
Note: The first idle-conversation check is always performed 15 seconds after the conversation becomes idle.

Syntax:

interval=seconds

Properties:

Default: 15 seconds

Comments:

Setting this to 0 disables the idle-conversation checking entirely.
Parent topic: [idle check] Section


error

Enables or disables the idle-conversation error check.

Syntax:

error=yes|no

Properties:

Default: yes

Comments:

The error check retrieves error information from the communications stack regarding the local endpoint for the conversation. In some cases, a failure such as a network error will update this information, letting MFCS know the conversation is no longer usable. In other cases, it is necessary to try to perform I/O on the conversation to detect the failure. If an error is detected, the conversation is processed accordingly. Typically, there is no requirement to disable this check; this option is provided in case a problem is found with the error check mechanism.
Parent topic: [idle check] Section


readable

Enables or disables the idle-conversation readability check.

Syntax:

readable=yes|no

Properties:

Default: yes

Comments:

The readability check queries the communications stack regarding the local endpoint for the conversation to determine if a receive operation will return immediately. This can be true if there is data to be read, or if the peer has closed its end of the conversation, or for certain failures. If the conversation is readable, MFCS will attempt to receive a single byte. Any received data is buffered for later processing; if MFCS gets an indication that the conversation is closed or failed, it is processed accordingly. Typically, there is no requirement to disable this check; this option is provided in case a problem is found with the readability check mechanism.
Parent topic: [idle check] Section


trace

Enables tracing of idle-conversation processing.

Syntax:

trace=trace-level

Properties:

Default: 0

Comments:

Trace level 0 disables tracing; positive numbers enable it. In principle higher numbers produce more verbose tracing, but currently all trace points for this feature are traced at level 1.
Parent topic: [idle check] 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


[logging] Section

  • closed during initial receive
    Enables you to log the conversation closed during initial receive information messages.
Parent topic: Editing Communications Settings


closed during initial receive

Enables you to log the conversation closed during initial receive information messages.

Syntax:

closed during initial receive=enable-logging

Parameters:

yes
Log the conversation closed during initial receive information message.
no
Do not log the conversation closed during initial receive information message.

Properties:

Default: no

Comments:

You can enable this logging by adding this configuration to your mf-server.dat file, the enterprise server region's Configuration Information field, or the Custom Configuration field for the Communications Server Properties.

Parent topic: [logging] 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 , 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:

From Enterprise Server 7.0 Patch Update 2, performance of the mutex-sweep process has been improved. Micro Focus recommends that you do not use this setting to disable the mutex sweep.

This sweep is a defensive measure that is typically 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.

Typically, it is not recommended to change this setting. In cases when there is a very busy enterprise server instance, the sweep might cause MFCS to fall behind in task processing, causing a gradual drop in throughput. In this case, 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

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


Idle conversation check

The Micro Focus Communications Server (MFCS) periodically tests idle conversations to ensure that they are still valid. A conversation is classified as "idle" if it is waiting for further processing by Enterprise Server, for example, because all Service Execution Processes (SEPs) are busy. If a conversation is waiting for data from the client, it is not idle but in receive state, where conversation closure or failure is normally determined quickly.

The tests performed by MFCS for idle conversations do not involve sending any data to the peer, and will not cause issues for any peer applications.

By default, tests are performed every 15 seconds. There are two types of tests:

  • The error test checks to see if any error conditions have been posted for the conversation by the communications stack.
  • The readability test checks to see if the conversation is readable, and if so, attempts to receive data from it.

Aspects of the idle conversation check can be customized. See [idle check] Section for more information.

Parent topic: Editing Communications Settings
Related reference
[idle check] Section


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 by its conversation type.

For some conversation types, you can enable the Legacy Micro Focus Application Format setting. It is automatically enabled for some types. Where the option is available, it should only be checked for certain cases described in the topics for specific conversation types.

  • CICS Transaction Gateway conversation type
  • DCAS conversation type
  • Fileshare conversation type
  • MSS Inter-System Communication conversation type
  • MSS Inter-System Communication (inbound only) conversation type
  • Remote File Access conversation type
  • SOAP /J2EE (legacy) conversation type
  • TN3270 conversation type
  • Web conversation type
  • Web Services and J2EE conversation type
Parent topic: Configuring Client-Server Communications


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


timeout

Syntax:

timeout=number-of-seconds

Properties:

Default: Timeout for the communications process, which is 7200 seconds (two hours)
Parent topic: CICS Transaction Gateway conversation type
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) 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: CICS Transaction Gateway conversation type
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) 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: CICS Transaction Gateway conversation type
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) 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: CICS Transaction Gateway conversation type
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type


file

Syntax:

file=pathname

Properties:

Default: Trace messages are written to the MFCS log (as HTML).
Parent topic: CICS Transaction Gateway conversation type
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) conversation type


DCAS conversation type

The DCAS connector checks the configuration options when started and when modified. Changes affect current and new conversations.

[Certificate]
certificate directory=certificate-mapping-directory
[Operation]
allow unauthenticated clients=unauthenticated-clients-option
allowed formats=allowed-DCAS-request-formats
check client authorization=client-authorization-option
check user authorization=user-authorization-option
fingerprint algorithm=encryption-algorithm
fingerprint fallback=use-secondary-algorithm
pad with spaces=yes|no
[Tracing]
trace=trace-level
[Operation]
userid source=registration|cn|cn fallback
map CN=yes|no
fold CN to uppercase=yes|no
Note: For the DCAS conversation type, the section names (Certificate, Operation, and Tracing) can be preceeded by "DCAS", as in DCAS Certificate. This permits configuring internal DCAS in a TN3270 listener's configuration. See DCAS Security and TN3270 conversation type for more information.
  • certificate directory
    Specify the directory where the certificate-to-user mappings have been stored.
  • allow unauthenticated clients
    Controls whether clients must be authenticated with a certificate
  • allowed formats
    Specifies what formats of DCAS packets this listener accepts.
  • check client authorization
    Enables or disables the client authorization check
  • check user authorization
    Enables or disables the user authorization check
  • fingerprint algorithm
    Specifies the algorithm used to generate the fingerprints of certificates.
  • fingerprint fallback
    Specifies whether to attempt to use a default fallback algorithm for certificate fingerprints
  • pad with spaces
    Specifies whether user IDs shorter than 8 characters will be padded with EBCDIC space characters in the DCAS response message.
  • trace
    Specifies the trace level.
  • userid source
    Specifies whether Enterprise Server user IDs for Format 1 requests are taken from the certificate registration files or from the certificates themselves.
  • map CN
    Enables ESF name mapping for certificate common names.
  • fold CN to uppercase
    Enables converting certificate common names to uppercase.
Parent topic: Configuring Listener Conversation Types
Related concepts
Configuring a region for Express Logon Feature
TN3270 conversation type
Configuring a region for Express Logon Feature
Configuring a region for Automated Sign-On for Mainframe


certificate directory

Syntax:

certificate directory=certificate-mapping-directory

Parameters:

certificate-mapping-directory Specify the directory where the certificate-to-user mappings have been stored.

Properties:

Default: None

Comments:

This sets the directory that the DCAS listener looks in to find certificate mapping information, used for ELF logins to map the user's certificate to the username.

Parent topic: DCAS conversation type
Related concepts
fingerprint algorithm


allow unauthenticated clients

Syntax:

allow unauthenticated clients=unauthenticated-clients-option

Parameters:

unauthenticated-clients-option If this is set to “yes”, clients may connect without a client certificate, or with a client certificate which is not registered with Enterprise Server. (If the client sends a certificate, it must still be signed by a Certificate Authority in the DCAS listener's CA root file.)

Properties:

Default: Require a registered client certificate
Note: Enabling this option is a security risk, but restores the behavior of earlier versions of Enterprise Server. Customers using DCAS and upgrading from an earlier version may wish to set this option for backward compatibility until they have an opportunity to assess the security of their DCAS configuration. See the topic DCAS Security for more information.
Parent topic: DCAS conversation type
Related concepts
DCAS Security


allowed formats

Syntax:

allowed formats=allowed-DCAS-request-formats

Parameters:

allowed-DCAS-request-formats Specifies the formats of requests that this listener accepts.

Properties:

Default: | both
Values: | 1, 2, both

Comments:

This setting constrains the DCAS listener to process just Format 1 or Format 2 requests. This could be used to configure two separate DCAS listeners, one for each type of request.

Format 1 requests are used by ELF to map a certificate to a username and passtoken. Format 2 requests are used by Automated Sign-On for Mainframe to return a passtoken for a user that has already been verified.

To avoid unnecessary security risks, Micro Focus recommends configuring this option if you only need to support one type of DCAS request. Also note that if you are using DCAS only for TN3270 ELF, you no longer need a DCAS listener. See DCAS Security for more information.

Parent topic: DCAS conversation type
Related concepts
DCAS Security


check client authorization

Syntax:

check client authorization=client-authorization-option

Parameters:

client-authorization-option If this is set to "yes" or "1", client authorization for DCAS is checked.

Properties:

Default: | no
Values: | No, 0, Yes, 1

Comments:

This setting can be used to enable the optional client-authorization check that DCAS normally makes before requesting a passticket for the user. This feature requires the check user authorization setting also be enabled (this is the default).

The main function of the DCAS service is to ask the External Security Facility to create a passticket (temporary password) for a user. The DCAS user authorization check, which is enabled by default, queries the security system to see whether the user identified by the request is allowed to use passtickets. The client authorization check, which is enabled using this setting, checks whether the certificate sent by the client as part of its connection to the DCAS listener is allowed to use DCAS.

In other words, client authorization restricts who can make DCAS requests, while user authorization restricts for whom they can be made. The client authorization check is made in the name of the requested user, so it can also be used to restrict which users can be granted a passticket when a request is made by a particular client.

If this setting is enabled then before requesting the passticket, DCAS will make an ESF Authorization request using the request user ID. The resource name will be the Subject Distinguished Name from the client certificate and the resource class is DCASCCRT. The user must have Read access to this resource for a Format 1 (ELF) request, or Control access for a Format 2 (Automated Sign-on for Mainframe) request; otherwise the DCAS request is rejected. If this setting is enabled and the DCASCCRT resource class does not exist, all DCAS requests will be rejected.

The DCASCCRT resource class is not defined in the sample LDAP security definitions included with Enterprise Server. To make this authorization check useful you must define the DCASCCRT class and create suitable resource access rules in it.

For additional DCAS security, enable this option and configure the PTKTDATA resource class rules for your environment. See DCAS Security for more information.

Example:

Suppose you have a region that will use DCAS with TN3270 ELF for one set of users, and you also have another specialized application which uses DCAS Format 2 requests to sign on any of a small group of special users. The ELF users are all issued personal certificates with Subject DNs that include O=My Company Inc (an Organization element) and OU=ELF Users (an Organizational Unit). So these users can be recognized by these elements in their client certificate subject names.

Meanwhile, anyone who has a company client certificate can use DCAS for the specialized application, but only to create passtickets for user IDs that are members of the SPECAPP user group.

You could enable the client authorization check and create the following rules in the DCASCCRT resource class:

Rule name | Access control entry | Comment
**/O=My Company Inc/OU=ELF Users/** | allow:*:read | Anyone who connects to DCAS with a client certificate with a name matching this pattern can make a Format-1 request
**/O=My Company Inc/** | allow:SPECAPP group:control | Anyone with a client certificate issued by our company can create a passticket for a user ID in the SPECAPP group

Creating rules for the DCASCCRT class may require some planning, but it allows fine-grained control over the parameters of permitted DCAS requests.

Note: The Subject DN format used for DCASCCRT rule names is in the OpenSSL "compatible" format. You can display a certificate's Subject DN in this format using the openssl utility, for example:
openssl x509 -in file.pem -noout -subject -nameopt compat

The cascertreg utility now also inserts a comment into certificate registration files with the subject in this format.

Parent topic: DCAS conversation type
Related concepts
DCAS Security
Related reference
APPLID template
check user authorization
cascertreg


check user authorization

Syntax:

check user authorization=user-authorization-option

Parameters:

user-authorization-option If this is set to "no" or "0", user authorization for DCAS is not checked.

Properties:

Default: | yes
Values: | No, 0, Yes, 1

Comments:

This setting can be used to disable the user-authorization check that DCAS normally makes before requesting a passticket for the user.

The main function of the DCAS service is to ask the External Security Facility to create a passticket (temporary password) for a user. The user ID either comes from a successful mapping of a client certificate (DCAS Format 1 request) or is supplied by the client (Format 2 request). DCAS requests also contain a string called an APPLID (Application ID) which on the mainframe usually identifies the region the user is attempting to sign on to.

If this setting is enabled (the default) then before requesting the passticket, DCAS makes an ESF Authorization request using the request user ID. The resource name is the APPLID from the request and the resource class is PTKTDATA. This is similar, though not identical, to how the PTKTDATA resource class is used on the mainframe. If the user does not have Update access to this resource, the DCAS request is rejected. If the PTKTDATA resource class does not exist, the request is allowed to proceed. (The passticket request may subsequently be denied by ESF for other reasons, for example because the ESMs configured for the region do not permit passtickets for this user.)

The PTKTDATA resource class is not defined in the sample LDAP security definitions included with Enterprise Server. To make this authorization check useful you must define the PTKTDATA class and create suitable resource access rules in it.

Note: For DCAS Format 1 requests from a TN3270 listener for ELF, the APPLID can be controlled by the TN3270 listener configuration. See TN3270 conversation type. For DCAS Format 2 requests, the APPLID is under the control of the DCAS client. DCAS Format 2 access should be restricted to trusted clients only, such as Host Access Automated Sign-On for Mainframe.

For additional DCAS security, leave this option enabled (or enable it explicitly) and configure the PTKTDATA resource class rules for your environment. See DCAS Security for more information.

Parent topic: DCAS conversation type
Related concepts
TN3270 conversation type
DCAS Security
Related reference
check client authorization


fingerprint algorithm

Syntax:

fingerprint algorithm=encryption-algorithm

Parameters:

encryption-algorithm Specifies the algorithm DCAS uses to generate certificate fingerprints.

Properties:

Default: | SHA1
Values: | MD5, SHA1, SHA224, SHA256, SHA384, SHA512

Comments:

This is the algorithm that the connector uses to generate certificate fingerprints from certificates for Format 1 requests. This is used to look for a certificate mapping in the certificate directory. See certificate directory for more information.
Note: This algorithm must match the one used by cascertreg when it creates the mapping file. See cascertreg for more information.
Parent topic: DCAS conversation type
Related concepts
fingerprint fallback
Related reference
cascertreg
certificate directory


fingerprint fallback

Syntax:

fingerprint fallback=use-secondary-algorithm

Parameters:

use-secondary-algorithm Specifies whether or not to try a secondary fingerprint algorithm.

Properties:

Default: | 0 (no secondary algorithm used.)
Values: | 0, 1, y, Yes, yes

Comments:

Optionally enables a second algorithm to generate certificate fingerprints if the first failed to find a mapping. The algorithm used is SHA1, the default used by cascertreg, see cascertreg for more information.
Note: If fingerprint algorithm is not set or is set to SHA1, setting this option has no effect. See fingerprint algorithm for more information.
Parent topic: DCAS conversation type
Related reference
cascertreg
fingerprint algorithm


pad with spaces

Syntax:

pad with spaces=yes|no

Parameters:

pad with spaces If the option is set to yes, user IDs shorter than 8 characters will be padded with EBCDIC space characters in the DCAS response message. If it is set to no, they will be padded with low-values

Properties:

Default: | no
Values: | yes, no

Comments:

The default value is no. This is to improve interoperability with certain clients. Earlier versions of this feature used space padding exclusively.

Parent topic: DCAS conversation type


trace

Syntax:

trace=trace-level

Parameters:

trace-level Specifies the amount of tracing to include in the log.

Properties:

Default: | 0 (tracing is disabled)
Values: | 0, 1, 2, 3, y, Yes

A trace value of "y" or "Yes" is treated as trace level 2.

Comments:

This enables tracing for this connector, which is written to the Micro Focus Communications Server (MFCS) log. Trace level 1 provides function tracing, including what type of calls are made to ESF. Trace level 2 provides everything level 1 does, along with data tracing, printing out the first 32 bytes of incoming packets and the first 30 bytes of outgoing packets. This ensures sensitive data, such as the certificate and the passtoken, are not printed. Trace level 3 displays some additional information regarding request processing.
Note: For trace level 2, the usernames are displayed. This trace level also emits messages regarding the format of the incoming certificate. All non-recoverable errors are printed in all cases.
Parent topic: DCAS conversation type


userid source

Syntax:

userid source=source-setting

Parameters:

source-setting If this is set to registration , certificate registration files are used to map certificates to Enterprise Server user IDs. If it is set to cn , the common name attribute of the certificate's Subject Distinguished Name is extracted and used as the user ID (or user "long name" if name mapping is enabled with the map CN option). If it is set to cn fallback , a registration is used if one exists; otherwise the certificate subject CN is used.

Properties:

Default: | registration
Values: | registration, cn, cn fallback

Comments:

This setting determines how the DCAS listener determines what Enterprise Server user ID is returned for a successful Format 1 request. The default is to look for a certificate mapping file for the certificate, and get the user ID from that; this was the behavior of earlier versions of the DCAS connector.

The cn and cn fallback options let DCAS get the user ID from the certificate itself, specifically from the CN component of the certificate's Subject Distinguished Name, possibly after passing it through ESF name mapping. If the certificate does not have a CN in its Subject name, the request is rejected.

Using the certificate as the user ID source can be useful if you wish to avoid provisioning certificate mappings.

Parent topic: DCAS conversation type


map CN

Syntax:

map CN=yes|no

Parameters:

yes|no If this is set to yes, the value of the CN is submitted to the External Security Facility's name mapping procedure, as if it were a "long name", to be converted to an Enterprise Server user ID. The effect of name mapping depends on the security configuration.

Properties:

Default: | no
Values: | yes, no

Comments:

This setting only affects Format 1 requests, and only if userid source is set to cn or cn fallback.

If it is enabled, then after the CN value has been extracted from the certificate, it undergoes long-to-short name mapping. The default mapper truncates names to 8 characters and removes characters not permitted in Enterprise Server user IDs, but another mapper can be enabled by the security configuration.

This setting can be useful if you wish to use the certificate as the user ID source, but have certificates with CNs that cannot be used directly as Enterprise Server user IDs.

Parent topic: DCAS conversation type


fold CN to uppercase

Syntax:

fold CN to uppercase=yes|no

Parameters:

yes|no If this is set to yes, convert the value of the CN to uppercase before returning it in the DCAS response message.

Properties:

Default: | no
Values: | yes, no

Comments:

This setting only affects Format 1 requests, and only if userid source is set to cn or cn fallback.

If it is enabled, then the CN value is converted to uppercase. This can be useful for mainframe compatibility, or if the ESM Module that performs user verification treats user IDs as case-sensitive.

Parent topic: DCAS 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


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
synchronous=synchronous-option

[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.
  • synchronous
    Enables synchronous processing for inbound ISC conversations.
Parent topic: Configuring Listener Conversation Types


synchronous

Syntax:

synchronous=synchronous-option

Parameters:

synchronous-option If this is set to yes or 1 MFCS will use a dedicated thread for each inbound ISC conversation. This consumes more resources but provides shorter latency (faster response time) for ISC request processing.

Properties:

Default: By default this option is disabled.
Parent topic: MSS Inter-System Communication conversation type
Parent topic: MSS Inter-System Communication (inbound only) 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 the one used for outbound connections (usually named MF MTO Inter-System Communication). A communications process may have multiple ISC listeners, but only one will be used for outbound connections.

[Operation] changes take effect for the conversations that commence after you make changes, but not for existing conversations.

[Trace] changes take effect for both new and existing conversations.

[Operation]
timeout=number-of-seconds
synchronous=synchronous-option

[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.
  • synchronous
    Enables synchronous processing for inbound ISC conversations.
Parent topic: Configuring Listener Conversation Types


Remote File Access conversation type

This conversation type is used for Remote File Access (RFA), including any of:

  • Remote access to normal filesystem files.
  • Local and remote access to the Enterprise Server JCL spool and cataloged datasets
  • Local and remote access to the COBOL File Service, used by the IDE-integrated COBOL data file editor.

The [Allowed paths] section is required, as RFA will not permit any file access except for paths that are listed under Allowed paths. Other sections are optional.

Micro Focus recommends that customers using RFA consider using the access and allow feature options in the [Security] section to disable any RFA features they do not need, for additional security. The [Denied paths] section is primarily useful to remove access to specific subdirectories under an area that is listed in [Allowed paths], should that be necessary. The remaining options are for convenience or diagnostics.

The RFA connector checks the configuration options when started and when modified. Changes affect current and new conversations.

[Filter Options]
parser trace=yes|no
debug rules=yes|no
[Tracing]
trace=trace-level
[Sessions]
lifetime=seconds
idle timeout=seconds
[Security]
access={read,update,alter}
origin check=no|none|loose|strict
allow feature=yes|no
[Allowed Paths]
path-element
[Denied Paths]
path-element
  • parser trace
    Trace allow and deny rule parsing
  • debug rules
    Trace the application of allow and deny rules
  • trace
    Specifies the trace setting.
  • lifetime
    Sets the session maximum lifetime
  • idle timeout
    Sets the session idle timeout
  • access
    Sets the overall maximum access level provided by the listener
  • origin check
    Configures the HTTP origin check
  • allow feature
    Restrict which RFA features are enabled
  • path-element of Allowed Paths
    Specify an allowed path and optionally a mapping
  • path-element of Denied Paths
    Specify a denied path
Parent topic: Configuring Listener Conversation Types
Related concepts
Enhanced security for HTTP and MFBINP


parser trace

parser trace=yes|no

Parameters:

parser trace
If the option is set to yes, information about parsing the rules in [Allow Paths] and [Deny Paths] will be written to the Communications Process log.

Properties:

Default:
no (tracing is disabled)
Values:
yes, no
Parent topic: Remote File Access conversation type


debug rules

debug rules=yes|no

Parameters:

debug rules
If the option is set to yes, information about applying the rules in [Allow Paths] and [Deny Paths] to requests will be written to the Communications Process log.

Properties:

Default:
no (tracing is disabled)
Values:
yes, no
Parent topic: Remote File Access conversation type


trace

Syntax:

trace=trace-setting

Parameters:

trace-setting Specifies the trace setting

Properties:

Default: | 0
Values: | 0, 1, 2, 3, y

Comments:

The trace-setting can be an integer or string. The value "0", or any unrecognized value, disables tracing. Values 1, 2, and 3 enable progressively more verbose tracing. A string beginning with "y" is equivalent to the value 2, medium tracing.

Parent topic: Remote File Access conversation type
Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


lifetime

lifetime=seconds

Parameters:

seconds
Specifies the maximum lifetime of an RFA session in seconds. Any session older than this time will be closed during periodic session cleanup, regardless of how recently it has been active.

Properties:

Default:
43200 (12 hours)
Values:
1-2147483647
Parent topic: Remote File Access conversation type


idle timeout

lifetime=seconds

Parameters:

seconds
Specifies the maximum idle time of an RFA session in seconds. Any session which has been idle for longer than this period will be closed during periodic session cleanup.

Properties:

Default:
600 (10 minutes)
Values:
1-2147483647
Parent topic: Remote File Access conversation type


access

access={read,update,alter}

Parameters:

access
Lists one or more tokens (separated by commas and/or spaces) that enable a form of access. Tokens are case insensitive.

The possible access types are:

read
Allows read access to files.
update
Allows write access to existing files.
alter
Allows creating new files.

Properties:

Default:
read, update, alter
Values:
Any or all of: read, update, alter

Comments:

The access security configuration option is useful as a defensive measure if an RFA listener is only intended for read-only or update access to files. Some sites might have multiple RFA listeners, where some have read-only access (to allowed paths) and are broadly available, while others have update or alter access but are more tightly restricted.

The access level specified with this option is a maximum: other security checks, such as the ESF Authorization checks against the PHYSFILE class if external security is configured, can further restrict access, but they cannot grant permission that is denied by the access configuration setting.

Note: This setting applies to native file access and dataset access. Spool access is always read-only; denying read access with this setting will prevent retrieving spooled data. This setting does not apply to COBOL File Service access, which is used by the new IDE-hosted COBOL data file editor.

Example:

The following restricts the listener to read-only access, regardless of other security rules:

[Security]
access=read
Parent topic: Remote File Access conversation type


origin check

origin check=no|none|loose|strict

Parameters:

origin check
This option can be set to one of the following options:
no or none
No origin check is performed on requests.
loose
A request is permitted if the source or target origin match, or either origin is missing or opaque (the origin string is "null"). This will block browser-based Cross-Site Request Forgery (CSRF) attacks, including Javascript ones.
strict
Requests with missing or opaque source or target origin are also blocked.

Properties:

Default:
loose
Values:
no, none, loose, strict

Comments:

The origin check on HTTP requests is a recommended practice for defense against Cross-Site Request Forgery (CSRF). In practice, it is difficult to mount a CSRF attack against an RFA listener because RFA is not normally used from a browser, and browsers are usually required for CSRF. However, RFA includes the origin check as a defense-in-depth measure. Usually customers will not need to change this setting. It can be set to strict for additional protection if its clients are rigorous about setting origin properly, typically with the HTTP Origin and Host headers, or to none if non-compliant clients cause problems with requests being rejected by the origin check.

Parent topic: Remote File Access conversation type


allow feature

allow file access=yes|no
allow spool access=yes|no
allow catalog access=yes|no
allow COBOL file service=yes|no
allow lock service=yes|no
allow API documentation=yes|no

Parameters:

allow feature
If the option is set to yes, the specified feature is enabled. If it is set to no, the feature is disabled.

The available features are:

file access
Access to regular files using filesystem paths, possibly mapped using allow rules.
spool access
Access to spooled output datasets created by JES jobs.
catalog access
Access to cataloged datasets.
COBOL file service
Access to the COBOL file service, which is used by the IDE-hosted COBOL data file editor.
lock service
Access to the enterprise server spool/catalog lock service. This must be enabled for spool and catalog access; if it is disabled, those features will also be disabled.
API documentation
Access to the online RFA API documentation through the RFA listener.

Properties:

Default:
yes (all features are enabled)
Values:
yes, no

Comments:

For enterprise server instance with one or more RFA listeners, you can use these configuration settings to disable features you do not need. Doing so improves security.

Example:

[Security]
allow COBOL file service=no
allow API documentation=no
Parent topic: Remote File Access conversation type


path-element of Allowed Paths

 virtual-wildcard-path[=file-system-path]

Parameters:

virtual-wildcard-path
A path that will be matched against the path specified in the HTTP request. This can contain wildcards as described below. On Windows, slashes or backslashes can be used as path separators.
file-system-path
Optional: The path in the filesystem which the initial non-wildcard part of the virtual path is mapped to. If this is omitted, the filesystem path is the same as the virtual path. In this case, omit the = character.

The available wildcards are:

*
Matches any number of any characters except the path separator / (UNIX) or \ on (Windows).
**
Matches any number of any characters. This can be interpreted as "include subdirectories".

Properties:

Default:
None; at least one entry under [Allowed Paths] must be configured to use RFA's native file access feature.
Values:
A list of virtual path, usually with wildcards, and each optionally with a filesystem path. Requests containing a path which matches one or more of the allowed paths are permitted to proceed, further security checks might apply. If more than one virtual path matches, the best match will determine which filesystem path the request will be mapped to.

Comments:

Entries under [Allowed Paths] affect RFA access to normal filesystem files. They do not affect spool, dataset, or COBOL file service operations.

By default, no paths are allowed; so to use RFA to retrieve, alter, or create normal files on the remote system, you must configure at least one allowed-path element.

It is common to end a virtual path with * or possibly an expression such as *.txt to indicate it matches all or some files in the target directory. End a virtual path with **, for example **.dat to include subdirectories.

The filesystem-path part of each element is optional, but Micro Focus recommends using it, to provide an abstraction that lets you relocate the target files without changing clients, and to hide information about the filesystem.

Example:

[Allowed paths]
/reports/*.txt=/home/app/output
/docs/reference/**=/opt/refdocs/public
Parent topic: Remote File Access conversation type


path-element of Denied Paths

 virtual-wildcard-path

Parameters:

virtual-wildcard-path
A path that will be matched against the path specified in the HTTP request. This can contain wildcards as described below. On Windows, slashes or backslashes can be used as path separators.

The available wildcards are:

*
Matches any number of any characters except the path separator / (UNIX) or \ on (Windows).
**
Matches any number of any characters. This can be interpreted as "include subdirectories".

Properties:

Default:
None. Paths which do not match those listed in [Allowed Paths] are denied by default, as if the element ** was specified in the [Denied Paths].
Values:
A list of virtual path, usually with wildcards, and each optionally with a filesystem path. Requests containing a path which matches one or more of the denied paths are not permitted to proceed, unless there is an [Allowed Paths] rule which is a better match

Comments:

Entries under [Denied Paths] affect RFA access to normal filesystem files. They do not affect spool, dataset, or COBOL file service operations.

Paths which do not match any of the [Allowed Paths] are denied by default, so [Denied Paths] is only required if you need to block access to some files or directories within an area that is otherwise allowed.

It is common to end a virtual path with * or possibly an expression such as *.txt to indicate it matches all or some files in the target directory. End a virtual path with **, for example **.dat to include subdirectories.

When multiple allowed and/or denied paths match, the outcome is determined by the best (closest) match. Closeness is determined by how many characters in the source path have to be matched by a wildcard. So, for example, if the paths /top/** and /top/next/** both match, the latter would take precedence, for the allow/deny result and for optional path mapping (for an allowed path).

Example:

[Allowed paths]
/docs/reference/**=/opt/refdocs/public

# Don't permit access to git files
[Denied paths]
/docs/reference/.git*
/docs/reference/**/.git*
Parent topic: Remote File Access conversation type


SOAP /J2EE (legacy) conversation type

The SOAP /J2EE (legacy) conversation type accepts the following configuration options which are all case-insensitive:

[Tracing]
trace=trace-setting

[Operation]
timeout=timeout-seconds
maximum timeout=max-seconds
infinite timeout=inf-seconds
async send=async-setting
automatic discard=discard-setting
force persistent=force-setting
client closes=close-setting

[MFBINP]
header=header-type
Note: The SOAP / J2EE (legacy) conversation type has been superseded by the Web Services and J2EE conversation type, and is only used for compatibility with older server definitions. New servers should use the Web Services and J2EE conversation type for listeners that will handle SOAP, JSON, J2EE, ESMAC, and JES job submission /output retrieval requests. Existing listeners that use the SOAP /J2EE (legacy) conversation type can be updated to use Web Services and J2EE.
  • trace
    Specifies the trace setting.
  • header
    Configures the type of MFBINP header to send to the client.
  • timeout
    Specifies the timeout for the HTTP conversation.
  • maximum timeout
    Specifies the maximum timeout for MFBINP conversations.
  • infinite timeout
    Specifies an infinite timeout for the MFBINP protocol.
  • automatic discard
    Enables the auto-discard mode.
  • force persistent
    Enables force-persistence mode.
  • client closes
    Enables the client-closes mode.
  • async send
    Forces all outbound data to be sent asynchronously.
Parent topic: Configuring Listener Conversation Types


header

Syntax:

header=header-type

Parameters:

header-type Specifies the type of MFBINP header to send

Properties:

Default: | Send a normal header
Values: | simple

Comments:

If header-type is simple, only a minimal MFBINP header is sent to the client. This option should only be enabled on instruction from OpenText Support for Micro Focus Products.

Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


timeout

Syntax:

timeout=timeout-seconds

Parameters:

timeout-seconds Specifies the timeout for the HTTP communications process.

Properties:

Default: 3600 seconds (1 hour).

Comments:

Specifies the value for HTTP conversations and the default timeout for MFBINP conversations, if the client did not request a different timeout value.
Note: MFBINP conversations include J2EE services and various Enterprise Server operations such as submitting JCL.
Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


maximum timeout

Syntax:

maximum timeout=max-seconds

Parameters:

max-seconds Specifies the maximum timeout for MFBINP conversations, if the client did request a specific timeout.

Comments:

If the client requests a timeout greater than max-seconds, MFCS uses max-seconds instead. If this configuration parameter is not specified or set to 0, MFCS uses the timeout requested by the client.

Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


infinite timeout

Syntax:

infinite timeout=inf-seconds

Parameters:

inf-seconds If this is set to 0, MFCS will allow infinite timeouts - conversations that are never timed out.

Properties:

Default: 86400 seconds (one day).

Comments:

If the infinite timeout configuration option is used, MFCS sets a timeout of inf-seconds when the client requests an infinite timeout.

Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


automatic discard

Syntax:

automatic discard=discard-setting

Parameters:

discard-setting Enables the auto-discard mode.

Properties:

Default: | N/A
Values: | A string beginning with "y" or "1".

Comments:

Lets MFBINP clients switch MFBINP session IDs during a conversation without explicitly closing the old session.

This setting should only be necessary if an MFBINP client incorrectly creates multiple sessions without closing old sessions when they are no longer needed. Sometimes this issue is encountered with Enterprise Java Beans (EJBs) that use the Enterprise Server connector module to make persistent requests to COBOL EJBs running under Enterprise Test Server. In this case you may observe a gradual increase in the memory used by the mfcs process and a progressive decline in performance. It is usually safe to use this option unless you have an EJB which deliberately switches between two or more sessions; this is very unusual.

Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


force persistent

Syntax:

force persistent=force-setting

Parameters:

force-setting Enables the force-persistence mode.

Properties:

Default: | Disabled
Values: | A string beginning with "y" or "1" to enable.

Comments:

When enabled, MFCS attempts to make all MFBINP conversations persistent, even if the client did not request it.
Note: You should only enable this when instructed to do so by OpenText Support for Micro Focus Products.
Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


client closes

Syntax:

client closes=close-setting

Parameters:

close-setting Enables the client-closes mode.

Properties:

Default: | N/A
Values: | A string beginning with "y" or "1".

Comments:

If this is enabled, MFCS expects the client to close the conversation; it does not automatically close it when the session terminates. This can be used by clients that want to make multiple independent requests. Normally, clients that make multiple requests do so within a single session, using a dedicated SEP process. With this setting it is possible to have clients that make multiple unrelated requests in a single conversation, handled by normal SEPs, with no transactional relationship. This lets the clients sustain a higher rate of processing.

Parent topic: SOAP /J2EE (legacy) conversation type
Parent topic: Web Services and J2EE conversation type


async send

Syntax:

async send=async-setting

Parameters:

async-setting Enables the async-only send mode.

Properties:

Default: | N/A
Values: | A string beginning with "y" or "1".

Comments:

If this is enabled, any synchronous sends by CAS are converted to asynchronous sends. This option should only be used when instructed by OpenText Support for Micro Focus Products.

Parent topic: SOAP /J2EE (legacy) conversation type


TN3270 conversation type

The TN3270 connector checks the settings below; changes affect current and new conversations.

[Logging]
client-close=client-close-logging

[Operation]
allow-any-terminal-type=terminal-type-option
default-printer-mode=LU1-or-LU3
default-terminal-type=terminal-type-name
new environ=environ-option
output resets timeout=output-resets-option
printers time out=printers-timeout-option
serialize=serial-option
SGA=suppress-go-ahead-option
timeout=number-of-seconds
TN3270E=negotiation-type
validate=address-validation
[Trace]
trace=control-flow-trace
data=data-trace
length=trace-length
sem=send-semaphore-trace
file=trace-filename
[DCAS]
APPLID template=template
internalinternal-option
name=DcasCtr
  • 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.
  • TN3270E
    Disables Enhanced TN3270 support.
  • file
    Specifies the full path of the file to receive trace messages. The file is written as HTML (unlike the Fileshare and ISC traces).
  • sem
    Enables the tracing of operations on the send semaphore.
  • length
    Specifies the maximum number of data bytes to include in the data trace.
  • data
    Enables data tracing.
  • trace
    Enables the tracing of control flow in the connector.
  • allow-any-terminal-type
    Enables use of non-standard terminal-type strings.
  • default-printer-mode
    Sets default printer mode.
  • new environ
    Disables the TN3270E NEW-ENVIRON request.
  • serialize
    Serializes certain operations.
  • validate
    Disables address validation.
  • SGA
    Enables sending the Suppress Go-Ahead option.
  • Output resets timeout
    Allows output (send) operations to count for timeout purposes.
  • Printers time out
    Enables timeouts for printer sessions.
  • APPLID template
    Formats the APPLID for the DCAS request.
  • internal
    Controls how DCAS is invoked for ELF.
  • name
    Specifies the name of the DCAS listener the TN3270 listener uses.
Parent topic: Configuring Listener Conversation Types
Related concepts
Configuring a region for Express Logon Feature
DCAS conversation type
Configuring a region for Express Logon Feature
Configuring a region for Automated Sign-On for Mainframe
Related reference
check user authorization


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)

This property does not apply to printer sessions.

Parent topic: TN3270 conversation type


TN3270E

Disables Enhanced TN3270 support.

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.

Parent topic: TN3270 conversation type


file

Syntax:

file=trace-filename

Properties:

Default: Trace messages are written to the MFCS log (as HTML)
Parent topic: TN3270 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: TN3270 conversation type


length

Syntax:

length=trace-length

Properties:

Default: 40 bytes
Parent topic: TN3270 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: TN3270 conversation type


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: TN3270 conversation type


allow-any-terminal-type

Syntax:

allow-any-terminal-type=terminal-type-option

Parameters:

terminal-type-option If this is set to “yes”, MFCS will not validate the terminal-type string sent by the client against the TN3270E standard. It will simply pass any terminal-type string on to CAS.
Some TN3270 clients, in some configurations, send non-standard terminal-type strings and will require this setting.

Properties:

Default: The terminal-type string sent by the client must be one recognized by MFCS.

Standard terminal types

The standard terminal type strings are:

  • IBM-3278-2, -3, -4, and -5.
  • The same four with -E appended (IBM-3278-2-E and so on).
  • The eight types from 1 and 2 above, but with 3279 in place of 3278 (IBM-3279-2-E and so on).
  • IBM-3287-1. This is only allowed for a printer session, and you must use it for a printer session if allow-any-terminal-type=yes is not specified.
Parent topic: TN3270 conversation type


default-printer-mode

Syntax:

default-printer-mode=LU1-or-LU3

Parameters:

LU1-or-LU3 The values LU1 and SCS set the default printer mode to SNA Character Stream (SNA LU1 printing). The values LU3 and 3270 set it to 3270 datastream (SNA LU3) printing.

Properties:

Default: The default printer mode is 3270 Datastream.

TN3270E clients may support either or both of two types of printer data streams: SCS (LU1) and 3270 (LU3). The type of printer required depends on the migrated mainframe application.

During TN3270E negotiation a printer session will identify which print mode or modes it supports. If an application sends output to a printer session that supports both modes, and CAS cannot determine which printer type the application expects, then the value of default-printer-mode is consulted to determine how to identify the data to the client.

Parent topic: TN3270 conversation type


new environ

Syntax:

new environ=environ-option

Parameters:

environ-option If this is set to no, MFCS will not attempt to negotiate the TN3270 NEW-ENVIRON option.

NEW-ENVIRON is required for ELF (TN3270 Express Logon Facility). Most clients support it regardless of whether ELF is used, but some clients may not handle it correctly. In that case, the new environ setting may be used to disable it.

Parent topic: TN3270 conversation type


serialize

Syntax:

serialize=serial-option

Parameters:

serial-option If this is set to yes, certain operations will be serialized. This should only be configured on instruction from OpenText Support for Micro Focus Products.
Parent topic: TN3270 conversation type


validate

Syntax:

validate=address-validation

Parameters:

address-validation If this is set to no, MFCS will not attempt to validate addresses returned by CAS. This should only be configured on instruction from OpenText Support for Micro Focus Products.
Parent topic: TN3270 conversation type


SGA

Syntax:

SGA=suppress-go-anead-option

Parameters:

suppress-go-abead-option If this is set to yes, MFCS will send the TN3270 WILL SGA command to the client. As some clients do not handle this command correctly, and it is usually not necessary, it is disabled by default. This should only be configured on instruction from OpenText Support for Micro Focus Products.
Parent topic: TN3270 conversation type


Output resets timeout

Syntax:

Output resets timeout=yes

Properties:

Default: no (only input resets the timeout timer)

By default, the TN3270 session timeout is based on the time since the last message was received from the client. See the Timeout topic for more information.

When this option is enabled, the timeout timer for a session is restarted each time either data is received from the client, or data is sent to it. It is particularly useful for printer sessions, or for terminal sessions that are used mostly to display output from long-running programs.

Parent topic: TN3270 conversation type


Printers time out

Syntax:

Printers time out=yes

Properties:

Default: no (printers do not time out)

Normally, the TN3270 session timeout applies only to terminal sessions, not printer sessions. Use this option to enable timing out for printers as well. See the Timeout topic for more information.

By default, the TN3270 session timeout is based on the last time data was received by the client, and printer sessions are usually output-only, so they would time out and be closed when the timeout expired, regardless of whether they were in use. There are two options for preventing active printer sessions from timing out:

  • Configure your TN3270 client software to send a Telnet keepalive (also known as a heartbeat) flow periodically, so Enterprise Server knows the client is still connected. In Micro Focus Rumba+ Desktop 10.2 SP2, for example, this is the Send NOP option. Note that this must be a Telnet keepalive, not a TCP keepalive.
  • Enable the Output resets timeout option. When this is enabled, the timeout period is restarted each time data is received from the client or sent to the client. In this mode, print operations to a printer session within the timeout period will prevent it from timing out.
Parent topic: TN3270 conversation type


APPLID template

Syntax:

APPLID template=template

Parameters:

template A string with optional substitution tokens {0} and/or {1}

Properties:

Default: | empty (equivalent to {0})
Values: | See below

Comments:

This setting can be used to control the APPLID passed to DCAS for ELF requests. This is useful if the optional PTKTDATA authorization check is enabled in DCAS. See check client authorization under DCAS conversation type for more information about this feature.

The template parameter is used to format the APPLID for the DCAS request. It may contain the following substitution tokens:

Token | Replaced with
{0} | The APPLID string supplied by the TN3270 client using the Telnet NEW-ENVIRON command. If the client did not specify an APPLID, the region name is used.
{1} | The region name.
{n} (n any other digit) | An empty string.
Note: If the client does send an APPLID using the TN3270 NEW-ENVIRON command, the TN3270 listener will force it to conform to the IBM VSAM name rules:
  • All characters not in the permitted character set are removed. The permitted characters are ASCII letters, digits, and the punctuation characters "@", "#", and "$".
  • Letters are folded to uppercase.
  • The resulting name is truncated to 8 characters.

The APPLID template can include characters not permitted in VSAM names, such as "-". This makes it impossible for a client to forge an APPLID that matches one produced by the template.

Examples:

The following setting:

[DCAS]
APPLID template={1}

would ignore the APPLID sent by the client and always use the region name as the APPLID for the DCAS request. This would be useful if the PTKTDATA resource class has been configured to control DCAS access by region name.

The following setting:

[DCAS]
APPLID template={1}-{0}

would make TN3270 use an APPLID formed from the region name and then the APPLID sent by the client. So, for example, if the region were named "PROD" and the client sent an APPLID of "CUST", the DCAS request would receive an APPLID of PROD-CUST. More complex APPLID templates like this may be useful for sites where APPLIDs are already in use to access different mainframe applications.

Parent topic: TN3270 conversation type
Related reference
check client authorization


internal

Syntax:

internal=internal-option

Parameters:

internal-option If this is set to 1 or yes, DCAS is invoked internally rather than using a DCAS listener

Properties:

Default: | no
Values: | Yes, Y, 1, No, N, 0

Comments:

When Express Login Facility (ELF) is used with TN3270, and the TN3270 client triggers ELF processing by sending a client certificate during connection establishment and subsequently including an ELF token in the input data stream, the TN3270 listener must make a request to the Digital Certificate Authentication Service (DCAS). In Enterprise Server 5.0 and earlier, it was necessary to define a DCAS listener in the enterprise server region to provide this service. Beginning with Enterprise Server 6.0, the TN3270 listener can instead invoke DCAS directly, without requiring that a listener be defined. This is known as internal DCAS.

We encourage those who use DCAS only for ELF to use internal DCAS. This prevents any possible security issues with having a DCAS listener potentially exposed to hostile clients.

Normally, DCAS is configured using the DCAS listener. When internal DCAS is used, the DCAS configuration can be supplied in the configuration area for the TN3270 listener by prefixing each DCAS section name with "DCAS". For example:

[DCAS Operation]
allowed formats=1
check user authorization=yes

[DCAS Certificate]
certificate directory=/path/to/registration/files

[DCAS Tracing]
trace=1

When internal DCAS is used, the name option in the [DCAS] configuration section has no effect.

Parent topic: TN3270 conversation type


name

Syntax:

name=DcasCtr

Parameters:

name Specifies the name of the DCAS listener this TN3270 listener should use.

Properties:

Default: None. A search is performed to find a DCAS listener.

Comments:

The Express Logon Facility (ELF) lets a TN3270 client automatically log the user on if the TN3270 listener is configured for TLS (SSL) and client certificates are used. To enable ELF, the TN3270 listener must communicate with a DCAS listener. If this setting is not provided, the TN3270 listener searches for the first DCAS endpoint defined in the current Communications Processes and uses that. If there are multiple DCAS listeners with different configurations, set this configuration option to make the TN3270 listener communicates with the listener specified.

Parent topic: TN3270 conversation type


Web conversation type

These options are checked for each request.

[options]
logging=logging-level
[trace]
trace=trace-option
[virtual paths]
<default>=default-directory
element=file-system-path
[allow]
element=list-of-filenames
[security]
restricted=restrict-option
authentication=authentication-types
class=resource-class-name
realm=HTTP-realm

The [options] section has a single setting, logging, which enables additional logging messages when set to "1" or a string beginning with "y". The trace setting in the [trace] section, added in Enterprise Server 5.0, has the same effect; it has been added for consistency with other conversation types.

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.

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

Security for the Web conversation type

Beginning with Enterprise Server 5.0, the Web conversation type supports additional security mechanisms. These are configured in the [security] section. (Administrators should also consider enabling SSL/TLS, using the Enterprise Server firewall mechanism, and restricting Web listeners to the loopback interface. See Security Considerations for Service Deployment.)

The [security] section can contain the following settings:

restricted=restrict-option
If this is set to "1" or a value beginning with "y", deployment is restricted. This means:
  • The Enterprise Server instance must have External Security enabled.
  • Deployment requests must be authenticated. Currently username/password and client certificate authentication are supported.
  • Optionally, deployment requests can also require authorization. An authorization request will be made to the External Security Facility, using the resource class "Enterprise Server Web", the virtual directory from the deployment request, and the appropriate permission ("read" to retrieve deployment logs, "add" and "execute" to add a service). If this class is not defined to the External Security Manager(s), the deployment request is permitted; otherwise, authorization must be granted by ESF or the deployment request will be rejected.
authentication=authentication-types
This configures what types of authentication are permitted for this listener. authentication-types is a list of tokens, separated by spaces or commas. They are case-insensitive. Available values are:
  • MF is a proprietary mechanism for passing username and password. This is used in older versions of Enterprise Server and can be enabled for backward compatibility.
  • HTTP is HTTP Basic Authentication, a standard way to send a username and password.
  • Cert (or Certificate) enables authentication using registered client certificates.
  • Register, like Cert, enables client certificate authentication. It also enables automatic registration of client certificates using HTTP Basic Authentication.
class
Sets the class name to be used when authorizing a deployment request. The default is "Enterprise Server Web". Usually the only reason to set this value is to use different resource control rules for different Web listeners.
realm
Sets the HTTP Realm string for Basic Authentication. The default is "MF Communications Server for region server", where server is the name of the Enterprise Server instance.

For more information on configuring Web security, particularly authentication, see the topic Deployment Listeners.

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


Web Services and J2EE conversation type

The Web Services and J2EE conversation type accepts the following configuration options which are all case-insensitive:

[Tracing]
trace=trace-setting

[Operation]
timeout=timeout-seconds
maximum timeout=max-seconds
infinite timeout=inf-seconds
automatic discard=discard-setting
force persistent=force-setting
client closes=close-setting

[MFBINP]
header=header-type

[Response Headers]
name=value
  • trace
    Specifies the trace setting.
  • sessions
    Specifies the trace setting
  • header
    Configures the type of MFBINP header to send to the client.
  • timeout
    Specifies the timeout for the HTTP conversation.
  • maximum timeout
    Specifies the maximum timeout for MFBINP conversations.
  • infinite timeout
    Specifies an infinite timeout for the MFBINP protocol.
  • automatic discard
    Enables the auto-discard mode.
  • force persistent
    Enables force-persistence mode.
  • client closes
    Enables the client-closes mode.
  • header-name
    Specifies an arbitrary header to HTTP responses sent by this listener.
Parent topic: Configuring Listener Conversation Types
Related concepts
Enhanced security for HTTP and MFBINP


sessions

Syntax:

sessions=trace-setting

Parameters:

trace-setting Specifies the trace setting

Properties:

Default: | 0
Values: | 0,1,y

Comments:

The trace-setting can be an integer or string. The value "0", or any unrecognized value, disables session tracing. A string beginning with "1" or "y" enables trace messages (written to the Communications Process log) regarding MFBINP session processing.

Parent topic: Web Services and J2EE conversation type


header-name

Syntax:

header-name=value

Parameters:

header-name Specifies an arbitrary header to HTTP responses sent by this listener

Comments:

The Response Headers section is optional. It may be used to add arbitrary headers to HTTP responses sent by this listener. For example:

[Response Headers]
X-my-header=some string

would cause all responses to include:

X-my-header: some string

See HTTP Strict Transport Security for another example.

Parent topic: Web Services and J2EE conversation type


Conversation Filtering

Enterprise Server provides you with a conversation filter or "firewall" feature. You can use it to restrict which client systems can connect to an enterprise server region.

Clients are granted or denied a connection based on rules, which apply to a client IP address or hostname. Rules can use wildcards, and the most specific rule that matches the client address or name determines which rule is used. The default action is to grant a connection to unmatched clients. The default behavior can be changed by using a "deny" rule which matches all clients that are not covered by a more specific rule. For example, a generic deny rule for IPv4 connections would be deny:0.0.0.0/0.

Note: This rule would not block IPv6 connections. See Filter Rules for more information.

You can configure rules for the server, each communications process, and each listener. If the best matching listener rule has the same rank (specificity) as the best matching communications process or server rule, then the listener rule takes precedence.

  • Filter Rules
  • Filter Options
  • Example
Parent topic: Configuring Client-Server Communications
Related concepts
DCAS Security


Filter Rules

For each client connection, Enterprise Server scans the rules specified for the endpoint, if there are any, and the rules for the communications process and server, if any. Each of the rules which match the client's IP address, or its fully qualified hostname, if there are any hostname rules, are ranked based on how well the rule matches. A rule with no wildcards and matches is an exact match and overrides any rule containing wildcards. Rules with wildcards are ranked based on how many characters the wildcard replaces; fewer replaced characters means a closer, or more exact match.

For example, if the client's IP address is 192.168.1.100, then for the following rules:

deny:**
This would match with rank 14.
allow:192.168.2.*
This would not match.
allow:192.168.1.*
This would match with rank 4.
Note: Lower rank is a closer match.
deny:192.168.1.100
This would be an exact match, or rank 0.

The result would be that the last rule would be applied to the client and the connection would be denied (blocked).

Note: The rule applied is always selected based on rank. The order of the rules that are specified in the Configuration Information field does not determine rank.

You can configure rules using the Enterprise Server Common Web Administration (ESCWA) interface. Specify the rules in the Configuration Information or Custom Configuration field, in any or all of the following locations:

  • An enterprise server region's General Properties page:
    1. In the ESCWA menu bar, click Native.
    2. In the navigation pane, expand Directory Servers.
    3. Click the enterprise server region you want to configure.
    4. Click General > Properties.
    5. In the Configuration Information field, type the filter rules you want to apply.
    6. Click Apply.
  • The Communications Processes page for the communications process control:
    Note: Rules configured here apply to all listeners under the communications process.
    1. In the ESCWA menu bar, click Native.
    2. In the navigation pane, expand Directory Servers.
    3. Click the enterprise server region you want to configure.
    4. Click General > Listeners.
    5. In the communications process navigation pane, click the communications process you want to configure.
    6. Click Configure to expand the configuration options.
    7. In the Custom Configuration field, type the filter rules you want to apply.
    8. Click Apply.
  • The Communications Processes page for each individual listener:
    1. In the ESCWA menu bar, click Native.
    2. In the navigation pane, expand Directory Servers.
    3. Click the enterprise server region you want to configure.
    4. Click General > Listeners.
    5. In the communications process navigation pane, click the listener you want to configure.
    6. In the Custom Configuration field, type the filter rules you want to apply.
    7. Click Apply.

In the Configuration Information or Custom Configuration field, add the [Connection rules] section header if it does not already exist, and then type your rules. One rule per line. Comments can be added after a hash "#" and can go to the end of the line. Blank lines are also permitted.

The rule options in the connection rules section:

[Connection rules]
action:source[:options]

where:

action
Can be allow or deny.
source
Specifies which clients the rule applies to, described below.
options
Optional - Currently the only option is log, which causes additional logging when the rule applies to a client connection.

The source has four possible forms, which can include the wildcards "*" and "**". The "*" wildcard matches zero or more characters but not the "." character; the "**" wildcard matches anything, including ".". The source forms are:

  • IPv4 address, for example, 192.168.1.2 or 192.**.
  • IPv6 address, for example 2600:1405:1000::17d0:8c09, ::1, or 2600:1405:*.
    Note: IPv6 addresses do not use the "." character, so the "**" wildcard does not need to be used with them.
  • IPv4 CIDR network address, for example, 192.168.1.0/24 or 10/8. Any valid CIDR network length can be used, and trailing 0 octets can be omitted as in the second example.
  • Fully-qualified DNS name, for example, *.opentext.com.

Additional considerations

Micro Focus recommends you do not create rules using DNS names. Such rules are processed using a reverse DNS (PTR record) query, and reverse DNS can be unreliable, insecure, and slow.

Mixing IPv4-address rules and CIDR-network rules might produce unexpected results. Network rules are matched against the binary representation of the IPv4 address, while address rules are matched against the decimal representation. So a network rule such as 192.168/16 is outranked by the address rule 192.**, even though the network rule is technically more specific. Try to avoid ambiguous sets of rules that mix these two forms.

Earlier versions of the product documentation described the source ** as matching all conversations, making it suitable for a generic or default rule. This is not correct. The source ** is interpreted as an IPv4 address (which is all wildcards), so it does not match IPv6 connections. Also, as described above, it might outrank IPv4 CIDR-network rules because it is applied to the decimal representation of the address. The preferred way to specify default behavior, for example to deny all conversations not allowed by a more-specific rule, is with a pair of rules for IPv4 (using CIDR) and IPv6:

deny:0.0.0.0/0
deny:[*]

The first rule blocks IPv4 connections that do not match any allow rules; the second blocks IPv6 connections that do not match any allow rules.

Parent topic: Conversation Filtering


Filter Options

Configuration options can be specified in the Configuration Information field for the server or communications process:

[Filter options]
parser trace={yes|no}
debug rules={yes|no}
  • parse trace
    Enables the parse trace mode.
  • debug rules
    Enables the debug rules mode.
Parent topic: Conversation Filtering


parse trace

Syntax

parser trace={yes|no}

Parameters

parse trace Enables the parse trace mode.

Properties

Default: | Disabled
Values: | "yes" to enable and "no" to disable.

Comments

When enabled this option outputs messages in the CS Console log as filter rules are parsed during start up. This option can assists you with debugging problems with rule syntax.

Parent topic: Filter Options


debug rules

Syntax

debug rules={yes|no}

Parameters

debug rules Enables the debug rules mode.

Properties

Default: | Disabled
Values: | "yes" to enable and "no" to disable.

Comments

When this option is enabled it produces a number of messages in the CS Console as each client connection is tested against the available rules. This option produces a significant amount of output. Micro Focus recommends you disable this option on a busy system.
Parent topic: Filter Options


Example

The Configuration Information field of a server or communications process might contain:

# Enable client connection filtering
[Connection rules]
deny:**                    # deny all clients by default
allow:10/8                 # allow internal network 10
allow:192.168.1.10*        # allow 192.168.1.100 - 192.168.1.109
deny:dmz.mycorp.com:log    # block and log cconnections from DMZ

[Filter options]
parser trace=yes
debug rules=no

Individual listeners might have their own rules to augment or supersede the global rules. For example, in the configuration for the Web listener:

# Restrict access to program deployment to 192.168.1.10*
[Connection rules]
deny:10/8

When the best-ranked listener rule conflicts with a global rule at the same rank, as with the two rules for 10/8 here, the listener rule takes precedence. In this case, the listener's clients in the 10/8 network (any client with an IP address beginning with 10) would not be allowed to connect.

Parent topic: Conversation Filtering


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
  • Supported IBM MQ APIs
    A number of IBM MQ APIs are supported in Enterprise Server.
  • WebSphere MQ Environment Variables
    Lists environment variables related to configuring the WebSphere MQ environment.
  • MQ Monitoring User Exit
    The following user exit can be used to monitor MQ connections.
Parent topic: Enterprise Server configuration and administration


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


Supported IBM MQ APIs

The following IBM MQ APIs are supported in Enterprise Server:

  • MQBACK
  • MQBEGIN
  • MQBUFMH
  • MQCLOSE
  • MQCMIT
  • MQCONN
  • MQCONNX
  • MQCRTMH
  • MQDISC
  • MQDLTMH
  • MQDLTMP
  • MQGET
  • MQINQ
  • MQINQMP
  • MQMHBUF
  • MQOPEN
  • MQPUT
  • MQPUT1
  • MQSET
  • MQSETMP
  • MQSUB

Please refer to the IBM documentation for full details of each API call.

Parent topic: Configuring Enterprise Server for IBM WebSphere MQ


WebSphere MQ Environment Variables

Attention: 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 OpenText Support for Micro Focus Products.
Parent topic: Configuring Enterprise Server for IBM WebSphere MQ
Related tasks
To create an XA resource for a trigger monitor
Related information
XAR for WebSphere MQ
XA Resource Manager Definition for WebSphere MQ


MQ Monitoring User Exit

The following user exit can be used to monitor MQ connections.

The user exit module must be called ES_MQMONEX and placed in your product's %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory:

       identification division.
       program-id. ES_MQMONEX.

      *****************************************************************
      *** Example MQ monitoring exit.                               ***
      *** Stores a table of object handles and their names.         ***
      *****************************************************************

       environment division.
       configuration section.

       data division.
       working-storage section.

       78 78-exit-version                      value 1.

       *> -- Flag to enable initialisation on first call
       01 ws-initialised-flag                  pic x value 'n'.
          88 ws-initialised-88                 value 'y' false 'n'.

       *> -- Table to store mapping of objects and queue names
       01 ws-object-table.
          78 78-table-size                     value 10.
          03 ws-obj-idx                        pic x(4) comp-5.
          03 ws-object occurs 78-table-size times.
             05 ws-obj-handle                  pic x(4) comp-5.
             05 ws-obj-name                    pic x(48).

       linkage section.
       copy casmqmon.cpy replacing ==()== by ==lk==.

       procedure division using lk-mqmonex-out.

           if not ws-initialised-88

               *> -- Initialise on first entry
               if 78-exit-version not = lk-mqmonex-version

                  *> -- This exit is using a different version of casmqmon.cpy
                  *> -- compared to the product, so switch off the exit.

                  set lk-mqmonex-switch-off-88
                                       to true
                  goback

               end-if

               initialize ws-object-table

               set ws-initialised-88   to true

           end-if

           evaluate lk-mqmonex-api

           when = 'MQCONN'
           when = 'MQCONNX'
           when = 'MQDISC'

               *> -- No queue, so do nothing

               continue

           when = 'MQOPEN'

               *> -- Find a free space to save queue name and handle
               perform varying ws-obj-idx from 1 by 1
               until ws-obj-idx > 78-table-size

                   if ws-obj-handle(ws-obj-idx) = 0

                       *> -- Empty space found so populate with queue name and handle

                       move lk-mqmonex-hobj
                                       to ws-obj-handle(ws-obj-idx)

                       move lk-mqmonex-qname
                                       to ws-obj-name(ws-obj-idx)

                       exit perform

                   end-if

               end-perform

               if ws-obj-idx > 78-table-size

                   *> -- No space in table to store this queue name and handle.
                   *> -- Handle the error!

                   continue

               end-if

           when other

               *> -- Locate queue name in table using object handle that was passed.

               perform varying ws-obj-idx from 1 by 1
               until ws-obj-idx > 78-table-size

                   if ws-obj-handle(ws-obj-idx) = lk-mqmonex-hobj

                       *> -- Found the queue name in the table at ws-obj-idx

                       exit perform

                   end-if

               end-perform

               if ws-obj-idx > 78-table-size

                   *> -- Failed to find the queue name
                   *> -- Handle the error!

                   continue

               end-if

           end-evaluate

           perform do-something

           if lk-mqmonex-api = 'MQCLOSE'

               *> -- Initialise element containing closed queue

               perform varying ws-obj-idx from 1 by 1 until
               ws-obj-idx > 78-table-size

                   if ws-obj-handle(ws-obj-idx) = lk-mqmonex-hobj

                       *> -- Found the queue, so clear this element

                       initialize ws-object(ws-obj-idx)

                       exit perform

                   end-if

               end-perform

           end-if

           goback
           .

       do-something section.

           *> -- Log the data somewhere

           exit section
           .

           end program ES_MQMONEX.

casmqmon.cpy:

       01 ()-mqmonex-out.
          03 ()-mqmonex-version                    pic x(4) comp-5.
             88 ()-mqmonex-version-1-88            value 1.
             88 ()-mqmonex-switch-off-88           value 255.
          03 ()-mqmonex-qmanager-name              pic x(48).
          03 ()-mqmonex-api-call-info.
             05 ()-mqmonex-hconn                   pic x(4) comp-5.
             05 ()-mqmonex-api                     pic x(8).
             05 ()-mqmonex-qname                   pic x(48).
             05 ()-mqmonex-hobj                    pic x(4) comp-5.
             05 ()-mqmonex-jobname.
                07 ()-mqmonex-termid               pic x(4).
                07 ()-mqmonex-tranid               pic x(4).
             05 ()-mqmonex-task                    pic x(4) comp-5.
             05 ()-mqmonex-pid                     pic x(4) comp-5.
             05 ()-mqmonex-timein.
                07 ()-mqmonex-timein-year          pic x(2) comp-x.
                07 ()-mqmonex-timein-month         pic x(1) comp-x.
                07 ()-mqmonex-timein-day           pic x(1) comp-x.
                07 ()-mqmonex-timein-hour          pic x(1) comp-x.
                07 ()-mqmonex-timein-minute        pic x(1) comp-x.
                07 ()-mqmonex-timein-seconds       pic x(1) comp-x.
                07 ()-mqmonex-timein-ms            pic x(2) comp-x.
             05 ()-mqmonex-timeout.
                07 ()-mqmonex-timeout-year         pic x(2) comp-x.
                07 ()-mqmonex-timeout-month        pic x(1) comp-x.
                07 ()-mqmonex-timeout-day          pic x(1) comp-x.
                07 ()-mqmonex-timeout-hour         pic x(1) comp-x.
                07 ()-mqmonex-timeout-minute       pic x(1) comp-x.
                07 ()-mqmonex-timeout-seconds      pic x(1) comp-x.
                07 ()-mqmonex-timeout-ms           pic x(2) comp-x.
             05 ()-mqmonex-duration-ms             pic x(8) comp-x.
             05 ()-mqmonex-compcode                pic x(4) comp-5.
             05 ()-mqmonex-reason                  pic x(4) comp-5.
Parent topic: Configuring Enterprise Server for IBM WebSphere MQ


Monitoring Enterprise Server

  • Starting and Stopping the Directory 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


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 Run the Directory Server as a Non-Root User
  • 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 Enterprise 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. 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
  2. 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 Run the Directory Server as a Non-Root User

On UNIX, MFDS can run as a non-root user on a port number equal or greater than 1024. When running MFDS as a non-root user you must consider the following:

  • Ensure that the mfds32 process has appropriate file permissions for:
    • Its initial configuration file.
    • The repository files.
    • The Journal.
    • Programs it executes, for example, casstart.
  • All regions started from the MFDS user interface will run under the default user ID specified on the Options page, if there is one; or under the same user ID as mfds32 if no default user ID is configured. So you must either start your regions from the command line or ensure that this account (the default user ID or the mfds32 user ID) also has all the necessary permissions for resources used by Enterprise Server and Enterprise Server-hosted applications.
  • Check UNIX resource limits (ulimit command) for the account, and ensure that MFDS and any child processes will not be killed if they exceed CPU time limits or resource restrictions.

You can use the CCITCP2_PORT environment variable to bind to a non-standard port, but this option should be used with caution, as some programs depend on Directory Server using the default port (86). If you do set CCITCP2_PORT, ensure it is set in the environment for Enterprise Server regions and COBOL programs which use the directory server.

From Enterprise Server 6.0, if MFDS is run as the root user, and a default user ID is configured for it on the Options page, then after binding to the port MFDS will change its process user ID to the specified user ID (dropping root privileges). The above considerations also apply if a default user ID is configured for MFDS. See Syntax for specifying a default user ID in mfds for more information.

Parent topic: Starting and Stopping the Directory Server
Related reference
mfds


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 [/d|/n network-address] [/j journal-path] [/r]
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 %ALLUSERS%\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 %ALLUSERS%\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 %ALLUSERS%\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


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.

  • Displaying Server Information
  • Accessing Remote MF Directory Servers
  • Monitoring Facilities
Parent topic: Monitoring Enterprise Server


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: Monitoring the Directory Server
Parent topic: Accessing the Enterprise Server Administration UI


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 Test Server Security.
Parent topic: Monitoring Facilities
Related information
Securing an Enterprise Server Installation


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
Note: There is an additional level, in which extra file and internal operations are written to the journal, but this level should only be enabled on request of OpenText Support for Micro Focus Products.

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: 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\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 (deprecated)
  • 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.

To include custom data in the record

To include more detail in your HSF records, you can insert custom data by adding up to five CUSTOM fields per record.

Configure the number of CUSTOM fields to appear by setting the environment variable ES_HSF_CFG=CUSTOM=x; where x is a value between 1-5. To populate the field with your custom text, call the ES_WRITE_CUSTOM_HSF library routine, passing in the user-defined text and a unique ID (0-255). The first call that is processed populates the first CUSTOM field with data, the second call populates the second CUSTOM field, and so on...

Parent topic: Collecting and Viewing Data on Transactions
Related information
ES_HSF_CFG
To start an enterprise server instance


Viewing HSF Information in ESMAC (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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 milliseconds (ms), between Enterprise Server receiving the requests and the tasks beginning to run.
Average Response Time
The average time, in milliseconds (ms), that the tasks ran for (not including latency time).
Count
How many times the task has run.

By clicking on the magnifying glass icon Magnifying glass icon 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 hhmmssttt (where ttt denotes thousandths of a second).
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, details of individual transaction runs are written to comma-separated-values files, one HSF record per line.

These files are named cashsf-a.csv and cashsf-b.csv, and are located in the system directory. One of these file is the active file at any one time, and once the active file is full, or when you click the Switch button in the HSF Data section of the ESMAC Control page, records are written to the alternate file, until the maximum file size is reached or the Switch button is clicked again.

The .csv files produced in this version of the product have the following header, and contain the following fields:

#HSFVer=05;Custom=xx;CicsFiles=xx;TSQ=xx;TDQ=xx;SUBTASK_ID=yy
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,Custom01,File01,Count01,Time01,TS01,Count01,Time01,TD01,Count1,Time1

The number of Custom, File, TS and TD fields correspond to the xx values in the header, which are set according to the ES_HSF_CFG environment variable.

When setting the variable, values must be set within a permissible range, otherwise the default value is used for that field. Also, if the field name is not explicitly set within the variable, its default value is used. The ranges and defaults are:

Field name | Range | Default
CUSTOM | 0-5 | 0
CICSF | 0-20 | 5
TSQ | 0-20 | 5
TDQ | 0-20 | 5
SUBTASK | 00-FF | 00

For example: ES_HSF_CFG=CUSTOM=2;CICSF=10;TSQ=32;SUBTASK=F1 generates 2 custom fields, 10 CICS file fields, 5 TSQ fields, and 5 TDQ fields and trace id x’F1’ is used to generate SUBT records.

Field types

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
  • SUBT - for custom sub tasks
  • 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 hhmmssttt (where ttt denotes thousandths of a second).
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 milliseconds (ms), 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 milliseconds (ms), 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 milliseconds (ms), 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 milliseconds (ms), 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 milliseconds (ms), 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.
CPU Time
Amount of CPU time, in milliseconds (ms), the task used1.
Mem Usage
Amount of memory usage, in kilobytes (kB)1.
IO Read Size
Amount of data read, in kilobytes (kB)1.
IO Write Size
Amount of data written, in kilobytes (kB)1.
IO Read Count
Number of read system calls1.
IO Write Count
Number of write system calls1.
MQ Time
Time spent, in milliseconds (ms), making MQ API calls1.
EZASOKET Time
Time spent, in milliseconds (ms), making EZASOKET API calls1.
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
1 These fields will only contain values if the region is configured to output them. This can be controlled by setting the environment variable ES_HSF_RTS_MONITOR to ON or OFF.

On Windows, support for these fields is not enabled by default. To enable them, set ES_HSF_RTS_MONITOR=ON

Configurable Field Types

The following additional fields may be repeated based on the value of the ES_HSF_CFG environment variable:

Customxx
Custom data written to the record via a call to ES_WRITE_CUSTOM_HSF from the user application.
Filexx
The name of a file that the transaction accessed.
Countxx
The number of times the transaction accessed this filexx.
Timexx
The time, in milliseconds (ms), the transaction spent accessing filexx.
TSxx
The name of a temporary storage queue (TSQ) that the transaction accessed.
Countxx
The number of times the transaction accessed TS xx.
Timexx
The time, in milliseconds (ms), the transaction spent accessing TS xx.
TDxx
For CICS records, the name of a transient data queue (TDQ), blank for non-CICS records.
Countxx
The number of times the transaction accessed TD xx.
Timexx
The time, in milliseconds (ms), the transaction spent accessing TD xx.

Sample content viewed in Microsoft Excel

Sample HSF information shown in Microsoft Excel

SUBT Type

The format for SUBT types is as follows:

"SUBT",PID,Task.Seq,Trans-id/job step,Custom data

For example:

SUBT,1234,12.1,HSF1,My data

"Custom data" is written in the same way as for custom fields, that is, by calling ES_WRITE_CUSTOM_HSF or ESCSTHSF with a 1 byte trace ID.

Note: For custom fields, multiple calls to ES_WRITE_CUSTOM_HSF/ESCSTHSF with the same ID, within the same transaction will result in data being appended to the same field up to a maximum of 255 bytes. There can be up to 5 custom fields within each record.

For sub task records, only a single ID can be used. Every call to ES_WRITE_CUSTOM_HSF/ESCSTHSF with that ID will result in a new SUBT record being generated. Custom data for these records can be up to 1024 bytes in length.

To configure this feature, the value for the ES_HSF_CFG environment variable needs to contain SUBTASK=ID where ID is the unpacked hex ID that will identify traces that will be used to generate the SUBT records. Valid values are 01 - FF. If ES_HSF_CFG does not contain a SUBTASK or if SUBTASK=00 then the feature is switched off.

For example, setting the following:

ES_HSF_CFG=SUBTASK=1A

would require a call to ES_WRITE_CUSTOM_HSF/ESCSTHSF using an ID of H"1A" in order to generate a SUBT record.

Note: If custom data contains a null character then the data will be truncated.
Parent topic: Collecting and Viewing Data on Transactions
Related information
ES_HSF_CFG


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.
/G{s} | Aggregate the output into {s} second intervals where {s} = seconds from 1 to 9999.
/S[sd,st,ed,et] | Aggregate the output data by the second. Optionally, you can specify a start date (sd), start time (st), end date (ed), and end time (et). Where [sd,st,ed,et] = yyyymmdd,hhmmss,yyyymmdd,hhmmss
/M[sd,st,ed,et] | Aggregate the output data by the minute (default if error). Optionally, you can specify a start date (sd), start time (st), end date (ed), and end time (et). Where [sd,st,ed,et] = yyyymmdd,hhmm,yyyymmdd,hhmm
/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.
R{t}[[,{t}]...] | Response time criteria by specified ID where {t} = seconds to two decimal places. Default is t=1 second.
/T | Report transaction IDs by type.
/X | Output date and time as separate columns.

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,SYS<=,%SYS<=,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.
SYS<= | The number of transactions that ran within the time range specified with the /R option or within 1 second if the option was not used.
%SYS<= | The percentage of transactions that ran within the time range specified with the /R option or within 1 second if the option was not used.
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 milliseconds (ms), spent in CICS API (EXEC CICS statements) for this task, and the minimum and maximum times.
SQL,min,max | The average time, in milliseconds (ms), spent in SQL API (EXEC SQL statements) for this task, and the minimum and maximum times.
IMS,min,max | The average time, in milliseconds (ms), 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=03;Custom=xx;CicsFiles=xx;TSQ=xx;TDQ=xx

where xx corresponds to the number of fields for each type, as specified by the ES_HSF_CFG environment variable.

HSF output from earlier versions of the product may either not have this line at all, or start with:
#HSFVer=01 or 02

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:
    Statistics shown in 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 (ms).
    • the average response time is 10 milliseconds (ms).
    • the total (system) response time is 20 milliseconds (ms).
Parent topic: Collecting and Viewing Data on Transactions
Related information
ES_HSF_CFG


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

Note: The user starting the region must be able to write to the registry under "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\eventlog" (including the ability to create subkeys).
  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, in milliseconds (ms).
  • Dump Count (since start-up)
  • Pending request Count
  • SEP Count
  • Task Count (last 60 seconds)
  • Task Count (since start-up)
Note: Windows Performance Counters now work using a V2 provider DLL and will appear in Performance Monitor under 'Micro Focus Server System V2'.
  • To Enable Performance Counters
  • To Use Performance Counters
Parent topic: Monitoring Enterprise Server


To Enable Performance Counters

Note: The user starting the region must:
  • be able write to the 'Active Servers' value under the following key in the registry: "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Micro Focus Server\Performance".
  • have the SeCreateGlobalPrivilege privilege (in order to create the area of named shared memory where the performance counter data will be written).
  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 Test 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.

Note: Enterprise Server has been tested with SCOM 2022.

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 Test 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 behavior. Refer to the System Center Operations Manager documentation for details on how to do this.

Parent topic: Management Packs for System Center Operations Manager


Remote File Access (RFA)

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

Remote File Access (RFA) is a feature of Enterprise Server which provides a set of Web APIs for reading, writing, creating, and deleting ordinary files, COBOL data files, cataloged datasets, and spool output datasets.

RFA is designed to be used from special-purpose HTTP clients. It is not a general-purpose Web server and cannot be used directly from browsers, except for the online API documentation. RFA is not enabled by default. It must be configured as a listener in an enterprise server instance or a standalone server, with a set of access rules that are appropriate for the organization.

RFA can be invoked from Javascript on a Web page, from COBOL programs invoking it as a JSON Web service, from third-party HTTP client utilities such as curl, and from other scripting and programming languages which can invoke JSON Web services.

  • RFA security
  • RFA access to catalog and spool
  • RFA Web API
Parent topic: Enterprise Server configuration and administration


RFA security

An RFA listener provides remote access to files on the host system, so it is important to ensure it is properly secured. Access is controlled by various security mechanisms.

There are multiple levels of security that can be applied to restrict what paths the RFA connector is allowed to serve files to/from.

Operating system file permissions

Operating system file permissions apply to all operations performed by an RFA listener. The listener runs under the user account used to start the enterprise server instance or standalone server. For RFA running in an enterprise server instance that is started by ESCWA, this will be the user account of the MFDS service (Windows) or the enterprise server user account (UNIX).

Note: Micro Focus does not recommend relying on operating system permissions to restrict RFA access, though they can serve as an additional defense against misuse.

Allowed paths (required)

To allow an RFA listener to serve files you must configure at least one allowed path. By default there are no paths defined as either allowed or denied, and undefined paths are implicitly denied, so by default no access is given to any file.

Allowed and denied paths are specified in the configuration text area for each RFA listener. Each entry in the [Allowed paths] and [Denied paths] section defines a file-system path, optionally including wildcards, that will allow or deny access to that location.

Optionally, you can also map an allowed path to a different file system path. For instance, if a request was made to download a file /a/directory/file.txt and the RFA listener was configured with the allowed path /a/directory=/a/different/directory then the file accessed would actually be /a/different/directory/file.txt.

User authentication (requires ESF security)

A client using RFA must begin with a logon request before requesting any file operations. If the enterprise server instance or standalone MFCS server that the RFA listener belongs to has security enabled, then ESF will be used to authenticate the credentials (username and password) supplied in the logon request.

PHYSFILE resource class (required if ESF security is enabled)

If the enterprise server instance or standalone MFCS server that the RFA listener belongs to has security enabled, then RFA will also make an ESF authorization request for the specified file system path, under the PHYSFILE resource class. You should ensure that you have the required PHYSFILE resource rules configured to allow access to those file system paths that you wish to give RFA access to.

Note: You will also need to configure suitable allowed paths as these are checked first before PHYSFILE rules. Micro Focus recommends configuring suitably restrictive allowed and denied paths to cover your use case.

For RFA, the PHYSFILE resource class works differently than it does for JES. See Resource Classes for JES Security for more information. The differences are:

Path canonicalization
On Windows, when interpreting both rule names and candidate file paths for PHYSFILE rules, backslash characters (\) are converted to forward slashes (/).
Wildcard interpretation
Under RFA, the * (single asterisk) wildcard matches zero or more of any characters except the / (slash) path separator character. The ** (double asterisk) wildcard character matches zero or more characters, including the slash.
Access permissions
Under RFA, one or more of various permissions can be granted by a PHYSFILE rule. These are interpreted as separate permissions rather than a single access level. The permissions currently supported are none, read, update, and all. The rule can list multiple permissions separated by commas (for example, read, update) or use none or all to grant (or deny, for a deny-type rule) no or all permissions. Read permission is required to download a file, and update permission is required to upload a new or altered file.

Access type (optional)

An RFA listener can be configured to only provide a certain level of access (read, update, or alter) regardless of file system permissions and PHYSFILE rules. For example:

[Security]
access=read

in the configuration will prevent RFA from modifying, creating, or deleting any files.

Feature restriction (optional)

The RFA conversation type provides a number of features: direct file access, access to cataloged datasets, and so forth. An RFA listener can be configured to only permit certain features, as an additional security measure. For example:

[Security]
allow catalog access=no

disables support for all catalog operations and access to cataloged datasets. The physical file containing the dataset data might still be accessible directly, if a suitable allowed path is configured.

TLS

Like other enterprise server listeners, RFA supports TLS (SSL). Micro Focus recommends configuring TLS for RFA listeners, to help ensure data confidentiality and integrity.

See RFA conversation type for more information on configuring an RFA listener.

Parent topic: Remote File Access (RFA)


RFA access to catalog and spool

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

A Remote File Access (RFA) listener in a JCL-enabled enterprise server region can optionally provide access to the catalog, cataloged datasets, and spool (JES job) output.

Access to the catalog and spool requires invoking an internal service provided by the enterprise server region. This service performs catalog and spool lookups, checks user authorization, and provides enqueue/dequeue (lock) operations so exclusive and shared access to datasets can interoperate with applications running in the enterprise server region.

In order to maintain data integrity the RFA APIs for enqueuing and dequeuing datasets should be called before (enqueue) and after (dequeue) accessing datasets. Since an enqueue is automatically released after 30 seconds, there is also an API for periodically renewing an enqueue. It is up to your application to correctly manage the enqueues.

For catalog and spool access the RFA listener will perform a service lookup using MFDS to locate the MF ES service of the enterprise server region it is attached to. The MF ES service is normally created automatically for each enterprise server region defined in MFDS. The RFA listener uses the Micro Focus Common Client (MFCC) to resolve the MF ES service and communicate with it.

If MFDS is configured to refuse anonymous binds, which is the default, then MFCC will need credentials to bind to MFDS. Under the default Enterprise Server security configuration, MFCC will look for credentials for the readonly user in the vault and use those to bind to MFDS. If those credentials are not present in the vault, you might need to edit the bin/mf-client.dat file included with the product to provide different credentials for MFCC. For example:

[mldap]
username=mf_dep
password=mf_dep

See The Default Enterprise Server Security Configuration and Micro Focus Common Client for more information.

Security

In addition to the mechanisms listed in RFA security, the service which provides catalog and spool access will make an authorization check against the DATASET resource class for dataset access, and the JESSPOOL class for spool access. See the descriptions of these resource classes in the product Help for more information.

Note: RFA only allows downloading spooled data, not modifying, creating, or deleting it.

When RFA contacts the MF ES service of the enterprise server region for catalog and spool access, it does so using an HTTP conversation with the associated listener, which is usually the Web Services and J2EE listener. If this listener is configured to use TLS, MFCC will need a suitable TLS client configuration: a root setting in mf-client.dat which points to a file containing the certificate(s) needed to validate the listener's certificate, and possibly a client certificate and other settings.

Note: Micro Focus in general recommends using TLS. In the specific case of RFA connecting to the MF ES service, however, this will usually be a local (same-system) connection, and so will not actually be exposed on the network, so enabling TLS is less urgent for this connection.
Parent topic: Remote File Access (RFA)


RFA Web API

Remote File Access (RFA) is used through a Web API with JSON messages. This API is designed to follow modern Web API best practices.

The Web API can be invoked from a variety of clients and programming languages. It is not intended to be invoked directly from a browser (for example, by entering RFA request URLs in the address bar, or using links in Web pages), but can be used with Javascript APIs such as XMLHttpRequest and fetch from Web applications. It can be invoked from the RFA online documentation which is served by the RFA listener, if not disabled, but that is intended for testing and educational purposes.

It is important to use the RFA API in a secure manner. See RFA security for more information. See RFA access to catalog and spool for more information if you are using the RFA API for catalog or spool access.

  • RFA Web API requirements
  • RFA session management
  • RFA interactive API library
Parent topic: Remote File Access (RFA)


RFA Web API requirements

When using the RFA Web API:

  • HTTP/1.0 and HTTP/1.1 are supported. HTTP/1.1 is recommended. Chunking and compression with gzip are supported.

  • The X-Requested-With header must be set. For Web browser clients, this is typically set to XMLHttpRequest. For other clients, you should give this a value that clearly identifies it as your application.

  • The host header must be set to the location of your RFA listener, for example, localhost:9999.
  • One of the Origin or Referer headers must be set to the location of the RFA listener, for example, https://localhost:9999.
  • For any API that returns a JSON message body, the Accept header should be set to application/json; text/html. The text/html is for receiving the body of HTTP error messages if the request fails.

    For APIs that return file data, the Content-Type can be set to various values depending on the file type inferred from the file extension. Certain common file extensions are recognized and Content-Type is set accordingly, for example to text/plain or image/jpeg. Unrecognized file types are sent as application/octet-stream. You can set Accept to */* for requests that return files, or to a more-specific value such as text/*; application/*.

  • For any API that requires a body in the request, the Content-Type header must be set to application/json. The body length must be indicated per the HTTP/1.1 standard, with either the Content-Length header set to the length of the body in octets, or the chunked transfer-encoding used.

    For file uploads, set Content-Type to application/octet-stream or, if you prefer, to a more-specific value.

  • You can have file data compressed for transfer when downloading by setting Accept-Encoding to gzip. It is the client's responsibility to decompress the data.

    You can compress the file data for transfer when uploading using the gzip algorithm. Set Transfer-Encoding to gzip, or gzip, chunked if the request is chunked, in this case.

  • For APIs that are not transferring file data (for example, logon), message bodies should be UTF-8 encoded. Note that ASCII is a subset of UTF-8. Response message bodies that are not file data are also encoded in UTF-8. For file-transfer APIs, the data encoding depends on the file; RFA does not transcode file data.
Parent topic: RFA Web API


RFA session management

All clients must use a session to perform their actions

To create a session, a request must first be sent to the endpoint /logon with your credentials. The response will have a Set-cookie header containing MFES-RFA-Session. This cookie must be sent with every subsequent request.

Once your script is complete it should finish with a request to the /logoff endpoint to clean up the session. This is to reduce the risk of reaching the session limit and minimize resource usage, and is also a best practice for Web API security.

Sessions have both a maximum lifetime and a maximum idle time, set in the RFA listener configuration. See Remote File Access conversation type for more information.

Parent topic: RFA Web API


RFA interactive API library

The API library documents all of the APIs Remote File Access provides.

The library runs as an interactive client served to your browser by an RFA listener. This enables you to test actual requests and responses against your configuration.

To access the interactive API library, append /mfrfa/docs to your base RFA URI in your browser address bar, for example http://localhost:9999/mfrfa/docs.

To start using the interactive API:

  1. Click Server to open the Server category. The /logon and /logoff APIs should be listed.
  2. Click /mfrfa/logon to open the Logon dialog.
  3. Click Try it out to open the area where you can edit the request body.
  4. Replace the two "string" string values in the sample request body with your username and password. For example:
    {
   "mfUser": "SYSAD",
   "mfPassword": "abcd1234"
}
  5. Click Execute.
  6. If the request was successful, you will receive a server response with an HTTP status code of 200 and an empty JSON response body ({}).

Once you have a cookie for a valid session you can perform other RFA requests, such as getting and putting files.

Note: Your session will eventually time out. You can clear it manually using the /logoff API.

The interactive API library manages the Host, Origin, Referer, Accept, Content-Type, and Content-Length headers for you. It also stores and applies the cookie for session handling.

Note: The interactive API library and any other RFA use in the browser share a session. Logging in or out from one will affect the other.
Parent topic: RFA Web API


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.

You specify a user exit program and the exit points at which it is to be invoked by the request handler at run time as part of the interface mapping process, described in the chapter COBOL Web Services with the Interface Mapping Toolkit in your Web Services and COBOL book. This information is built into the interface definition table (IDT) associated with the mapped service.

  • User Exit Points Provided
  • Structure Definitions and Type Definitions
  • Linkage Section Field Names
  • Deploying a User Exit Program
  • Web Service Client Exits
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 Test 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 Test Server\bin or \bin64 (64-bit).

Parent topic: User Exits for Request Handlers


Web Service Client Exits

  • Implementing exit-soap-request and exit-soap-response user exits
  • Implementing exit-json-request and exit-json-response user exits
  • Implementing exit-http-headers user exit
  • Implementing exit-http-resp-headers user exit
Parent topic: User Exits for Request Handlers


Implementing exit-soap-request and exit-soap-response user exits

Signature of Web Service SOAP user exit functions

The signature of these functions are:

C terminology:

 Function_Name(char ** SOAP-ENVELOP, int *
SOAP-ENVELOPlength)

COBOL terminology:

 LINKAGE SECTION.
01 SOAP-ENV pic x. *> any length.
01 SOAP-ENVptr pointer.
01 SOAP-ENVlen pic s9(9) COMP-5 . *> =
int
PROCEDURE DIVISION.
EXIT PROGRAM.
…
ENTRY "exit-soap-request" using
By reference SOAP-ENVptr
By reference SOAP-ENVlen.
. Set address of SOAP-ENV to SOAP-ENVptr
…
EXIT PROGRAM.
ENTRY "exit-soap-response" using
By reference SOAP-ENVptr
By reference SOAP-ENVlen.
. Set address of SOAP-ENV to SOAP-ENVptr
…
EXIT PROGRAM.

The variables:

SOAP-ENVELOPE
Pointer to the SOAP body.
SOAP-ENVELOPlength
Pointer to the length of the SOAP body.

The variables SOAP-ENVELOPE and SOAP-ENVELOPlength are I/O parameters:

  • The user exit receives these parameters.
  • The user exit can update these parameters.
Parent topic: Web Service Client Exits


Implementing exit-json-request and exit-json-response user exits

Signature of Web Service JSON user exit functions

The signatures of these functions are:

C terminology:

exit-json-request (char ** JSON-BODYptr, int *
JSON-BODYlen, char ** JSON-PATHptr, int * JSON-PATHlen)
exit-json-response (char ** JSON-BODYptr, int * JSON-BODYlen)

COBOL terminology:

 LINKAGE SECTION.
01 JSON-BODY pic x. *> any length.
01 JSON-BODYptr pointer.
01 JSON-BODYlen pic s9(9) COMP-5 . *> = int.
01 JSON-PATH pic x.
01 JSON-PATHptr pointer.
01 JSON-PATHlen pic s9(9) COMP-5.
PROCEDURE DIVISION.
EXIT PROGRAM.
…
ENTRY "exit-json-request" using
By reference JSON-BODYptr
By reference JSON-BODYlen
By reference JSON-PATHptr
By reference JSON-PATHlen.
Set address of JSON-BODY to JSON-BODYptr.
Set address of JSON-PATH to JSON-PATHptr.
…
EXIT PROGRAM.
ENTRY "exit-json-response" using
By reference JSON-BODYptr
By reference JSON-BODYlen.

Set address of JSON-BODY to JSON-BODYptr.
…
EXIT PROGRAM.

The variables:

JSON-BODYptr
Pointer to the JSON body.
JSONBODYlen
Pointer to the length of the JSON body.
JSON-PATHptr
Pointer to the JSON path.
JSON-PATHlen
Pointer to the length of the JSON path.

The variables JSON-BODYptr, JSON-BODYlen, JSON-PATHptr, and JSON-PATHlen are I/O parameters:

  • The user exit receives these parameters.
  • The user exit can update these parameters.
Parent topic: Web Service Client Exits


Implementing exit-http-headers user exit

The exit-http-headers user exit is called before the Web Service is invoked. When a function named exit-http-headers exists, it is called from one to 100 times.

This user exit is called before the HTTP message is passed to the Web Service. It allows you to set named values in the HTTP header, for example, username=MFuser.

Signature of Web Service HTTP headers user exit function

The signature of this function is:

C terminology:

Function_Name(int headerNum, char * headerName, char * headerValue)

COBOL terminology:

 LINKAGE SECTION.
01 headerNum pic s9(9) COMP-5.*> = int
01 headerName pic X any length. *> 256 = Max Length
01 headerValue pic X any length. *> 8192 = Max Length
PROCEDURE DIVISION.
EXIT PROGRAM.
…
ENTRY "exit-http-headers" using
     By value headerNum
By reference headerName
By reference headerValue.
.
     …
     EXIT PROGRAM.

The variables:

headerNum
Number of the named value
headerName
Name of the named value
headerValue
Value of the named value

The variables use I/O terminology:

headerNum
Input parameter

This user exit is called repetitively from once to 100 times. The headerNum is just the index of the loop. The end of the loop occurs when:

  • § or headerNum = 100
  • § or headerName and headerValue are equal to low value
  • § or there has been no change in headerName and headerValue since last occurrence
headerName
Output parameter, null terminated string
headerValue
Output parameter, null terminated string
Parent topic: Web Service Client Exits


Implementing exit-http-resp-headers user exit

The exit-http-resp-headers user exit provides access to any and all HTTP headers present in the response message from a Web service.

Signature of Web Service HTTP response headers user exit function

C terminology:

Function_Name(void * headerArrayPtr, int headerCount)

COBOL terminology:

 LINKAGE SECTION.
01 headerArrayPtr pointer.
01 headerCount    pic 9(9) usage comp-5.
01 header.
  03 namePtr      pointer.
  03 valuePtr     pointer.
01 headerName     pic x(1).
01 headerValue    pic x(1).
PROCEDURE DIVISION.
EXIT PROGRAM.
…
ENTRY "exit-http-resp-headers" using
     By value headerArrayPtr, headerCount.
           set address of header to headerArrayPtr
           perform headerCount times
               set address of headerName to namePtr of header
               set address of headerValue to valuePtr of header
               perform varying headerNameLen from 1 by 1
                       until headerName(headerNameLen:1) = low-value
               end-perform
               subtract 1 from headerNameLen
               perform varying headerValueLen from 1 by 1
                       until headerValue(headerValueLen:1) = low-value
               end-perform
.
     …
     EXIT PROGRAM.

The variables:

headerName
Name of the named value
headerArrayPtr
Pointer to an array of named values in the HTTP response header.
headerCount
Count of named values in the array.

The variables use I/O terminology:

headerArrayPtr
Input parameter.
headerCount
Input parameter.
Parent topic: Web Service Client Exits


Enterprise Server LOCKDB

The LOCKDB feature replaces the functionality of the Enterprise Server Cluster Global Lock Manager (GLM). A LOCKDB is a group of MFDBFH enabled enterprise server regions where the locking mechanism is orchestrated by the MFDBFH layer.

Members of a LOCKDB group do not have to be connected by an Intersystem Communication (ISC) link, this used to be the case for GLM configured systems.

Any locks (ENQs) for CICS, JES, IMS, and so on, are processed by MFDBFH.

Configuration

Setting up a DBLOCK group requires the following configuration. The LOCKDB feature mechanism is based on an MFDBFH setup. See Micro Focus Native Database File Handling and Enterprise Server Region Database Management for more information. Once MFDBFH has been configured, you need to set the ES_LOCKDB environment variable to the name of a region database for each enterprise server region which is to be part of the LOCKDB group. For example, to configure LOCKDB membership for two enterprise server regions, one called LOCKDB1M and the other called LOCKDB2M, add the following entries in their MFDBFH.cfg file:

<dsn name="SS.LOCKDB1M.REGION" type="region.cas" region="LOCKDB1M" feature="all" connect="db=LOCKDB;uid=xxxx;pwd=yyyy"/>
<dsn name="SS.LOCKDB2M.REGION" type="region.cas" region="LOCKDB2M" feature="all" connect="db=LOCKDB;uid=xxxx;pwd=yyyy"/>

For the first enterprise server region set the following environment variable:

ES_LOCKDB=LOCKDB1M

For the second enterprise server region set the following environment variable:

ES_LOCKDB=LOCKDB2M

JCL Submission

The sequence of the lock processing on JCL submission is the same as the previous Enterprise Server Cluster sequence. See JCL Submission for more information.

Lock Processing

The current lock list can be monitored and verified using ESMAC. For a CICS and JES enabled enterprise server region. In the left pane, from the Resources list, select Active, and then click Locks. This will display a list of active locks.
Note: The CASLOCK command cannot be used for a LOCKDB group.

Resource Name List Support

The Resource Name List (RNL) is an IBM mainframe method used by Global Resource Serialization (GRS) to identify resource scope. Of all the RNL functions, only those that are essential for identification of a SYSZDSN lock scope have been implemented. The support of RNL in a LOCKDB group is identical to Enterprise Server Cluster support. The RNL file can be a database controlled file.

Startup Sequence

In a LOCKDB group, the first enterprise server region must be cold started. For example, in a LOCKDB group consisting of two regions, the firsts region must be started as follows:

casstart -rLOCKDB1M -S:C

Once the first region has been cold started, you can start subsequent regions as follows:

casstart -rLOCKDB2M
Warning: Performing a cold start on subsequent regions will result in unexpected behavior.

VSAM Shareoptions

VSAM shareoptions are supported in a LOCKDB group.

Parent topic: Enterprise Server configuration and administration
Related concepts
Enterprise Server Clustering (deprecated)
The Global Lock Manager
Related information
ES_LOCKDB


Enterprise Server Clustering (deprecated)

Note: Micro Focus recommends that you adopt the Scale-Out Performance and Availability Cluster (PAC) solution for your clustering requirements. See Scale-Out Performance and Availability Clusters for more information.

The LOCKDB feature replaces the functionality of the Enterprise Server Cluster Global Lock Manager (GLM). See Enterprise Server LOCKDB for more information.

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 data set 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: CICS data set locks are processed by GLM so share a lock between CICS and JES.
  • 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
Related tasks
Enterprise Server LOCKDB


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


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).
Note: The LOCKDB feature replaces the functionality of the Enterprise Server Cluster Global Lock Manager (GLM). See Enterprise Server LOCKDB for more information.

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 (deprecated)
Related tasks
Enterprise Server LOCKDB


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.
Screenshot of Enterprise Server JES General tab

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 (deprecated)
Related information
ES_GLM
ES_GLM_TIMEOUT


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


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:
Server Information page of ESMAC (CASRDO5), NOWORK state

When all Enterprise Server Cluster clients marked as ACTIVE in CASGLM.LCK have reconnected, the following will be displayed:
Server Information page of ESMAC (CASRDO5), ACTIVE state

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):
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 (deprecated)


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:

Screenshot of an active Locks screen in ESMAC, showing all locks
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:
Screenshot of an active Locks screen in ESMAC, showing only the owner's locks

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.

You can use caslock to view locks in a PAC or LOCKDB environment. Querying the locks for an enterprise server region that is a member of a PAC will return a list of all the locks associated with that PAC. For example:

caslock /l /rRAS1
Global Locks (Held In Database)
===============================
OwnedLocks
----------
   PID        TID        Task             Region/PAC UID          Scope    Share Mode  QNAME     RNAME
   51580      75284      31      70A1C876A72B0E421A7E06A627DE5214 System   Exclusive   SYSZCICS  aaa.bvvvc.ddddd
                      System     MYPAC                            Systems  Exclusive   SYSZDSN   CICS.SSTM.OUTJCL
                      System     MYPAC                            Systems  Exclusive   SYSZDSN   SIS.ARQTEC.FICHERO.PLIMSG

where RAS1 is a region within the PAC.

Note: You cannot use caslock to remove locks in a PAC.

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.
Screenshot of Remove Locks button

Parent topic: Enterprise Server Clustering (deprecated)


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


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.
IBM RNLs processing flowchart as emulated by an Enterprise Server cluster

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


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


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


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:
Cluster trace box

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:
Cluster trace box

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


Legacy Enterprise Server Administration User Interface

Micro Focus recommends you adopt the Enterprise Server Common Web Administration (ESCWA) interface. ESCWA is a modern and feature-rich interface that combines functionality from Enterprise Server Administration, ESMAC, and the ESF LDAP Security Administration interfaces.

By default, the legacy Enterprise Server Administration user interface is disabled. To enable the interface:

    1. Run services.msc to open the Windows Service Manager.
    2. In the Services list, right-click Micro Focus Directory Server and then click Stop.
    3. From an Enterprise Developer command prompt, type:
      mfds --UI-on
    4. In the Services list, right-click Micro Focus Directory Server and then click Start.

The legacy Enterprise Server Administration user interface requires the following minimum Web browser versions:

  • 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.
  • User Interface Tables
  • Navigation
  • Accessing the Enterprise Server Administration UI
  • Configuring and Administering Enterprise Server Instances
  • Enterprise Server Administration Console Help Pages
Parent topic: Enterprise Server configuration and administration


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: Legacy Enterprise Server 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: Legacy Enterprise Server 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 the following 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.
  • Using the Loopback Address
Parent topic: Legacy Enterprise Server Administration User Interface
Parent topic: Enterprise Server Task Index


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


Using the Loopback Address

On Windows, by default, the Enterprise Server Administration Web interface can only be contacted using the loopback address (localhost or 127.0.0.1).

To turn loopback mode off

To enable remote access to the Web interface, turn loopback mode off. There are two methods that you can use. You can turn the loopback mode off by using the command line:

  1. Run services.msc to open the Windows Service Manager.
  2. In the Services list, click Micro Focus Directory Server.
  3. Click Stop.
  4. On a command prompt, type:
    mfds --listen-all
  5. In the Services list, click Micro Focus Directory Server, and then click Start.

Alternatively, you can turn the loopback mode off using the Web interface:

  1. In the Home pane of Enterprise Server Administration, click Options.
    Note: The Web interface is only accessible via localhost or the 127.0.0.1 address.
  2. Click the General tab.
  3. On the Configure General Options page, uncheck TCP on loopback only.
  4. Click OK.
  5. Run services.msc to open the Windows Service Manager.
  6. In the Services list, click Micro Focus Directory Server.
  7. Click Restart.

To turn loopback mode on

To disable remote access to the Web interface, turn loopback mode on. There are two methods that you can use. You can turn the loopback mode on by using the command line:

  1. Run services.msc to open the Windows Service Manager.
  2. In the Services list, click Micro Focus Directory Server.
  3. Click Stop.
  4. On a command prompt, type:
    mfds --listen-loopback
  5. In the Services list, click Micro Focus Directory Server, and then click Start.

Alternatively, you can turn the loopback mode on using the Web interface:

  1. In the Home pane of Enterprise Server Administration, click Options.
  2. Click the General tab.
  3. On the Configure General Options page, check TCP on loopback only.
  4. Click OK.
  5. Run services.msc to open the Windows Service Manager.
  6. In the Services list, click Micro Focus Directory Server.
  7. Click Restart.
    Note: The Web interface is now only accessible via localhost or the 127.0.0.1 address.
Parent topic: Accessing the Enterprise Server Administration UI


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 (deprecated)
  • Stopping and Restarting an Installation
  • Using the Command-line Interface
Parent topic: Legacy Enterprise Server Administration User Interface


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 %ALLUSERS%\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


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_MFDS_ADDRESS | Specifies the server address which is used by casstart if the /m parameter is not provided.
ES_HOME | Server work directory (location of log files); this comes from the System Directory field on the Add Server or Edit Server > Properties > General page.
ES_SERVER | Server name (note that Enterprise Server will use this as the server name if no -r switch is specified on casstart or casstop).
MFDS_PORT | The port on which the Directory Server listens (usually 86).
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. 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 > Scripts page.

Parent topic: Connecting to a Server Instance


Administering Enterprise Server Instances using ESMAC (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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 (deprecated)
  • 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 (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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


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


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


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


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


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


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 an Enterprise Developer installation, from the Start menu, select: Start > All Programs > Micro Focus Enterprise Developer> Tools > Product Name Command Prompt.

  • casclsec
    A secure utility used to prevent the user ID and password from being visible to a process monitoring tool. This is done by calling a user exit to retrieve security credentials. The secure storage of security credentials is defined and managed at installation.
  • casdump
    Forces a system dump.
  • casdup
    Formats a system dump or auxiliary trace so that it is suitable for analysis.
  • casesxml
    Imports and exports enterprise server definitions.
  • caspac
    The caspac utility can be used to administer a PAC.
  • casstart
    Starts an enterprise server.
  • casstop
    Stops an enterprise server.
  • casutl
    An Enterprise Server utility program.
  • casverify
    Verifies the configuration of specified components for an enterprise server region.
Parent topic: Configuring and Administering Enterprise Server Instances


casclsec

A secure utility used to prevent the user ID and password from being visible to a process monitoring tool. This is done by calling a user exit to retrieve security credentials. The secure storage of security credentials is defined and managed at installation.

Syntax:

casclsec es-command [command-parameters]

Parameters:

es-command | The command to execute, which includes a subset of the available commands. If the supplied command is not part of the subset, casclsec displays a message
command-parameters | Any parameters that apply to the command specified as es-command.

Dependencies:

Some valid commands specified as es-command work only against a started enterprise server instance.

Comments:

The primary purpose of casclsec is to prevent security credentials from being visible to process monitoring tools; therefore you must create a user exit that provides the user ID, password, and group. This user exit program must be named cassclue and must be located in a directory included in the COBPATH environment variable concatenation. Its interface is declared in cassclue.cpy.

If located, the exit is called by casclsec, the enterprise server instance name and, if supplied on the command line, the user ID, password and group ID. The exit should return the appropriate credentials through the interface.

The command provided by es-command is then invoked using the parameters provided plus details returned by the exit.

Parent topic: Using the Command-line Interface


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
Related concepts
Dumps
Related reference
MQ Listener (listener-name)


casdup

Formats a system dump or auxiliary trace so that it is suitable for analysis.

Syntax:

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

Parameters:

/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 Interface (API) entries
/d | Display module IDs
/ffile-name | The name of the output formatted dump file
/n | Omit page headers
/ifile-name | The name of the input trace file. Overrides /a, /b, /r, /x, and aux
/l | List summary information only
/mxx{,xx}... | The module IDs to be included in the screen trace
/pnn{,nn}... | The process IDs to be included in the screen trace
/res-name | Name of the enterprise server that owns the dump. Defaults to ESDEMO
/snnnnnn | Split output after every nnnnnn lines
/w | Wide trace format
/0 | Module/transaction trace
/1 | /0 level trace plus API
/2 | /0 and /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
/e | Exclude user data mode
/h | Display usage

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


casesxml

Imports and exports enterprise server definitions.

casesxml can perform one of two operations:

  • generate .xml files, in casesxml export format, that contain structured definitions of a region, a CICS resource definition file, and the catalog
  • import a casesxml export format .xml file to update the definitions of a region, a CICS resource definition file, and the catalog

casesxml is useful in any situation where you want to make a copy of the key resource definitions used in your Enterprise Server setup. This could be for backup purposes, for instance, or to enable you to share common resource definitions across multiple users.

casesxml consolidates functionality from the mfds command, the casrdtex CICS command, and the mfcatxml catalog import/export utility. Whether you use casesxml or an individual command or utility depends on the type of information that you want to import or export.

Note: The casesxml command-line utility can only import files that have been exported using casesxml. Repository files exported from MFDS or ESCWA can be imported using the mfds command.

Syntax:

casesxml command [switch ...] [parameter ...]

Parameters:

command
export | Definitions are to be exported from Enterprise Server to an .xml file.
import | Definitions are to be imported from an .xml file into Enterprise Server.
switch
Import and export:
-s | Include security definitions.
-v | Display verbose output.
Export only:
-a | Include all RDT entries.
Import only:
-o | Overwrite existing definitions.
parameter
Import and export:
-dresource-definition-file-location The location of the CICS resource definition file.

If this is not supplied, it will be determined from the Micro Focus Directory Server (MFDS) region definition.

This override may be required if the resource definition file's location is defined using an environment variable which is not set when the export is executed or, in an import scenario, a different resource definition file should be targeted.

This override may be required when exporting if the resource definition file's location is defined using an environment variable which is not set when the export is executed, or when importing if a different resource definition file is to be targeted.

-pmfds-password | The password to use when retrieving information from MFDS.
-umfds-user-name | The user name to use when retrieving information from MFDS.
-c All output is combined into one file. The name of the combined file is region-name_combined.xml.

If you do not specify -c a number of .xml files are produced depending on the information that is returned.

Output files that already exist are overwritten.
Note: If the enterprise server definition has been exported using this option then you must import using the -c parameter.
Export only:
-rregion-name The region whose definition is to be exported.

This is required when exporting but optional when importing.

-tmfds-timeout | The timeout period, in seconds, to use when retrieving information from MFDS. The default is 5.
-wwork-location | The location where the output files are to be written. The default is %TMP%. To use the current directory specify -w%CD%. Output files that already exist are overwritten.
-z In addition to producing one or more .xml files, produce a .zip file containing the .xml files.

The name of the .zip file is region-name_export.zip. The file is overwritten if it already exists.

Import only:
-ffile-to-import | The name of the file to import, which can be an .xml file in casesxml export format or a .zip file containing casesxml export format files.
Parent topic: Using the Command-line Interface
Related concepts
Importing and Exporting a Catalog: import export utility
Related reference
casrdtex
mfds


caspac

The caspac utility can be used to administer a PAC.

Syntax:

caspac -a{action}=object -p{pacName} -s{store} -n{psorName}

Parameters:

-p
Specifies the PAC name to use, if not specified then the value of the ES_PAC environment variable will be used.
-a
Specifies the action to perform and the object it will be performed on.
action

The following actions support PAC administration:

InitPac
Initializes the PAC ready for a cold start. Forcing the PAC to initialize will remove all information from the PSOR. This option is must only be applied if all the regions in the specified PAC have been stopped.
Status
Provides the current status for the PAC.
Dump
Creates a dump file of the SOR that have been created for the specified PAC.
Note: The filename created by the caspac Dump action are different, they do not include the endpoint but instead the text _coh_, the extension remains .rdmp.
Restore
Restores a dump file into the specified Scale-Out Repository (SOR).
PacLog
Creates a log file for messages generated by the PAC using the specified SOR.
SetMode
The specified work mode can be:
Running
Sets the work mode flag in the specified PSOR so that batch workload and EXEC CICS START are enabled to be processed.
Quiesce
Sets the work mode flag in the specified PSOR to prevent batch workload and EXEC CICS START from being processed.
CheckCompat
Use this to check the compatibility of the current installed enterprise server instance version against the specified PSOR if it was created using a different version. The following or similar message will be displayed if it is incompatible along with a -1 return code:
Located an incompatible CSA record in the PSOR, a compatible upgrade is not possible.
RemOldPAC
Enables you to remove a PAC stores (PSOR) created pror to Enterprise Developer 7.0 PU8 that are not prefixed with a PAC name.
RemShrQueues
Deletes all stores called Shared_CasTSQ_RC, Shared_CasTSQ_NR, Shared_CasTDQ_RC, and Shared_CasTDQ_NR that are introduced in Enterprise Developer 8.0 and that enables you to share TS and TD between PACs using the new ESCWA option when defining a SOR.

The following actions support recovery:

CasDEQs="file_path\file_name.csv"
Use this to list all errors that might have occurred on DEQs either at the END of Task or while a Job or Transaction was executing.

This action generates a CSV file that can be used to manually recover the DEQs using dbfhadmin commands.

RecoverUUID
Specifying the UUID of the enterprise server region that left the PAC will remove all entries related to that enterprise server region from the PSOR.
RecoverLostUUID
This enables you to recover all enterprise server regions on a specified hostname that might have lost their connection to the PSOR, or that have been killed by the user.

The following actions support program deployment:

Delete
Deletes a loaded file from the SOR.
List
Lists the user programs that have been loaded into the SOR.
Load
Loads and deploys a non CICS or JES object as soon as the caspac command is issued. The object is deployed into the PAC_LOADLIB folder of the region's workarea.
LoadCics
Loads an object ready to be deployed into CICS when you execute the CPMT NE command. The object is deployed into the PAC_LOADLIB_CICS folder of the region workarea.
LoadJes
Load an object and deploy it directly into the PAC_LOADLIB_JES folder of the region workarea
object
Specifies the object the action is to use and can take one of the following values depending on the action being taken:
  • DLL
  • Share Object
  • PAC Name
  • Dump File
  • PAC Log File
Note: The object name is case-sensitive.
Retrieve
Retrieves binaries loaded in the SOR, such as CICS or JES objects. Specify the matching criteria using the asterisk "*" wildcard. You can include a -o parameter to specify an output folder. The output filename will be determined by the name of the objects retrived from the SOR.
-ssor
Specifies the SOR type and its connection parameters.
Note: Redis and Oracle Coherence have different connection parameters. See PAC and SOR Environment Variables for more information.

To connect to a Redis SOR, for example:

redis,127.0.0.1:6741

To connect to a Coherence SOR, for example:

coherence,mfes-cache-config.xml,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1:7574
-n{psorName}
Name of the PAC SOR. This is only required for Redis AUTH authentication requests or Redis SENTINEL. See Providing Credentials for Redis using Secrets for more information.

When using Redis AUTH you will need to create a secret in the vault facility for each PSOR that is used as a reference using the -n option.

-p{PACName}
The PAC name to use, if this is not specified the PAC name is taken from the ES_PAC environment variable. The PSOR is prefixed by the PAC name and a version number enabling you to run multiple PACs from the same PSOR, this can assist with performing an incompatible upgrade process.

Comments:

From Enterprise Developer 8.0, the PSOR stores are prefixed by the PAC name and a version number enabling you to run multiple PACs in the same PSOR, this simplifies the incompatible upgrade process.

The caspac utility enables you to add the PAC name as part of the command line parameters using -pPACName or if not specified using the ES_PAC environment variable.

Examples

  • The following example loads acct.dll into the SOR represented by the Redis server located at 127.0.0.1 on port 6741. The acct.dll can then be deployed to all active enterprise server instances in the PAC using the New Copy command:
    caspac -pMyPAC -aLoadCics="c:\new files\acct.dll" -sredis,127.0.0.1:6741 -npsorName
  • The following example loads all files under c:\new files into the SOR represented by the Redis server located at 127.0.0.1 on port 6741. Because this is for JES, a new copy command is not required:
    caspac -pMyPAC -aLoadJes="c:\new files\*.*" -sredis,127.0.0.1:6741 -npsorName
  • The following example loads all non CICS and JES files under c:\new files into the SOR represented by the Redis server located at 127.0.0.1 on port 6741:
    caspac -pMyPAC -aLoad="c:\new files\*.*" -sredis,127.0.0.1:6741 -npsorName
  • The following example removes acct.dll from the SOR represented by the Redis server located at 127.0.0.1 on port 6741:
    caspac -pMyPAC -aDelete=acct.dll -sredis,127.0.0.1:6741 -npsorName
  • The following example lists user programs that have been uploaded into the SOR:
    caspac -pMyPAC -aList=* -sredis,127.0.0.1:6741 -npsorName
  • The following example initializes the PAC called MyPAC ready for a cold start. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aInitPac=MyPAC -sredis,127.0.0.1:6741 -npsorName

    Alternatively, the following example uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:

    caspac -aInitPac=MyPAC -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
  • The following example returns the status of the PAC called MyPAC. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aStatus=MyPAC -sredis,127.0.0.1:6741 -npsorName

    Alternatively, the following example returns the status of the PAC that uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:

    caspac -aStatus=MyPAC -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
  • The following example creates a dump of the PAC called MyPAC. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aDump=MyPAC -sredis,127.0.0.1:6741 -npsorName

    Alternatively, the following example creates a dump of the PAC that uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:

    caspac -aDump=MyPAC -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
  • The following example restores a PAC from a the CasPAC_127.0.0.1_06741.rdmp dump file. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aRestore=CasPAC_127.0.0.1_06741.rdmp -sredis,127.0.0.1:6741 -npsorName
  • The following example restores a PAC from a dump file that matches the use of the * wildcard. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aRestore=*.rdmp -sredis,127.0.0.1:6741 -npsorName

    Alternatively, the following example restores a PAC from a dump file that matches the use of the * wildcard. The PAC has a PSOR that uses Oracle Coherence with a cluster called MyPAC_cluster located at 127.0.0.1:

    caspac -aRestore=*.rdmp -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MYPAC_cluster=127.0.0.1
  • The following example writes a PAC log file to the folder and file specified. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aPacLog="c:\temp\PacLog.log" -sredis,127.0.0.1:6741 -npsorName

    Alternatively, the following example writes a PAC log file to the folder and file specified from a PSOR that uses Oracle Coherence and has a cluster called MyPAC_cluster located at 127.0.0.1:

    caspac -aPacLog=/tmp/paclog.log -scoherence,,coherence.cluster=MyPAC_cluster,mfescache.wka.MyPAC_cluster=127.0.0.1
  • The following example checks the compatibility of the specified PAC with the PSOR that uses Redis server located at 127.0.0.1 on port 6741:
    caspac -aCheckCompat=MyPAC -sredis,127.0.0.1:6741
  • The following example sets the PAC to running mode or normal operating mode. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aSetMode=Running -sredis,127.0.0.1:6741 -npsorName
  • The following example places the PAC in Quiesce mode. The PAC has a PSOR that uses a Redis server located at 127.0.0.1 on port 6741:
    caspac -aSetMode=Quiesce -sredis,127.0.0.1:6741 -npsorName
  • The following example exports a .csv file that contains a list of the DEQ errors for the Redis server located at 127.0.0.1 on port 6741:
    caspac -pMyPAC -aCasDEQs="c:\temp\DEQ_report.csv" -sredis,127.0.0.1:6741 -npsorName
  • The following example will remove entries from the PSOR corresponds to the UUID specified for the Redis server located at 127.0.0.1 on port 6741:
    caspac -pMyPAC -aRecoverUUID=1059443BD0330489609618E90F76B91B -sredis,127.0.0.1:6741 -npsorName
  • The following example removes all PSOR entries for MyPAC from the Redis server located at 127.0.0.1 on port 6741 for stores that where not prefixed:
    caspac -aRemOldPAC=MyPAC -sredis,127.0.0.1:6741 –npsorName
  • The following example removes all the Shared_CasTSQ_RC, Shared_CasTSQ_NR, Shared_CasTDQ_RC, and Shared_CasTDQ_NR stores from the Redis server located at 127.0.0.1 on port 6741:
    caspac -aRemShrQueues -sredis,127.0.0.1:6741 -npsorName
  • The following example will recover all regions on the hostname which is a member of the PAC called MyPAC and which has a Redis server located at 127.0.0.1 on port 6741:
    caspac -pMyPAC -aRecoverLostUUID=hostname -sredis,127.0.0.1:6741 -npsorName
  • The following example will retrieve a CICS DLL file from the Redis server located at 127.0.0.1 on port 6741 from a named PSOR and output it to the folder specified by the -o parameter:
    caspac -pMyPAC -aRetrieve=CICS@acct.dll -sredis,127.0.0.1:6741 -npsorName -o"c:\folder"
Parent topic: Using the Command-line Interface


casstart

Starts an enterprise server.

Syntax:

casstart [/res-name] [/oconfig-name][/uusername] [/ppassword] [/cgroup] [/z[userid]] [/x[userid]] [/w[seconds]] [/s:start-type] [/mhost:port] [/j:SYSIDNT=xxxx]

Parameters:

/res-name | Name of the enterprise server to start. Defaults to ESDEMO
/oconfig-name | When using this option in MSS-enabled regions, config-name should be the name of a SIT. The region starts 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 Micro Focus 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. It might 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.

Exception: This parameter 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 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.

/z[userid] The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /p.
/x[userid] Retrieve user credentials from user input.
Note: userid is optional.
/w[seconds]

Introduces a delay in seconds, to the end of the startup process. Values can range from 0 to 999 but the minimum delay is 15 seconds. The delay specified enables processes for the enterprise server region to start before control is passed to the user. It prevents the casstart process from exiting until the region has either started or the delay expires.

Note: Specifying the /w option without a value for the time will result in the minimum delay of 15 seconds.

Omitting this parameter means that casstart can exit before the region is ready to accept requests.

/s:start-type This option is used to start an enterprise server region that is part of a PAC. Where start-type can be:
w
For warm start.
c
For cold start. Only the first enterprise server region started in a PAC can be cold started.
Note: It is not mandatory to cold start the first enterprise server region in a PAC.
u
For an upgrade start which will prevent participating enterprise server regions from processing batch workloads as part of its normal operation, and any EXEC CICS START requests will be rejected.
The remaining enterprise server instances that are part of the PAC should be performed as warm starts. See Starting a PAC for more information.
Note:
  • If an attempt is made to cold start an enterprise server instance when one or more enterprise server instances are already running in the PAC, then it will ignore the cold start flag.
  • When /s: is specified the value of the option will override the cold/warm start settings for TS/TD queues in the SIT. If /s: is not explicitly specified then the SIT settings for TS/TD queues will be applied.
If this option is used to start an enterprise server instance that is not part of a PAC then it overrides the SIT options for TS/TD.
/mhost:port Enables you to specify the host and port that casstart should look for an MFDS service on, where the default host and port (localhost:86 or 127.0.0.1:86) is not the port the target MFDS service is bound to.
Note: If the /m parameter has not been specified but the ES_MFDS_ADDRESS environment variable has been then this will be used instead. See General Enterprise Server Environment Variables for more information.
/j:SYSIDNT=xxxx | Enables you to override the SYSID of the enterprise server region. Specify the 4-character local system identifier, SYSIDNT, which corresponds to the SYSID that you want to override.

Comments:

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

The command line utilities casstart, casstop, casfile, casout, and cassub can be invoked by a program using the call interface and passing the command line parameters to the call. For instance, you could 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 fails and issues 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] [/cgroup] [/z[userid]] [/x[userid]] [/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

This option can be used with the /s or /l option so can be run on a remote machine. Casstop sends a message to the region for it to kill all its processes. There is no shutdown processing.

/w[n] | Causes casstop to wait 'n' seconds after initiating the stop request before returning. No region state check is performed. This is to enable synchronisation when stopping from a script. If no value for 'n' is provided casstop waits for the default wait time of 15 seconds before returning.
/f Force a shutdown.

This option must be used with the /r option and can only be run on the local machine. Casstop connects to the region, retrieves the process IDs and then kills all of these processes. There is 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.

/z[userid] The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /p.
/x[userid] Retrieve user credentials from user input.
Note: userid is optional.
/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:

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


casutl

An Enterprise Server utility program.

Syntax:

casutl [/res-name]
       [/sprototype:host:port]
       [/lservername]
       [/n]
       [/xfiles-to-switch]
       [/ccurrent-directory]
       [/uuserid]
       [/ppassword]
       [/ggroup]
       [/z[userid]]
                            [/f{[e|d|s]}]
       [/h{[e|d|c]}]
       [/te{[ tracelist],[aux],[all],[ims]}]
       [/td{[ tracelist],[aux],[all],[ims]}]
       [/tl]
       [/a{[amax|admin]=nnn}]
       [/w{[l|p|f]}]

Parameters:

Table 1. Connection parameters
/res-name

Connects to an enterprise server with the specified name, es-name.

Restriction: When calling casutl from either JCL or from a Web service (that is, when you are running casutl within a SEP), it is not possible to use the /r option to connect to the server. In such cases, you must use either /s or /l to connect to the server.
/sprototype:host:port Uses the specified URL to locate the enterprise server to connect to. For example:
stcp:localhost:9003
/lservername Looks up the specified servername to find the enterprise server to connect to.
Note: If neither /r , /s or /l is specified, this defaults to /rESDEMO[64].
Table 2. Other parameters
/n | Creates a new console log file, console.log. The contents of the current console.log are saved to a new file, console.nnn_switch_date_time.
/xfiles-to-switch

Switches the active aux trace, dump and/or HSF files.

files-to-switch specifies the files to switch. This can be one or more of the following single-character arguments:

t
Stands for trace. Switches between casauxta.rec and casauxtb.rec.
d
Stands for dump. Switches between casdumpa.rec and casdumpb.rec.
h
Stands for HSF. Switches between cashsf-a.csv and cashsf-b.csv.
/ccurrent-directory | Sets an internal FS current directory.
/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 | Specifies an authorization password.
/ggroup | Specifies the sign-on group to use when running commands.
/z[userid] The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /p.
[/f{[e|d|s]}]
e
Enables Force Phase In
d
Disables Force Phase In
s
Show the current state of the Force Phase In option.
/h{[e|d|c]}
e
Enables HSF.
d
Disables HSF.
c
Closes the HSF file that is currently active.
/te{[ tracelist],[aux],[all],[ims]} Enables trace flags. Where:
tracelist
is a comma-delimited list of trace flags. This can also include the following keywords:
aux
Aux trace.
all
All trace flags (not including aux).
ims
All ims trace flags.

See the Examples section.

/td{[ tracelist],[aux],[all],[ims]} Disables trace flags. Where:
tracelist
is a comma-delimited list of trace flags. This can also include the following keywords:
aux
Aux trace.
all
All trace flags (not including aux).
ims
All ims trace flags.

See the Examples section.

/tl | List of valid trace flags that can be used in tracelist on the /te and /td options.
/a{[amax|admin]=nnn} Change the number of default SEPs or admin SEPs:
amax
Default SEPs
admin
Default admin SEPs
Note: nnn is an integer between 1 and 999.
/w{[l|p|f]} All changes to timeouts, trace flags, and memory strategy will be applied to:
l
Only the local region.
p
All members of a PAC except the regions where local changes have been made.
f
All members of a PAC.

Dependencies:

You must start the enterprise server before you can issue a casutl command.

Comments:

The /r, /s and /l options are alternatives and are mutually exclusive.

Examples

The following examples demonstrate a few scenarios where you can use casutl. MYREGION is the name of your enterprise server instance.

To switching the active trace file, use the following command:

casutl /rMYREGION /xt

To switch both the active dump and HSF files at the same time, use the following command:

casutl /rMYREGION /xdh

To start a new console log, use the following command:

casutl /rMYREGION /n

This creates the new log file and also creates a backup copy of the existing console.log as console.nnn_switch_date_time.

To enable aux,api,scp and kcp, use the following command:

casutl /teaux,api,scp,kcp

To enable all trace flags:

castul /teall

To disable all ims trace flags:

casutl /tdims

To dynamically modify the number of application execution processes to 5 for the duration of the current region instance:

casutl /rMYREGION /aamax=05
Parent topic: Using the Command-line Interface


casverify

Verifies the configuration of specified components for an enterprise server region.

Syntax:

casverify {-r{server-name}|-l|-i{stage-id}} [-e{stage-id[,...]}] [-s:{w|c|u}] [-u{userid}] [-p{password}] [-z{userid}] [-c{group}] [-m{mfds-address}] [-o{config-name}] [-f{t|j}] [-a{w|e|s|f}] [-v{i|w|e|s}] [-d{trace-file}]

Parameters:

-r{server-name}
The name of the enterprise server region to be verified.
-l
Lists all the verification stages available and their coresponding stage-id.
-i[stage-id]
This parameter requires a specific stage-id and will return more information for that verification stage.
-e{stage-id[,...]}
Specifies a list of verification stages to execute. This can be a single stage-id or comma separated list of stage-id.
Note: The order in which the verification stages are executed might be different to the sequence that you specify. This is because some stages can be dependent on others.
-s:{w|c|u}
Verifies the enterprise server region in the context of how it is to be started in a PAC environment:
w
Warm start.
c
Cold start.
u
Upgrade mode.
-u{userid}
Specify an authorized user. This user must exist within the security domains of both the Enterprise Server and Micro Focus Directory Server. That is, the security configuration for both Enterprise Server and Directory Server must be able to verify the user credentials supplied.
Note: The Enterprise Server and Directory Server might be using different security managers. It might be necessary that the user is defined in more than one security repository.
-p{password}
The password for the user.
-z{userid}
The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to -u and -p.
-c{group}
The sign-on group for the user. By default, when a user requests access to a resource, some external security managers 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.

-m{mfds-address}
Host name and port number for the Directory Server. The default value is localhost:86.
-o{config-name}
Name of the SIT to use for the enterprise server region rather than the one specified in the Enterprise Server Common Web Administration (ESCWA) pages.
-f{t|j[u]}
Specifies the output format of the verification information:
t
Text
j
JSON

The default output value is t. Append u to receive regular JSON output.

-a{w|e|s|f}
Specifying this will abort the verification process on the first instance of a:
w
Warning
e
Error
s
Severe error
f
Fatal error

The default value is f.

Note: The verification process will abort if a more severe value is encountered. For example, a value of e is specified, however, a severe or fatal occurrence is encountered first.

Encountering a severe error will result in that verification stage ending but other verification stages not dependent on it can continue to run and carry out their own verification checks. Fatal errors will always result in subsequent verification stages failing to run.

-v{i|w|e|s}
Specifies the verbosity of the logging:
i
Information
w
Warning
e
Error
s
Severe

The default value is w, which will output warnings, errors, and severe messages.

-d{trace-file}
Enables auxiliary tracing which is written as a formatted text file to an specified trace-file location. The trace-file can be specified as a file with an absolute or relative path. A trace-file that contains spaces must be quoted.

Comments:

The casverify command will return a code, which correspond to the stage-id with the highest severity or internal error which has a return code below 100. If there are no verification issues then the return code will be set to 0.

This command must be run on the same machine that will run the specified enterprise server region with the same permissions used when executing the casstart command. The casverify command cannot be executed remotely.

Parent topic: Using the Command-line Interface


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: Legacy Enterprise Server Administration User Interface


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 OpenText Support for Micro Focus Products via the OpenText Support for Micro Focus Products 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 to C:\ProgramData\Micro Focus\<product name> (assuming your %SYSTEMDRIVE% is C:). 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 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 Directory Server (MFDS).

Expand/Contract button

Click + icon 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 icon 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 icon 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 icon 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 icon 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 icon 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 + icon 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 the file can grow to the maximum file size supported; 4GB.

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 Communications 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 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 runs.

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

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) (deprecated)
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, 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 Test 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 behavior 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 region 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. 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 region.

To access this page:

  1. In ESCWA, select the enterprise server region you require.
  2. Click IMS > Configuration to open the IMS Configuration page, and then click the TM tab.
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.
Queue 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 region 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 more information.
Buffer Count
This is the tuning control. More buffers means less swapping of blocks in memory for message queue activity. The default value is 2.
CAUTION:
Micro Focus recommends you consider the implications before changing this setting.
Cold Start

Choose what information is deleted when you next start this enterprise server region:

None
No information is deleted. This is the default value.
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 list occurs each time this enterprise server region starts. By default, this is unchecked.

MFS Path

Specify the location for the files produced by MFSGENs. The default value is $IDE_MODPATH.

MFS Attribute Bias

Choose how attributes are assumed to be defined for transaction programs running on this enterprise server region:

Binary
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".
This is the default value.
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.

Active 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 value is 64. Specifying 0 indicates that keypoints are only generated when the enterprise server region 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 region. By default, this 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. The default value is 0.

Application Path

Specify the location of the transaction programs running on this enterprise server region. The default value 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
Related information
ES_TMC_AGGREGATE


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 > Permissions tabs.
User Group

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 the file can grow to the maximum file size supported; 4GB.

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 file, located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin.

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: We suggest that you back up the mf-server.dat file 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 Verify (sign-on, user authentication) 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. For example, allow the user to sign on or reject the sign-on attempt.

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

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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
  • XAT (Active)
  • Log Off
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.
XAT

Click this to view the XAT (Active) page, which enables you to view the XA-compliant database table definitions (XA resources) configured for this server.

Log Off

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


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 (1000/sec) - The average latency for transactions on this server. This is shown in milliseconds (ms), and as a graphical representation in yellow.
  • Average tasks (1000/sec) - The average time taken to complete a task on this server. This is shown in milliseconds (ms), 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) (deprecated)


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 milliseconds (ms), and as a graphical representation in yellow.
  • The average time taken to complete a task. This is shown as a figure in milliseconds (ms), 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) (deprecated)


HSF

  • HSF (summary)
  • HSF (transaction name)
Parent topic: Enterprise Server Monitor and Control (ESMAC) (deprecated)


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 milliseconds (ms), between Enterprise Server receiving the requests and the tasks beginning to run.
Average Response Time
The average time, in milliseconds (ms), 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 hhmmssttt (where ttt denotes thousandths of a second).
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.
Dynamic CTF Config File
Specify the location of the dynamic CTF configuration file to use when tracing this enterprise server region. You can then specify the dynamic CTF action for tracing based on the dynamic CTF configuration file provided:
As on file
The CTF trace will be set as specified in the dynamic CTF configuration file. The output location for the trace will be either the location configured by the original configuration file if MFTRACE_CONFIG was specified before starting the enterprise server region, otherwise it will use the enterprise server region's working directory.
All on
The CTF trace will be configured for "debug" on all components that have an mftrace.level.component_name entry in the dynamic CTF configuration file. The output location for the trace will be either the location configured by the original configuration file if MFTRACE_CONFIG was specified before starting the enterprise server region, otherwise it will use the enterprise server region's working directory.
All off
The CTF tracing will be disabled for all components that have an mftrace.level.component_name entry in the dynamic CTF configuration file.
HSF Data
CAUTION:
You must set the dynamic CTF action to All off before modifying the Dynamic CTF Config File or its file's content. Failure to do this will result in memory corruption.
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 run-time system 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 Communications Server - 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.

Validate PGM entry/exit
Validate the memory on the entry to and the exit from each program.
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) (deprecated)
Related information
ES_MEM_STRATEGY


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


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.

Stop
Stops active printers.
Parent topic: Enterprise Server Monitor and Control (ESMAC) (deprecated)


Diagnostics

  • Dump data set
  • Trace store
Parent topic: Enterprise Server Monitor and Control (ESMAC) (deprecated)


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, hundredths of a second, and milliseconds.

Parent topic: Diagnostics


Resources

  • Services
  • Active
  • ESMAC (deprecated)
  • 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) (deprecated)


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


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)
  • XAT (Active)
  • SysC (Active)
  • TST (Active)
  • T-TYPE (Active)
  • DOCTEMPLATE (Active)
  • TCPIPSv (Active)
  • URIMAP (Active)
  • BUNDLE (Active)
  • PIPELINE (Active)
  • WEBSERVICE (Active)
  • TRANCLASS (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.
Note:

To be able to purge a TD Queue from ESMAC, you need to have a CZTD entry in the TCICSTRN resource in the LDAP repository and the user must have at least READ access rights.

To create an entry in the LDAP repository, you need to add some code in the LDF file similar to the following:

###################
###### PCT : CZTS #
###################
dn: CN=CZTS,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro
Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: TSQ purge transaction

###################
###### PCT : CZTD #
###################
dn: CN=CZTD,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro
Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: TDQ purge transaction
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 icon (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


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
  • XAT
Parent topic: Lists of Active Resources
Parent topic: Enterprise Server Monitor and Control (ESMAC) (deprecated)


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


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
Note:

To be able to purge a TS Queue from ESMAC, you need to have a CZTS entry in the TCICSTRN resource in the LDAP repository and the user must have at least READ access rights.

To create an entry in the LDAP repository, you need to add some code in the LDF file similar to the following:

###################
###### PCT : CZTS #
###################
dn: CN=CZTS,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro
Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: TSQ purge transaction

###################
###### PCT : CZTD #
###################
dn: CN=CZTD,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro
Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: TDQ purge transaction
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


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


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


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 the name of the URIMAP; whether the URIMAP definition is for an HTTP server, HTTP client, or PIPELINE; and whether it is enabled or disabled.

Parent topic: Lists of Active Resources


BUNDLE (Active)

Use this page to view the BUNDLES available on this server.

Details
Click this to display detailed information for the BUNDLE.

The rest of the information in this row shows the name of the BUNDLE, and whether it is enabled or disabled.

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


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


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)
  • XAT
  • SysC Entry (sysc_name)
  • TST Entry (tst_name)
  • T-TYPE Entry (ttype_name)
  • DOCTEMPLATE Entry (doctemplate_name)
  • TCPIPService Entry (tcpipsv_name)
  • URIMAP Entry (urimap_name)
  • BUNDLE Entry (bundle_name)
  • PIPELINE Entry (pipeline_name)
  • TRANCLASS Entry (trnclass_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.

Cataloged file, FCT Fix Up
The Fix Up process is applied to FCTs which point to catalog DSNs. Typically this happens automatically on first access, and once only. If a change is made to a catalog entry which is referred to by an FCT, this button enables you to force a Fix Up process to prevent run time divergence between the physical file's DCB information and that held in the live table(s).
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


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
Parent topic: XAT (Active)


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


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


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


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


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


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
  • PIPELINE
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 – 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.
Socketclose
The duration for which the http connection is held once Enterprise Server has finished using it. Enter 0 for immediate release, or a figure corresponding to hhmmss (for example, 000130 for 1 minute and 30 seconds).
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


BUNDLE Entry (bundle_name)

Use this page to view information and set values for the BUNDLE named bundle_name, selected from the BUNDLE (Active) page.

Click Apply to save changes you have made to the page and refresh the page.

BUNDLE
The name of this BUNDLE definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the BUNDLE have been saved and the entry updated. Click Refresh to remove this message.
Status
  • Enabled - the BUNDLE Entry is enabled.
  • Disabled - the BUNDLE Entry is disabled.
Base Scope
Not supported for this release.
Bundle Dir
The full path to the directory that contains the JSBIND file for the BUNDLE.
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.
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


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

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.
  • 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 (deprecated)


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


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


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.
GMTRAN
Specify what to do when F3 or CLEAR is pressed on the CICS Signon transaction CESN/CESL. You can specify either Exit (default) or Disconnect (will disconnect the TN3270 terminal from the region).
NQRNL
Set to Yes if you want the global resource serialization to perform RNL processing, searching an appropriate RNL to determine the scope of the resource. Set to No by default.
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.

Reset time
Specify the action that CICS should take to handle automatic time changes:
Immediate
The system detects a timezone (date) change at any time. It then changes the clock in the region on the next transaction which is started.
No
The system detects a timezone change at midnight and writes a notification in the console.log. You then need to run a transaction that will issue the PERFORM RESETTIME for the time to be changed.
Yes
The system detects a timezone change at midnight and automatically resets the clock.
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 run time 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 run time 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 run time 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 run time 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 Focus.
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 behavior 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 to equate to a BMS paging command. Prefix the character string with the command you want to execute when the key is pressed, followed by any additional commands. For example, if the BMS PAGIN RETRIEVE command is set to /P and you want PF1 to execute a page forward, specify the /PN character string where /P executes the BMS PAGIN RETRIEVE command and N executes NEXT.

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


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.
GMTRAN
Specify what to do when F3 or CLEAR is pressed on the CICS Signon transaction CESN/CESL. You can specify either Exit (default) or Disconnect (will disconnect the TN3270 terminal from the region).
NQRNL
Set to Yes if you want the global resource serialization to perform RNL processing, searching an appropriate RNL to determine the scope of the resource. Set to No by default.
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.

Reset time
Specify the action that CICS should take to handle automatic time changes:
Immediate
The system detects a timezone (date) change at any time. It then changes the clock in the region on the next transaction which is started.
No
The system detects a timezone change at midnight and writes a notification in the console.log. You then need to run a transaction that will issue the PERFORM RESETTIME for the time to be changed.
Yes
The system detects a timezone change at midnight and automatically resets the clock.
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 run time 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 run time 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 run time 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 run time 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 Focus.
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 behavior 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 to equate to a BMS paging command. Prefix the character string with the command you want to execute when the key is pressed, followed by any additional commands. For example, if the BMS PAGIN RETRIEVE command is set to /P and you want PF1 to execute a page forward, specify the /PN character string where /P executes the BMS PAGIN RETRIEVE command and N executes NEXT.

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
  • XATs for CICS Startup List name
  • DOCTEMPLATEs for CICS Startup List name
  • TCPIPServices for CICS Startup List name
  • URIMAPs for CICS Startup List name
  • BUNDLEs for CICS Startup List
  • PIPELINEs for CICS Startup List name
  • WEBSERVICEs 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


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


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


URIMAPs for CICS Startup List name

Use this page to view all 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, HTTP client, or PIPELINE; and its description.

New
Click one of the buttons to create a new resource.
Parent topic: by StartL


BUNDLEs for CICS Startup List

Use this page to view all BUNDLEs 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 BUNDLE in this row.

The rest of the information in this row shows the name of the BUNDLE, the group to which it belongs, and its description.

New
Click one of the buttons to create a new resource.
Parent topic: by StartL


PIPELINEs for CICS Startup List name

Use this page to view all PIPELINEs 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 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 StartL


WEBSERVICEs for CICS Startup List name

Use this page to view all WEBSERVICEs 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 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 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 DOCTEMPLATE
  • CICS Defined TCPIPSERVICE
  • CICS Defined URIMAP
  • CICS Defined BUNDLE
  • CICS Defined PIPELINE
  • CICS Defined WEBSERVICE
  • CICS Defined TRANCLASS
  • CICS Defined THRESHOLD
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 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 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 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 BUNDLE

Use this page to view all defined BUNDLE resources. You can also create a new resource from this page.

Details

Click this to see detailed information for the BUNDLE in this row.

The rest of the information in this row shows the name of the BUNDLE, 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 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


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 THRESHOLD

Use this page to view all defined THRESHOLD resources. You can also create a new resource from this page.

Note: For Windows, the Windows Management Instrumentation (WMI) service must be started for the THRESHOLD feature to work.
Details

Click this to see detailed information for the THESHOLD in this row.

The rest of the information in this row shows the name of the THRESHOLD, 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).

Dispatch
Click this to see the Dispatch queue. This lists jobs that are scheduled to a batch or printer process but not yet actioned (transient state).
Active

Click this to see the Active queue. This lists jobs that are currently running.

Complete
Click this to see the Complete queue. This lists data sets with the following statuses:
  • Output - the output files waiting to be printed (usually waiting for a printer for the correct class to be available)
  • OutHold - the output files that are held (Hold button on a job’s entry in the Complete Queue)
  • Printed - the output files 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.

Disable Additional Qualifiers

Use this option to make catalog searching and filtering more consistent with the results produced on the mainframe. Check the option to disable the use of additional qualifiers when filtering the catalog results. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B (as if A.B** had been entered).

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.
Note: You must remain on the same page when using the 'Dump' feature. Select Dump, and then click Display.

This displays the file records in hexadecimal.

Details

Check this if you want extra details to be included in the display of the file contents.

MGMTCLAS

The management class for a SMS-managed data set.

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
Resource Classes for ESMAC and Operator Command Security


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 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 Term
  • CICS TST
  • CICS T-Type
  • CICS XAT
  • CICS DOCTEMPLATE
  • CICS TCPIPSERVICE
  • CICS URIMAP
  • CICS BUNDLE
  • CICS PIPELINE
  • Create, View and Edit an IMS Transaction
  • CICS TRANCLASS
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.

Refresh
Click this option to refresh the FCT details: any edits that have not been applied are reverted back to their original value.
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).

Status

Choose whether the file is accessible to transactions at system startup

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

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.

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.

File Path

Specify the path of the physical file if you want to override the default. The file can be located on disk or within a database. For database-hosted files, use the notation sql://host[/instance]/datastore[?folder=/path] - for more information, refer to The dbfhdeploy Command Line Utility. Do not include the filename or file extension. The file path can be up to 255 characters long. You must uncheck Use catalog before you can specify a path, because if you use the catalog, this information is stored in the catalog, and not the FCT entry.

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.

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

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.

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.

Display

Click to display the currently installed definition of this resource.

Install

Click to install (make active) this resource.

Delete

Click to delete this FCT. This button is displayed only after you click Add.

Copy

Click 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

Click to create and view dump information for this FCT. This button is displayed only after you click Add.

Parent topic: Pages for Creating Resources
Related concepts
The dbfhdeploy Command Line Utility


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.

The IBM transaction attribute TASKREQ is supported via the use of hexadecimal transaction names, using the following hexadecimal values:

PF Keys | TASKREQ Values
1 - 9 | x’f1ffffff’ to x’f9ffffff’
10 - 12 | x'7affffff', x'7bffffff', x'7cffffff'
13 - 21 | x'c1ffffff' to x'c9ffffff'
22 - 24 | x'4affffff', x'4bffffff', x'4cffffff'
PA Keys | TASKREQ Values
1 - 3 | x'6cffffff', x'6effffff', x'6bffffff'
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”.

FQ Partner name
Identifies a fully qualified partner name for LU62 connection definitions. This field is formed of a NETWORK ID and a Partner LU name (both must be eight characters at the most) separated by a period ('.'). For example, BBNET1.CICSDEV1.

If the Fully Qualified Partner name in the connection is validated and installed, it will be used at run time on the APPC Allocate verb, whereas the PARTNER LU Alias is set to binary zeroes.

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 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. If the terminal definition includes a user ID, Enterprise Server honors the terminal user ID, and you can leave the this field blank.

CAUTION:
When the user ID is specified in the terminal definition, this logs you into the terminal without password verification. Use with care!
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 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 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 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:
Indicates whether the TCP/IP service is to use the secure sockets layer (SSL) for encryption and authentication. See SSL Support for CICS Web Interface Servers for more information.
DNS Connection Balancing:
Not supported for this release.
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
  • A CICS PIPELINE (used for inbound CICS Web Services requests)
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.
Socketclose
The duration for which the http connection is held once Enterprise Server has finished using it. Enter 0 for immediate release, or a figure corresponding to hhmmss (for example, 000130 for 1 minute and 30 seconds).
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
The CICS PIPELINE resource for the Web service.
WebService
The CICS WEBSERVICE resource for the Web service.
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 enterprise server 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 BUNDLE

Use this page to create a new BUNDLE.

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

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.

BUNDLE
The name of this BUNDLE definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the BUNDLE have been saved and the entry updated. Click Refresh to remove this message.
Status
  • Enabled - the BUNDLE Entry is enabled.
  • Disabled - the BUNDLE Entry is disabled.
Base Scope
Not supported for this release.
Bundle Dir
The full path to the directory that contains the JSBIND file for the BUNDLE.
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.
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


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 DOCTEMPLATE - doctemplate_name (group_name)
  • CICS TCPIPSERVICE - tcpipservice_name (group_name)
  • CICS URIMAP - urimap_name (group_name)
  • CICS BUNDLE - bundle_name (group_name)
  • CICS PIPELINE - pipeline_name (group_name)
  • CICS TRANCLASS trnclass_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”.

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. If the terminal definition includes a user ID, Enterprise Server honors the terminal user ID, and you can leave the this field blank.

CAUTION:
When the user ID is specified in the terminal definition, this logs you into the terminal without password verification. Use with care!
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 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 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 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.
Socketclose
The duration for which the http connection is held once Enterprise Server has finished using it. Enter 0 for immediate release, or a figure corresponding to hhmmss (for example, 000130 for 1 minute and 30 seconds).
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 BUNDLE - bundle_name (group_name)

Use this page to view and edit the BUNDLE bundle_name, selected from the CICS Group group_name page.

Click Apply to save changes you have made to the page and refresh the page.

BUNDLE
The name of this BUNDLE definition. If you click Apply, the message "Update complete" is also displayed when the changes you have made to the BUNDLE have been saved and the entry updated. Click Refresh to remove this message.
Status
  • Enabled - the BUNDLE Entry is enabled.
  • Disabled - the BUNDLE Entry is disabled.
Base Scope
Not supported for this release.
Bundle Dir
The full path to the directory that contains the JSBIND file for the BUNDLE.
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.
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


Users

  • Users List
  • Create a New CICS SNT
  • View and Edit a CICS SNT
Parent topic: Enterprise Server Monitor and Control (ESMAC) (deprecated)


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


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


Log Off

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

Enter the password/phrase associated with your user ID.

Select Force all to upper case to ensure each character you type in the Password/Phrase box is submitted as upper case.

Group
The group of which this user is a member.
New PW/Phrase

If you want to create a new password/phrase for your user ID, enter it in this field. You must enter your current password in the Password/Phrase field before you can change your password/phrase.

Repeat PW/Phrase

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


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 might 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 full pathname of your server certificate - for example, srvcert.pem.
Keyfile
Specify the full pathname of your private key file - for example, srvkey.pem. The private key is used to decrypt encrypted data you receive.
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 optional textual configuration information that determines the startup and run-time behavior of the listener. See Configuration Information section in the chapter Communications Processes and Service Listeners in your Configuration and Administration Guide for more information.

Description

Specify an optional text description of the listener, for example, its purpose and owner.

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

Check this to make the communications process SSL-enabled. See To Create a Secure Listener for more information.

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

Check this to enable Transport Layer Security (TLS/SSL), which provides encrypted communication between server and client applications and authentication of online entities.

Note: Passphrases for communication processes certificates must be provided in the communication process configuration file (mf-server.dat). See To Configure the Passphrase in a File in the chapter Setting Up Secure Communications.

In order for MFDS to be able to communicate with MFCS via TLS (SSL), MFDS must have the environment variable MFDS_server_CAROOT where server is the name of the Enterprise Server instance. The environment variable specifies the full file path of the CA root certificate used to sign the control channel's certificates.

Certificate
Specify the absolute path and filename for 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.
Keyfile
Specify the absolute path and filename for your private key file - for example, srvkey.pem. The private key is used to decrypt encrypted data you receive.
Server CA Root Certificate
This is the absolute file path to the CA root certificate used to sign the control channel's certificates.
Note: MFDS requires this to enable it to communicate with MFCS via TLS (SSL). If the MFDS_server_CAROOT environment variable has been specified then it takes precedence over the Server CA Root Certificate value.
Configuration Information

Optional, specify textual configuration information that determines the start-up and run-time behavior of the communications process. You cannot change this field if the enterprise server has a status of "Started". For details of the valid entries, see Editing Communications Settings in the chapter Configuring Client-Server Communications.

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

Most ESM Modules ignore this parameter. It is supported by the MLDAP 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 required from the security manager.

Most ESM Modules ignore this parameter. It is supported by the MLDAP 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 Test Server\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 standard information

Check this if you want journal entries to be written for all events.

Journal level - Extra debug information

Check this if you want journal entries to be written for additional file and internal operations. Only check this option if specifically requested to by OpenText Support for Micro Focus Products.

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 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 Test Server\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.

Most ESM Modules ignore this parameter. It is supported by the MLDAP 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.

Most ESM Modules ignore this parameter. It is supported by the MLDAP 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 OpenText Support for Micro Focus Products via the OpenText Support for Micro Focus Products 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 stop 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

Optional custom server certificate passphrase.

Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This takes the following form:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
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.

Cipher suites
Specifies the priority of cipher suites to be used.

The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:

!
Exclude. Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add. Add the cipher suite to the end of the collection.
-
Delete. Delete the cipher suite from the existing collection.

By default, the following cipher suite list is used:

kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP

To determine the cipher suites supported by your version of OpenSSL, type the following from a command prompt:
openssl ciphers -v 'ALL:COMPLEMENTOFALL'
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.

DH minimum group size
Specifies the size in bits of the modulus length of the Diffie-Hellman group.
Note: Micro Focus recommends a minimum modulus size of 2048 bits.
Key Exchange Cipher Groups
Specifies the Elliptic Curve Cryptograph (ECC) curve collection to be used. By default, the collection used is:
secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1
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 administration 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 might 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 Verify against all Security Managers for more information.

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.

TLS honor server cipher list
By default, the TLS honor server cipher list is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
Note: If the TLS protocols and Cipher suites list are not specified then it uses the default. See Configuring a TLS Protocols List and Configuring a Cipher Suites List for more information.
TLS protocols
Specifies the list of TLS protocols to be used in order of precedence listed.
Valid protocols are SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, and TLS1.4, where TLS1.4 is a placeholder to enable support for future versions. By default, only the TLS protocols are enabled. Each specified protocol is preceded by one of the following operators:
!
Exclude. Permanently exclude the protocol and ignore any subsequent attempt to add the protocol back in.
+
Add. Add the protocol to the existing collection.
-
Delete. Delete the protocol from the existing collection.
Note: You can use the special option ALL to specify all of the supported protocols. Use -ALL to empty the default options list followed by the new options you require.

You must use @SECLEVEL=0 for TLS 1.1 and earlier. See Security Levels for more information.

For example, to only use TLS1.1 and TLS1.2, type the following:

-ALL+TLS1.1+TLS1.2

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 TLS is enabled, check this option and specify the paths for root certificates, server certificate, key file, and passphrase. In addition, the MF_ROOT_CERT environment variable will need to be set to the root-certificates file 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 unauthorized 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 (that is, 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 required 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.

See Configuring a Cipher Suites List and Security Levels for more information.

For additional information on cipher suite configuration please refer to the OpenSSL documentation, click here.

Parent topic: Security Configuration Screen Help
Related information
MF_ROOT_CERT


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 does not return a certificate, 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 root and intermediate certificates of CAs that you trust. This file must contain the root certificate of the CA that signed the client certificate, and also any intermediate CA certificates that are used in the client certificate chain and are not provided by the client. For example, if you want to use client certificates signed by Demo CA, you could set this to:

DemoCA-dir/entities/CAs/EC_CAcollection.pem

where DemoCA-dir is the absolute path of the directory you specified to Demo CA when creating certificates and keys.

Note: Enterprise Developer supports DER, CER, PKCS#7, PKCS#8, PKCS#12 and PEM certificate file formats and PKCS#8, PKCS#12 and PEM for key file formats.
TLS honor server cipher list
By default, the TLS honor server cipher list is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
Note: If the TLS protocols and Cipher suites list are not specified then it uses the default. See Configuring a TLS Protocols List and Configuring a Cipher Suites List for more information.
TLS protocols
Specifies the list of TLS protocols to be used in order of precedence listed.
Valid protocols are SSL2, SSL3, TLS1, TLS1.1, TLS1.2, TLS1.3, and TLS1.4, where TLS1.4 is a placeholder to enable support for future versions. By default, only the TLS protocols are enabled. Each specified protocol is preceded by one of the following operators:
!
Exclude. Permanently exclude the protocol and ignore any subsequent attempt to add the protocol back in.
+
Add. Add the protocol to the existing collection.
-
Delete. Delete the protocol from the existing collection.
Note: You can use the special option ALL to specify all of the supported protocols. Use -ALL to empty the default options list followed by the new options you require.

You must use @SECLEVEL=0 for TLS 1.1 and earlier. See Security Levels for more information.

For example, to only use TLS1.1 and TLS1.2, type the following:

-ALL+TLS1.1+TLS1.2

Cipher suites
Specifies the priority of cipher suites to be used.

The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:

!
Exclude. Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add. Add the cipher suite to the end of the collection.
-
Delete. Delete the cipher suite from the existing collection.

By default, the following cipher suite list is used:

kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP

To determine the cipher suites supported by your version of OpenSSL, type the following from a command prompt:
openssl ciphers -v 'ALL:COMPLEMENTOFALL'
DH minimum group size
Specifies the size in bits of the modulus length of the Diffie-Hellman group.
Note: Micro Focus recommends a minimum modulus size of 2048 bits.
Key Exchange Cipher Groups
Specifies the Elliptic Curve Cryptograph (ECC) curve collection to be used. By default, the collection used is:
secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1

See Configuring a Cipher Suites List and Security Levels for more information.

For additional information on cipher suite configuration please refer to the OpenSSL documentation, click here.

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 Test Server\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 Interfaces Created Using the Interface Mapping Toolkit
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.

The Interface Mapping Toolkit, part of your COBOL development system, allows you to expose services to clients. These COBOL services can then be invoked by clients as Web Services or through a J2EE connector or through the COM interface. Services that have been deployed using the Interface Mapping Toolkit always contain one or more operations.

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 only Configuration Information settings for services are for deployment services, the special services with Service Class “MF Deployment” which are used by the Interface Mapping Toolkit to deploy Web Services and J2EE EJBs.

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, 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:
The process within which an Application-managed service is executed does not terminate when that service completes. You should consider how this might affect resource manager client disposition. For example, if the service is accessing Resource Managers (RMs) for which there is no XAT defined there may be a need to manage the connection.

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

When you deploy a service using the Interface Mapping Toolkit, all the objects required are created automatically, complete with their relationships.

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 milliseconds (ms).
  • The average time taken to complete a task, in milliseconds (ms).
  • 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 (deprecated)
  • 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 (deprecated)


To Record Service Input and Output (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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


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 %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\es-name where es-name is the name of the enterprise server. The file is named casdumpa.rec (or it might be named casdumpb.rec if you specified a maximum diagnostics file size on the Edit Server page).

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 also runs under that account. Hence, the location of the files is typically %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREAes-name 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 Test 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 Interfaces Created Using the Interface Mapping Toolkit

To view documentation for the deployment of service interfaces created using the IMTK, see one or more of the following topics, depending on what type of information you want to view:

  • For concept topics on deploying COBOL Program service interfaces, see Deploying Service Interfaces to Enterprise Server under Programming > COBOL Programming > Interface Mapping Toolkit (IMTK).
  • For task topics on deploying COBOL Program service interfaces, see Deploy Service Interfaces to Enterprise Server under Programming > COBOL Programming > Interface Mapping Toolkit (IMTK) > How to
Parent topic: Deploying and Configuring Modernized Applications


Enterprise Server Task Index

  • Command Prompts
  • Accessing the Enterprise Server Administration UI
  • Accessing the ESMAC User Interface
  • Administer a Server Using ESMAC (deprecated)
  • Configure the Directory Server
  • Deploy Service Interfaces to Enterprise Server
    Tasks related to deploying service interfaces to Enterprise 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


Command Prompts

  • To start an Enterprise Test Server command prompt
  • To start an Enterprise Test Server command prompt as an administrator
  • To start an Enterprise Test Server command prompt
  • To start an Enterprise Test Server command prompt as an administrator
Parent topic: Enterprise Server Task Index
Parent topic: Tools


To start an Enterprise Test Server command prompt

Windows 7 and Earlier
  1. From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Test Server > Tools.
  2. Depending on your operating system, right-click either Enterprise Test Server Command Prompt (32-bit) or Enterprise Test Server Command Prompt (64-bit); then select Run as administrator from the context menu.
  3. If prompted, click Yes.
Windows 8, 8.1, and Windows Server 2012
  1. From the Windows Start screen, right-click either the Enterprise Test Server Command Prompt (32-bit) or the Enterprise Test Server Command Prompt (64-bit) tile.
  2. On the bottom of the page, click Run as administrator.
  3. If prompted, click Yes.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus > Enterprise Test Server > Enterprise Test Server Command Prompt (32-bit) or Enterprise Test Server Command Prompt (64-bit) > More > Run as Administrator.
Windows 11
  • Open Windows Terminal on your machine, and click Open a new tab. From the drop-down menu, select either Micro Focus Enterprise Test Server Command Prompt (32-bit) or Micro Focus Enterprise Test Server Command Prompt (64-bit).
Parent topic: Command Prompts
Parent topic: Command Prompts


To start an Enterprise Test Server command prompt as an administrator

Windows 7 and Earlier
  1. From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Test Server > Tools.
  2. Depending on your operating system, right-click either Enterprise Test Server Command Prompt (32-bit) or Enterprise Test Server Command Prompt (64-bit); then select Run as administrator from the context menu.
  3. If prompted, click Yes.
Windows 8, 8.1, and Windows Server 2012
  1. From the Windows Start screen, right-click either the Enterprise Test Server Command Prompt (32-bit) or the Enterprise Test Server Command Prompt (64-bit) tile.
  2. On the bottom of the page, click Run as administrator.
  3. If prompted, click Yes.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Test Server > Enterprise Test Server Command Prompt (32-bit) or Command Prompt (64-bit) > More > Run as Administrator.
Windows 11
  • Open Windows Terminal on your machine, and click Open a new tab. From the drop-down menu you can select either Micro Focus Enterprise Test Server Command Prompt (32-bit) or the Micro Focus Enterprise Test Server Command Prompt (64-bit). Press Ctrl when you click the item to run as administrator.
Parent topic: Command Prompts
Parent topic: Command Prompts
Related concepts
Offline Extract Schema Solution


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

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.
  • 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 (deprecated)
  • 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 (deprecated)
  • 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 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: Administer a Server Using ESMAC (deprecated)


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: Administer a Server Using ESMAC (deprecated)


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 (deprecated)
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 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: Administer a Server Using ESMAC (deprecated)


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 (deprecated)
Related information
To shut down a server
To view a local trace for a SEP


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: Administer a Server Using ESMAC (deprecated)


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: Administer a Server Using ESMAC (deprecated)


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

    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.

    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: Administer a Server Using ESMAC (deprecated)
Related reference
casdump
Related information
Viewing a Dump
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


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: Administer a Server Using ESMAC (deprecated)


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: Administer a Server Using ESMAC (deprecated)


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 displayed, 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, and service end.

    This is the default value.

    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.

    Each level includes all lower-level information.

  7. In the next group of fields, below the heading PIDs, if you do not 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 do not 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: Administer a Server Using ESMAC (deprecated)
Related information
Viewing a System Trace: Diagnostics Example
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


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 Service Interfaces to Enterprise Server

  • To add or remove application files to deploy
  • To associate an enterprise server with a project
  • To compile a service driver program on a remote UNIX machine
  • To generate and deploy a service interface from a project
  • To delete a deployed service
  • To deploy to a remote enterprise server
  • To deploy a service interface using imtkmake
  • To install a deployment package using mfdepinst
  • To redeploy a service interface
  • To set deployment properties
Parent topic: Enterprise Server Task Index


To add or remove application files to deploy

  1. Use Add Files and Remove Files to create a list of application files to deploy.
  2. Click OK.
Parent topic: Deploy Service Interfaces to Enterprise Server


To associate an enterprise server with a project

  1. In Server Explorer, expand Micro Focus Servers to see a list of available enterprise server instances.
  2. Right-click the enterprise server instance with which to associate the project; then select Associate with project > projectName.
Note: Ensure that the bitism of the enterprise server instance and the associated project match.
Parent topic: Deploy Service Interfaces to Enterprise Server


To compile a service driver program on a remote UNIX machine

  1. Log on to the target machine.
  2. Go to the package path folder. If you are using a telnet session originating from your development machine, you can paste the package path from the clipboard.
  3. Compile the service driver source using the cob command.
Parent topic: Deploy Service Interfaces to Enterprise Server


To generate and deploy a service interface from a project

  1. From , associate an enterprise server instance with the project containing the service interface you want to deploy.
  2. Start the enterprise server instance.
  3. Ensure that you have set all appropriate properties for service interface deployment.
  4. In , right-click your service interface; then select Deploy from the context menu.
Notes:
  • Enterprise Server Administration lists your deployed service as a service of the enterprise server running your application. You must delete the service from your enterprise server before you can redeploy it.
Parent topic: Deploy Service Interfaces to Enterprise Server


To delete a deployed service

  1. To start ESCWA from the Server Explorer, right-click , and select .
  2. In the menu bar, click NATIVE.
  3. In the navigation tab, expand Directory Servers > Default, and then select your enterprise server instance.
  4. On the GENERAL drop-down list, click Services.
  5. Expand http://tempuri.org/service-interface-name.
  6. Select the row for deployed service you want to delete.
    Tip: The names of deployed services appear on the list preceded by a hash tag (#).
  7. Click Delete DELETE in the row for your deployed service.

    This opens DELETE SERVICE confirmation dialog box.

  8. Click DELETE.
Parent topic: Deploy Service Interfaces to Enterprise Server


To deploy to a remote enterprise server

  1. Edit the mf-client.dat file, located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory by default, to add the location of your remote enterprise server. Use the following syntax:
    mrpi://{IPaddress | hostname}:port
    Where IPaddress is the IP address for the remote machine, hostname is the machine name of the remote machine (use one or the other), and port is the port number. For example, the following is an excerpt from mf-client.dat that shows the default server specification, and the addition of one remote server specification:
    [directories]
; Point MFCC to local default MFDS. The port specification ":0" means MRPI
; will first look for the CCITCP2_PORT environment variable for the port to
; connect to. If that's not set, it will try to look up the "mfcobol"
; service name in the /etc/services (%WINDIR%\system32\drivers\etc\services
; on Windows), and use that port. If that's not found either, it will use
; the official Micro Focus directory port, which is 86.
mrpi://127.0.0.1:0
mrpi://105.1.168.92:86
    Note: Before making changes to mf-client.dat, we recommend that you copy the file to an alternative location. After updating the file, set the MFC_CONFIG environment variable to point to the new location.
  2. In the Server Explorer, right-click , and select from the context menu.
  3. In the field, type the number of the port you want to use (default is 86); then click .
Parent topic: Deploy Service Interfaces to Enterprise Server


To deploy a service interface using imtkmake

  1. Start an Enterprise Developer command prompt.
  2. Change to the directory that contains your service interface (.svi) file.
  3. Enter the following:
    imtkmake -generate -deploy service=service-name type=service-type server=server-name,deployer-name [optional-parameters]
    where:
    service-name | The name of your service interface
    service-type One of:
    • EJB
    • J2SEbean
    • WebService
    • REST
    server-name | The name of the enterprise server to which you want to deploy the service interface
    deployer-name | The name of a deployment service on that enterprise server
    optional-parameters | Optional parameters available with the imtkmake command

See the imtkmake command reference topic for complete information.

Parent topic: Deploy Service Interfaces to Enterprise Server


To install a deployment package using mfdepinst

  1. If you don't already have one, generate a COBOL archive (.car) file by either deploying a service interface from an Enterprise Developer project or using the imtkmake command.
  2. Deploy the .car file using the mfdepinst command.
    You can either pass any required install options for mfdepinst at the command line or use the .mfdeploy file. For example, to deploy the services in myService.car, enter the following at a command prompt:
    mfdepinst [install-options] myService.car

See mfdepinst command for complete details about the install options and .mfdeploy.

Parent topic: Deploy Service Interfaces to Enterprise Server


To redeploy a service interface

  1. In the Server Explorer, stop the enterprise server instance.
  2. Delete the service from the enterprise server instance.
  3. Deploy the service using the deployment method of your choice.
  4. Confirm that the service has been successfully deployed by refreshing Enterprise Server Administration.
Parent topic: Deploy Service Interfaces to Enterprise Server


To set deployment properties

  1. From the , right-click a service interface; then click Properties.
  2. Modify property settings as required. For complete information on each property, see .
Parent topic: Deploy Service Interfaces to Enterprise Server


Deploy to Java EE Application Servers

Note: Some components that might be required to successfully deploy to a Java AS are either provided or are built using our Enterprise Developer product. These components are noted in the following topics.
  • To Deploy to WebSphere
  • To Deploy to WebLogic
  • To Deploy to JBoss
  • To deploy to Tomcat
  • 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


To Deploy to WebSphere

This topic describes how to deploy an application developed using the Interface Mapping Toolkit to WebSphere Application Server.

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.

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: Deploy to Java EE Application Servers


To Deploy to WebLogic

This topic describes how to deploy an application developed using the Interface Mapping Toolkit to WebLogic Application Server.

  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 Test 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
    Located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 directory by default.
    mfconnector.jar
    Located in the subdirectory of %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\javaee\javaee7\appsrv directory, where appsrv represents a subdirectory named for your Java application server and, in some cases, the version as well. For a list of supported application servers, see the Java Application Servers section of the Supported Operating Systems and Third-party Software topic. that corresponds to your application server. For example, the mfconnector.jar file for WebLogic is located in a subdirectory named oracleweblogic1221.
  3. Open the startup script for your project in a text editor. This startup script is StartWebLogic.cmd , and is located in your domain's bin directory of your WebLogic installation.
  4. Go to the end of the file.
  5. 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 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.

    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: Deploy to Java EE Application Servers


To Deploy to JBoss

This topic describes how to deploy an application developed using the Interface Mapping Toolkit to JBoss Application Server.

Important: For a current list of supported JBoss application server versions, see the Application Server JCA support for Enterprise Server topic under Additional Software Requirements.

Installing JBoss Application Server

You can download JBoss Application Server from the JBoss official website, 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 administration console. To start the console:

  • Enter http://localhost:9990/console/App.html in your Web browser. Port 9990 is predefined as the Management Console socket binding.

Starting and Stopping JBoss Application Server

You can start and stop JBoss Application Server from the JBoss console or from the command line, as follows.

  • Run jboss_home\bin\standalone.bat to start it.
  • Run jboss_home\bin\jboss-cli --connect command=:shutdown to stop it.

Deploying the Resource Adapter

To deploy a resource adapter for JBoss EAP 7.x, update the standalone.xml file, located in your JBoss installation's standalone\configuration directory, as follows:

Disable the jca subsystem
Edit the <archive-validation> child of the <subsystem xmlns="urn:jboss:domain:jca:5.0"> element to read as follows:
<archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>
Add the mfcobol-notx.rar resource adapter
Replace the existing resource-adapters subsystem element in its entirety with the following subsystem definition:
<subsystem xmlns="urn:jboss:domain:resource-adapters:5.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
Within the <subsystem xmlns="urn:jboss:domain:resource-adapters:5.0"> tag, add the following <resource-adapter> definition as a child of <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>
Add the mfcobol-xa.rar resource adapter
Within the <subsystem xmlns="urn:jboss:domain:resource-adapters:5.0"> tag, add the following <resource-adapter> definition as a child of <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>

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.

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

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: Deploy to Java EE Application Servers


To deploy to Tomcat

Installing Tomcat Application Server

You can download Tomcat Application Server from http://tomcat.apache.org, and install it from there.

Starting and Stopping Tomcat

You can start and stop Tomcat from the command line, as follows:

Tomcat 7
  • Run tomcat_home\bin\catalina.bat start to start it.
  • Run tomcat_home\bin\catalina.bat stop to stop it.

Deploying the Application .war File

When you generate a client and a J2SE Bean together, a .war file is generated and placed into the my-project\repos\my-service.deploy directory. The simultaneous generation of both a client and J2SE Bean is supported for Tomcat only.

Tomcat 7
Copy the application .war file from the directory my-project\repos\my-service.deploy\my-service.war into your Tomcat deployment directory which is, by default, tomcat_home\webapps

Undeploying the Application .war File

You can undeploy an application .war file from a Web browser providing a URL constructed as follows:

http://servername:port/manager/text/stop?undeploy=/application-context

Logging

Tomcat 7
Tomcat stores log files by default in tomcat_home\logs.

Further Information

For further information, see the official Tomcat Web site.

Parent topic: Deploy to Java EE Application Servers


To Create Deployment Descriptors Manually

Note: For some application servers, deployment descriptors are automatically created when you generate an EJB using the IMTK. A list of application servers for which deployment descriptions are automatically created appears in the drop-down list for the field . See To set deployment properties and for details.

You can create deployment descriptors using the administration tool provided by your Java application server. Alternatively, you can generate a sample descriptor using the Interface Mapping Toolkit and edit the sample. 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.

    JNDI name | Reference name
    Java EE 7 | eis\MFCobol_v1.5 | CCIMFCobol_v1.5

To create deployment descriptors from dummy ones:

  1. Generate a dummy EJB and client using the Interface Mapping Toolkit.
  2. Create deployment descriptors, by deploying the dummy EJB using the Deploy tool:

    The descriptors are packaged in the myService.ear file in the folder repos/myService.deploy. The following descriptors are generated:

    • application*.xml
    • *ejb-jar*.xml
    • *web*.xml
  3. Extract the descriptors from the .ear file using jar commands similar to the following for WebSphere:
    jar -xvf JMapServ-WS.ear JMapServ.jar JMapServ.war
jar -xvf JMapServ-WS.ear META-INF/application.xml
jar -xvf JMapServ.jar META-INF/ibm-ejb-jar-bnd.xml
jar -xvf JMapServ.war WEB-INF/ibm-web-bnd.xml
jar -xvf JMapServ.war WEB-INF/web.xml
  4. Make copies of the descriptors and edit them using an XML editor of your choice, making sure that you retain valid XML. Edit the descriptors as follows:
    • application*.xml. Replace the .jar and .war filenames with the names of your files.

      For WebLogic, a weblogic-application.xml file is not required.

    • *ejb-jar*.xml. Replace the JNDI name with the JNDI name of your EJB. Notice that the JNDI name of the resource adapter is set to eis/MFCobol_*** (where *** is the version), which you must not change.
    • *web*.xml. Replace the JNDI name with the JNDI name of your EJB.
  5. Put each descriptor into a subdirectory below the archive file to which the descriptor belongs, as follows:
    Descriptor | Directory
    application*.xml | my-ear-dir\meta-inf
    *ejb-jar*.xml | my-jar-dir\meta-inf
    *web*.xml | my-war-dir\web-inf
  6. Package your descriptors into your archive files using jar commands similar to:
    jar -uvf myService.ear META-INF/myAppServer-application.xml
jar -uvf myService.jar META-INF/myAppServer-ejb-jar.xml
jar -uvf myService.war WEB-INF/myAppServer-web.xml
  7. Package your updated .jar and .war into your .ear file, using jar command similar to:
    jar -uvf myService.ear myService.jar myService.war
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: Deploy to Java EE Application Servers


To Add Micro Focus Support for EJBs

  1. Locate the file mfejblib.jar, which contains the Micro Focus support for EJBs, and is stored by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\javaee\javaee7\appsrv directory, where appsrv represents a subdirectory named for your Java application server and, in some cases, the version as well. For a list of supported application servers, see the Java Application Servers section of the Supported Operating Systems and Third-party Software topic.
  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

    Exception: WebSphere Liberty application servers use different class loading policies; therefore, do not include its mfejblib.jar file in the .ear or the .war archive file.
Parent topic: Deploy to Java EE Application Servers


To add support for Micro Focus resource adapters

  1. Locate the appropriate mfcobolpure.jar and mfconnector.jar files. These files contain the classes that support the Micro Focus resource adapters.
    mfcobolpure.jar
    Stored in %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin and \bin64
    mfconnector.jar

    Stored in the %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\javaee\javaee7\appsrv directory, where appsrv represents a subdirectory named for your Java application server and, in some cases, the version as well. For a list of supported application servers, see the Java Application Servers section of the Supported Operating Systems and Third-party Software topic.

  2. Update the classpath to point to the mfcobolpure.jar and mfconnector.jar archive files using one of the following methods:
    From the IDE
    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.

Parent topic: Deploy to Java EE Application Servers


To Deploy a Micro Focus Resource Adapter to a Java Application Server

Tip: For detailed information on deploying specific resource adapters, see the Related tasks topics listed below.
  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 Test 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. They are supplied with your Enterprise Test Server installation in the %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\javaee\javaee7\appsrv directory, where appsrv represents a subdirectory named for your Java application server and, in some cases, the version as well. For a list of supported application servers, see the Java Application Servers section of the Supported Operating Systems and Third-party Software topic.

  3. Optionally, configure the resource adapter by editing the <config-property> values set in the ra.xml file packaged with the specified .rar file (see step 2 above). The following describes each editable property:
    ServerHost
    Sets the server host name.
    Valid values: Server host machine name or IP address
    Default: localhost
    ServerPort
    Specifies the port used by Enterprise Test Server Web Services and J2EE listeners.
    Valid value: The port number used by Enterprise Test Server Web Services and J2EE listeners
    Default: 9003
    Trace
    Sets tracing on or off.
    Valid values: true or false
    Default: false
    SecureGUID
    Sets the level of encryption for each generated GUID.
    Valid values: true - generates cryptographically strong GUIDs

    false - generates GUIDs using the standard Random function seeded with a random number

    Default: false
    ReadTimeoutInSeconds
    Sets the wait period, in seconds, that a socket waits before timing out on a read.
    Valid values: 0 - timeout wait period is infinite

    Any positive integer - represents the number of seconds to wait before timing out

    Default: 0
    OpenTimeoutInSeconds
    Sets the wait period, in seconds, that a socket waits before timing out on a connect.
    Valid values: 0 - timeout wait period is infinite

    Any positive integer - represents the number of seconds to wait before timing out

    Default: 120
    EnterpriseServerSocketCloseDueToInactivity
    Sets the wait period, in hours, that Enterprise Test Server waits before closing a socket due to inactivity.
    Valid values: 0 - timeout wait period is infinite

    Any positive integer - represents the number of hours that Enterprise Test Server waits before closing a socket

    Default: 72
Parent topic: Deploy to Java EE Application Servers


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 using a run-time tunable file
Parent topic: Enterprise Server Task Index


To configure run-time core dumps using a run-time tunable file

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:

Example of using a run-time tunable text file to configure run-time core dumps

Parent topic: Monitor Directory Server


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 set a fixed port in a listener endpoint address
  • 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


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: Work with Communication Processes and Service Listeners
Parent topic: Common Configuration Tasks


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: Work with Communication Processes and Service Listeners


To set a fixed port in a listener endpoint address

  1. If started, stop the enterprise server.
  2. On the Enterprise Server Administration page, in the row for your enterprise server, click the Details button for the Listeners in the Communications Processes column.
  3. Click Edit on the row for the appropriate listener.

    The default setting for Endpoint Address is *:*. The second * indicates an ephemeral (dynamic) port number.

  4. Change the Endpoint Address to *:nnnn where nnnn is a fixed port number.
    Note: The default fixed port number used for service interfaces is 9003. If you use a port number other than 9003, be sure to edit the Service endpoint URL in your service interface properties to match. See To set deployment properties for more information.
  5. Click OK.
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: 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: 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: Work with Communication Processes and Service Listeners


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: 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: 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: 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: Work with Communication Processes and Service Listeners


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: 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: 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: 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: 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: Work with Communication Processes and Service Listeners


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 change the system directory

  1. In ESCWA, click Native.
  2. In the navigation pane, expand Directory Servers > Default, and then select your enterprise server instance.
  3. Click General > Properties.
  4. Type the full path to your new system directory into the System Directory field.
    Notes: The directory specified must exist; Enterprise Server does not create it for you.

    The System Directory cannot be shared between enterprise servers.

  5. Click Apply.
    Note: If started when you made the change, restart the server for the change to take effect.
Parent topic: Work with Servers
Related concepts
System Directory Location


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 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: 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 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
The network address of the queue manager (connection name). The valid values of this parameter depend on the value of the TRPTYPE parameter. CONNAME is mandatory when multiple MQ listeners are defined to make an MQ connection from the Micro Focus Directory Server, and optional when connecting using a single MQ listener. 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
Note: For one-phase commit transactions, you must set the environment variable ES_MQ_1PC=Y|y|T. See Environment variables in alphabetical order for more information.
Parent topic: Work with WebSphere MQ
Parent topic: Resources (deprecated)
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 (deprecated)
Related reference
WebSphere MQ Environment Variables
Related information
XAR for WebSphere MQ


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
  • To automatically clean up the temporary storage queues
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 (deprecated)
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 Region 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


To automatically clean up the temporary storage queues

From Enterprise Developer 5.0 PU4, the CICS TSMODEL can be specified with an EXPIRYINTMIN value that is honored for TS queues that match the PREFIX in that TSMODEL.

When a TS queue is created, if a TSMODEL is found with a PREFIX that matches the TS queue name, the EXPIRYINTMIN value is applied to the queue.

If the TSQ clean up transaction CTSC is not already running, it is started and the SEP becomes transient, with another SEP being started to replace it.

Note: The resource definition file will need to be upgraded to acquire the definition for CTSC. This can be done by issuing the following command:
caspcupg /dp={resource-definition-path}

CTSC scans TSQs every 10 minutes or 10% of the lowest expiry interval found on the previous scan, whichever is larger, but subject to a 60 minute maximum.

If CTSC finds no TSQs with an expiry interval, then the transaction finishes. It will be restarted when another TSQ is written which has an expiry interval.

Recoverable queues and queues that start with 'DF', '$$', '**' or x'FA' through x'FF' are ignored and hence are not deleted even if they have an expiry interval applied to them.

If CTSC ABENDs then it is restarted on the next write to a queue with an expiry interval. This means that expiry intervals in existing queues are ignored until a new TSQ is created with an expiry interval.

In a PAC, CTSC will run in each region that creates a TSQ with an expiry interval, that is, CTSC cannot be configured to run in specific regions.

Note: This support is only available in enterprise server regions that are NOT TRANCLASS enabled.

Only the following attributes of TSMODEL are currently supported:

  • PREFIX
  • XPREFIX - must be ASCII
  • EXPIRYINTMIN
  • EXPIRYINT - A TSMODEL with this attribute can be imported by casrdtup, but its value will be converted to minutes. This attribute cannot be used in the creation of a new TSMODEL via the web interface - EXPIRYINTMIN should be used.
Parent topic: Control and Configuration


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 (deprecated)
Related concepts
Defining IMS Resources
IMS-enabled Enterprise Server Administration using ESMAC (deprecated)
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)


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 (deprecated)
Related concepts
Defining IMS Resources
IMS-enabled Enterprise Server Administration using ESMAC (deprecated)
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)


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.
Note:

To be able to purge a TS Queue from ESMAC, you need to have a CZTS entry in the TCICSTRN resource in the LDAP repository and the user must have at least READ access rights.

To create an entry in the LDAP repository, you need to add some code in the LDF file similar to the following:

###################
###### PCT : CZTS #
###################
dn: CN=CZTS,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro
Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: TSQ purge transaction

###################
###### PCT : CZTD #
###################
dn: CN=CZTD,CN=TCICSTRN,CN=Enterprise Server Resources,CN=Micro
Focus,CN=Program Data,DC=X
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: TCICSTRN
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read
microfocus-MFDS-Resource-ACE: deny:*:execute
microfocus-MFDS-UID: mfuid
description: TDQ purge transaction
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 MSS-enabled enterprise server for IMS applications from Enterprise Test 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 (deprecated)
  • Transactions
  • WebSphere MQ
Parent topic: Enterprise Server Task Index
Parent topic: Mainframe Support for Deployed Applications


To create an MSS-enabled enterprise server for IMS applications from Enterprise Test 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 Test 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 Test 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 Region 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 Region 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 Region 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 application files, which should be the same as the Output Path specified in your Enterprise Developer project COBOL properties.
  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 Test Server\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 Region 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
    Warning: Setting this exposes the user id and password which you use. Ensure that you remove this setting to avoid security information from being printed when used in the production environment.
  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

  1. In ESCWA, open the Server Instance Properties: MSS IMS TM General page for your enterprise server region. See Server Instance Properties: MSS IMS TM General for details.
  2. In the MFS null character field, type an appropriate value.
    Note: You can override this value at transaction level.
  3. Click Apply.
Note: This task is value only when the codeset bias is set to 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 followed by a trailing space.
Notes:
  • The trailing space after the transaction name might not be required depending on your configuration. See the Trailing space entry in the IMS Configuration topic for details.
  • 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
Related reference
IMS Configuration


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. In ESCWA, start your IMS enabled enterprise server region.
  2. Click IMS > Control.
  3. Click the TM tab.
  4. In the System Overview and Control group, modify the Message Queue Max and/or the Cushion fields as required. See IMS Control for more information.
  5. 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
Server Instance Properties: MSS IMS TM General
IMS Control


To enable dynamic IMS message queue performance tuning

To enable dynamic IMS message queue performance tuning, preform the following steps in ESCWA:

  1. If started, stop your enterprise server region from the Control page.
  2. In the menu bar, click Native.
  3. In the navigation tab, expand Directory Servers, and then select your enterprise server region.
  4. Click General > Properties.

    This opens the General Properties page.

  5. In the Configuration Information field, type [ES-Environment] and on a new line 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.
  6. 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
Server Instance Properties: MSS IMS TM General
IMS Control


To dynamically tune IMS message queue performance

To dynamically tune IMS message queue performance, preform the following steps in ESCWA:

  1. In the menu bar, click Native.
  2. In the navigation tab, expand Directory Servers, and then select your enterprise server region.

    Ensure that you have set the ES_TMC_AGGREGATE environment variable. See To enable dynamic IMS message queue performance tuning for more information.

  3. Click General > Control, and then click Start.
  4. Click IMS > Control.

    This opens the IMS Control page.

  5. Click the TM tab. This will display the System Overview and Control group.
  6. In the System Overview and Control group, modify any of the following as required:
    • Transaction Threshold
    • Enable Q Flush Aggregate
    • Q Flush Time
    • Disable Dynamic Flushing
    • Keypoint Frequency

    See IMS Control for more information.

  7. When you have completed your modifications, 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
Server Instance Properties: MSS IMS TM General
IMS Control
Related information
ES_TMC_AGGREGATE


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 Region 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 Test Server publishes this device to theEnterprise Test Server IMS TM.
  10. Click Add.
Parent topic: Printers
Related concepts
Configuring IMS Printers
Creating and Configuring an Enterprise Server Region 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 (deprecated)


To enable printer security for an IMS-enabled enterprise server

Note: This topic applies specifically to the use of legacy SNT security for Enterprise Test 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 Region for IMS
Related tasks
To start an enterprise server instance
To Start ESMAC for an enterprise server instance (deprecated)


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+ Desktop 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 Region 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 (deprecated)


Resources (deprecated)

Note: You must perform the following tasks from the Enterprise Server Monitor and Control (ESMAC) interface.
Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.
  • To Start ESMAC for an enterprise server instance (deprecated)
  • 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 (deprecated)


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 (deprecated)
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)
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 (deprecated)
Related concepts
Defining IMS Resources
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)
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 (deprecated)
Related tasks
To Start ESMAC for an enterprise server instance (deprecated)
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 Test 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 Processing
  • 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 region to automatically route specified message classes to an Out Hold status.

To do this, perform the following steps in ESCWA:

  1. In the menu bar, click Native.
  2. In the navigation tab, click Directory Server and then select the enterprise server region.
  3. Click General > Properties.

    This takes you to the General Properties page.

  4. In the Configuration Information field, type the ES_SYSOUT_HOLD environment variable and specify the message classes that you want to route to the Complete queue with an Out Hold status. For example:
    [ES-Environment]
ES_SYSOUT_HOLD=AB
    In this case, message classes A and B will be routed to the Complete queue with an Out Hold status.
    Note: The maximum size of this value is 36 characters.
  5. Click Apply and restart your enterprise server region.
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 region
  • 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 –s parameter:

    /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

    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 region

  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.
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 is advisable to run this command in a separate session.

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 JOBnnnnnnn page, where nnnnnnn 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 JOBnnnnnnn page, where nnnnnnn 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 Complete queue with the Output checkbox enabled, 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 JOBnnnnnnn page, where nnnnnnn 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 JOBnnnnnnn page, where nnnnnnn 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 Processing

You can process catalog entries from ESMAC as follows:

  • View the catalog
  • Search for catalog entries

When viewing a catalog entry, you can:

  • Copy a catalog entry for a data set
  • Create a catalog entry for a data set
  • Delete a catalog entry for a data set
  • Update a catalog entry for a data set
  • View the contents of a data set
  • View the details of a catalog entry

The following catalog utility enables you to update the content of a catalog without having to run the region:

  • Importing and Exporting a Catalog: import export utility
  • To view the catalog
  • Searching for Catalog Entries
  • 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
  • To view the contents of a data set
  • To view the details of a catalog entry
  • Importing and Exporting a Catalog: import export utility
    Describes how to use the catalog import-export utility
Parent topic: JCL Support Tasks


To view the catalog

  1. In the 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_MAX_CATALOG_LINES environment variable.

For example, the maximum number of items displayed can be set to 100:

configuration:
[ES-Environment]
ES_MAX_CATALOG_LINES=100
Parent topic: JCL Catalog Processing
Parent topic: Viewing the Catalog and Data Sets


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 Processing


To copy a catalog entry for a data set

  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.
    Note: Check Disable Additional Qualifiers to disable the use of implied wild cards; for example, a filter of A.B would only return a data set of A.B (and not all data sets that start A.B, as if A.B** had been entered).
  4. Click the List button.
  5. On the Data Catalog page, click DCB against the entry that you want to copy.
  6. On the Catalog Entry page click Copy.
  7. Specify the properties of the data set in the new catalog entry.
  8. Click Apply.
Parent topic: JCL Catalog Processing
Parent topic: Viewing the Catalog and Data Sets


To create a catalog entry for a data set

  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. Click the List button.
  4. On the Data Catalog page, click New.
  5. Specify the properties of the data set.
  6. Click Apply.
Parent topic: JCL Catalog Processing
Parent topic: Viewing the Catalog and Data Sets


To delete a catalog entry for a data set

  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.
    Note: Check Disable Additional Qualifiers to disable the use of implied wild cards; for example, a filter of A.B would only return a data set of A.B (and not all data sets that start A.B, as if A.B** had been entered).
  4. Click the List button.
  5. 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.
  6. Click Delete.
Parent topic: JCL Catalog Processing
Parent topic: Viewing the Catalog and Data Sets


To update a catalog entry for a data set

  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.
    Note: Check Disable Additional Qualifiers to disable the use of implied wild cards; for example, a filter of A.B would only return a data set of A.B (and not all data sets that start A.B, as if A.B** had been entered).
  4. Click the List button.
  5. 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.
  6. Change the properties of the data set as required.
  7. Click Apply.
Parent topic: JCL Catalog Processing
Parent topic: Viewing the Catalog and Data Sets


To view the contents of a data set

  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.
    Note: Check Disable Additional Qualifiers to disable the use of implied wild cards; for example, a filter of A.B would only return a data set of A.B (and not all data sets that start A.B, as if A.B** had been entered).
  4. Click the List button.
  5. On the Data Catalog, page click DCB against the entry that you want to update.
  6. 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.
  7. In Codeset choose the codeset that you want to be used for the display.
  8. If you want to see extra details check Details.
  9. 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 Processing
Parent topic: Viewing the Catalog and Data Sets


To view the details of a catalog entry

  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.
    Note: Check Disable Additional Qualifiers to disable the use of implied wild cards; for example, a filter of A.B would only return a data set of A.B (and not all data sets that start A.B, as if A.B** had been entered).
  4. Click the List button.
  5. On the Data Catalog page, click DCB against the entry that you want to view.
Parent topic: JCL Catalog Processing
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

Controlling the case of the PCDSN field

When run in a Windows environment, the PCDSN field (that is, the physical file location and name) is folded into upper case when catalog records are inserted or updated, unless the following environment variable is set:
MFJ_STRICT_CASE=Y

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

For Windows:

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.

On completion, mfcatxml displays a message which indicates either success or a failure. The return codes are as follows:
0
The utility has completed successfully.
12
The utility encountered an error.
Note: When exporting a large catalog, you can limit the number of records in each xml document by setting the environment variable MF_MVSP0034_LIMIT. For example, MF_MVSP0034_LIMIT=10000 will limit the number of catalog records in each document to 10000.

When this value has been reached, a new catalog xml document is created. The name of the file is constructed from the output file name plus an incremental suffix number from 001 to 999. For example:

mfcatxml func(exp) outfile(cat_export.xml)

Produces the following files: cat_export.xml, cat_export001.xml, cat_export002.xml, etc.

Export entire catalog: Func = EXP

Exports the entire catalog to an XML file.

OUTFILE | The name of the file to hold the exported data.
RELATIVE_PATH(Y) | If the physical location of the cataloged data file is under the folder that contains the system catalog, then using RELATIVE_PATH(Y) causes the full path value in the R-PC-DSN element of the catalog record to be replaced by <CatalogFolder>. For example: <R-PC-DSN><CatalogFolder>\DATA\S2.SSSS.DAT</R-PC-DSN>
SUPPRESS_DT(Y) | Sets the value of create date, create time, change date, change time, compile date and compile time to zero.

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 Processing
Parent topic: Viewing the Catalog and Data Sets
Parent topic: Administering JCL-enabled Enterprise Servers
Related information
MFJ_STRICT_CASE


Micro Focus FTP Utility MFFTP

The MFFTP utility provides a support mechanism for batch processes that takes advantage of FTP from JCL on the mainframe. It also provides FTP support for JCL-enabled enterprise servers within Enterprise Server . .

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
Parent topic: JCL Support Tasks
Related concepts
Features Added in Enterprise Test Server 2.3


Prerequisites

The MFFTP utility is installed as part of Enterprise Test 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, 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 control 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 fxxxxxxx.snnn.eol.zzzz, where xxxxxxx 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 Control 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 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 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. If you specify a partitioned data set name, the directory in which the data set resides is used. 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 Control Variables
    You can set control variables from within Enterprise Server Administration or, put them into a dataset called FTP.DATA or , optionally, by specifying the ENVVAR DD statement in JCL.
  • MFFTP Control Variables
  • MFFTP DD Statements
    List of the DD statements required with MFFTP and their definition.
  • Input and Output Temporary Files
  • MFFTP Using SFTP As An FTP Client
    Using SFTP as an ftp client.
  • MFFTP Using lftp as an FTP Client
  • 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.
  • Using Data Conversion Modules with MFFTP
    To translate data before and after sending, you can either use the in-built ASCII-EBCDIC conversion modules, or you can write your own conversion module to handle other translations.
Parent topic: Micro Focus FTP Utility MFFTP


Specifying Control Variables

You set control 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 create a cataloged DATASET called FTP.DATA that contains the control variables required . An example is provided in the example given in Running MFFTP.

You can use an optional ENVVAR DD statement to specify control 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 Control Variables

You can use the following control 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 control 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_DISABLE_EOL={Y | N}
If set to Y, it enables the Variable Block (VB) file to be transferred from the Enterprise Server environment instead of the temporary end-of-line (eol) file.

The default value is N.

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_IN_LINE_CMD={N|Y}
Create the put/get command on one line rather than splitting across multiple lines. lftp requires the command on one line. The default value is N.
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_LCD_SPLIT=number_of_characters
If MFFTP_USE_LCD=Y then you can use this variable as well. This variable specifies the maximum length of each lcd command. For example, if the path to the file is 120 characters and a value of 50 is used you will need to specify at least 3 lcd statements.
Note: You do not need to specify a value. MFTP automatically inserts the required number of lcd commands.
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_PROCESS_TRAILS_ONGET={TRUE | FALSE}
Determines whether trailing spaces are processed during a GET command. The default is TRUE. Set to FALSE, in conjunction with the LOCSITE value TRAILINGBLANKS=FALSE, to ignore any trailing blank spaces.
Note: When set to FALSE, this option causes MFFTP to honor line breaks in LSEQ input records, and pad the resulting output records with spaces.
MFFTP_QUOTE_SITE={N | Y}
Prepends the QUOTE subcommand to the SITE command. Default is Y.
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_SENDSITE={N | Y}
Enables the issuing of the SITE command before a PUT or an MPUT command. Default is N.
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_USE_LCD={N|Y}
Can be use to insert the lcd command into the command stream to change the local current directory to the location where the file is being transferred or received to. This avoids long absolute paths and file names on the put/get command.
MFFTP_USE_LFTP_D_FLAG={N|Y}
Use the lftp -d flag to specify debugging output messages. This is required for lftp so that MFFTP can analyse the output messages to determine the appropriate return codes for the actions. The default value is N.
MFFTP_USE_O_REMOTE={N|Y}
Use the -o flag [-o rfile] for get and put commands. For example:
ftp put localfile.dat –o remotefile.dat
ftp get remotefile.dat –o localfile.dat
The default value is N.
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_USE_MV_RENAME={N|Y}
Replace rename with mv. The default value is N.
MFFTP_USE_RM_DEL={N|Y}
Replace del with rm, mdel with mrm. The default value is N.
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.
MFFTPXIT

Specifies the user exit program invoked from MFFTP for file transmission operations. This user exit reads a *.exit file containing FTP information for operations that transfer or change a file via the MFFTP Utility. See MFFTP User Exit for more information.

Parent topic: Configuring the MFFTP Utility
Related concepts
Major Features of the MFFTP Utility


MFFTP DD Statements

MFFTP requires one of the following DD statements:

INPUT
For JES2. Defines the command that will be sent to the native FTP client together with the actual FTP commands.
SYSIPT
For VSE. 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 control variables, one per line. It overrides any values set at a global level by, for example, the values in the FTP.DATA dataset.
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:

ftp.jxxxxxxx.snnn.ip and ftp.jxxxxxxx.snnn.op

Where:

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


MFFTP Using SFTP As An FTP Client

Secure FTP or sftp is achieved by the main MFFTP program shelling out and invoking the putty sftp implementation.

This is FTP over secure shell or ssh , not FTPS or FTP using TLS.

Prerequisites

The putty toolset needs to be installed and on the path.

More specifically, the putty sftp executable psftp.exe is required.

These utilities can be downloaded from here

If you are going to use a certificate-based authorisation, a certificate needs to be available. Please refer to the putty documentation for the process used to do this.

Configuration

The following control Variables need to be configured:

MFFTP_CLIENT=SFTP
This configures the MFFTP program to use psftp as the ftp client.
MFFTP_SFTP_AUTH=n

Used to determine the artifacts to be used for authentication as follows:

Each of the 4 variables is assigned a value as follows:

1 – userid

2 – password

4 – certificate

8 – passphrase

Add the required values together to get elements to be used for authentication as follows:

1 - user id only

2 - password only

3 - userid plus password

4 - certificate only

5 - certificate plus userid

6 - certificate plus password

7 - certificate plus userid plus password

8 - invalid (need a certificate to have a passphrase)

9 - invalid

10 - invalid

11 - invalid

12 - certificate plus passphrase

13 - certificate plus passphrase plus userid

14 - certificate plus passphrase plus password

MFFTP_SFTP_CONNECT_TIMEOUT
Time to wait for the connection in seconds. The default is five seconds.
MFFTP_SFTP_ERRLVL
Set to 2 in order to report all messages in the sftp log. This is unset by default so only log messages that begin with 'INFO' or 'ERROR' are reported in the step output.
MFFTP_SFTP_IDLE_TIMEOUT
Time to wait for a response in seconds. The default is 60 seconds.

The following DD definitions provide the ability to configure authorisation parameters

  • //SFTPAUTH DD .....

    The following parameters are valid, replacing the text within <> with correct values

    machine <machine name>
    The machine name to connect for the session
    user <username>
    The user name to log in as
    pass <password>
    keypcn <path to ppk certificate file >
    Optional, only when using certificate authentication. It is preferable to store the certificate within a catalog-controlled dataset and use it in the SFTPPPK DD described below.
    keypass <pass phrase for use with ppk certificate >
    Optional. Only when using certificate and passphrase authentication.
    hostkey <specific hostkey for machine connecting to >
    This is optional. If not provided, this hostkey must exist in the machine's host key store. Please refer to putty documentation for more information.
  • //SFTPPPK DD .... Contains the ppk certificate to be used to connect to the sftp server . This method of storing the certificate is preferable to storing it on disk somewhere.

An example JCL to configure control variables in a dataset called FTP.DATA , and place the ppk certificate in a dataset called FTP.PRIV.DATA

//SETUP02 JOB 'FTP.DATA',MSGCLASS=X,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=FTP.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//DEL2    DD DSN=FTP.AUTH.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//DEL3    DD DSN=FTP.PRIV.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       FTP.PRIV CONFIGURATION FILE
//*==========================================================
//DEFPRIV  EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
PuTTY-User-Key-File-2: ssh-rsa
Encryption: aes256-cbc
Comment: slesz1
Public-Lines: 6
AAAAB3NzaC1yc2EAAAABJQAAAQEAmTd1uLtTsQ6RoyTuhzr3VxFBa0zAK7p91XbQ
sa1NRh9lcVs8zeI3xOzNfW4fyTAe4YUyLCxF0dSXTChDvJtqNeNa9bXiY/noTzc8
WmnWklGzOI+JoxLGIfFvzEN/LjxkB3Tzmc5ESsLLC/xTJrvcuCw/H5Wbh377xaKH
6S4NfXCtaYxWJ3vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv0MRfH15y8DqF9bWhOP6
ywmZAmIZqJeL+0cgeGFtADiV7DSGSrMyEvKayh1OTTRpgebJ40fFaqWvPW6D5yQW
LafvaQLh+OIuMc9iAUwhoetw7VNBLekIFUvwtpS6Pdrs98f0ZQ==
Private-Lines: 14
Wo+ACSDjbOHFd3XXSaYI+meJ5wgJklTLIRjYzJe6QB3bRelm0iSdPTo+lJ8Gtn0u
7mXHsszk0hXAtkv1nWAVPYszk5tk+kY/zuT9YVRp03nwsuW/WQkofNAn5C205/sC
WfvlklaYIBe5FBVmVUYu+p4FzTJYmshZDqMRLYGougB8LLI8knlRfmJn3jgjWR3Z
yRS7XIzgBExy+NX6dyv6UA1mWHU2kV22ao7NBot9M9p2BrVh8NTyYwc4SDz238H9
JIV50m+BZkmZLhRHUokABY3DwAzDQnQHMRFLJ8rOFkPw4WfrJHyy9Do1wU5PlqJ/
SF7FSpTVlzilP7aI5mzexdrXs5WZtxJ5wDvSHTUmtcQSh2YDLxAZf4IPavHsD+eM
nJh4AsU8Pvd4Op5ONPBJY1xrCdQ0AtfrvudFWjPlLJgm8901wo7Mzokbk3ys5sR+
IVu6FWCBk9iN+0KLLPxxxxxxxxxxxVmVzUK8AtbWkBr01bFSAbHiLgnwm1M4LwJz
r1vY96CrBGEfj7wCKeaFmw7FIvc1r8n3WyYcmUfiv0WqZeuBX+yb90QwxzarQBuD
Cbn7hgXgQq6ckE2BerhpM8TRpa2xHk5t0ACrZNyOIrfyRs6E+Bk6dmseMqWJYdRb
7lqdHH6smXW/fMLMurFv0P4WX7f4IPF4OrBG3CoJ3rBCTFXa6/+RaUjaC0/RKUtu
n09m8WLdxVemHhlrg99NQmLx9JEUSr+GbiriAgj5bdppZB5Niz3YiKodZVtcH3ow
90rND6pMrKF/Fs6Zkt7Oxf8bIX3yzs7dpq9OqWU0AuyS5oMwtyMdBjmDrTBEumoF
tKtHuQxX95/TXOJasCaMNRCb1RmGo7bbzo00Xjiq0UHj/fDZuGg9E1Dm2oXYGxg8
Private-MAC: 54aba03aff3cd77f65335b92b6a72df08034462b
/*
//SYSUT2  DD DSN=FTP.PRIV.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(RECFM=LSEQ,LRECL=80),DISP=(NEW,CATLG)
/
//*==========================================================
//*       FTP.AUTH CONFIGURATION FILE
//*==========================================================
//* keypcn d:\util\putty\keys\slesz11-3private.ppk
//DEFAUTH  EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
machine slesz1 user fred pass password
keypass slesz1ABCDEF
hostkey 12:03:da:81:ea:49:6d:96:ed:6f:46:eb:84:27:4d:12
/*
//SYSUT2  DD DSN=FTP.AUTH.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
/
//*==========================================================
//*       FTP.DATA CONFIGURATION FILE
//*==========================================================
//DEFFTP   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *

; ---------------------------------------------------------------------
; MFFTP SETTINGS
; ---------------------------------------------------------------------

MFFTP_ABCODE 3085 ; SET DEFAULT ABEND CODE FOR MFFTP

MFFTP_OUTPUT_LRECL 120

MFFTP_PREFIX=Y
MFALLOC_LOC d:\temp\j1
;MFFTP_VERBOSE_OUTPUT ON
;MFFTP_KEEP_IP Y
;MFFTP_KEEP Y
MFFTP_CLIENT=SFTP
MFFTP_SFTP_AUTH=13
..... and so on

/*
//SYSUT2  DD DSN=FTP.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
//
An example JCL to use FTP using sftp.
//MFFTP05  JOB 'MFFTP TEST',CLASS=A,MSGCLASS=A
//* sftp flavour .
//*
//* Delete files
//*
//DEL1  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 DELETE MFI01.MFFTP.FBFILE.TOUPLD FORCE
 DELETE MFI01.FTPDATA.FBFILE FORCE
 DELETE MFI01.MFFTP.GDG FORCE
 SET MAXCC=0
/*
//*
//* Allocate GDG base
//*
//ALLOC  EXEC  PGM=IDCAMS
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
  DEFINE  GDG -
         (NAME(MFI01.MFFTP.GDG) -
          LIMIT(5) -
          NOEMPTY -
          SCRATCH)
/*
//*
//* Create an FB/10 dataset
//*
//STEP0 EXEC PGM=IEBGENER
//SYSPRINT  DD SYSOUT=*
//SYSIN     DD DUMMY
//SYSUT1    DD *
AAAAAAAAAA
BBBBBBBBBB
/*
//SYSUT2    DD DSN=MFI01.MFFTP.FBFILE.TOUPLD,
//             DISP=(NEW,CATLG,DELETE),
//             DCB=(RECFM=FB,LRECL=10)
//*
//* Upload an MVS dataset
//*
//STEP1 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT  DD *
cd MFFTP_TEST
mkdir machine_os
cd machine_os
put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
quit
/*
//*
//* Download a text file to an MVS dataset (FB/10)
//*
//STEP2 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT DD *
cd MFFTP_TEST/machine_os
locsite recfm=fb lrecl=10
get MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
MFFTP_VARS
quit
/*
//*
//* Download a text file to a new GDG bias
//*
//STEP3 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT DD *
cd MFFTP_TEST/machine_os
locsite recfm=fb lrecl=10
locstat
get MFFTP01.txt MFI01.MFFTP.GDG(+1)
del MFFTP01.txt
cd ..
rmdir machine_os
/*
Parent topic: Configuring the MFFTP Utility


MFFTP Using lftp as an FTP Client

MFFTP supports the use of lftp as the ftp client on Linux platforms. Lftp is a command line utility for transferring files using various protocols. The lftp utility is not compliant with the ftp standards and requires changes to the command file that MFFTP generates in order for it to operate correctly. MFFTP can be configured to make the required changes to the command file fed into lftp.

Configuration

The following control variables need to be configured:

MFFTP_IN_LINE_CMD=Y
This creates the put and/or the get command on the one line rather than splitting across multiple lines.
MFFTP_USE_O_REMOTE=Y
This adds an '-o' to the local file or remote file parameter for get and put commands, such as ftp get … remotefile -o localfile or ftp put … localfile -o remotefile.

Because lftp does not recognise the DELETE or RENAME ftp commands you should configure MFFTP to replace these as follows:

MFFTP_USE_RM_DEL=Y
Ensures that rm and mrl commands are used as appropriate.
MFFTP_USE_MV_RENAME=Y
Uses mv command instead of rename.
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 control 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 control 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 ftp.jxxxxxxx.snnn.eol.zzzz (where xxxxxxx 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


Using Data Conversion Modules with MFFTP

If you are required to perform some type of translation of data before sending a file or after receiving it, there are several options that you can use.

You can call MFFTP with a parameter stating that a conversion module should be used (for example, EXIT TRAN ASC2EBC), which would call the in-built ASCII to EBCDIC module. This would translate the file from ASCII to EBCDIC if the ftp action is PUT; the same module would be called to translate the received file from EBCDIC to ASCII if the ftp action is GET. Conversely, the in-built EBC2ASC module performs the reserve of these actions: EBCDIC to ASCII on PUT and ASCII to EBCDIC on GET).

You can also specify these data conversion modules using the SBDATACONN or MBDATACONN parameters of the LOCSITE command:

LOCSITE ENCODING=SBCS
LOCSITE SBDATACONN=ASC2EBC

If you need to perform any other type of translation, you can write your own conversion module - see Writing Your Own Data Conversion Module.

The jcl-examples section of the Samples Browser contains two sample conversion modules and the jobs required to run them.

  • MFTPDEM1.JCL uses a conversion module called MYE2A to perform a translation from EBCDIC to ASCII. This module uses a copybook (codeset.cpy) generated by the Codecomp module. Please note that MYE2A is just a sample, and should not be used as a general EBCDIC to ASCII conversion module.
  • MFTPDEM2.JCL uses a more specialised translation, by taking ASCII input and using the CBL_STRING_CONVERT function to produce UTF-8 output. This module is called IBM-1252.
  • Writing Your Own Data Conversion Module
Parent topic: Configuring the MFFTP Utility


Writing Your Own Data Conversion Module

If you are writing your own data conversion module, because your require translations not offered by the in-built modules, the module:

  • Should have a name no longer than 8 characters.
  • be compiled with CHARSET"ASCII".
  • is called using the following interface:
    linkage section.
01  lk-function          pic x(3). *> PUT or GET
01  lk-len               pic 9(5). *> len of lk-data
01  lk-data.                       *> data to translate
    05  lk-bytes         pic x(1)
         occurs 32767 times.

procedure division using lk-function
                         lk-len
                         lk-data.
...

If the purpose of your module is to perform a translation from ASCII to EBCDIC, lk-function should be set to 'PUT', and if it is to perform a translation from EBCDIC to ASCII, lk-function should be set to 'GET'.

On return from your conversion module, lk-len should hold the length of the returned data. For a single-byte character set, these values will be unchanged, but for a double-byte character set, the length may be different. The retuned value is used by MFFTP to write the output record.

Your Micro Focus product already supports many different codesets, but with the Enterprise Developer development products, you can install additional ones - see The Codecomp Utility in the Codeset Translation section of the development documentation. The module you create for translation in MFFTP will be similar to the module described there using the sample CSnnnn.cbl program provided (described in To Customize Character Set Conversion). One notable difference is that the interface described above should not be compiled as 'NOCANCEL', as it is only being called from MFFTP.

If you find you have a more general need for a specialist codeset conversion module, and you create a CSnnnn program, you can code your MFFTP conversion module to call into that module.

The conversion module is called at least twice by MFFTP for each job step it is used in. The first 2 calls are to check that a 'round trip' translation works.

  • The first call is made with a data length (lk-len) of 256 and the data (lk-data) contains hexadecimal values from x'00' through to x'FF', and the function (lk-function) is PUT.
  • The second call contains the output from the first call, and the function is GET.

A comparison is then made to see that the return from the GET call is the same as the input to the PUT call. If the module fail this check, a warning message is issued and the module is not used unless the setting MFFTP_TRANSLATE_SAFETY=OFF is set.

The third and subsequent calls to the module is the translation of the data set, record by record.

Parent topic: Using Data Conversion Modules with MFFTP


Running the MFFTP Utility

The following is a sample JCL job that creates the FTP.DATA control dataset and populates it with some variables.

The file format is based on the IBM FTP.DATA format .

//SETUP01 JOB 'FTP.DATA',MSGCLASS=X,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=FTP.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       FTP.DATA CONFIGURATION FILE
//*==========================================================
//DEFFTP   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *

;***********************************************************************
;                                                                      *
;   Name of File:             SEZAINST(FTCDATA)                        *
;                                                                      *
;   Descriptive Name:         FTP.DATA  (for FTP Client)               *
;                                                                      *
;   SMP/E Distribution Name:  EZAFTPAC                                 *
;                                                                      *
;   Copyright:    Licensed Materials - Property of IBM                 *
;                                                                      *
;                 "Restricted Materials of IBM"                        *
;                                                                      *
;                 5694-A01                                             *
;                                                                      *
;                 Copyright IBM Corp. 1977, 2011                       *
;                                                                      *
;                 US Government Users Restricted Rights -              *
;                 Use, duplication or disclosure restricted by         *
;                 GSA ADP Schedule Contract with IBM Corp.             *
;                                                                      *
;   Status:       CSV1R13                                              *
;                                                                      *
;                                                                      *
;   This FTP.DATA file is used to specify default file and disk        *
;   parameters used by the FTP client.                                 *
;                                                                      *
;   Note: For an example of an FTP.DATA file for the FTP server,       *
;   see the FTPSDATA example.                                          *
;                                                                      *
;   Syntax Rules for the FTP.DATA Configuration File:                  *
;                                                                      *
;   (a) All characters to the right of and including a ; will be       *
;       treated as a comment.                                          *
;                                                                      *
;   (b) Blanks and <end-of-line> are used to delimit tokens.           *
;                                                                      *
;   (c) The format for each statement is:                              *
;                                                                      *
;       parameter value                                                *
;                                                                      *
;                                                                      *
;   The FTP.DATA options are grouped into the following groups in      *
;   this sample FTP client FTP.DATA configuration data set:            *
;                                                                      *
;   0.  MFFTP settings
;   1.  Basic configuration options                                    *
;   2.  Unix System Services file options                              *
;   3.  Default attributes for MVS data set creation                   *
;   4.  MVS data set transfer options                                  *
;   5.  Code page conversion options                                   *
;   6.  DB2 (SQL) interface options                                    *
;   7.  Security options                                               *
;   8.  Timers                                                         *
;   9.  Return codes                                                   *
;   10. Checkpoint / Restart options                                   *
;   11. Socks server access                                            *
;   12. Debug (trace) options                                          *
;   13. Additional advanced options                                    *
;                                                                      *
;   For options that have a pre-selected set of values, a (D) indicates*
;   the default value for the option.                                  *
;                                                                      *
;   Options that can be changed via LOCSITE subcommands are identified *
;   with an (S).                                                       *
;                                                                      *
;***********************************************************************

; ---------------------------------------------------------------------
; MFFTP SETTINGS
; ---------------------------------------------------------------------

MFFTP_ABCODE 3085 ; SET DEFAULT ABEND CODE FOR MFFTP

MFFTP_OUTPUT_LRECL 120

MFFTP_PREFIX=Y
MFFTP_VERBOSE_OUTPUT ON
MFFTP_KEEP_IP Y
MFFTP_KEEP Y

; ---------------------------------------------------------------------
;
; 1. Basic FTP client configuration options
;
; ---------------------------------------------------------------------
;SUPPRESSIGNOREWARNINGS  FALSE   ; Suppress message EZYFT47I
                                     ; while processing remaining
                                     ; statements in this FTP.DATA
                                     ; TRUE - Yes
                                     ; FALSE (D) - No. EZYFT47I is
                                     ; issued to warn of ignored
                                     ; statements
 FILETYPE          SEQ           ; (S) Client mode of operation
                                     ; SEQ = transfer data sets or
                                     ;       files (D)
                                     ; SQL = submit queries to DB2
;SEQNUMSUPPORT FALSE             ; Support sequence numbers when input
                                     ; read from //INPUT DD file
                                     ; FALSE = (D) Do not support
                                     ;         sequence numbers.
                                     ;         EZYFS33I issued if
                                     ;         sequence numbers detected

; etcetera ......
/*
//SYSUT2  DD DSN=FTP.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
//

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 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 Control 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 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)


Enterprise Server Reference

  • Administration and Configuration Commands
  • Enterprise Server Error Messages
  • User Exits
  • MQ Listener and Writer Types
    Describes MQ listener and writer types used by Enterprise Test Server.
Parent topic: Enterprise Server


Administration and Configuration Commands

The following commands are available for performing Enterprise Server administration procedures.

  • cascertreg
    Use the cascertreg command-line utility to list, delete, or add certificate registrations required for CICS Web Interface servers, deployment listeners, etc....
  • 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.
  • fixcat
    A Windows batch file (.bat) that rebuilds a corrupt catalog.dat file.
  • mfdepinst command
    Installs the service interface contained in a deployment package (.car) file to 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..
  • SPLREPAIR
    A Windows batch file (.bat) that rebuilds corrupt spool control files.
Parent topic: Enterprise Server Reference
Related concepts
Command-Line Utilities


cascertreg

Use the cascertreg command-line utility to list, delete, or add certificate registrations required for CICS Web Interface servers, deployment listeners, etc....

Syntax:

cascertreg [common-options] command [command-options] [parameters]

Common options:

-directory path | Specifies the certificate registration directory. You can also specify this by setting the ES_CERT_REG environment variable.
-nobanner | Specifies not to display the banner (program name and copyright message).
-quiet | Provide minimal output - do not ask for confirmation when deleting registrations.
-verbose | Provide more output.
-algorithm | Specifies the algorithm to use for generating fingerprints. Default is SHA1, values can be SHA224, SHA256, SHA384, and SHA512.

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). List matches registrations and prompts 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. Fails if a registration for the certificate already exists. With the -file option, the certificate must be in PEM or DER format.
 | -cwi setting |  | Set the cwi option for the certificate, indicating whether CICS Web Interface is allowed to map this certificate to a user. The value can be yes' or no. The default is yes.
 | -dcas setting |  | As for -cwi, but for the Digital Certificate Authentication Service.
 | -issuer |  | Specifies the optional certificate issuer DN when -fingerprint is used. (For -file, this is taken from the file.)
 | -subject |  | Specifies the optional certificate subject DN when -fingerprint is used. (For -file, this is taken from the file.)

Examples

List all the certificate registrations in the specified directory. The list shows 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 is 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
As above, but this time using the SHA512 algorithm for the certificate fingerprint:
cascertreg add -file client.pem SYSAD –algorithm SHA512
Parent topic: Administration and Configuration Commands
Related concepts
fingerprint algorithm
fingerprint fallback
DCAS Security
Configuring a region for Express Logon Feature
Configuring a region for Express Logon Feature
Related reference
check client authorization
Related information
ES_CERT_REG


fixcat

A Windows batch file (.bat) that rebuilds a corrupt catalog.dat file.

Syntax:

fixcat.bat path-to-corrupted-catalog path-to-new-catalog.dat

Parameters:

path-to-corrupted-catalog
The path to the catalog file that is corrupt.
path-to-new-catalog.dat
The path and file name of the rebuilt catalog.dat file.

Comments:

As you will want to rebuild a catalog.dat file in the same location as the corrupted file, rename the corrupted file before running fixcat.

Example:

rename C:\myFiles\CATALOG.DAT C:\myFiles\CATALOG.DAT.bkup
fixcat C:\myFiles\CATALOG.DAT.bkup C:\myFiles\CATALOG.DAT
Parent topic: Administration and Configuration Commands


mfdepinst command

Installs the service interface contained in a deployment package (.car) file to an enterprise server.

The mfdepinst command handles the server-side part of the process of deploying a service to an enterprise server. The tool installs the files contained in a .car to an enterprise server instance by extracting the deployment package files (.int, .idt, etc.) from the .car file, updating the Directory Service directory for the new services and packages, and if the enterprise server is running, informs it of the new services so they are available for use.

Syntax:

mfdepinst [install-options] myservice.car

Parameters:

myservice.car
The name of the .car file containing the service to be deployed.
install-options
install-options enable you to modify the installation. These options will override any settings specified in an .mfdeploy file. The available options are:
-m location
Set MFDS location
-s
Log to stderr rather than to a deploylog.txt file.
-u
Enable updates to existing services.
-- environment name=value
Set an environment variable.
--server name
Specify a server name.
--listener name
Specify a listener name.
--username name
Specify a username for connecting to MFDS.
--password password
Specify a password for connecting to MFDS.
--replace
Replace any existing package and services for the same namespace as the services being installed (as specified by the manifest in the CAR file). You can do this by first deleting the package and services, so if installation fails, the old services will not be available unless the old CAR file is re-installed.
Note: Use this option with care. This option cannot be used with -u (update); if both are specified, the last one specified takes precedence.

Dependencies:

Run mfdepinst from an Enterprise Developer command prompt from the same directory that contains the .car file.

You can specify mfdepinst installation options in one of the following ways:

  • Specify any required install-options at the command line. This method was first introduced in release 6.0.
  • Add an .mfdeploy file in the parent directory of the directory that contains the .car file (../.mfdeploy).

    If using .mfdeploy, before running mfdepinst, copy the .mfdeploy file in the %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\bin to the parent directory of the directory that contains the .car file.

Important: If both methods are used, the install-options specified at the command-line options will override the settings in the .mfdeploy file.

Comments:

The mfdepinst command extracts files from the .car file and installs them on the enterprise server specified as specified using install-options at the command line or in an .mfdeploy file in the parent directory (../.mfdeploy).

The .mfdeploy file specifies the location, name, and listener for the enterprise server to which the service interface is deployed. So, for example, if the .car file is in %COBDIR%\myservice\myservice.deploy , the .mfdeploy file must be in %COBDIR%\myservice .

Edit .mfdeploy as necessary to specify values other than the default values.

mfdepinst records its progress in the file deploylog.txt in the current directory, overwriting any existing deploylog.txt. After mfdepinst completes, you can examine this file to find out if deployment succeeded.

You can set the mfdepinst security credentials in the .mfdeploy file in the deployment parent directory. The mfdepinst command does not allow you to set any security credentials as command-line options. The credentials are set as name-value pairs, as follows:
MFDS_USER=username
MFDS_PASSWORD=password
Note: Name-value pairs are case-sensitive.

Beginning with Enterprise Developer 5.0, the .mfdeploy file supports an extended syntax and additional settings. See the associated related reference topic for more information.

Parent topic: Administration and Configuration Commands
Related reference
The .mfdeploy file


mfds

Manages the Directory Server.

Syntax for starting or stopping the Directory Server:

mfds [/d|/n network-address] [/j journal-path] [/r]

Syntax for stopping the Directory Server:

mfds /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>
CAUTION:
If MFDS is configured to store sensitive values in the vault (for example XA openstring or autostart credentials), these values can be included when exporting Enterprise Server configuration data in legacy file, XML, or JSON format. Micro Focus recommends that you protect the exported files with appropriate access control.

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.xml) will be used. By default, the mfdsacfg.xml file is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Server\etc.

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 vice versa.

Syntax for secure access to MFDS:

mfds /b

Use this startup option to block anonymous read access to the MFDS Enterprise Server configuration data. If this option is specified, applications that connect to the MFDS process to query Enterprise Server configuration information (for example, mdump and other utilities) will be required to specify valid credentials based on the current MFDS security configuration, otherwise the connection will be rejected.

Note: From Enterprise Developer 7.0, this has become the default behavior.

Syntax for installing and uninstalling Windows services:

mfds /c
mfds /u
mfds /i

Syntax for importing an XML formatted repository:

mfds /g [repository type] [repository address] <opts> <user id> <password>

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
/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 exported 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 Lightweight Directory Server (AD LDS)
1
Active Directory

This is the default value.

2
OpenLDAP
3
Sun Directory
4
OpenLDAP (v2.4)
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.

The default: mfds_schema_[ mfds version ].ldf (for example, mfds_schema_1.05.09.ldf)

schema-version-1
Specifies the version of the schema extensions to be generated:
0
Is the current schema version and is the default value. 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 than 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-addresses
Bind to specific network adapters at network-addresses, where network-addresses can be an IPv4, IPv6 address, or a hostname. Multiple addresses can be specified as a quoted, space-separated list. Each address can be specified with either TCP: or UDP: protocol proceeding the address. For example:
mfds /n "TCP:252.162.131.105 UDP:6202:8e2a:686a:6a77:2855:c4df:960f:3cc2 TCP:host-name"
Note: If a UDP protocol is used then MFDS will attempt to start the UDP listener on that address. If no UDP protocol is used then MFDS will use the first available IPv4 address to start the UDP listener on.

If "0.0.0.0" is specified for the network-address then it will listen on all IPv4 addresses and if "::" is specified then it will listen on all IPv6 addresses. You can combine these to listen on both IPv4 and IPv6 addresses, for example, mfds /n "0.0.0.0 ::"

/r
Refuse access to the Enterprise Server Administration interface.
/s option [username password]
Request a controlled shutdown of a Directory Server and optionally the associated enterprise servers. If the Directory Server is not using the default port, then you must specify the CCITCP2_PORT environment variable with 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.

This option supports the specification of the optional Enterprise Server user id and password parameters using a configured Micro Focus Vault Facility location rather than using literal strings for credentials. For example:
mfds /s 1 mfsecret:user/user_001/id mfsecret:user/user_001/pwd
where user/user_001/id and user/user_001/pwd are examples of secrets stored in the default configured vault. These values can be populated and administered using the mfsecretsadmin utility. See Vault Facility for more information.

The mfds /x and /g command-line options also support credentials stored in the vault.

/u
Uninstall Directory Server as a Windows service
/v
Show version information for Directory Server
/x [repository type]
Enables you to export the Enterprise Server configuration information from the running MFDS process. You can exported in either of the following formats:
1
file://
5
XML
CAUTION:
If MFDS is configured to store sensitive values in the vault (for example XA openstring or autostart credentials), these values can be included when exporting Enterprise Server configuration data in legacy file, XML, or JSON format. Micro Focus recommends that you protect the exported files with appropriate access control.
[repository address]
Absolute directory path to repository.
[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.
/g [repository type]
Enables you to import the Enterprise Server configuration into the current running MFDS process. You can import either of the following formats:
1
file://
5
XML
[repository address]
Absolute directory path to repository.
<opts>
  • D = Default import, do not delete or overwrite any existing regions with a duplicate name in the current repository.
  • O = Delete and overwrite any existing regions with a duplicate name in the current repository.
    Note: The D and O options are mutually exclusive.
  • S = Import server and security manager configuration.
    Note: MFDS restricted administration access must be OFF.
<user id> <password>
These are the MFDS credentials required if administration access is restricted.
--listen-all
Set MFDS to listen on all configured network adapters.
--listen-loopback
Set MFDS to listen on loopback only.
--vault-migrate
Migrates sensitive data values from the default MFDS repository into the configured vault. From Enterprise Developer 8.0, the migration occurs automatically when MFDS first starts. Once migrated, sensitive data values stored in the MFDS repository are removed and are available only from the configured vault.
--ui-on
Set MFDS to enable Web UI.
--ui-off
Set MFDS to disable Web UI.
--anonymous-access-on
Set MFDS to allow anonymous client access.
--anonymous-access-off
Set MFDS to disallow anonymous client access.

Comments:

Note: Issuing an mfds command with any of the parameters /c, /e, /i, /l, /m, /u, /v does not start the Directory Server.

You can use both a dash (-) or a forward slash (/) before a parameter.

Parent topic: Administration and Configuration Commands
Related tasks
To Run the Directory Server as a Non-Root User
Related information
CCITCP2_PORT


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


SPLREPAIR

A Windows batch file (.bat) that rebuilds corrupt spool control files.

The utility first backs up the existing SPL* files (to a separate directory), and then attempts to rebuild them.

Syntax:

SPLREPAIR.bat backup-directory

Parameters:

backup-directory
The path and directory name of the location to which your existing spool control files will be backed up.
Note: The directory must already exist, but not contain existing copies of the SPL* files that will be backed up.

Comments:

Run SPLREPAIR from the location that contains your spool control files (that is, the same location as catalog.dat, or the directory indicated by the MVSSPOOLDIR environment variable if the spool control files are stored elsewhere).

Example:

SPLREPAIR C:\SpoolCTRL\bkup
Parent topic: Administration and Configuration Commands


Enterprise Server 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
9000 | Failed to add an item to a configuration block
9001 | Invalid handle specified when building a configuration block
9002 | Invalid type of item specified when building a configuration block
9003 | Invalid tunable name specified when building a configuration block
9004 | Invalid tunable value specified when building a configuration block
9005 | Invalid tunable type specified when building a configuration block
9006 | Invalid tunable index specified when building a configuration block
9010 | Failed to associate a configuration block with a server context
9011 | Invalid server context specified for association with a configuration block
9020 | Failed to destroy a configuration block
9021 | Invalid configuration block specified to be destroyed
9030 | Failed to initialize configuration block
9040 | Service lookup failed
9041 | Service not found
9042 | Service disabled
9043 | Failed to load IDT
9044 | Service lookup request only valid before program execution
9050 | User exit not found
9051 | Error loading user exit
9060 | Service information request failed
9061 | Invalid service information request type
9062 | Cannot request service execution while in transaction end processing
9063 | Cannot make a dispose request within a transaction
9064 | Cannot start a new transaction within a transaction
9065 | Cannot start a new transaction when a dispose is outstanding
9066 | Cannot end a transaction while in transaction end processing
9067 | Cannot end/commit/rollback/recover a transaction that doesn't exist
9068 | Cannot prepare when the transaction has already been prepared
9069 | Cannot commit/rollback/recover when not in transaction end processing
9070 | Cannot commit/rollback/recover when transaction has already been completed
9071 | A stateful/stateless service request conflicts with current execution state
9072 | Cannot make an end transaction request in a local transaction
9073 | Transaction start failed
9074 | Transaction end failed
9075 | Transaction prepare failed
9076 | Transaction commit failed
9077 | Transaction rollback failed
9080 | Trace request failed
9090 | Unable to execute program as no service lookup was performed
9100 | SEP terminating due to run-time error while debugging service
Parent topic: Enterprise Server 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: Enterprise Server 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
    The copy operation was successful with no warnings or errors.
  • 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

The copy operation was successful with no warnings or errors.
Parent topic: Directory Server Error Messages 0 to 20


MDS0007E Duplicate server exists

You tried to create a server with the same name as one that already exists.
Note: This error can occur when an internal search operation specifies an additional search property of a server, such as its current state, or an internal unique identifier encountered when importing from another data or XML repository.
Parent topic: Directory Server Error Messages 0 to 20


MDS0008E Duplicate server name already exists

You tried to create a server with the same name as one that already exists.
Note: This is a specific case of the more general MDS0007E error message. MDS0008E applies specifically to the server name and occurs when adding or editing servers that results in a name clash.
Parent topic: Directory Server Error Messages 0 to 20


MDS0009E Invalid server specified.

You have specified an invalid server name or IP address when copying an enterprise server.
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 the journal for more information of the error.
  • MDS0035E Minimum object limit is 1024
    You tried to reduce the limit for the maximum number of objects below 1024, 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

You entered an invalid minimum page size for the journal.
Resolution:

This can be produced when you attempt to change values for the Entries displayed field, on the Configure Journal Options page.

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Options.
  2. Click the Journal tab.
  3. In the Entries displayed field, type a value of 5 or greater.
  4. Click OK.
Parent topic: Directory Server Error Messages 21 to 40


MDS0022E Minimum journal size is 32 KB

You entered an invalid minimum journal size for the journal.
Resolution:

This can be produced when you attempt to change values for the Maximum file size (KB) field, on the Configure Journal Options page.

  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Options.
  2. Click the Journal tab.
  3. In the Maximum file size (KB) field, type a value of 32 (KB) or greater.
  4. Click OK.
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

You tried to copy a server but the Directory Server was unable to copy all objects related to the server.
Typically this can be a result of:
  • File locking
  • Directory permissions
  • A clash of names
  • Data file corruption
  • Out of memory
Note: This is not an exhaustive list.
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

There was an error adding the object. See the journal for more information of the error.

Typically this can be a result of an out of memory condition but not exclusively.

Parent topic: Directory Server Error Messages 21 to 40


MDS0035E Minimum object limit is 1024

You tried to reduce the limit for the maximum number of objects below 1024, which is not allowed.
Resolution:
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Options.
  2. Click the General tab.
  3. In the Maximum MF Directory Server object count field, type a value equal or greater than 1024.
  4. Click OK.
Note: The minimum and default object limit is 1024.
Parent topic: Directory Server Error Messages 21 to 40


MDS0036E Maximum object limit is 9999

You tried to reduce the limit for the maximum number of objects above 9999, which is not allowed.
Resolution:
  1. On the menu at the left side of the Enterprise Server Administration Web page, under Configure, click Options.
  2. Click the General tab.
  3. In the Maximum MF Directory Server object count field, type a value less than 9999.
  4. Click OK.
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

You tried to reduce the maximum object count to less than the current number of registered objects.
Resolution:

You can resolve this issue by specifying a higher object limit:

  1. Open the Enterprise Server Administration page.
  2. In the left pane under Configure, click Options.
  3. Click the General tab.

    This displays the Configure General Options page.

  4. In the Maximum MF Directory Server object count field, type a higher limit.
  5. Click OK.
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\bin if Enterprise Server is installed standalone.
  • 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.
  • MDS0047W Package usually must have an IDT path
    You tried to add a package without a 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 displayed which is an HTTP status code.
  • 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


MDS0047W Package usually must have an IDT path

You tried to add a package without a IDT path value, or you deleted the IDT path value while editing the package.
Resolution:

You can resolve this issue by specifying an IDT path value:

  1. Open the Enterprise Server Administration page.
  2. In the Status column, click Details.
  3. Click the Packages tab.
  4. Next to the package that requires an IDT, click Edit.
  5. In the IDT field, type the platform appropriate file path to the IDT file.
  6. Click OK.
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:

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 displayed which is an HTTP status 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 takes 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

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.
Resolution:

You can resolve this issue by specifying an ID value for the resource manager definition:

  1. Open the Enterprise Server Administration page.
  2. Click Edit for the affected region.
  3. Click Server > Properties > XA Resources.
  4. Click Edit next to the XA Resource that requires an ID.
  5. In the ID field, type a value.
  6. Click Add.
Parent topic: Directory Server Error Messages 41 to 60


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.
Resolution:

You can resolve this issue by specifying a name value for the resource manager definition:

  1. Open the Enterprise Server Administration page.
  2. Click Edit for the affected region.
  3. Click Server > Properties > XA Resources.
  4. Click Edit next to the XA Resource that requires a name.
  5. In the Name field, type a name.
  6. Click Add.
Parent topic: Directory Server Error Messages 41 to 60


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.
Resolution:

You can resolve this issue by specifying a module for the resource manager definition:

  1. Open the Enterprise Server Administration page.
  2. Click Edit for the affected region.
  3. Click Server > Properties > XA Resources.
  4. Click Edit next to the XA Resource that requires a module.
  5. In the Module field, type a full path to the module filename.
  6. Click Add.
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

You asked to view an enterprise server console entry outside the range of existing entries.
Resolution:

You can resolve this issue by specifying a valid range for the Show entries from fields from either the ES Console or CS Console tabs.

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 service which it is associated with, or delete the services that reference it, and then delete it.

To disassociate the listener from a service:

  1. Open the Enterprise Server Administration page.
  2. Click Edit on the server row you want to disassociate the listener for.
  3. Click the Services tab.
  4. Click Edit on the row containing the listener that you want to disassociate.
  5. Add an alternative listener to the Accepting Listener(s) list:
    1. Click a listener in the Available Listeners(s) list.
    2. Click Add.
  6. Click the listener you want to disassociate in the Accepting Listener(s) list.
  7. Click Remove.
  8. Click OK.

To delete the listener:

  1. Open the Enterprise Server Administration page.
  2. Click Edit on the server row you want to disassociate the listener for.
  3. Click the Listeners tab.
  4. Click Edit on the row containing the listener you want to delete.
  5. Click Delete.
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

You have attempted to import a repository into the Directory Server schema, but the import failed.

This can be a result of the following reasons:

  • Access permissions.
  • Target/source directories not existing.
  • Attempting to save to a pre-existing or incompatible repository data version.
Note: This is not an exhaustive list.

Check 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

This can be a result of the following reasons:

  • Access permissions.
  • Target/source directories not existing.
  • Attempting to save to a pre-existing or incompatible repository data version.
Note: This is not an exhaustive list.

Check 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 enterprise server region, 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 when 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

When adding an MSS-enabled enterprise server region, 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.
Note: The port value must be greater than 0 and less than or equal to 65535. Certain port ranges have restrictions, depending on platform and version used. You should avoid port values already in use.
Parent topic: Directory Server Error Messages 81 to end


MDS0091E ISC listener port must have a valid value

Note: The port value must be greater than 0 and less than or equal to 65535. Certain port ranges have restrictions, depending on platform and version used. You should avoid port values already in use.
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

Displayed when a request is made to start an already-started enterprise server.
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

If both the MFDS SSL option and custom certificate option have both been specified, then a certificate and keyfile have to be specified.
Resolution:

To specify a certificate and keyfile:

  1. Open the Enterprise Server Administration page.
  2. In the left pane under Configure, click Security.
  3. Click the MF Directory Server tab.

See MF Directory Server Security for more information.

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

Some Security Manager names are reserved for internal use only, for example “mfds_esm”.
Parent topic: Directory Server Error Messages 81 to end


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.
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 - CICS Region Management Error Messages
  • CASBJ - CICS Batch Job Error Messages
  • CASCD - CICS Console Daemon Error Messages
  • CASCF - CICS Configuration Support Error Messages
  • CASCL - CICS for UNIX Client Error Messages
  • CASCS - CICS Communications Error Messages
  • CASCT - CICS Supplied Transactions Error Messages
  • CASCV - Enterprise Server Verification Utility Error Messages
  • CASDB - IMS Database Control Error Messages
  • CASDU - CICS Dump Control Error Messages
  • CASFC - CICS File Control Error Messages
  • CASFD - CICS Dump Formatter Error Messages
  • CASFF - CICS File Finder Error Messages
  • CASFS - Fileshare Error Messages
  • CASIP - CICS IMS Message Processing Error Messages
  • CASIS - CICS Web Interface Error Messages
  • CASJC - CICS Journal Control Error Messages
  • CASKC - CICS Task Control Error Messages
  • CASMG - Error Message File Error Messages
  • CASMQ - Trigger Monitor Error Messages
  • CASMS - CICS Trigger Monitor Error Messages
  • CASOP - CICS User Messages to Console
  • CASPA - Scale-Out Performance and Availability Cluster Error Messages
  • CASPC - CICS Program Control Error Messages
  • CASPI - WebSphere Error Messages
  • CASRA - CICS Resource Definition API Error Messages
  • CASRB - Miscellaneous Error Messages
  • CASRD - CICS Resource Definition DFHRDEF Error Messages
  • CASRM - CICS Resource Manager Control Error Messages
  • CASRS - CASRAS Process Error Messages
  • CASSE - CICS Security Error Messages
  • CASSI - CICS System Initialization Error Messages
  • CASSP - CICS Syncpoint and Recovery Services Error Messages
  • CASST - CICS Region Termination Error Messages
  • CASTD - CICS Transient Data Error Messages
  • CASTM - CICS System Termination Error Messages
  • CASTP - Transaction Paging Error Messages
  • CASTR - TRC Service Process Error Messages
  • CASTS - TSC Service Process Error Messages
  • CASXB - CICS BMS Macro Processor Error Messages
  • CASXO - CICS Transaction Manager Error Messages
  • COBEC - CICS API Preprocessor Error Messages
Parent topic: Enterprise Server Error Messages


CASAM - CICS Region Management Error Messages

  • CASAM1000 - CASAM1019
  • CASAM1020 - CASAM1039
  • CASAM1100 - CASAM1119
  • CASAM2000 - CASAM2019
  • CASAM2020 - CASAM2039
  • CASAM2040 - CASAM2059
  • CASAM2060 - CASAM2079
  • CASAM3000 - CASAM3019
  • CASAM3020 - CASAM3039
Parent topic: Enterprise Server Error Messages


CASAM1000 - CASAM1019

  • CASAM1001W CFMT file (or dataset) name not supplied
    The file name to action was not supplied Usage is CFMT {fn} {file-name}.
  • CASAM1002I CFMT Usage {fn} {file name} where fn={OPen,CLose,ENable,DIsable,INquire,NAme}
    No input was supplied with the transaction.
  • CASAM1003I Zero length input for CFMT at terminal-id, user user-id
    The transaction CFMT started on the terminal but there was no input data.
  • CASAM1004W Invalid CFMT initiation at terminal-id, user user-id
    The transaction CFMT started on the terminal but the start was not a valid start.
  • CASAM1005I CFMT - File file-id opened successfully; terminal-id, user user-id
    The request to open file-id by user user-id and terminal terminal-id was successful.
  • CASAM1006I CFMT - File file-id closed successfully; terminal-id, user user-id
    The request to close file-id by user user-id and terminal terminal-id was successful.
  • CASAM1007I CFMT - File file-id enabled successfully; terminal-id, user user-id
    The request to enable file-id by user user-id at terminal terminal-id was successful.
  • CASAM1008I CFMT - File file-id disabled successfully; terminal-id, user user-id
    The request to disable file-id by user user-id and terminal terminal-id was successful.
  • CASAM1009I CFMT - File file-id is open-status and enable-status; terminal-id, user user-id
    The inquire request by user user-id at terminal terminal-id was successful.
  • CASAM1010W CFMT invalid request (request) for file file-id at terminal-id, user user-id
    The request request for file file-id by user user-id and terminal terminal-id was not recognized.
  • CASAM1011W CFMT file file-id not found; terminal-id, user user-id
    The file file-id was not found.
  • CASAM1012E CFMT request not authorized for file file-id at terminal-id, user user-id
    The request for file file-id by user user-id at terminal terminal-id is not authorized.
  • CASAM1013E CFMT file file-id unexpected response (eibresp); terminal-id, user user-id
    The requested action for file file-id resulted in an unexpected API response of eibresp.
  • CASAM1014W CFMT illogic response for request to file file-id; terminal-id, user user-id
    The requested action for file file-id resulted in an illogic API response.
  • CASAM1015I CFMT file file-id DSNAME (DSNAME)
    The DSNAME associated with file file-id is displayed.
  • CASAM1016I CFMT function function completed. error-count error(s) encountered. See CEBR.
    The requested action has completed.
  • CASAM1017E CFMT file file-id IOERR (eibresp/eibresp2); terminal-id, user user-id
    The requested action for file file-id resulted in an IOERR.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM1001W CFMT file (or dataset) name not supplied

The file name to action was not supplied Usage is CFMT {fn} {file-name}.
Resolution:
Correct the input and resubmit the request.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


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

Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


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

Resolution:
Correct the input and resubmit the request.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


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

Resolution:
Correct the transaction initiation and resubmit the request.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1005I CFMT - File file-id opened successfully; terminal-id, user user-id

The request to open file-id by user user-id and terminal terminal-id was successful.
System Action:
The file was opened.
Module:
dfhzcfmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM1000 - CASAM1019


CASAM1006I CFMT - File file-id closed successfully; terminal-id, user user-id

The request to close file-id by user user-id and terminal terminal-id was successful.
System Action:
The file was closed.
Module:
dfhzcfmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM1000 - CASAM1019


CASAM1007I CFMT - File file-id enabled successfully; terminal-id, user user-id

The request to enable file-id by user user-id at terminal terminal-id was successful.
System Action:
The file was enabled.
Module:
dfhzcfmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM1000 - CASAM1019


CASAM1008I CFMT - File file-id disabled successfully; terminal-id, user user-id

The request to disable file-id by user user-id and terminal terminal-id was successful.
System Action:
The file was disabled.
Module:
dfhzcfmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM1000 - CASAM1019


CASAM1009I CFMT - File file-id is open-status and enable-status; terminal-id, user user-id

The inquire request by user user-id at terminal terminal-id was successful.

The status of file file-id is open-status and enable-status. If an unexpected CVDA value is returned for either of these statuses, the actual numeric status will be reported.

Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1010W CFMT invalid request (request) for file file-id at terminal-id, user user-id

The request request for file file-id by user user-id and terminal terminal-id 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.
Resolution:
Correct the input and resubmit.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1011W CFMT file file-id not found; terminal-id, user user-id

The file file-id was not found.

The file name is case sensitive. The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1012E CFMT request not authorized for file file-id at terminal-id, user user-id

The request for file file-id by user user-id at terminal terminal-id is not authorized.
System Action:
The request is ignored.
Resolution:
Correct the input or consult with the security administrator.
Module:
dfhzcfmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM1000 - CASAM1019


CASAM1013E CFMT file file-id unexpected response (eibresp); terminal-id, user user-id

The requested action for file file-id resulted in an unexpected API response of eibresp.

The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1014W CFMT illogic response for request to file file-id; terminal-id, user user-id

The requested action for file file-id resulted in an illogic API response.

The request was submitted by user user-id at terminal terminal-id. The requested transition is not logical, for example, an open request for a file that is already open.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1015I CFMT file file-id DSNAME (DSNAME)

The DSNAME associated with file file-id is displayed.
System Action:
None.
Resolution:
None.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1016I CFMT function function completed. error-count error(s) encountered. See CEBR.

The requested action has completed.

The number of errors (error-count) is shown.

System Action:
None.
Resolution:
Use the CEBR transaction to view the log.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1017E CFMT file file-id IOERR (eibresp/eibresp2); terminal-id, user user-id

The requested action for file file-id resulted in an IOERR.

The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcfmt
Destination:
Terminal
Parent topic: CASAM1000 - CASAM1019


CASAM1020 - CASAM1039

  • CASAM1020W 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.
  • CASAM1030I CNCL Usage: CNCL {program-name} {NW}
    No input was supplied with the transaction.
  • CASAM1031I Zero length input for CNCL at terminal-id, user user-id
    The transaction CNCL started on the terminal but there was no input data.
  • CASAM1032W Invalid CNCL initiation at terminal-id, user user-id
    The transaction CNCL started on the terminal but the start was not a valid start.
  • CASAM1033E 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.
  • CASAM1035I CNCL request for program program-name issued at terminal-id, user user-id
    The program release request was issued successfully.
  • CASAM1036W CNCL request for program program-name failed at terminal-id, user user-id
    The program release request failed.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM1020W 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 a RTS error. Common values for status:

Status   Reason              Action
3,005    file not found      Correct file name in FCT or create
                             file with CFCR if necessary.
9,065    file locked         Ensure that another program has not
                             opened the file exclusively.
9,124    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.
Resolution:
Correct the error and open the file using the CFMT transaction.
Module:
dfhzplt
Destination:
Console
Parent topic: CASAM1020 - CASAM1039


CASAM1030I CNCL Usage: CNCL {program-name} {NW}

No input was supplied with the transaction.

This message documents the required parameters. The user should enter the transaction ID and program name. The user can optionally specify NW for no wait on the cancel action.

Module:
dfhzcncl
Destination:
Terminal
Parent topic: CASAM1020 - CASAM1039


CASAM1031I Zero length input for CNCL at terminal-id, user user-id

The transaction CNCL started on the terminal but there was no input data.

The request executed on terminal terminal-id where user user-id was signed on.

Resolution:
Correct the input and resubmit the request.
Module:
dfhzcncl
Destination:
Terminal
Parent topic: CASAM1020 - CASAM1039


CASAM1032W Invalid CNCL initiation at terminal-id, user user-id

The transaction CNCL 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.

Resolution:
Correct the transaction initiation and resubmit the request.
Module:
dfhzcncl
Destination:
Terminal
Parent topic: CASAM1020 - CASAM1039


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

Resolution:
Use the CPMT transaction to release the CICS program.
Module:
dfhzcncl
Destination:
Terminal
Parent topic: CASAM1020 - CASAM1039


CASAM1035I CNCL request for program program-name issued at terminal-id, user user-id

The program release request was issued successfully.
Module:
dfhzcncl
Destination:
Terminal
Parent topic: CASAM1020 - CASAM1039


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

Module:
dfhzcncl
Destination:
Terminal
Parent topic: CASAM1020 - CASAM1039


CASAM1100 - CASAM1119

  • CASAM1101W 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.
  • CASAM1102W Unexpected error (return-code) requesting CKTI
    The CICS Option Process Requester returned an unexpected response.
  • CASAM1103W No initiation queue name given
    To start an WebSphere MQ monitor, you need to supply an initiation queue name.
  • CASAM1104I Usage: CKQC STARTCKTI <initiation-queue>
    To start an WebSphere MQ monitor via the LINK interface, you need to supply an initiation queue name.
  • CASAM1105W Invalid function key - use ENTER to accept data
    The only keys that are recognized are: CLEAR, PF3 & ENTER.
  • CASAM1106E WebSphere MQ queue manager name not found. RC=return-code
    The WebSphere MQ queue manager name cannot be found.
  • CASAM1107I CKTI requested for initiation-queue
    A request to start a CKTI has been initiated.
Parent topic: CASAM - CICS Region Management Error Messages


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

Resolution:
Restart CICS Option in multi-tasking mode, and reinvoke CKQC.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM1102W Unexpected error (return-code) requesting CKTI

The CICS Option Process Requester returned an unexpected response.
System Action:
The CKTI monitor is not started.
Resolution:
Retry the CKQC transaction. If the problem persists, contact Micro Focus Customer Support.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM1103W 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.
Resolution:
Resubmit, specifying a queue name.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM1104I 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.
Resolution:
Resubmit, specifying a queue name.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM1105W Invalid function key - use ENTER to accept data

The only keys that are recognized are: CLEAR, PF3 & ENTER.
Resolution:
Retry using a valid key.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM1106E WebSphere MQ queue manager name not found. RC=return-code

The WebSphere MQ queue manager name cannot be found.
Resolution:
Check that WebSphere MQ has been configured correctly in the system initialization table.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM1107I 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.
Resolution:
Check console.
Module:
dfhzckqc
Destination:
Terminal
Parent topic: CASAM1100 - CASAM1119


CASAM2000 - CASAM2019

  • CASAM2001W CPMT program or table name not supplied
    The program name to action was not supplied Usage is CPMT {fn} {program-name}.
  • CASAM2003I Zero length input for CPMT at terminal-id, user user-id
    The transaction CPMT started on the terminal but there was no input data.
  • CASAM2004W Invalid CPMT initiation at terminal-id, user user-id
    The transaction CPMT started on the terminal but the start was not a valid start.
  • CASAM2005I CPMT - Program program-id newcopy; terminal-id, user user-id
    The request to load a new copy of program-id by user user-id at terminal terminal-id was successful.
  • CASAM2006I CPMT - Program program-id phasein; terminal-id, user user-id
    The request to load a new copy of program-id by user user-id at terminal terminal-id was successful.
  • CASAM2007I CPMT - Program program-id private; terminal-id, user user-id
    The request to mark program program-id as private by user user-id at terminal terminal-id was successful.
  • CASAM2008I CPMT - Program program-id shared; terminal-id, user user-id
    The request to mark program program-id as shared by user user-id at terminal terminal-id was successful.
  • CASAM2009I CPMT - Program program-id dplsubset; terminal-id, user user-id
    The request to mark program program-id as dplsubset by user user-id at terminal terminal-id was successful.
  • CASAM2010I CPMT - Program program-id fullapi; terminal-id, user user-id
    The request to mark program program-id as fullapi by user user-id at terminal terminal-id was successful.
  • CASAM2011I CPMT - Program program-id cedf; terminal-id, user user-id
    The request to mark program program-id as cedf by user user-id at terminal terminal-id was successful.
  • CASAM2012I CPMT - Program program-id nocedf; terminal-id, user user-id
    The request to mark program program-id as nocedf by user user-id at terminal terminal-id was successful.
  • CASAM2013I CPMT - Program program-id is disabled; terminal-id, user user-id
    The request to mark program program-id as disabled by user user-id at terminal terminal-id was successful.
  • CASAM2014I CPMT - Program program-id is enabled; terminal-id, user user-id
    The request to mark program program-id as enabled by user user-id at terminal terminal-id was successful.
  • CASAM2016I Program program-id is not currently loaded
    Program program-id has not been loaded.
  • CASAM2018W CPMT invalid request (request) for program program-id at terminal-id, user user-id
    The request request for program program-id by user user-id and terminal terminal-id was not recognized.
  • CASAM2019W CPMT program program-id not found; terminal-id, user user-id
    The program program-id was not found.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM2001W CPMT program or table name not supplied

The program name to action was not supplied Usage is CPMT {fn} {program-name}.
Resolution:
Correct the input and resubmit the request.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2000 - CASAM2019


CASAM2003I Zero length input for CPMT at terminal-id, user user-id

The transaction CPMT started on the terminal but there was no input data.

The request executed on terminal terminal-id where user user-id was signed on.

Resolution:
Correct the input and resubmit the request.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2000 - CASAM2019


CASAM2004W Invalid CPMT initiation at terminal-id, user user-id

The transaction CPMT 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.

Resolution:
Correct the transaction initiation and resubmit the request.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2000 - CASAM2019


CASAM2005I CPMT - Program program-id newcopy; terminal-id, user user-id

The request to load a new copy of program-id by user user-id at terminal terminal-id was successful.
System Action:
A new copy of the program is loaded.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2006I CPMT - Program program-id phasein; terminal-id, user user-id

The request to load a new copy of program-id by user user-id at terminal terminal-id was successful.

The new copy will be used for all new requests.

System Action:
A new copy of the program is being phased in.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2007I CPMT - Program program-id private; terminal-id, user user-id

The request to mark program program-id as private by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2008I CPMT - Program program-id shared; terminal-id, user user-id

The request to mark program program-id as shared by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2009I CPMT - Program program-id dplsubset; terminal-id, user user-id

The request to mark program program-id as dplsubset by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2010I CPMT - Program program-id fullapi; terminal-id, user user-id

The request to mark program program-id as fullapi by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2011I CPMT - Program program-id cedf; terminal-id, user user-id

The request to mark program program-id as cedf by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2012I CPMT - Program program-id nocedf; terminal-id, user user-id

The request to mark program program-id as nocedf by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2013I CPMT - Program program-id is disabled; terminal-id, user user-id

The request to mark program program-id as disabled by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2014I CPMT - Program program-id is enabled; terminal-id, user user-id

The request to mark program program-id as enabled by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2016I Program program-id is not currently loaded

Program program-id has not been loaded.

The full name cannot be displayed until it has been accessed.

Resolution:
Do a NEWCOPY or PHASEIN command and repeat this inquiry.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2000 - CASAM2019


CASAM2018W CPMT invalid request (request) for program program-id at terminal-id, user user-id

The request request for program program-id by user user-id and terminal terminal-id 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.
Resolution:
Correct the input and resubmit.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2000 - CASAM2019


CASAM2019W CPMT program program-id not found; terminal-id, user user-id

The program program-id was not found.

The program name is case sensitive on some platforms. The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2000 - CASAM2019


CASAM2020 - CASAM2039

  • CASAM2020E CPMT request not authorized for program program-id at terminal-id, user user-id
    The request for program program-id by user user-id at terminal terminal-id is not authorized.
  • CASAM2021E CPMT program program-id unexpected response (eibresp); terminal-id, user user-id
    The requested action for program program-id resulted in an unexpected API response of eibresp.
  • CASAM2022E Error opening extrapartition destination (queue-id) group (group-id) - status=(file-status-1,file-status-2)
    An extrapartition destination marked as Open Init / Enabled could not be opened in system initialization due to the I/O error specified in file-status.
  • CASAM2023I CPMT - PPT for Program program-id was discarded; terminal-id, user user-id
    The request to discard the PPT for program program-id by user user-id at terminal terminal-id was successful.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM2020E CPMT request not authorized for program program-id at terminal-id, user user-id

The request for program program-id by user user-id at terminal terminal-id is not authorized.
System Action:
The request is ignored.
Resolution:
Correct the input or consult with the security administrator.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2020 - CASAM2039


CASAM2021E CPMT program program-id unexpected response (eibresp); terminal-id, user user-id

The requested action for program program-id resulted in an unexpected API response of eibresp.

The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2020 - CASAM2039


CASAM2022E Error opening extrapartition destination (queue-id) group (group-id) - status=(file-status-1,file-status-2)

An extrapartition destination marked as Open Init / 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
3,005    file not found      The DCT may specify I/O type as
                             Input but the physical file does not
                             yet exist.
9,065    file locked         Ensure that another program has not
                             opened the file exclusively.
9,124    comms error         Make sure the Fileshare server is
                             running and the correct CCI protocol
                             is defined in the FHREDIR configuration
                             file.
System Action:
The destination will not be opened.
Resolution:
Correct the error the system will attempt to open the destination during the next access.
Module:
dfhzplt
Destination:
Console
Parent topic: CASAM2020 - CASAM2039


CASAM2023I CPMT - PPT for Program program-id was discarded; terminal-id, user user-id

The request to discard the PPT for program program-id by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2020 - CASAM2039


CASAM2040 - CASAM2059

  • CASAM2051W CDMT DocTemplate name not supplied
    The DocTemplate name to action was not supplied Usage is CDMT NEwcopy {doctemplate-name}.
  • CASAM2055I CDMT DocTemplate DocTemplate newcopy; terminal-id, user user-id
    The request to load a new copy of DocTemplate by user user-id at terminal terminal-id was successful.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM2051W CDMT DocTemplate name not supplied

The DocTemplate name to action was not supplied Usage is CDMT NEwcopy {doctemplate-name}.
Resolution:
Correct the input and resubmit the request.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2040 - CASAM2059


CASAM2055I CDMT DocTemplate DocTemplate newcopy; terminal-id, user user-id

The request to load a new copy of DocTemplate by user user-id at terminal terminal-id was successful.
System Action:
A new copy of the DocTemplate is loaded.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2040 - CASAM2059


CASAM2060 - CASAM2079

  • CASAM2068W CDMT invalid request (request) for DocTemplate DocTemplate at terminal-id, user user-id
    The request request for DocTemplate DocTemplate by user user-id and terminal terminal-id was not recognized.
  • CASAM2069W CDMT DocTemplate DocTemplate not found; terminal-id, user user-id
    The DocTemplate DocTemplate was not found.
  • CASAM2070E CDMT request not authorized for DocTemplate DocTemplate at terminal-id, user user-id
    The request for DocTemplate DocTemplate by user user-id at terminal terminal-id is not authorized.
  • CASAM2071E CDMT DocTemplate DocTemplate unexpected response (eibresp); terminal-id, user user-id
    The requested action for DocTemplate DocTemplate resulted in an unexpected API response of eibresp.
  • CASAM2073I CDMT - DocTemplate DocTemplate was discarded; terminal-id, user user-id
    The request to discard the DocTemplate DocTemplate by user user-id at terminal terminal-id was successful.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM2068W CDMT invalid request (request) for DocTemplate DocTemplate at terminal-id, user user-id

The request request for DocTemplate DocTemplate by user user-id and terminal terminal-id was not recognized.

It may be NEwcopy, DIscard 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.
Resolution:
Correct the input and resubmit.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2060 - CASAM2079


CASAM2069W CDMT DocTemplate DocTemplate not found; terminal-id, user user-id

The DocTemplate DocTemplate was not found.

The DocTemplate name is case sensitive on some platforms. The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2060 - CASAM2079


CASAM2070E CDMT request not authorized for DocTemplate DocTemplate at terminal-id, user user-id

The request for DocTemplate DocTemplate by user user-id at terminal terminal-id is not authorized.
System Action:
The request is ignored.
Resolution:
Correct the input or consult with the security administrator.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2060 - CASAM2079


CASAM2071E CDMT DocTemplate DocTemplate unexpected response (eibresp); terminal-id, user user-id

The requested action for DocTemplate DocTemplate resulted in an unexpected API response of eibresp.

The request was submitted by user user-id at terminal terminal-id.

System Action:
The request is ignored.
Resolution:
Correct the input and resubmit.
Module:
dfhzcpmt
Destination:
Terminal
Parent topic: CASAM2060 - CASAM2079


CASAM2073I CDMT - DocTemplate DocTemplate was discarded; terminal-id, user user-id

The request to discard the DocTemplate DocTemplate by user user-id at terminal terminal-id was successful.
Module:
dfhzcpmt
Destination:
Terminal, CSMT td queue, and console
Parent topic: CASAM2060 - CASAM2079


CASAM3000 - CASAM3019

  • CASAM3000S Critical Event Manager storage error
    The Event Manager Process encountered a local storage failure that was not recoverable.
  • CASAM3001I Event Manager exit enabled (exit-program-name)
    The Event Manager Process loaded the user-defined exit exit-program-name.
  • CASAM3002W Event Manager unable to load exit (exit-program-name)
    The Event Manager Process was unable to load the user-defined exit exit-program-name.
  • CASAM3003E Unable to allocate Shared memory. Event Manager exits disabled
    Castrc was unable to allocate SHM.
  • CASAM3005E 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.
  • CASAM3006I Event Filter for (exit-name) has been enabled/disabled. Filter string: "filter-string"
    Event manager has enabled/disabled the event filter for this exit.
  • CASAM3007E 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.
  • CASAM3008E Illegal Type-id: "type-id-found". Max type-id: "max-type-id"
    The type id specified exceeds the maximum type id.
  • CASAM3009E 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.
  • CASAM3010E Illegal id range: "id-lo" - "id-hi"
    the id range specified is invalid.
  • CASAM3011W Exit initialization failed. Exit name: "exit-name"
    The exit returned a return code specifying its initialization failed.
  • CASAM3012E Initialization to generate Windows Events from EMP failed.
    EMP is unable to generate Windows events based on the events reported to EMP.
  • CASAM3013E 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.
  • CASAM3014E Unable to create Server Monitoring and Management shared memory. Monitoring and Management support disabled. Error: "Return code"
    Event Manager is unable to create the shared memory region for Monitoring and Management.
  • CASAM3015W Unable to deregister the server from active servers list for Monitoring and Management. Error Accessing registry
    Event Manager is unable to deregister the server from the active servers for Monitoring and Management list.
  • CASAM3016I ES Monitoring and Management support enabled
    The Monitoring and management support for this server has been enabled.
  • CASAM3017E 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.
  • CASAM3018E 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.
  • CASAM3019W ES Monitoring and Management retrieved unexpected value for "Registry key\Registry value name": actual=Actual value of registry key, expectedExpected value of registry key.
    Event manager retrieved an unexpected value for the performance registry key value.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM3000S 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.
Resolution:
The event manager could not allocate local storage, try to free some memory.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3001I Event Manager exit enabled (exit-program-name)

The Event Manager Process loaded the user-defined exit exit-program-name.
System Action:
The Event Manager call the exit at appropriate points.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3002W Event Manager unable to load exit (exit-program-name)

The Event Manager Process was unable to load the user-defined exit exit-program-name.
System Action:
The Event Manager will ignore the exit.
Resolution:
Check the exit specification and ensure it is on the search path.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3003E Unable to allocate Shared memory. Event Manager exits disabled

Castrc was unable to allocate SHM.

Hence the Event Manager exits have been disabled.

System Action:
The Event Manager exits will be disabled.
Resolution:
Check the region configuration.
Module:
castrc
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3005E 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.
Resolution:
Check the filter string, and restart the server.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3006I Event Filter for (exit-name) has been enabled/disabled. Filter string: "filter-string"

Event manager has enabled/disabled the event filter for this exit.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3007E 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.
Resolution:
Contact Micro Focus Customer Support.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3008E Illegal Type-id: "type-id-found". Max type-id: "max-type-id"

The type id specified exceeds the maximum type id.
Resolution:
check and correct the filter string.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3009E 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.
Resolution:
check and correct the filter string.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3010E Illegal id range: "id-lo" - "id-hi"

the id range specified is invalid.
Resolution:
check and correct the filter string.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3011W Exit initialization failed. Exit name: "exit-name"

The exit returned a return code specifying its initialization failed.
Resolution:
check the exit to find out why initialization of the exit failed.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3012E Initialization to generate Windows Events from EMP failed.

EMP is unable to generate Windows events based on the events reported to EMP.
Resolution:
Contact Micro Focus Customer Support.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3013E 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.
Resolution:
Contact Micro Focus Customer Support.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3014E Unable to create Server Monitoring and Management shared memory. Monitoring and Management support disabled. Error: "Return code"

Event Manager is unable to create the shared memory region for Monitoring and Management.
Resolution:
Contact Micro Focus Customer Support.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3015W Unable to deregister the server from active servers list for Monitoring and Management. Error Accessing registry

Event Manager is unable to deregister the server from the active servers for Monitoring and Management list.
Resolution:
Contact Micro Focus Customer Support.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3016I ES Monitoring and Management support enabled

The Monitoring and management support for this server has been enabled.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3017E 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.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3018E 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.
Resolution:
Perform an install repair on your system.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3019W ES Monitoring and Management retrieved unexpected value for "Registry key\Registry value name": actual=Actual value of registry key, expectedExpected 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.
Resolution:
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.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3000 - CASAM3019


CASAM3020 - CASAM3039

  • CASAM3020E 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.
  • CASAM3021W ES Monitoring and Management unable to get value for "Registry key\Registry value name": RC=Return code for WIN API call "RegQueryValueExA".
    Event manager retrieved an unexpected return code when querying the performance registry key value.
  • CASAM3022W 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.
  • CASAM3023E Error accessing file casglm.lck "Return code".
    While trying to access the file casglm.lck an error occurred.
  • CASAM3024E Unable to map shared memory for performance monitoring. Monitoring and Management support disabled. Error: "Return code"
    Event Manager is unable to map shared memory for performance monitoring.
  • CASAM3025I Region detected a timezone/daylight savings time change and automatically reset the time
    The system detected that the active timezone changed.
  • CASAM3026W Region detected a timezone/daylight savings time change - time needs to be reset
    The system detected that the active timezone changed.
  • CASAM3027I Region timezone reset by user (Logged on user) from transaction (Active transaction) at terminal (Active terminal)
    The active timezone was reset under programmatic control.
  • CASAM3028E Unexpected failure renaming current aux trace file to filename for new aux file renamed, reason = File status RC1,File status RC2
    ES failed to rename the current aux file The COBOL file status after failure is File status RC1,File status RC2.
  • CASAM3029I Aux trace switching notification exit enabled (exit-program-name)
    Castrc loaded the user-defined exit.
  • CASAM3030E ES Monitoring and Management failed to initialise counters. RC=Return code for WIN API call "CounterInitialize".
    Castrc retrieved an unexpected return code when initialising the V2 performance counters.
  • CASAM3031E ES Monitoring and Management failed to create a counterset instance. RC=Return code for WIN API call "PerfCreateInstance".
    Castrc retrieved an unexpected return code when creating an instance of the V2 performance counters.
  • CASAM3032E ES Monitoring and Management failed to load the counter values. RC=Return code for WIN API call "PerfSetCounterRefValue".
    Castrc retrieved an unexpected return code when finding the value associated with a V2 performance counter.
Parent topic: CASAM - CICS Region Management Error Messages


CASAM3020E 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.
Resolution:
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.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3021W ES Monitoring and Management unable to get value for "Registry key\Registry value name": RC=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.

Resolution:
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.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


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

Resolution:
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.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3023E Error accessing file casglm.lck "Return code".

While trying to access the file casglm.lck an error occurred.
Resolution:
Check the return code, and contact Micro Focus Customer Support.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3024E Unable to map shared memory for performance monitoring. Monitoring and Management support disabled. Error: "Return code"

Event Manager is unable to map shared memory for performance monitoring.
Resolution:
Contact Micro Focus Customer Support.
Module:
casevmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3025I Region detected a timezone/daylight savings time change and automatically reset the time

The system detected that the active timezone changed.

This may be due to DST changes.

System Action:
System time is automatically reset.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3026W Region detected a timezone/daylight savings time change - time needs to be reset

The system detected that the active timezone changed.

This may be due to DST changes.

Resolution:
Reset system time by executing a program which invokes PERFORM RESETTIME.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3027I Region timezone reset by user (Logged on user) from transaction (Active transaction) at terminal (Active terminal)

The active timezone was reset under programmatic control.

This may have been to cater for DST changes.

Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3028E Unexpected failure renaming current aux trace file to filename for new aux file renamed, reason = File status RC1,File status RC2

ES failed to rename the current aux file The COBOL file status after failure is File status RC1,File status RC2.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
castrc
Destination:
standard error
Parent topic: CASAM3020 - CASAM3039


CASAM3029I Aux trace switching notification exit enabled (exit-program-name)

Castrc loaded the user-defined exit.
System Action:
Castrc will call the exit every time an auxiliary trace file is switched.
Module:
castrc
Destination:
Console.
Parent topic: CASAM3020 - CASAM3039


CASAM3030E ES Monitoring and Management failed to initialise counters. RC=Return code for WIN API call "CounterInitialize".

Castrc retrieved an unexpected return code when initialising the V2 performance counters.

The performance counters may not have been loaded correctly.

Module:
castrc
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3031E ES Monitoring and Management failed to create a counterset instance. RC=Return code for WIN API call "PerfCreateInstance".

Castrc retrieved an unexpected return code when creating an instance of the V2 performance counters.

The performance counters may not have been loaded correctly.

Module:
castrc
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASAM3032E ES Monitoring and Management failed to load the counter values. RC=Return code for WIN API call "PerfSetCounterRefValue".

Castrc retrieved an unexpected return code when finding the value associated with a V2 performance counter.

The performance counters may not have been loaded correctly.

Module:
castrc
Destination:
Console and standard error.
Parent topic: CASAM3020 - CASAM3039


CASBJ - CICS Batch Job Error Messages

  • CASBJ0000 - CASBJ0019
  • CASBJ0020 - CASBJ0039
  • CASBJ0040 - CASBJ0059
Parent topic: Enterprise Server Error Messages


CASBJ0000 - CASBJ0019

  • CASBJ0000I message
    This is an ad hoc message for the JES subsystem.
  • 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.
  • CASBJ0002E JCL parser not available
    The batch JCL parser is not available on this server.
  • CASBJ0003E JOBjob-number duplicates an existing job number
    The Job Entry Subsystem generated a job number that duplicates an existing job number.
  • CASBJ0004I JOBjob-number job-name class job-class, TYPRUN=type-run
    The Job Entry Subsystem accepted the submitted job.
  • 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.
  • CASBJ0006I Batch initiator initialization started
    The batch initiator process initialization started.
  • CASBJ0007S Error return-code during initialization of server PCA
    An error occurred whilst initializing the server's Process Control Area.
  • 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.
  • CASBJ0009I Batch initiator shutdown complete.
    The batch initiator server process has shutdown normally.
  • CASBJ0010E Batch Spool File Error; Status action-status.
    The batch execution server failed trying to open the Spool reference file.
  • CASBJ0011E Batch Spool File Error; Status action-status.
    The batch execution server failed trying to close the Spool reference file.
  • CASBJ0012I Batch Input Spool has been "cold-started"
    An exixting Input Spool Repository for this Server was not found and therefore a new one was created.
  • CASBJ0013E Batch Spool File Error; Status action-status.
    The batch execution server failed trying to open the Spool reference file.
  • CASBJ0014I JOBaction-status started
    The batch initiator has started processing action-status.
  • CASBJ0015I message
    This reports informational messages from the JCL execution engine.
  • CASBJ0016W message
    This reports warning messages from the JCL execution engine.
  • CASBJ0017E message
    This reports error messages from the JCL execution engine.
  • CASBJ0018S message
    This reports severe error messages from the JCL execution engine.
  • CASBJ0019U message
    This reports unrecoverable error messages from the JCL execution engine.
Parent topic: CASBJ - CICS Batch Job Error Messages


CASBJ0000I message

This is an ad hoc message for the JES subsystem.
System Action:
as stated.
Module:
casmgr
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


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.

System Action:
The JES spool queue is initialized.
Module:
cassuba
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0002E JCL parser not available

The batch JCL parser is not available on this server.
System Action:
The submitted job is rejected.
Resolution:
Correct the installation.
Module:
cassuba
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0003E JOBjob-number duplicates an existing job number

The Job Entry Subsystem generated a job number that duplicates an existing job number.
System Action:
The submitted job is rejected.
Resolution:
Retry the submission.
Module:
cassuba
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0004I JOBjob-number job-name class job-class, TYPRUN=type-run

The Job Entry Subsystem accepted the submitted job.
System Action:
The submitted job placed on the input queue.
Module:
cassuba
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


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

Module:
casbati1
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0006I Batch initiator initialization started

The batch initiator process initialization started.
Module:
casbati1
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


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.

System Action:
Stop the server process.
Resolution:
Make sure that the region for which the server was to be started is running and retry.
Module:
casbati1
Destination:
Console and standard error
Parent topic: CASBJ0000 - CASBJ0019


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.

System Action:
The JES spool queue is initialized.
Module:
casbat
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0009I Batch initiator shutdown complete.

The batch initiator server process has shutdown normally.
System Action:
The process terminates normally.
Resolution:
None.
Module:
casbat
Destination:
System Console and standard error.
Parent topic: CASBJ0000 - CASBJ0019


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.

System Action:
The process terminates.
Resolution:
Correct the problem with the spool file and retry.
Module:
casbat
Destination:
System Console and standard error.
Parent topic: CASBJ0000 - CASBJ0019


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.

System Action:
The process terminates.
Resolution:
Correct the problem with the spool file and retry.
Module:
casbat
Destination:
System Console and standard error.
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0012I Batch Input Spool has been "cold-started"

An exixting 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.

System Action:
The JES spool queue is initialized.
Module:
casmgr
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


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.

Resolution:
Correct the problem with the spool file and retry.
Module:
casmgr
Destination:
System Console and standard error.
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0014I JOBaction-status started

The batch initiator has started processing action-status.
Module:
casbat
Destination:
System Console and standard error.
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0015I message

This reports informational messages from the JCL execution engine.
System Action:
as stated.
Module:
casbat/cassub
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0016W message

This reports warning messages from the JCL execution engine.
System Action:
as stated.
Module:
casbat/cassub
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0017E message

This reports error messages from the JCL execution engine.
System Action:
as stated.
Module:
casbat/cassub
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0018S message

This reports severe error messages from the JCL execution engine.
System Action:
as stated.
Module:
casbat/cassub
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0019U message

This reports unrecoverable error messages from the JCL execution engine.
System Action:
as stated.
Module:
casbat/cassub
Destination:
ES Console
Parent topic: CASBJ0000 - CASBJ0019


CASBJ0020 - CASBJ0039

  • CASBJ0020I Batch printer initialization started
    The batch printer process initialization started.
  • CASBJ0021I Batch printer started for print output classes "output-classes"
    The batch printer was started an is available for processing system output.
  • CASBJ0022I Batch printer definition-name: class(es) "print-classes"
    The batch printer was started an is available for processing output.
  • CASBJ0023I Batch initiator definition-name: class(es) "initiator-classes"
    The batch initiator was started an is available for processing output.
  • CASBJ0024I Batch Printer: "printer-name"
    The batch printer was started and will write to physical printer "printer-name".
  • CASBJ0025E Printer not found: "printer-name"
    The physical printer "printer-name" was not found.
  • CASBJ0026I Exit Module: "exit-module"
    The batch printer is configured to use exit module "exit-module".
  • 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.
  • CASBJ0028E Load failed for exit Module: "exit-module"
    The batch printer failed to load exit module "exit-module".
  • CASBJ0029I print-dataset-title on printer-name
    The batch printer is printing "print-dataset-title" on printer printer-name.
  • CASBJ0030E error-message
    The batch print processor experienced the stated problem.
  • CASBJ0031E Printer open failed. RC=return-code
    Call to open assigned printer failed with a return-code of return-code.
  • CASBJ0032E Printer write failed. RC=return-code
    Call to write to the assigned printer failed with a return-code of return-code.
  • CASBJ0033E Printer error accessing spool data: status-data
    Print processor encounterd an error accessing the spool data.
  • CASBJ0034I Printer process shutdown complete.
    The print processor server process has shutdown normally.
  • CASBJ0035I Console input request is pending.
    A job or service has requested input from the system console.
  • CASBJ0036E job-number Spool purge processor not available
    Print processor could not locate the Spool purge processor.
  • CASBJ0037E job-number Spool purge failed: RC = return-code
    Print processor failed.
  • CASBJ0038I job-number Spool SYSOUT Purged
    Processing of job-number completed and the spool output has been purged.
  • CASBJ0039E JES support not enabled; Start for Printer rejected
    The requested Printer was not started because JES support is not enabled.
Parent topic: CASBJ - CICS Batch Job Error Messages


CASBJ0020I Batch printer initialization started

The batch printer process initialization started.
Module:
casbati1
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


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

Module:
casprn(dfheini1)
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


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

Module:
casmgr
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


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

Module:
casmgr
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0024I Batch Printer: "printer-name"

The batch printer was started and will write to physical printer "printer-name".
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0025E Printer not found: "printer-name"

The physical printer "printer-name" was not found.
System Action:
The ES printer process will shutdown.
Resolution:
Correct the printer name and retry the operation.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0026I Exit Module: "exit-module"

The batch printer is configured to use exit module "exit-module".
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


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.
System Action:
The ES printer process will shutdown.
Resolution:
Correct the printer name and retry the operation.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0028E Load failed for exit Module: "exit-module"

The batch printer failed to load exit module "exit-module".
System Action:
Printer process is shutdown.
Resolution:
Correct exit module name or location and restart printer.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0029I print-dataset-title on printer-name

The batch printer is printing "print-dataset-title" on printer printer-name.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0030E error-message

The batch print processor experienced the stated problem.
System Action:
Printer process bypasses the job.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0031E Printer open failed. RC=return-code

Call to open assigned printer failed with a return-code of return-code.
System Action:
The ES printer process will shutdown.
Resolution:
Correct the printer problem and retry the operation.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0032E Printer write failed. RC=return-code

Call to write to the assigned printer failed with a return-code of return-code.
System Action:
operation bypassed.
Resolution:
Correct the printer problem and retry the job.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0033E Printer error accessing spool data: status-data

Print processor encounterd an error accessing the spool data.

The operation and status is status-data.

System Action:
operation terminated.
Resolution:
Correct the problem and retry the job.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0034I Printer process shutdown complete.

The print processor server process has shutdown normally.
System Action:
The process terminates normally.
Resolution:
None.
Module:
casbat
Destination:
System Console and standard error.
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0035I Console input request is pending.

A job or service has requested input from the system console.
System Action:
The process waits for console input.
Resolution:
Reply to the request.
Module:
cassi
Destination:
System Console and standard error.
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0036E job-number Spool purge processor not available

Print processor could not locate the Spool purge processor.
System Action:
operation bypassed.
Resolution:
Correct the problem and restart the print processor.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0037E job-number Spool purge failed: RC = return-code

Print processor failed.

The return code was return-code.

System Action:
operation bypassed.
Resolution:
Correct the problem and restart the print processor.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0038I job-number Spool SYSOUT Purged

Processing of job-number completed and the spool output has been purged.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0020 - CASBJ0039


CASBJ0039E JES support not enabled; Start for Printer rejected

The requested Printer was not started because JES 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: CASBJ0020 - CASBJ0039


CASBJ0040 - CASBJ0059

  • CASBJ0040E JES support not enabled; Start for Initiator rejected
    The requested Job Initiator was not started because JES support is not enabled.
  • CASBJ0041E Printer JES interface initialization failed. RC=Return code
    The requested Printer output processor failed to start because JES initialization failed.
  • CASBJ0042E Batch initiator JES interface initialization failed. RC=Return code
    The requested initiator JES interface failed.
  • CASBJ0043E JOB Submit JES interface initialization failed. RC=Return code
    The requested JOB Submit JES interface failed.
  • CASBJ0044I Batch initiator restart requested for job classes "job-classes"
    A batch initiator is terminating because of a "dirty container" condition.
  • CASBJ0045I JOBjob-number, DD number dd-number, size dataset-size requested
    An external process requested this dataset and transmission has started.
  • 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.
  • 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.
  • 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.
  • 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.
  • CASBJ0050E JES support not enabled; Job rejected
    The requested Job was not submitted because JES support is not enabled.
  • CASBJ0051S Batch initiator JES interface initialization failed for ES Cluster manager ES Cluster manager APPLID, Cluster request failed. RC=Return code
    The requested initiator JES interface failed to connect to ES Cluster manager.
  • CASBJ0052S Batch initiator JES interface initialization failed for ES Cluster manager ES Cluster manager APPLID, no connection to GLM. RC=Return code
    No connection available for JES interface failed to connect to ES Cluster manager.
  • CASBJ0053S Batch initiator failed to switch user to Target batch job USER for job JOB Number RC=Return code
    Attempt to switch user to the user specified via the JOB card failed.
Parent topic: CASBJ - CICS Batch Job Error Messages


CASBJ0040E JES support not enabled; Start for Initiator rejected

The requested Job Initiator was not started because JES 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: CASBJ0040 - CASBJ0059


CASBJ0041E Printer JES interface initialization failed. RC=Return code

The requested Printer output processor failed to start because JES initialization failed.
System Action:
the printer output processor stops.
Resolution:
Please contact Micro Focus Customer Support with the return code received from casspool.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0042E Batch initiator JES interface initialization failed. RC=Return code

The requested initiator JES interface failed.
System Action:
the batch initiator stops.
Resolution:
Please contact Micro Focus Customer Support with the return code received from casspool.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0043E JOB Submit JES interface initialization failed. RC=Return code

The requested JOB Submit JES interface failed.
System Action:
the submitted job is rejected.
Resolution:
Please contact Micro Focus Customer Support with the return code received from casspool.
Module:
casprn
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


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

Module:
casbati1
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0045I JOBjob-number, DD number dd-number, size dataset-size requested

An external process requested this dataset and transmission has started.
Module:
casouta
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


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.
System Action:
the request is rejected.
Resolution:
correct the credentials and retry the operation.
Module:
cassuba
Destination:
ES Console & requestor
Parent topic: CASBJ0040 - CASBJ0059


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.
System Action:
the request is rejected.
Resolution:
retry the operation with authorized credentials.
Module:
cassuba
Destination:
ES Console & requestor
Parent topic: CASBJ0040 - CASBJ0059


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.
System Action:
The request is rejected.
Resolution:
correct the credentials and retry the operation.
Module:
casouta
Destination:
ES Console & requestor
Parent topic: CASBJ0040 - CASBJ0059


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.
System Action:
for this action. The request is rejected.
Resolution:
Retry the operation with authorized credentials.
Module:
casouta
Destination:
ES Console & requestor
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0050E JES support not enabled; Job rejected

The requested Job was not submitted because JES support is not enabled.
System Action:
the request is rejected.
Resolution:
enable support and retry the operation.
Module:
cassub
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0051S Batch initiator JES interface initialization failed for ES Cluster manager ES Cluster manager APPLID, Cluster request failed. RC=Return code

The requested initiator JES interface failed to connect to ES Cluster manager.
System Action:
the batch initiator stops.
Resolution:
Check that the connection to the GLM is active, and correct the error on the received message.
Module:
casbat
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0052S Batch initiator JES interface initialization failed for ES Cluster manager ES Cluster manager APPLID, no connection to GLM. RC=Return code

No connection available for JES interface failed to connect to ES Cluster manager.
System Action:
the batch initiator stops.
Resolution:
Check that the connection to the GLM is active.
Module:
casbat
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASBJ0053S Batch initiator failed to switch user to Target batch job USER for job JOB Number RC=Return code

Attempt to switch user to the user specified via the JOB card failed.
System Action:
The requested job is moved to the held spool queue.
Resolution:
Check the user is valid.
Module:
casbat
Destination:
ES Console
Parent topic: CASBJ0040 - CASBJ0059


CASCD - CICS Console Daemon Error Messages

  • CASCD0000 - CASCD0019
  • CASCD0020 - CASCD0039
  • CASCD0040 - CASCD0059
  • CASCD0060 - CASCD0079
  • CASCD0080 - CASCD0099
  • CASCD0100 - CASCD0119
  • CASCD0120 - CASCD0139
  • CASCD0140 - CASCD0159
  • CASCD0160 - CASCD0179
  • CASCD1000 - CASCD1019
  • CASCD1020 - CASCD1039
  • CASCD1040 - CASCD1059
  • CASCD1060 - CASCD1079
  • CASCD1080 - CASCD1099
  • CASCD1100 - CASCD1119
  • CASCD1120 - CASCD1139
  • CASCD1200 - CASCD1219
  • CASCD4000 - CASCD4019
Parent topic: Enterprise Server Error Messages


CASCD0000 - CASCD0019

  • CASCD0001F TX Daemon could not be started
    The request to start a TX daemon was not successful.
  • CASCD0002S Failed to create TX Daemon, reason = errno
    TX failed to create a new process in which to run the TX daemon A UNIX 'fork' call returned with errno set to errno.
  • CASCD0003S Failed to 'exec' COBOL RTS, reason = errno
    TX was unable to run the COBOL RTS in the TX daemon process A UNIX 'exec' call returned with errno set to errno.
  • CASCD0004S Error creating named-pipe 'pipe-name', reason = errno
    TX failed to create named pipe 'pipe-name' which was to be used for communication with the TX daemon.
  • CASCD0005S Error opening named-pipe 'pipe-name', reason = errno
    TX failed to open named pipe 'pipe-name' which was to be used to receive messages from the TX daemon A UNIX 'fopen' call returned with errno set to errno.
  • CASCD0006S Error reading named-pipe 'pipe-name', reason = errno
    An error occurred attempting to read from the named pipe pipe-name which was being used to receive messages from the TX daemon A UNIX 'fgets' call returned with errno set to errno.
  • CASCD0007S TX Daemon died unexpectedly, final status was process status
    The TX 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 Error Creating Message Queue, reason = function,errno
    TX failed to create a UNIX message queue.
  • CASCD0009F Error Reading from Message Queue, reason = function,errno
    TX detected an error whilst reading from a UNIX message queue.
  • CASCD0010F Error Deleting Message Queue, reason = function,errno
    TX failed to delete a UNIX message queue during shutdown.
  • CASCD0011F Unexpected failure opening log file, reason = RC1,RC2
    TX failed to open the system console log file The COBOL file status after failure is RC1,RC2.
  • CASCD0012F Unable to write to console log, system disk is full
    TX failed to write to the system console log file because the system disk is full.
  • CASCD0013F Attempt to start second Console Daemon rejected
    Only one TX Daemon is required, attempts to start more are rejected.
  • CASCD0014F User authorization failure, reason = errno
    A UNIX setuid call has failed, returning errno set to errno.
  • CASCD0015W Error communicating with TX Daemon
    After the TX Daemon has been created an attempt is made to communicate with it.
  • CASCD0016W Invalid auto-start region name 'auto-start-region-name'
    The region name specified on the command line to dfhtxs to auto-start was found to be invalid.
  • CASCD0017I cascd: cascd-message
    Ad hoc message.
  • CASCD0018I Batch job user impersonation active for user : 'Impersonation target user'
    Confirmation that user impersonation for batch job execution has been configured.
  • CASCD0019I Batch job user impersonation initialization failed for user : 'Impersonation target user' RC: return code errno: errno
    Environment initialization of user impersonation for batch job execution has been unsuccessful.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0001F TX Daemon could not be started

The request to start a TX daemon was not successful.
System Action:
The TX daemon is not started.
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0002S Failed to create TX Daemon, reason = errno

TX failed to create a new process in which to run the TX daemon A UNIX 'fork' call returned with errno set to errno.
System Action:
The TX daemon is not started.
Resolution:
Correct the cause of the error and retry.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0003S Failed to 'exec' COBOL RTS, reason = errno

TX was unable to run the COBOL RTS in the TX daemon process A UNIX 'exec' call returned with errno set to errno.
System Action:
The TX daemon is not started.
Resolution:
Correct the cause of the error and retry.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0004S Error creating named-pipe 'pipe-name', reason = errno

TX failed to create named pipe 'pipe-name' which was to be used for communication with the TX daemon.

A UNIX 'mknod' call returned with errno set to errno.

System Action:
The TX daemon is not started.
Resolution:
Correct the cause of the error and retry.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0005S Error opening named-pipe 'pipe-name', reason = errno

TX failed to open named pipe 'pipe-name' which was to be used to receive messages from the TX daemon A UNIX 'fopen' call returned with errno set to errno.
System Action:
The TX daemon is not started.
Resolution:
Correct the cause of the error and retry.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0006S Error reading named-pipe 'pipe-name', reason = errno

An error occurred attempting to read from the named pipe pipe-name which was being used to receive messages from the TX daemon A UNIX 'fgets' call returned with errno set to errno.
System Action:
The TX daemon is not started.
Resolution:
Correct the cause of the error and retry.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0007S TX Daemon died unexpectedly, final status was process status

The TX 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 TX daemon is not started.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0008F Error Creating Message Queue, reason = function,errno

TX failed to create a UNIX message queue.

A UNIX message queue call returned with errno set to function. The call that failed is specified by function, where:

1 = msgget
2 = msgctl
3 = msgrcv
4 = msgsnd
System Action:
The TX Daemon is not started.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0009F Error Reading from Message Queue, reason = function,errno

TX detected an error whilst reading from a UNIX message queue.

A UNIX message queue call returned with errno set to function. The call that failed is specified by function, where:

1 = msgget
2 = msgctl
3 = msgrcv
4 = msgsnd
System Action:
The TX System shuts down.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
cascd
Destination:
system console
Parent topic: CASCD0000 - CASCD0019


CASCD0010F Error Deleting Message Queue, reason = function,errno

TX failed to delete a UNIX message queue during shutdown.

A UNIX message queue call returned with errno set to function. The call that failed is specified by function, where:

1 = msgget
2 = msgctl
3 = msgrcv
4 = msgsnd
System Action:
The TX Daemon continues shutdown.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
cascd
Destination:
system console
Parent topic: CASCD0000 - CASCD0019


CASCD0011F Unexpected failure opening log file, reason = RC1,RC2

TX failed to open the system console log file The COBOL file status after failure is RC1,RC2.
System Action:
The TX Daemon is not started.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0012F Unable to write to console log, system disk is full

TX 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.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0013F Attempt to start second Console Daemon rejected

Only one TX Daemon is required, attempts to start more are rejected.
System Action:
The request is rejected.
Resolution:
Terminate existing Daemon if restart is required.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0014F User authorization failure, reason = errno

A UNIX setuid call has failed, returning errno set to errno.

This is probably caused by an attempt to start an TX Daemon without super-user authority.

System Action:
The TX Daemon is not started.
Resolution:
Retry the request from a super-user.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0015W Error communicating with TX Daemon

After the TX 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.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0016W Invalid auto-start region name 'auto-start-region-name'

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 $TXDIR 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.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0000 - CASCD0019


CASCD0017I cascd: cascd-message

Ad hoc message.
System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
cascd
Destination:
Console
Parent topic: CASCD0000 - CASCD0019


CASCD0018I Batch job user impersonation active for user : 'Impersonation target user'

Confirmation that user impersonation for batch job execution has been configured.
System Action:
None.
Resolution:
None.
Module:
cascd
Destination:
Console
Parent topic: CASCD0000 - CASCD0019


CASCD0019I Batch job user impersonation initialization failed for user : 'Impersonation target user' RC: return code errno: errno

Environment initialization of user impersonation for batch job execution has been unsuccessful.
System Action:
None.
Resolution:
None.
Module:
cascd
Destination:
Console
Parent topic: CASCD0000 - CASCD0019


CASCD0020 - CASCD0039

  • CASCD0020E CASCD lost connection to Redis server Redis server name at Redis server address port Redis port number
    CASCD lost the connection to Redis.
  • CASCD0021I CASCD reconnected to Redis server Redis server name at Redis server address port Redis port number
    CASCD reconnected to Redis.
  • CASCD0022E TX Daemon not running, Shutdown request ignored
    There is no TX Daemon to shutdown.
  • CASCD0023S Unrecognized option 'option-value'
    The specified option is not valid.
  • CASCD0024S Too many arguments, maximum is 1
    Too many arguments were specified, the maximum permitted is 1.
  • CASCD0025S Severe Error function while terminating TX daemon, reason = errno
    A UNIX call returned with errno set to errno.
  • CASCD0026S No response from TX Daemon, state not known
    The TX Daemon did not respond to the shutdown request, it is not possible to determine the current state of the daemon.
  • CASCD0027W WARNING - immediate shutdown ABENDs all running regions
    The immediate shutdown option of the console daemon shutdown utility abends all running regions.
  • CASCD0028I Console Daemon running with effective user ID = effective-user-id
    If the TX Console Daemon is not running with the effective user ID of root (UID=0) this message details the current effective user id.
  • CASCD0029I Console Daemon loaded server start exit "casexitv"
    This exit provides external control for starting CAS server instances.
  • CASCD0030I Console Daemon server instance start exit: return code = return-code
    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 Server server-number created for region region-name via "casexitv"
    A server has been started for region region-name.
  • CASCD0032E Console Daemon failed to load casmfdbfh
    casmfdbfh was not loaded.
  • CASCD0033E CASCD lost connection to Coherence using Coherence connection string
    CASCD lost the connection to Coherence cluster.
  • CASCD0034I CASCD reconnected to Coherence using Coherence connection string
    CASCD reconnected to Coherence.
  • CASCD0035I Region initializing PAC PAC name
    This region is the first region in a PAC and is initializing the PAC.
  • CASCD0036W Pending ITR issued by this region found during region termination. ITR will be removed. Type=Type of ITR, Action=Action on ITR, Resource=Resource
    An ITR was not completed and the region is shutting down.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0020E CASCD lost connection to Redis server Redis server name at Redis server address port Redis port number

CASCD lost the connection to Redis.
System Action:
will try to reconnect.
Resolution:
check the Redis server.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0021I CASCD reconnected to Redis server Redis server name at Redis server address port Redis port number

CASCD reconnected to Redis.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0022E TX Daemon not running, Shutdown request ignored

There is no TX Daemon to shutdown.
System Action:
The request is rejected.
Resolution:
Ensure an TX Daemon is running before attempting shutdown.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0020 - CASCD0039


CASCD0023S Unrecognized option 'option-value'

The specified option is not valid.
System Action:
The request is rejected.
Resolution:
Retry the request with a valid option.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0020 - CASCD0039


CASCD0024S Too many arguments, maximum is 1

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.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0020 - CASCD0039


CASCD0025S Severe Error function while terminating TX daemon, reason = errno

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 TX Daemon is not shut down.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0020 - CASCD0039


CASCD0026S No response from TX Daemon, state not known

The TX 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.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0020 - CASCD0039


CASCD0027W WARNING - immediate shutdown ABENDs all running regions

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.
Module:
dfhtxp
Destination:
Console and stdout
Parent topic: CASCD0020 - CASCD0039


CASCD0028I Console Daemon running with effective user ID = effective-user-id

If the TX 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 TX console Daemon runs as, and all region created, is set at installation time.

Module:
cascd
Destination:
Console.
Parent topic: CASCD0020 - CASCD0039


CASCD0029I Console Daemon loaded server start exit "casexitv"

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.

Module:
cascd
Destination:
Console.
Parent topic: CASCD0020 - CASCD0039


CASCD0030I Console Daemon server instance start exit: return code = return-code

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 appropriate to the exit program's return code.
Module:
cascd
Destination:
Console.
Parent topic: CASCD0020 - CASCD0039


CASCD0031I Server server-number created for region region-name via "casexitv"

A server has been started for region region-name.

server-number server start requests have been issued.

Module:
cascd
Destination:
system console
Parent topic: CASCD0020 - CASCD0039


CASCD0032E Console Daemon failed to load casmfdbfh

casmfdbfh was not loaded.
Module:
cascd
Destination:
system console
Parent topic: CASCD0020 - CASCD0039


CASCD0033E CASCD lost connection to Coherence using Coherence connection string

CASCD lost the connection to Coherence cluster.
System Action:
will try to reconnect.
Resolution:
check the Coherence cluster.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0034I CASCD reconnected to Coherence using Coherence connection string

CASCD reconnected to Coherence.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0035I Region initializing PAC PAC name

This region is the first region in a PAC and is initializing the PAC.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0036W Pending ITR issued by this region found during region termination. ITR will be removed. Type=Type of ITR, Action=Action on ITR, Resource=Resource

An ITR was not completed and the region is shutting down.

The ITR has been removed from the CasITR store.

Resolution:
Contact Micro Focus Customer Support.
Module:
cascd
Destination:
Console
Parent topic: CASCD0020 - CASCD0039


CASCD0040 - CASCD0059

  • CASCD0050I ES "region-name" initiation is starting
    The region initiation has been started.
  • CASCD0051F ES "region-name" was not started
    The request to start a region was not successful.
  • CASCD0052S ES Daemon is not active
    An attempt has been made to start a region before there is an active TX Daemon.
  • CASCD0053S No Responses received from region
    The REM has sent no progress messages, its state is not known.
  • CASCD0054S Severe Error function while starting region, reason = errno
    A UNIX call returned with errno set to errno.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0050I ES "region-name" initiation is starting

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.

Module:
dfhrem
Destination:
standard error
Parent topic: CASCD0040 - CASCD0059


CASCD0051F ES "region-name" was not started

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.
Module:
dfhrem
Destination:
standard error
Parent topic: CASCD0040 - CASCD0059


CASCD0052S ES Daemon is not active

An attempt has been made to start a region before there is an active TX Daemon.
System Action:
The region is not started.
Resolution:
Start an TX Daemon before attempting to start other components.
Module:
dfhrem
Destination:
standard error
Parent topic: CASCD0040 - CASCD0059


CASCD0053S No Responses received from region

The REM has sent no progress messages, its state is not known.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
dfhrem
Destination:
standard error
Parent topic: CASCD0040 - CASCD0059


CASCD0054S Severe Error function while starting region, reason = errno

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.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0040 - CASCD0059


CASCD0060 - CASCD0079

  • CASCD0060I Server started successfully
    The server has been started.
  • CASCD0061F Server was not started
    The request to start a server was not successful.
  • CASCD0062S TX Daemon is not active
    An attempt has been made to start a server before there is an active TX Daemon.
  • CASCD0063S No Responses received from server
    The server has sent no progress messages, its state is not known.
  • CASCD0064S Fatal Error function while starting server, reason = errno
    A UNIX call returned with errno set to errno.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0060I Server started successfully

The server has been started.
Module:
dfhserv
Destination:
standard error
Parent topic: CASCD0060 - CASCD0079


CASCD0061F Server was not started

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.
Module:
dfhserv
Destination:
standard error
Parent topic: CASCD0060 - CASCD0079


CASCD0062S TX Daemon is not active

An attempt has been made to start a server before there is an active TX Daemon.
System Action:
The server is not started.
Resolution:
Start an TX Daemon before attempting to start other components.
Module:
dfhserv
Destination:
standard error
Parent topic: CASCD0060 - CASCD0079


CASCD0063S No Responses received from server

The server has sent no progress messages, its state is not known.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
dfhserv
Destination:
standard error
Parent topic: CASCD0060 - CASCD0079


CASCD0064S Fatal Error function while starting server, reason = errno

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 TX Daemon is not shut down.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
dfhtxp
Destination:
standard error
Parent topic: CASCD0060 - CASCD0079


CASCD0080 - CASCD0099

  • CASCD0099I ES Build Tag: tag-number
    The TX Daemon tag for current version.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0099I ES Build Tag: tag-number

The TX Daemon tag for current version.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0080 - CASCD0099


CASCD0100 - CASCD0119

  • CASCD0100I ES Threaded Daemon Initialized (version-number) process-id = pid (Time)
    The TX Daemon has initialized and is waiting for work.
  • CASCD0101I ES Daemon Terminated
    The TX Daemon has completed termination.
  • CASCD0102F ES Daemon failed to initialize
    The TX Daemon has failed to initialize.
  • CASCD0103E Unknown request Request-Type received by TX Daemon
    The TX Daemon has received a message with an unknown request type of Request-Type.
  • CASCD0104I ES Daemon Initialized (version-number)
    The ES Daemon has initialized and is waiting for work.
  • CASCD0110I TX Daemon Shutdown started
    The TX Daemon is beginning a normal shutdown.
  • CASCD0111I TX Daemon is quiescing, number-of-regions regions running
    The TX Daemon is beginning an orderly shutdown and will wait for the number-of-regions regions to terminate before shutting down.
  • CASCD0112I TX Daemon Shutdown started, number-of-regions regions will be abended
    The TX Daemon is beginning an immediate shutdown and will abend number-of-regions regions before shutting down.
  • CASCD0113I TX Daemon Shutdown completed
    The TX Daemon has terminated.
  • CASCD0114W TX Daemon rejected shutdown, number-of-regions regions are running
    The TX Daemon cannot begin a normal shutdown while there are regions running.
  • CASCD0115E TX Daemon Shutdown is already in progress
    The TX Daemon was already shutting down when this request was received.
  • CASCD0116I TX Daemon accelerating to immediate shutdown
    The TX Daemon was in a normal or orderly shutdown already, but will now shutdown immediately.
  • CASCD0117S Fatal Error function while quiescing TX Daemon, reason = errno
    A UNIX call returned with errno set to errno during quiesce of the TX Daemon.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0100I ES Threaded Daemon Initialized (version-number) process-id = pid (Time)

The TX Daemon has initialized and is waiting for work.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0101I ES Daemon Terminated

The TX Daemon has completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD0100 - CASCD0119


CASCD0102F ES Daemon failed to initialize

The TX Daemon has failed to initialize.
System Action:
The TX daemon is not started.
Resolution:
Check previous messages for cause of error, correct the problem and retry if appropriate.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0100 - CASCD0119


CASCD0103E Unknown request Request-Type received by TX Daemon

The TX Daemon has received a message with an unknown request type of Request-Type.
System Action:
The request is ignored.
Module:
cascd
Destination:
system console
Parent topic: CASCD0100 - CASCD0119


CASCD0104I ES Daemon Initialized (version-number)

The ES Daemon has initialized and is waiting for work.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0110I TX Daemon Shutdown started

The TX Daemon is beginning a normal shutdown.
System Action:
shutdown.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0111I TX Daemon is quiescing, number-of-regions regions running

The TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0112I TX Daemon Shutdown started, number-of-regions regions will be abended

The TX Daemon is beginning an immediate shutdown and will abend number-of-regions regions before shutting down.
System Action:
abend the regions then shutdown.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0113I TX Daemon Shutdown completed

The TX Daemon has terminated.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0114W TX Daemon rejected shutdown, number-of-regions regions are running

The TX 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.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0100 - CASCD0119


CASCD0115E TX Daemon Shutdown is already in progress

The TX Daemon was already shutting down when this request was received.
System Action:
Ignore the redundant shutdown request.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0100 - CASCD0119


CASCD0116I TX Daemon accelerating to immediate shutdown

The TX Daemon was in a normal or orderly shutdown already, but will now shutdown immediately.
System Action:
Immediate shutdown.
Module:
cascd
Destination:
standard error
Parent topic: CASCD0100 - CASCD0119


CASCD0117S Fatal Error function while quiescing TX Daemon, reason = errno

A UNIX call returned with errno set to errno during quiesce of the TX Daemon.

The call that failed is specified by function, where:

1 = msgget
2 = msgsnd
3 = fgets
4 = fopen
5 = mknod
System Action:
The TX Daemon continues shutdown.
Resolution:
Dependent on value of errno.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0100 - CASCD0119


CASCD0120 - CASCD0139

  • CASCD0120I Server manager created for ES region-name, process-id = pid
    The REM for region region-name has been started.
  • CASCD0121W Manager process is being re-initialized due to a change in start mode
    The manager process is being restarted with a different start mode.
  • CASCD0122E Start for region region-name rejected, TX daemon is shutting down
    An attempt was made to start a region or server when the system was shutting down.
  • CASCD0123E Start for region region-name rejected, region already running
    An attempt was made to start a region (region-name) for which a REM was already running.
  • CASCD0124E Server request for region region-name rejected, region not running
    An attempt was made to start a server for a region which is not active.
  • CASCD0125I Could not exec executable-name, reason = errno
    TX attempted to exec executable-name, but the call failed with errno errno.
  • CASCD0126I Could not create process-name, reason = errno
    TX attempted to fork a new process from the TX Daemon process but the call failed with errno errno.
  • CASCD0127I SEP server-number created for ES region-name, process-id = pid
    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 3270 printer created for server region-name, process-id = pid
    The 3270 printer service has been started for region region-name.
  • CASCD0129I 3270 CCI gateway created for region region-name, process-id = pid
    The 3270 CCI gateway service has been started for region region-name.
  • CASCD0130I Server manager region-name has terminated normally
    Region region-name has successfully completed termination.
  • CASCD0131I SEP server-number for server region-name has terminated normally
    Server server-number of region region-name has successfully completed termination.
  • CASCD0132I 3270 printer service for server region-name has terminated normally
    The 3270 printer service for region region-name has successfully completed termination.
  • CASCD0133I 3270 CCI gateway service for Region region-name has terminated normally
    The 3270 CCI gateway service for region region-name has successfully completed termination.
  • CASCD0134I Could not exec dfhgdied, reason = errno
    TX attempted to exec dfhgdied, but the call failed with errno errno.
  • CASCD0135I Could not fork process, reason = errno
    TX attempted to fork a new process from the TX Daemon process but the call failed with errno errno.
  • CASCD0136W Could not exec dfhgrtrm, reason = errno
    TX attempted to exec dfhgrtrm, but the call failed with errno errno.
  • CASCD0137W Could not exec process, reason = errno
    The TX Daemon process created a child process which could failed in initialization due to a failed 'execlp' call.
  • CASCD0138F Could not exec dfhgrtrm, reason = errno
    TX attempted to exec dfhgrtrm, but the call failed with errno errno.
  • CASCD0139I ES Daemon auto-shutdown started
    The TX Daemon was started automatically as part of region startup.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0120I Server manager created for ES region-name, process-id = pid

The REM for region region-name has been started.

It will run with a process-id of pid.

Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0121W Manager process is being re-initialized due to a change in start mode

The manager process is being restarted with a different start mode.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0122E Start for region region-name rejected, TX daemon is shutting down

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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0123E Start for region region-name rejected, region already running

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).
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0124E Server request for region region-name rejected, region not running

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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0125I Could not exec executable-name, reason = errno

TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0126I Could not create process-name, reason = errno

TX attempted to fork a new process from the TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0127I SEP server-number created for ES region-name, process-id = pid

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.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0128I 3270 printer created for server region-name, process-id = pid

The 3270 printer service has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0129I 3270 CCI gateway created for region region-name, process-id = pid

The 3270 CCI gateway service has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0130I Server manager region-name has terminated normally

Region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0131I SEP server-number for server region-name has terminated normally

Server server-number of region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0132I 3270 printer service for server region-name has terminated normally

The 3270 printer service for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0133I 3270 CCI gateway service for Region region-name has terminated normally

The 3270 CCI gateway service for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD0120 - CASCD0139


CASCD0134I Could not exec dfhgdied, reason = errno

TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0135I Could not fork process, reason = errno

TX attempted to fork a new process from the TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0136W Could not exec dfhgrtrm, reason = errno

TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0137W Could not exec process, reason = errno

The TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0138F Could not exec dfhgrtrm, reason = errno

TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0139I ES Daemon auto-shutdown started

The TX Daemon was started automatically as part of region startup.

No regions are active so the TX Daemon is automatically terminating.

System Action:
shutdown.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0120 - CASCD0139


CASCD0140 - CASCD0159

  • CASCD0141S Server manager region-name failed in initialization, exited with value exit-value
    Region region-name has failed to initialize and exited, the value specified on the exit call was exit-value.
  • CASCD0142S Server manager region-name has abended, exited with value exit-value
    Region region-name has ended abnormally with an exit call, the value specified on the exit call was exit-value.
  • CASCD0143S Server manager region-name failed in termination, exited with value exit-value
    Region region-name has ended abnormally during termination with an exit call, the value specified on the exit call was exit-value.
  • CASCD0144S SEP server-number for ES region-name exited with value exit-value
    server server-number of region region-name has failed to initialize and exited, the value specified on the exit call was exit-value.
  • CASCD0145S 3270 printer service for server region-name exited with value exit-value
    The 3270 printer service of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD0146S 3270 CCI gateway for Region region-name exited with value exit-value
    The 3270 CCI gateway of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD0151S Server manager region-name abended in initialization by signal signal-value
    Region region-name has abended during initialization due to receipt of signal signal-value.
  • CASCD0152S Server manager region-name has abended due to signal signal-value
    Region region-name has abended during normal execution due to receipt of signal signal-value.
  • CASCD0153S Server manager region-name abended in termination by signal signal-value
    Region region-name has abended during termination due to receipt of signal signal-value.
  • CASCD0154S SEP server-number for ES region-name abended by signal signal-value
    server server-number of region region-name has abended due to receipt of signal signal-value.
  • CASCD0155S 3270 printer service for server region-name abended by signal signal-value
    The 3270 printer service of region region-name has abended due to receipt of signal signal-value.
  • CASCD0156S 3270 CCI gateway for Region region-name abended by signal signal-value
    The 3270 CCI gateway of region region-name has abended due to receipt of signal signal-value.
  • CASCD0157E CCI error: CCI-error-text
    An error occurred in the CCI communications of the TX console daemon.
  • CASCD0158E CCI error CCI-error in ES console daemon
    An error occurred in the CCI communications of the TX console daemon.
  • CASCD0159F Attempt to start second TX Daemon rejected
    Only one TX Daemon is required, attempts to start more are rejected.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0141S Server manager region-name failed in initialization, exited with value exit-value

Region region-name has failed to initialize and exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0142S Server manager region-name has abended, exited with value exit-value

Region region-name has ended abnormally with an exit call, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0143S Server manager region-name failed in termination, exited with value exit-value

Region region-name has ended abnormally during termination with an exit call, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0144S SEP server-number for ES region-name exited with value exit-value

server server-number of region region-name has failed to initialize and exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0145S 3270 printer service for server region-name exited with value exit-value

The 3270 printer service of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0146S 3270 CCI gateway for Region region-name exited with value exit-value

The 3270 CCI gateway of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0151S Server manager region-name abended in initialization by signal signal-value

Region region-name has abended during initialization due to receipt of signal signal-value.
Resolution:
If the problem persists, please contact Customer Support.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0152S Server manager region-name has abended due to signal signal-value

Region region-name has abended during normal execution due to receipt of signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0153S Server manager region-name abended in termination by signal signal-value

Region region-name has abended during termination due to receipt of signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0154S SEP server-number for ES region-name abended by signal signal-value

server server-number of region region-name has abended due to receipt of signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0155S 3270 printer service for server region-name abended by signal signal-value

The 3270 printer service of region region-name has abended due to receipt of signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0156S 3270 CCI gateway for Region region-name abended by signal signal-value

The 3270 CCI gateway of region region-name has abended due to receipt of signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0140 - CASCD0159


CASCD0157E CCI error: CCI-error-text

An error occurred in the CCI communications of the TX console daemon.

CCI-error-text is returned from CCI. This message will be generated prior to message TXCD0158E for CCI error return code 9.

Module:
cascd
Destination:
Console
Parent topic: CASCD0140 - CASCD0159


CASCD0158E CCI error CCI-error in ES console daemon

An error occurred in the CCI communications of the TX 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
Module:
cascd
Destination:
Console
Parent topic: CASCD0140 - CASCD0159


CASCD0159F Attempt to start second TX Daemon rejected

Only one TX Daemon is required, attempts to start more are rejected.
System Action:
The request is rejected.
Resolution:
Terminate existing Daemon if restart is required.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0140 - CASCD0159


CASCD0160 - CASCD0179

  • CASCD0160F Attempt to start TX Daemon failed - RC: error-id
    The DosStartSession failed with the return code error-id.
  • CASCD0161I TX Daemon successfully started
    The TX Daemon has initialized and is waiting for work.
  • CASCD0162S JCP service for Region region-name abended by signal signal-value
    The journal control service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0163S TDP service for Region region-name abended by signal signal-value
    The extra partition transient data service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0164S FS service for Region region-name abended by signal signal-value
    The FS service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0165W Error creating process-name, RC = return-code
    TX attempted to create a new process from the TX Daemon process but the call failed with RC=return-code from a DosExecPgm request.
  • CASCD0166W Error creating process-name, RC = return-code
    TX attempted to create a new process from the TX Daemon process but the call failed with RC=return-code from a CreateProcess request.
  • CASCD0167I ES Daemon successfully auto-started
    The TX daemon was not active when the start region request was issued.
  • CASCD0168S Spool service for Region region-name abended by signal signal-value
    The Spool service for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0169S ES Communications Server for ES region-name abended by signal signal-value
    The CAS gateway for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0170S Unrecognized process for Region region-name abended by signal signal-value
    A process for region region-name has abended due to the unexpected signal signal-value.
  • CASCD0171S WebSphere MQ (CKTI) gateway for Region region-name abended by signal signal-value
    The WebSphere MQ gateway for region region-name has abended due to an unexpected signal signal-value.
  • CASCD0172S ES Console Process is not running in multi-threaded mode
    The ES Console Process failed because it does not have the required threading support.
  • CASCD0173S ES Console thread name Thread Create failed - RC = return-code
    The ES Console tried to start a receive-all thread.
  • CASCD0174I ES Console process termination control thread exited
    The ES Console thread that handles process terminations has exited normally.
  • CASCD0175I Dynamic Debugging port range error: error-label
    Processing of ddbg port range detected an error Verify region configuration.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD0160F Attempt to start TX Daemon failed - RC: error-id

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 cascd.exe in directory $TXDIR\lib.

System Action:
The request is rejected.
Resolution:
Correct the cause of the return code error-id.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0160 - CASCD0179


CASCD0161I TX Daemon successfully started

The TX Daemon has initialized and is waiting for work.
Module:
dfhtxs
Destination:
standard error
Parent topic: CASCD0160 - CASCD0179


CASCD0162S JCP service for Region region-name abended by signal signal-value

The journal control service for region region-name has abended due to the unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0163S TDP service for Region region-name abended by signal signal-value

The extra partition transient data service for region region-name has abended due to the unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0164S FS service for Region region-name abended by signal signal-value

The FS service for region region-name has abended due to the unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0165W Error creating process-name, RC = return-code

TX attempted to create a new process from the TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0160 - CASCD0179


CASCD0166W Error creating process-name, RC = return-code

TX attempted to create a new process from the TX 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.
Module:
cascd
Destination:
standard error and system console
Parent topic: CASCD0160 - CASCD0179


CASCD0167I ES Daemon successfully auto-started

The TX daemon was not active when the start region request was issued.

The TX daemon was automatically started.

System Action:
Start TX daemon.
Module:
dfhrem
Destination:
standard error
Parent topic: CASCD0160 - CASCD0179


CASCD0168S Spool service for Region region-name abended by signal signal-value

The Spool service for region region-name has abended due to the unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0169S ES Communications Server for ES region-name abended by signal signal-value

The CAS gateway for region region-name has abended due to the unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0170S Unrecognized process for Region region-name abended by signal signal-value

A process for region region-name has abended due to the unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0171S WebSphere MQ (CKTI) gateway for Region region-name abended by signal signal-value

The WebSphere MQ gateway for region region-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0172S ES Console Process is not running in multi-threaded mode

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.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0173S ES Console thread name Thread Create failed - RC = return-code

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 none.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0174I ES Console process termination control thread exited

The ES Console thread that handles process terminations has exited normally.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD0175I Dynamic Debugging port range error: error-label

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.
Module:
cascd
Destination:
system console
Parent topic: CASCD0160 - CASCD0179


CASCD1000 - CASCD1019

  • CASCD1001S Error locating region directory for region region-name
    An error occurred locating the region directory for region region-name.
  • CASCD1002S Error locating region files directory
    An error occurred locating the target directory for the region work files.
  • CASCD1003S Error locating system files directory
    An error occurred locating the target directory for the system work files.
  • CASCD1004S Error setting process environment variables, reason reason-code
    An error occurred setting up the environment variables for the region.
  • CASCD1005I path-to-console-log
    Region is starting.
  • CASCD1010S Error while processing global configuration file
    An error occurred whilst processing the global configuration file.
  • CASCD1011S Error while processing region configuration file for region region-name
    An error occurred while processing the region configuration file.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1001S Error locating region directory for region region-name

An error occurred locating the region directory for region region-name.

Either the region is not defined or environment variable TXDIR is pointing to the wrong place.

System Action:
The region start request is not processed.
Resolution:
Correct the setting of TXDIR, correct region-name, or define the region.
Module:
dfhrem
Destination:
standard out
Parent topic: CASCD1000 - CASCD1019


CASCD1002S Error locating region files directory

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.
Module:
dfhrem
Destination:
standard out
Parent topic: CASCD1000 - CASCD1019


CASCD1003S Error locating system files directory

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.
Module:
dfhrem
Destination:
standard out
Parent topic: CASCD1000 - CASCD1019


CASCD1004S Error setting process environment variables, reason reason-code

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.
Module:
dfhrem
Destination:
standard out
Parent topic: CASCD1000 - CASCD1019


CASCD1005I path-to-console-log

Region is starting.

The console log is located at the displayed path.

System Action:
The region startup proceeds.
Module:
casstart
Destination:
standard out
Parent topic: CASCD1000 - CASCD1019


CASCD1010S Error while processing global configuration file

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.
Module:
dfhrem
Destination:
Console
Parent topic: CASCD1000 - CASCD1019


CASCD1011S Error while processing region configuration file for region region-name

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.
Module:
dfhrem
Destination:
Console
Parent topic: CASCD1000 - CASCD1019


CASCD1020 - CASCD1039

  • CASCD1020I JCP service process created for region region-name, process-id = pid
    The JCP service has been started for region region-name.
  • CASCD1021I Journal process for server region-name has terminated normally
    The JCP service process for region region-name has successfully completed termination.
  • CASCD1022S Journal process for server region-name exited with value exit-value
    The JCP service process of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1023I Extra-Partition TD (TDP) service created, server region-name, process-id = pid
    The TDP service has been started for region region-name.
  • CASCD1024I TDP service process for server region-name has terminated normally
    The Extra-Partition TD service process for region region-name has successfully completed termination.
  • CASCD1025S TDP service process for server region-name exited with value exit-value
    The Extra-Partition TD service process of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1026I Fileshare service process created, server region-name, process-id = pid
    The Fileshare service has been started for region region-name.
  • CASCD1027I Fileshare service process for server region-name has terminated normally
    The Fileshare service process for region region-name has successfully completed termination.
  • CASCD1028S Fileshare service process for server region-name exited with value exit-value
    The Fileshare service process of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1029I 3270 terminal created, region region-name, process-id = pid
    A 3270 terminal has been started for region region-name.
  • CASCD1030I ODBC service process for Region region-name has terminated normally
    The ODBC service process for region region-name has successfully completed termination.
  • CASCD1031S ODBC service process for Region region-name exited with value exit-value
    The ODBC service process of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1032I WebSphere MQ gateway (CKTI) created, server region-name, process-id = pid
    A WebSphere MQ Gateway has been started for region region-name.
  • CASCD1033I WebSphere MQ gateway (CKTI) for server region-name has terminated normally
    The WebSphere MQ Gateway service process for region region-name has successfully completed termination.
  • CASCD1034S WebSphere MQ gateway (CKTI) for server region-name exited with value exit-value
    The WebSphere MQ Gateway process of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1035I Spool service created, region region-name, process-id = pid
    A Spool service has been started for region region-name.
  • CASCD1036I Spool service for Region region-name has terminated normally
    The Spool service process for region region-name has successfully completed termination.
  • CASCD1037S Spool service for Region region-name exited with value exit-value
    The Spool service of region region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1038I ES Communications Server created, ES region-name, process-id = pid
    An ES Communications Server has been started for ES region-name.
  • CASCD1039I ES Communications Server for ES region-name has terminated normally
    The ES Communications Server process for ES region-name has successfully completed termination.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1020I JCP service process created for region region-name, process-id = pid

The JCP service has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1021I Journal process for server region-name has terminated normally

The JCP service process for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1022S Journal process for server region-name exited with value exit-value

The JCP service process of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1023I Extra-Partition TD (TDP) service created, server region-name, process-id = pid

The TDP service has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1024I TDP service process for server region-name has terminated normally

The Extra-Partition TD service process for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1025S TDP service process for server region-name exited with value exit-value

The Extra-Partition TD service process of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1026I Fileshare service process created, server region-name, process-id = pid

The Fileshare service has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1027I Fileshare service process for server region-name has terminated normally

The Fileshare service process for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1028S Fileshare service process for server region-name exited with value exit-value

The Fileshare service process of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1029I 3270 terminal created, region region-name, process-id = pid

A 3270 terminal has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1030I ODBC service process for Region region-name has terminated normally

The ODBC service process for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1031S ODBC service process for Region region-name exited with value exit-value

The ODBC service process of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1032I WebSphere MQ gateway (CKTI) created, server region-name, process-id = pid

A WebSphere MQ Gateway has been started for region region-name.

This gateway emulates the CKTI trigger monitor transaction.

Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1033I WebSphere MQ gateway (CKTI) for server region-name has terminated normally

The WebSphere MQ Gateway service process for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1034S WebSphere MQ gateway (CKTI) for server region-name exited with value exit-value

The WebSphere MQ Gateway process of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1035I Spool service created, region region-name, process-id = pid

A Spool service has been started for region region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1036I Spool service for Region region-name has terminated normally

The Spool service process for region region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1037S Spool service for Region region-name exited with value exit-value

The Spool service of region region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1038I ES Communications Server created, ES region-name, process-id = pid

An ES Communications Server has been started for ES region-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1039I ES Communications Server for ES region-name has terminated normally

The ES Communications Server process for ES region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1020 - CASCD1039


CASCD1040 - CASCD1059

  • CASCD1040S ES Communications Server for ES region-name exited with value exit-value
    The ES Communication Server of ES region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1041S ES Unknown process death reported
    The ES Console was notified of a process death that it did not know about.
  • CASCD1042I IMS TM Control Process created for Server server-name, process-id = pid
    The IMS TM Control Process has been started for Server server-name.
  • CASCD1043I IMS DB Control Process created for Server server-name, process-id = pid
    The IMS DB Control Process has been started for Server server-name.
  • CASCD1044I IMS DB Control Process for Server server-name has terminated normally
    The IMS DB Control Process for Server server-name has successfully completed termination.
  • CASCD1045S IMS DB Control Process for Server server-name exited with value exit-value
    The IMS DB Control Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1046S IMS TM Control Process for Server server-name abended by signal signal-value
    The IMS TM Control Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1047S IMS DB Control Process for Server server-name abended by signal signal-value
    The IMS TM Control Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1048I IMS TM Control Process for Server region-name has terminated normally
    The IMS TM Control Process for Server region-name has successfully completed termination.
  • CASCD1049S IMS TM Control Process for Server region-name exited with value exit-value
    The IMS TM Control Process for Server region-name has exited, the value specified on the exit call was exit-value.
  • CASCD1050I IMS MPR Process for Server server-name has terminated normally
    An IMS MPR Process for Server server-name has successfully completed termination.
  • CASCD1051S IMS MPR Process for Server server-name exited with value exit-value
    An IMS MPR Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1052I JES Initiator for Server server-name has terminated normally
    A JES Initiator for server server-name has successfully completed termination.
  • CASCD1053S JES Initiator for Server server-name exited with value exit-value
    A JES Initiator for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1054I JES Printer for Server server-name has terminated normally
    A JES Printer for Server server-name has successfully completed termination.
  • CASCD1055S JES Printer for Server server-name exited with value exit-value
    A JES Printer for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1056S IMS MPR Process for Server server-name abended by signal signal-value
    An IMS MPR process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1057S JES Initiator for Server server-name abended by signal signal-value
    A JES Initiator for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1058S JES Printer for Server server-name abended by signal signal-value
    A JES Printer for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1059I IMS MPR Process created for server server-name, process-id = pid
    An IMS MPR Process has been started for Server server-name.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1040S ES Communications Server for ES region-name exited with value exit-value

The ES Communication Server of ES region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1041S ES Unknown process death reported

The ES Console was notified of a process death that it did not know about.

This should not occur.

Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1042I IMS TM Control Process created for Server server-name, process-id = pid

The IMS TM Control Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1043I IMS DB Control Process created for Server server-name, process-id = pid

The IMS DB Control Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1044I IMS DB Control Process for Server server-name has terminated normally

The IMS DB Control Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1045S IMS DB Control Process for Server server-name exited with value exit-value

The IMS DB Control Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1046S IMS TM Control Process for Server server-name abended by signal signal-value

The IMS TM Control Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1047S IMS DB Control Process for Server server-name abended by signal signal-value

The IMS TM Control Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1048I IMS TM Control Process for Server region-name has terminated normally

The IMS TM Control Process for Server region-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1049S IMS TM Control Process for Server region-name exited with value exit-value

The IMS TM Control Process for Server region-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1050I IMS MPR Process for Server server-name has terminated normally

An IMS MPR Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1051S IMS MPR Process for Server server-name exited with value exit-value

An IMS MPR Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1052I JES Initiator for Server server-name has terminated normally

A JES Initiator for server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1053S JES Initiator for Server server-name exited with value exit-value

A JES Initiator for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1054I JES Printer for Server server-name has terminated normally

A JES Printer for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1055S JES Printer for Server server-name exited with value exit-value

A JES Printer for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1056S IMS MPR Process for Server server-name abended by signal signal-value

An IMS MPR process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1057S JES Initiator for Server server-name abended by signal signal-value

A JES Initiator for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1058S JES Printer for Server server-name abended by signal signal-value

A JES Printer for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1059I IMS MPR Process created for server server-name, process-id = pid

An IMS MPR Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1040 - CASCD1059


CASCD1060 - CASCD1079

  • CASCD1060I JES Initiator created for Server server-name, process-id = pid
    An JES Initiator Process has been started for Server server-name.
  • CASCD1061S Undefined create request for Server server-name, process-id = pid
    An undefined process request was received for Server server-name.
  • CASCD1062I JES Printer created for Server server-name, process-id = pid
    A JES Printer Process has been started for Server server-name.
  • CASCD1063I Event Manager created for Server server-name, process-id = pid
    An Event Manager Process has been started for Server server-name.
  • CASCD1064I Event Manager for Server server-name has terminated normally
    An Event Manager for Server server-name has successfully completed termination.
  • CASCD1065S Event Manager for Server server-name exited with value exit-value
    An Event Manager for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1066S Event Manager for Server server-name abended by signal signal-value
    An Event Manager for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1067I cobdebugremote process created for Server server-name, process-id = pid
    A cobdebugremote process has been started for Server server-name.
  • CASCD1068I cobdebugremote process for Server server-name has terminated normally
    A cobdebugremote process for Server server-name has successfully terminated.
  • CASCD1069S cobdebugremote process for Server server-name exited with value exit-value
    A cobdebugremote process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1070S 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.
  • CASCD1071I Administration SEP created for Server server-name, process-id = pid
    An administration SEP has been started for Server server-name.
  • CASCD1072I Administration SEP for Server server-name has terminated normally
    An administration SEP has been started for Server server-name has successfully completed termination.
  • CASCD1073S Administration SEP for Server server-name exited with value exit-value
    An administration SEP for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1074S Administration SEP for Server server-name abended by signal signal-value
    An administration SEP for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1075I ES TSC Service Process created for Server server-name, process-id = pid
    The ES TSC Service Process has been started for Server server-name.
  • CASCD1076I ES TSC Service Process for Region server-name has terminated normally
    The ES TSC Service Process for Server server-name has successfully completed termination.
  • CASCD1077S ES TSC Service Process for Region server-name exited with value exit-value
    The ES TSC Service Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1078S ES TSC Service Process for Region server-name abended by signal signal-value
    The ES TSC Service Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1079I Cobremotedaemon process created for Server server-name, process-id = pid
    A Cobremotedaemon process has been started for Server server-name.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1060I JES Initiator created for Server server-name, process-id = pid

An JES Initiator Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1061S Undefined create request for Server server-name, process-id = pid

An undefined process request was received for Server server-name.
System Action:
Continue.
Resolution:
Evaluate the impact of the error and take appropriate action.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD1060 - CASCD1079


CASCD1062I JES Printer created for Server server-name, process-id = pid

A JES Printer Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1063I Event Manager created for Server server-name, process-id = pid

An Event Manager Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1064I Event Manager for Server server-name has terminated normally

An Event Manager for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1065S Event Manager for Server server-name exited with value exit-value

An Event Manager for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1066S Event Manager for Server server-name abended by signal signal-value

An Event Manager for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1067I 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: CASCD1060 - CASCD1079


CASCD1068I cobdebugremote process for Server server-name has terminated normally

A cobdebugremote process for Server server-name has successfully terminated.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1069S cobdebugremote process for Server server-name exited with value exit-value

A 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: CASCD1060 - CASCD1079


CASCD1070S 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: CASCD1060 - CASCD1079


CASCD1071I Administration SEP created for Server server-name, process-id = pid

An administration SEP has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1072I Administration SEP for Server server-name has terminated normally

An administration SEP has been started for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1073S Administration SEP for Server server-name exited with value exit-value

An administration SEP for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1074S Administration SEP for Server server-name abended by signal signal-value

An administration SEP for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1075I ES TSC Service Process created for Server server-name, process-id = pid

The ES TSC Service Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1076I ES TSC Service Process for Region server-name has terminated normally

The ES TSC Service Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1077S ES TSC Service Process for Region server-name exited with value exit-value

The ES TSC Service Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1078S ES TSC Service Process for Region server-name abended by signal signal-value

The ES TSC Service Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1079I Cobremotedaemon process created for Server server-name, process-id = pid

A Cobremotedaemon process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1060 - CASCD1079


CASCD1080 - CASCD1099

  • CASCD1080I Cobremotedaemon process for Server server-name has terminated normally
    A Cobremotedaemon process for Server server-name has successfully terminated.
  • CASCD1081S Cobremotedaemon process for Server server-name exited with value exit-value
    A Cobremotedaemon process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1082S Cobremotedaemon process for Server server-name abended by signal signal-value
    A Cobremotedaemon process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1083I Debug SEP created for Server server-name, process-id = pid
    A debug SEP has been created.
  • CASCD1084I Debug SEP for Server server-name has terminated normally
    A Debug SEP for Server server-name has successfully completed termination.
  • CASCD1085S Debug SEP for Server server-name exited with value exit-value
    A Debug SEP for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1086S Debug SEP for Server server-name abended by signal signal-value
    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
    A Cobdebugremote process for Server server-name has successfully terminated.
  • CASCD1090S Cobdebugremote process for Server server-name exited with value exit-value
    A Cobdebugremote process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1095I ES TRC Service Process created for Server server-name, process-id = pid
    The ES TRC Service Process has been started for Server server-name.
  • CASCD1096I ES TRC Service Process for Region server-name has terminated normally
    The ES TRC Service Process for Server server-name has successfully completed termination.
  • CASCD1097S ES TRC Service Process for Region server-name exited with value exit-value
    The ES TRC Service Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1098S ES TRC Service Process for Region server-name abended by signal signal-value
    The ES TRC Service Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1099I Dynamic CTF updated with option "As on file, All Off, All On" using config file CTF config filename
    The CTF configuration file has been applied to the current region with the requested options.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1080I Cobremotedaemon process for Server server-name has terminated normally

A Cobremotedaemon process for Server server-name has successfully terminated.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1081S Cobremotedaemon process for Server server-name exited with value exit-value

A Cobremotedaemon process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1082S Cobremotedaemon process for Server server-name abended by signal signal-value

A Cobremotedaemon process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1083I Debug SEP created for Server server-name, process-id = pid

A debug SEP has been created.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1084I Debug SEP for Server server-name has terminated normally

A Debug SEP for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1085S Debug SEP for Server server-name exited with value exit-value

A Debug SEP for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1086S Debug SEP for Server server-name abended by signal signal-value

A Debug SEP for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


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: CASCD1080 - CASCD1099


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: CASCD1080 - CASCD1099


CASCD1089I Cobdebugremote process for Server server-name has terminated normally

A Cobdebugremote process for Server server-name has successfully terminated.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1090S Cobdebugremote process for Server server-name exited with value exit-value

A 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: CASCD1080 - CASCD1099


CASCD1095I ES TRC Service Process created for Server server-name, process-id = pid

The ES TRC Service Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1096I ES TRC Service Process for Region server-name has terminated normally

The ES TRC Service Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1097S ES TRC Service Process for Region server-name exited with value exit-value

The ES TRC Service Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1098S ES TRC Service Process for Region server-name abended by signal signal-value

The ES TRC Service Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1099I Dynamic CTF updated with option "As on file, All Off, All On" using config file CTF config filename

The CTF configuration file has been applied to the current region with the requested options.
Module:
cascd
Destination:
system console
Parent topic: CASCD1080 - CASCD1099


CASCD1100 - CASCD1119

  • CASCD1105I ES MQB Service Process created for Server server-name, process-id = pid
    The ES MQB Service Process has been started for Server server-name.
  • CASCD1106I ES MQB Service Process for Region server-name has terminated normally
    The ES MQB Service Process for Server server-name has successfully completed termination.
  • CASCD1107S ES MQB Service Process for Region server-name exited with value exit-value
    The ES MQB Service Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1108S ES MQB Service Process for Region server-name abended by signal signal-value
    The ES MQB Service Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1109I ES SNA Communications Process created for Server server-name, process-id = pid
    The ES SNA Communications Process has been started for Server server-name.
  • CASCD1110I ES SNA Communications Process for Region server-name has terminated normally
    The ES SNA Communications Process for Server server-name has successfully completed termination.
  • CASCD1111S ES SNA Communications Process for Region server-name exited with value exit-value
    The ES SNA Communications Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1112S ES SNA Communications Process for Region server-name abended by signal signal-value
    The ES SNA Communications Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1113I ES RAS Process created for Server server-name, process-id = pid
    The ES RAS Process has been started for Server server-name.
  • CASCD1114I ES RAS Process for Region server-name has terminated normally
    The ES RAS Process for Server server-name has successfully completed termination.
  • CASCD1115S ES RAS Process for Region server-name exited with value exit-value
    The ES RAS Process for Server server-name has exited, the value specified on the exit call was exit-value.
  • CASCD1116S ES RAS Process for Region server-name abended by signal signal-value
    The ES RAS Process for Server server-name has abended due to an unexpected signal signal-value.
  • CASCD1117I Enterprise Server time keeper daemon created for Server server-name, process-id = pid
    A time keeper daemon process has been started for Server server-name.
  • CASCD1118I Enterprise Server time keeper daemon for Server server-name has terminated normally.
    The time keeper daemon process has successfully completed termination.
  • CASCD1119S Enterprise Server time keeper daemon for Server server-name abended by signal signal-value
    The time keeper daemon process for Server server-name has abended due to an unexpected signal signal-value.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1105I ES MQB Service Process created for Server server-name, process-id = pid

The ES MQB Service Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1106I ES MQB Service Process for Region server-name has terminated normally

The ES MQB Service Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1107S ES MQB Service Process for Region server-name exited with value exit-value

The ES MQB Service Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1108S ES MQB Service Process for Region server-name abended by signal signal-value

The ES MQB Service Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1109I ES SNA Communications Process created for Server server-name, process-id = pid

The ES SNA Communications Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1110I ES SNA Communications Process for Region server-name has terminated normally

The ES SNA Communications Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1111S ES SNA Communications Process for Region server-name exited with value exit-value

The ES SNA Communications Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1112S ES SNA Communications Process for Region server-name abended by signal signal-value

The ES SNA Communications Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1113I ES RAS Process created for Server server-name, process-id = pid

The ES RAS Process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1114I ES RAS Process for Region server-name has terminated normally

The ES RAS Process for Server server-name has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1115S ES RAS Process for Region server-name exited with value exit-value

The ES RAS Process for Server server-name has exited, the value specified on the exit call was exit-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1116S ES RAS Process for Region server-name abended by signal signal-value

The ES RAS Process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1117I Enterprise Server time keeper daemon created for Server server-name, process-id = pid

A time keeper daemon process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1118I Enterprise Server time keeper daemon for Server server-name has terminated normally.

The time keeper daemon process has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1119S Enterprise Server time keeper daemon for Server server-name abended by signal signal-value

The time keeper daemon process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1100 - CASCD1119


CASCD1120 - CASCD1139

  • CASCD1120I Enterprise Server recovery MFDBFH daemon created for Server server-name, process-id = pid
    A recovery MFDBFH daemon process has been started for Server server-name.
  • CASCD1121I Enterprise Server recovery MFDBFH daemon for Server server-name has terminated normally.
    The recovery MFDBFH daemon process has successfully completed termination.
  • CASCD1122S Enterprise Server recovery MFDBFH daemon for Server server-name abended by signal signal-value
    The recovery MFDBFH daemon process for Server server-name has abended due to an unexpected signal signal-value.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1120I Enterprise Server recovery MFDBFH daemon created for Server server-name, process-id = pid

A recovery MFDBFH daemon process has been started for Server server-name.
Module:
cascd
Destination:
system console
Parent topic: CASCD1120 - CASCD1139


CASCD1121I Enterprise Server recovery MFDBFH daemon for Server server-name has terminated normally.

The recovery MFDBFH daemon process has successfully completed termination.
Module:
cascd
Destination:
system console
Parent topic: CASCD1120 - CASCD1139


CASCD1122S Enterprise Server recovery MFDBFH daemon for Server server-name abended by signal signal-value

The recovery MFDBFH daemon process for Server server-name has abended due to an unexpected signal signal-value.
Module:
cascd
Destination:
system console
Parent topic: CASCD1120 - CASCD1139


CASCD1200 - CASCD1219

  • CASCD1200I Transaction transaction-id terminated without issuing SPOOLCLOSE for token token
    The transaction transaction-id issued a SPOOLOPEN command but did not issue a subsequent SPOOLCLOSE command before transaction termination.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD1200I Transaction transaction-id terminated without issuing SPOOLCLOSE for token token

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:
Code a SPOOLCLOSE command to avoid tying up system resources.
Module:
dfhesysp
Destination:
Console
Parent topic: CASCD1200 - CASCD1219


CASCD4000 - CASCD4019

  • CASCD4002W Error (error-message) binding to MFDS
    An error occurred whilst binding to the MF Directory Server.
  • CASCD4003W Error (error-message) retrieving ES configuration from MFDS
    An error occurred whilst retrieving the ES configuration from the MF Directory Server.
  • CASCD4004W Error binding to MFDS, unable to load support module
    An error occurred whilst binding to the MF Directory Server.
  • CASCD4005I Windows event logging enabled
    Messages to CAS Deamon will be logged to the windows event log.
  • CASCD4006I Windows event logging disabled
    Messages to CAS Deamon will not be logged to the windows event log.
  • CASCD4007E Windows event logging error RC= return-code
    Error return-code when trying to log to the windows event log.
  • CASCD4008E PAC could not be started, please check console.log
    When trying to start the PAC, the region died.
  • CASCD4009E MFDBFH could not recover Region database or datastore url, RC return code.
    A call to MFDBFH recover the datastores failed.
  • CASCD4010F Unexpected failure creating configuration file Configuration file name, reason = RC1,RC2
    ES failed to create the configuration file The COBOL file status after failure is RC1,RC2.
  • CASCD4011F Memory allocation error reason = RC1
    ES failed to allocate memory to create the configuration file The allocation error returns is RC1.
  • CASCD4012W Region was not stopped properly, recovering previous region UUID UUID
    The region was not stopped properly, and previous UUID needs to be recovered.
  • CASCD4013I Previous region UUID UUID recovered
    ES attempted to recover the region from a previous run that did not shutdown the region properly.
  • CASCD4014I UUID recovery file log UUID recovery file log
    The log file of the recovery.
  • CASCD4015F Previous region UUID UUID recovery failed RC RC
    ES attempted to recover the region from a previous run that did not shutdown the region properly and failed.
  • CASCD4016E Failed to start Configuration Manager, RC=RC
    Error occurred during Configuration Manager setup.
  • CASCD4017E PAC seems to be in an invalid state, check the PAC status using caspac -aStatus command
    When trying to stop the PAC, the necessary keys were not found in the PSOR CasPAC store.
  • CASCD4018S Error initializing PAC support, RC=RC
    Error occurred during PAC setup.
  • CASCD4019S Region can not be started as the PAC failed to initialize properly
    The PAC failed to start, check the region console.log that started the PAC cold or in upgrade mode.
Parent topic: CASCD - CICS Console Daemon Error Messages


CASCD4002W Error (error-message) binding to MFDS

An error occurred whilst binding to the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4003W Error (error-message) retrieving ES configuration from MFDS

An error occurred whilst retrieving the ES configuration from the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4004W Error binding to MFDS, unable to load support module

An error occurred whilst binding to the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4005I Windows event logging enabled

Messages to CAS Deamon will be logged to the windows event log.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4006I Windows event logging disabled

Messages to CAS Deamon will not be logged to the windows event log.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4007E Windows event logging error RC= return-code

Error return-code when trying to log to the windows event log.
Resolution:
Report the error to Micro Focus Customer Support.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4008E PAC could not be started, please check console.log

When trying to start the PAC, the region died.
Resolution:
Report the error to Micro Focus Customer Support.
Module:
cascd
Destination:
Console and standard error
Parent topic: CASCD4000 - CASCD4019


CASCD4009E MFDBFH could not recover Region database or datastore url, RC return code.

A call to MFDBFH recover the datastores failed.
Resolution:
Recover using DBFHADMIN command, the issue might be a lost connection to the database.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4010F Unexpected failure creating configuration file Configuration file name, reason = RC1,RC2

ES failed to create the configuration file The COBOL file status after failure is RC1,RC2.
System Action:
The TX Daemon is not started.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4011F Memory allocation error reason = RC1

ES failed to allocate memory to create the configuration file The allocation error returns is RC1.
System Action:
The TX Daemon is not started.
Resolution:
Determine the cause of the error and retry if appropriate.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4012W Region was not stopped properly, recovering previous region UUID UUID

The region was not stopped properly, and previous UUID needs to be recovered.
System Action:
The TX Daemon is trying to recover.
Resolution:
Determine why the region was not stopped properly.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4013I Previous region UUID UUID recovered

ES attempted to recover the region from a previous run that did not shutdown the region properly.
System Action:
The TX Daemon invoked the command caspac -aRecoverUUID.
Resolution:
Recovery was succesful.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4014I UUID recovery file log UUID recovery file log

The log file of the recovery.
System Action:
The TX Daemon invoked the command caspac -aRecoverUUID.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4015F Previous region UUID UUID recovery failed RC RC

ES attempted to recover the region from a previous run that did not shutdown the region properly and failed.
System Action:
The TX Daemon invoked the command caspac -aRecoverUUID.
Resolution:
Recovery was not successful, please check with technical support.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4016E Failed to start Configuration Manager, RC=RC

Error occurred during Configuration Manager setup.
System Action:
Continue initialization without Configuration Manager.
Resolution:
Contact support.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4017E PAC seems to be in an invalid state, check the PAC status using caspac -aStatus command

When trying to stop the PAC, the necessary keys were not found in the PSOR CasPAC store.
Resolution:
Check the status of the PAC using caspac -aStatus command.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4018S Error initializing PAC support, RC=RC

Error occurred during PAC setup.
System Action:
The TX Daemon is not started.
Resolution:
Contact support.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCD4019S Region can not be started as the PAC failed to initialize properly

The PAC failed to start, check the region console.log that started the PAC cold or in upgrade mode.
System Action:
The TX Daemon is not started.
Resolution:
Contact support.
Module:
cascd
Destination:
System Console
Parent topic: CASCD4000 - CASCD4019


CASCF - CICS Configuration Support Error Messages

  • CASCF0000 - CASCF0019
  • CASCF0020 - CASCF0039
  • CASCF0040 - CASCF0059
  • CASCF0060 - CASCF0079
Parent topic: Enterprise Server Error Messages


CASCF0000 - CASCF0019

  • CASCF0001F Error Processing Global Configuration, reason = RC-1,RC-2
    An error has occurred during Region configuration file processing Refer to TXCF0002F for the possible values of RC-1 and RC-2.
  • CASCF0002F Error Processing Region Configuration, reason = error-type,error-qualifier
    An error has occurred during Region configuration file processing.
  • CASCF0003F config-module: Error loading messaging support module
    The messaging support module could not be loaded as part of system initialization.
  • CASCF0004F config-module: Error loading configuration support module
    The configuration support module could not be loaded as part of system initialization.
  • CASCF0005F config-module: Error loading utility support module
    The utility support module could not be loaded as part of system initialization.
  • CASCF0006F config-module: Error loading file handling support module
    The file handling support module could not be loaded as part of system initialization.
  • CASCF0007F config-module: Error loading file handling support module
    The file handling support module could not be loaded as part of system initialization.
  • CASCF0008F config-module: Unexpected error processing configuration file, RC=return-code
    An unexpected error occurred in system initialization while processing the configuration file.
  • CASCF0010S config-module: Unrecognized line in global configuration file, line = line-number
    An unrecognized line was found in the global configuration file ($TXDIR/dfhtx.cfg) at the line shown.
  • CASCF0011S config-module: Unrecognized line in region (region-name) configuration file, line = line-number
    An unrecognized line was found in the region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg) at the line shown.
  • CASCF0012S config-module: Unrecognized line in development configuration file, line = line-number
    An unrecognized line was found in the development configuration file (dfhtxdev.cfg) at the line shown.
  • CASCF0013S config-module: Can not find global configuration file
    The global configuration file ($TXDIR/dfhtx.cfg) could not located.
  • CASCF0014S config-module: Can not find region (region-name) configuration file
    The region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg) could not be located.
  • CASCF0015S config-module: Can not find development configuration file
    The development configuration file (dfhtxdev.cfg) could not be located.
  • CASCF0016S config-module: Can not find global configuration save file
    The global configuration save file ($TXDIR/gcf.bin) could not located.
  • CASCF0017S config-module: Can not find region configuration (region-name) save file
    The region configuration save file ($REGIONBASE/$TXREGN/rcf.bin) could not be located.
  • CASCF0018S config-module: Can not find development configuration save file
    The development configuration file (dcf.bin) could not be located.
  • CASCF0019S config-module: Error creating global configuration save file, RC = return-code
    An error occurred when creating the global configuration save file (gcf.bin).
Parent topic: CASCF - CICS Configuration Support Error Messages


CASCF0001F Error Processing Global Configuration, reason = RC-1,RC-2

An error has occurred during Region configuration file processing Refer to TXCF0002F 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.
Module:
dfh0cfg
Destination:
standard error and/or system console
Parent topic: CASCF0000 - CASCF0019


CASCF0002F Error Processing Region Configuration, reason = error-type,error-qualifier

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.
Module:
dfh0cfg
Destination:
Standard error and/or system console
Parent topic: CASCF0000 - CASCF0019


CASCF0003F config-module: Error loading messaging support module

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 $TXDIR is set correctly and the module "dfh0msg" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0004F config-module: Error loading configuration support module

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 $TXDIR is set correctly and the module "dfh0cfg" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0005F config-module: Error loading utility support module

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 $TXDIR is set correctly and the module(s) "dfh0utl?" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0006F config-module: Error loading file handling support module

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 $TXDIR is set correctly and the module "dfhextfh" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0007F config-module: Error loading file handling support module

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 $TXDIR is set correctly and the module "mffh" exists in $COBDIR.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0008F config-module: Unexpected error processing configuration file, RC=return-code

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  - TXLOCAL invalid
     09  - TXDIR 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.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0010S config-module: Unrecognized line in global configuration file, line = line-number

An unrecognized line was found in the global configuration file ($TXDIR/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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0011S config-module: Unrecognized line in region (region-name) configuration file, line = line-number

An unrecognized line was found in the region configuration file ($REGIONBASE/$TXREGN/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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0012S config-module: Unrecognized line in development configuration file, line = line-number

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0013S config-module: Can not find global configuration file

The global configuration file ($TXDIR/dfhtx.cfg) could not located.
System Action:
Terminate the requesting process.
Resolution:
Make sure that $TXDIR is set correctly and that the configuration file exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0014S config-module: Can not find region (region-name) configuration file

The region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg) could not be located.
System Action:
Terminate the requesting process.
Resolution:
Make sure that $TXDIR is set correctly and that the configuration file exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0015S config-module: Can not find development configuration file

The development configuration file (dfhtxdev.cfg) could not be located.
System Action:
Terminate the requesting process.
Resolution:
Make sure that $TXDIR is set correctly and that the configuration file exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0016S config-module: Can not find global configuration save file

The global configuration save file ($TXDIR/gcf.bin) could not located.
System Action:
Terminate the requesting process.
Resolution:
Make sure that $TXDIR is set correctly and that the configuration file exists. If you are using $TXLOCAL make sure that it is set correctly.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0017S config-module: Can not find region configuration (region-name) save file

The region configuration save file ($REGIONBASE/$TXREGN/rcf.bin) could not be located.
System Action:
Terminate the requesting process.
Resolution:
Make sure that $TXDIR is set correctly and a multi-tasking region is running.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0018S config-module: Can not find development configuration save file

The development configuration file (dcf.bin) could not be located.
System Action:
Terminate the requesting process.
Resolution:
Make sure that $TXDIR is set correctly and that the configuration file exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0019S config-module: Error creating global configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0000 - CASCF0019


CASCF0020 - CASCF0039

  • CASCF0020S config-module: Error creating region (region-name) configuration save file, RC = return-code
    An error occurred when creating the region configuration save file (rcf.bin).
  • CASCF0021S config-module: Error creating development configuration save file, RC = return-code
    An error occurred when creating the development configuration save file (dcf.bin).
  • CASCF0022S config-module: Error opening global configuration save file, RC = return-code
    An error occurred when opening the global configuration save file (gcf.bin).
  • CASCF0023S config-module: Error opening region (region-name) configuration save file, RC = return-code
    An error occurred when opening the region configuration save file (rcf.bin).
  • CASCF0024S config-module: Error opening development configuration save file, RC = return-code
    An error occurred when opening the development configuration save file (dcf.bin).
  • CASCF0025S config-module: Error opening global configuration file, RC = return-code
    An error occurred when opening the global configuration file ($TXDIR/dfhtx.cfg).
  • CASCF0026S config-module: Error opening region (region-name) configuration file, RC = return-code
    An error occurred when opening the region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg).
  • CASCF0027S config-module: Error opening development configuration file, RC = return-code
    An error occurred when opening the development configuration file (dfhtxdev.cfg).
  • CASCF0028S config-module: Error reading global configuration save file, RC = return-code
    An error occurred when reading the global configuration save file (gcf.bin).
  • CASCF0029S config-module: Error reading region (region-name) configuration save file, RC = return-code
    An error occurred when reading the region configuration save file (rcf.bin).
  • CASCF0030S config-module: Error reading development configuration save file, RC = return-code
    An error occurred when reading the development configuration save file (dcf.bin).
  • CASCF0031S config-module: Error reading global configuration file, RC = return-code
    An error occurred when reading the global configuration file ($TXDIR/dfhtx.cfg).
  • CASCF0032S config-module: Error reading region (region-name) configuration file, RC = region-name
    An error occurred when opening the region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg).
  • CASCF0033S config-module: Error reading development configuration file, RC = return-code
    An error occurred when opening the development configuration file (dfhtxdev.cfg).
  • CASCF0034S config-module: Error writing global configuration save file, RC = return-code
    An error occurred when writing the global configuration save file (gcf.bin).
  • CASCF0035S config-module: Error writing region (region-name) configuration save file, RC = return-code
    An error occurred when writing the region configuration save file (rcf.bin).
  • CASCF0036S config-module: Error writing development configuration save file, RC = return-code
    An error occurred when writing the development configuration save file (dcf.bin).
  • CASCF0037S config-module: Configuration error, TXLOCAL invalid
    The directory specified by the TXLOCAL environment variable is invalid.
  • CASCF0038S config-module: Configuration error, TXDIR invalid
    The directory specified by the TXDIR environment variable is invalid.
  • CASCF0039S config-module: Configuration error, region (region-name) files directory invalid
    The region file directory ($REGIONBASE/$TXREGN/files/reg) is invalid.
Parent topic: CASCF - CICS Configuration Support Error Messages


CASCF0020S config-module: Error creating region (region-name) configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0021S config-module: Error creating development configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0022S config-module: Error opening global configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0023S config-module: Error opening region (region-name) configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0024S config-module: Error opening development configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0025S config-module: Error opening global configuration file, RC = return-code

An error occurred when opening the global configuration file ($TXDIR/dfhtx.cfg).
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0026S config-module: Error opening region (region-name) configuration file, RC = return-code

An error occurred when opening the region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg).
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0027S config-module: Error opening development configuration file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0028S config-module: Error reading global configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0029S config-module: Error reading region (region-name) configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0030S config-module: Error reading development configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0031S config-module: Error reading global configuration file, RC = return-code

An error occurred when reading the global configuration file ($TXDIR/dfhtx.cfg).
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0032S config-module: Error reading region (region-name) configuration file, RC = region-name

An error occurred when opening the region configuration file ($REGIONBASE/$TXREGN/dfhtx.cfg).
System Action:
Terminate the requesting process.
Resolution:
Check the access permissions on the drive/directory/file.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0033S config-module: Error reading development configuration file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0034S config-module: Error writing global configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0035S config-module: Error writing region (region-name) configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0036S config-module: Error writing development configuration save file, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0037S config-module: Configuration error, TXLOCAL invalid

The directory specified by the TXLOCAL environment variable is invalid.
System Action:
Terminate the requesting process.
Resolution:
Check that the directory that is specified in TXLOCAL is valid and retry.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0038S config-module: Configuration error, TXDIR invalid

The directory specified by the TXDIR environment variable is invalid.
System Action:
Terminate the requesting process.
Resolution:
Check that the directory that is specified in TXDIR is valid and retry.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0039S config-module: Configuration error, region (region-name) files directory invalid

The region file directory ($REGIONBASE/$TXREGN/files/reg) is invalid.
System Action:
Terminate the requesting process.
Resolution:
Check that region name is correct and the directory exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0020 - CASCF0039


CASCF0040 - CASCF0059

  • CASCF0040S config-module: Configuration error, RDTDIR directory invalid
    The resource definition file path points to a directory is invalid.
  • CASCF0041S config-module: Configuration error, system files directory invalid
    The system files directory ($TXDIR/files/sys) in invalid.
  • CASCF0042S config-module: Configuration error, invalid region name (region-name) or directory
    The region's base directory ($REGIONBASE/$TXREGN) in invalid.
  • CASCF0043F config-module: Error loading messaging support module
    The messaging support module could not be loaded as part of system initialization.
  • CASCF0044F config-module: Error loading utility support module
    The utility support module could not be loaded as part of system initialization.
  • CASCF0045F config-module: Error loading file handling support module
    The file handling support module could not be loaded as part of system initialization.
  • CASCF0046F config-module: Error loading file handling support module
    The file handling support module could not be loaded as part of system initialization.
  • CASCF0047F config-module: Unexpected error processing configuration file, RC=return-code
    An unexpected error occurred in system initialization while processing the configuration file.
  • CASCF0048F config-module: Environment variable ID=environment-variable too large
    The value for the environment variable is larger than the internal work areas.
  • CASCF0049F config-module: Micro Focus protection check failed
    The activation key for the product is invalid or has expired.
  • CASCF0050S config-module: Console daemon not active, RC = return-code
    An error occurred accessing the console daemon configuration data.
  • CASCF0051S config-module: Region region-name not active, RC = return-code
    An error occurred accessing the region configuration data.
  • CASCF0052S config-module: Error reading console daemon configuration data, RC = return-code
    An error occurred reading the console daemon's stored configuration data.
  • CASCF0053S config-module: Error reading region "region-name" configuration data, RC = return-code
    An error occurred reading the region's stored configuration data.
  • CASCF0054S config-module: Error writing console daemon configuration data, RC = return-code
    An error occurred writing the console daemons stored configuration data.
  • CASCF0055S config-module: Error writing region "region-name" configuration data, RC = return-code
    An error occurred writing the region's stored configuration data.
  • CASCF0056S config-module: Error reading project configuration data, token = config-token
    An error occurred reading the project's configuration data.
  • CASCF0057S config-module: Error reading project configuration data, token = config-token
    An error occurred reading the project's configuration data.
  • CASCF0058S config-module: Error reading project configuration data, token = config-token
    An error occurred reading the project's configuration data.
  • CASCF0059F config-module: Error loading ES configuration support module
    The CAS configuration module could not be located during system initialization.
Parent topic: CASCF - CICS Configuration Support Error Messages


CASCF0040S config-module: Configuration error, RDTDIR directory invalid

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0041S config-module: Configuration error, system files directory invalid

The system files directory ($TXDIR/files/sys) in invalid.
System Action:
Terminate the requesting process.
Resolution:
Check that TXDIR is correct and the directory exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0042S config-module: Configuration error, invalid region name (region-name) or directory

The region's base directory ($REGIONBASE/$TXREGN) in invalid.
System Action:
Terminate the requesting process.
Resolution:
Check that region name is correct and the directory exists.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0043F config-module: Error loading messaging support module

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 $TXDIR is set correctly and the module "dfh0msg" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0044F config-module: Error loading utility support module

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 $TXDIR is set correctly and the module(s) "dfh0utl?" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0045F config-module: Error loading file handling support module

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 $TXDIR is set correctly and the module "dfhextfh" exists in $TXDIR/lib.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0046F config-module: Error loading file handling support module

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 $TXDIR is set correctly and the module "mffh" exists in $COBDIR.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0047F config-module: Unexpected error processing configuration file, RC=return-code

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  - TXLOCAL invalid
     09  - TXDIR 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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0048F config-module: Environment variable ID=environment-variable too large

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. values for ID are:

$COBCPY / TXCPYSRC
System Action:
Terminate the requesting process.
Resolution:
Check the directories specified in the appropriate environment variable / configuration items are required.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0049F config-module: Micro Focus protection check failed

The activation key for the product is invalid or has expired.
System Action:
Terminate the requesting process.
Resolution:
Contact your Micro Focus representative.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0050S config-module: Console daemon not active, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0051S config-module: Region region-name not active, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0052S config-module: Error reading console daemon configuration data, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0053S config-module: Error reading region "region-name" configuration data, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0054S config-module: Error writing console daemon configuration data, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0055S config-module: Error writing region "region-name" configuration data, RC = return-code

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0056S config-module: Error reading project configuration data, token = config-token

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0057S config-module: Error reading project configuration data, token = config-token

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0058S config-module: Error reading project configuration data, token = config-token

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0059F config-module: Error loading ES configuration support module

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.
Module:
config-module(dfhcpcfe)
Destination:
Standard error
Parent topic: CASCF0040 - CASCF0059


CASCF0060 - CASCF0079

  • CASCF0060F config-module: User not authorized to run system module
    The user is not a member of the group owning this module.
  • CASCF0061F config-module: System groups not configured
    The system groups have not been defined in $COBDIR/etc/cas/dfhtx.cfg.
  • CASCF0062F config-module: Module not recognized
    The module has not been recognized by the authorization process.
  • CASCF0063F config-module: Group associated with module not recognized
    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.
  • CASCF0065I Setting up Configuration Store
    Configuration Store is being created using MfConfigManagerData.
  • CASCF0066S Unexpected error in Configuration Manager - call-function, RC=RC (RC detail)
  • CASCF0068E Invalid Configuration Store File file-name, attempting recovery
  • CASCF0069W Configuration Manager is disabled. Failed to load API
    Unable to load mfconfigmanagerapi module.
  • CASCF0070E Unexpected error in Configuration Manager - call-function, RC=RC (RC detail)
  • CASCF0071W Configuration Manager - call-function
  • CASCF0072I Configuration Manager - call-function
Parent topic: CASCF - CICS Configuration Support Error Messages


CASCF0060F config-module: User not authorized to run system module

The user is not a member of the group owning this module.
System Action:
Terminate the requesting process.
Resolution:
Add user to relevant group.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0060 - CASCF0079


CASCF0061F config-module: System groups not configured

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.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0060 - CASCF0079


CASCF0062F config-module: Module not recognized

The module has not been recognized by the authorization process.
System Action:
Terminate the requesting process.
Resolution:
Contact Micro Focus.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0060 - CASCF0079


CASCF0063F config-module: Group associated with module not recognized

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.
Module:
config-module(dfhcpcfi)
Destination:
Standard error
Parent topic: CASCF0060 - CASCF0079


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: CASCF0060 - CASCF0079


CASCF0065I Setting up Configuration Store

Configuration Store is being created using MfConfigManagerData.
System Action:
Creating Configuration Store and validating MfConfigManagerData.
Module:
casgmfcm
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCF0066S Unexpected error in Configuration Manager - call-function, RC=RC (RC detail)

System Action:
Terminate configuration processing and shutdown region.
Resolution:
Contact support.
Module:
casgmfcm
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCF0068E Invalid Configuration Store File file-name, attempting recovery

System Action:
Attempt file recovery from local version.
Resolution:
Check for potential tampering to the file.
Module:
casgmfcm
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCF0069W Configuration Manager is disabled. Failed to load API

Unable to load mfconfigmanagerapi module.
System Action:
Disable Configuration Manager.
Resolution:
Check product is fully installed.
Module:
dfhginit
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCF0070E Unexpected error in Configuration Manager - call-function, RC=RC (RC detail)

System Action:
Terminate current configuration processing.
Resolution:
Contact support.
Module:
casgmfcm
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCF0071W Configuration Manager - call-function

Resolution:
Check region configuration.
Module:
casgmfcm
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCF0072I Configuration Manager - call-function

Module:
casgmfcm
Destination:
Console
Parent topic: CASCF0060 - CASCF0079


CASCL - CICS for UNIX Client Error Messages

  • CASCL0000 - CASCL0019
  • CASCL0020 - CASCL0039
Parent topic: Enterprise Server Error Messages


CASCL0000 - CASCL0019

  • 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.
  • 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.
  • 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 - CICS for UNIX Client 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 - CASCL0019


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


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


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


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


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


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


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


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


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


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


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


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


CASCL0020 - CASCL0039

  • 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 terminal-id auto-install failure, RC: tca-return-code
    An error occurred in the auto-install of printer terminal-id.
  • 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.
  • 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(model), device does not support SCS
    The device does not report SCS support but the selected terminal model requires SCS support.
  • CASCL0028E Auto-install error, Duplicate definition for Duplicate netname or termid
    During the auto-install process the termid or netname referenced where identified as duplicate.
  • CASCL0029W Terminal security user Terminal security userid for term definition for netname Terminal name. not recognized
    the userid specified in the term resource definition could not be identified.
  • CASCL0030E Auto-install error, NETNAME(netname) PAC access store error (PAC store access return code)
    There was an error trying to access the PAC store.
Parent topic: CASCL - CICS for UNIX Client 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 - CASCL0039


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


CASCL0022W Printer terminal-id auto-install failure, RC: tca-return-code

An error occurred in the auto-install of printer terminal-id.
System Action:
The printer will not be available for print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASCL0020 - CASCL0039


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


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


CASCL0025I Terminal disconnected successfully

The 3270 terminal has disconnected successfully.
Module:
dfhzexit
Destination:
Standard error
Parent topic: CASCL0020 - CASCL0039


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


CASCL0027E Auto-install error, LU1 NETNAME(netname) MODEL(model), device does not support SCS

The device does not report SCS support but the selected 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 - CASCL0039


CASCL0028E Auto-install error, Duplicate definition for Duplicate netname or termid

During the auto-install process the termid or netname referenced where identified as duplicate.
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: CASCL0020 - CASCL0039


CASCL0029W Terminal security user Terminal security userid for term definition for netname Terminal name. not recognized

the userid specified in the term resource definition could not be identified.
System Action:
terminal is installed as out of service.
Resolution:
Try correcting the userid and install again.
Module:
dfheserv
Destination:
console
Parent topic: CASCL0020 - CASCL0039


CASCL0030E Auto-install error, NETNAME(netname) PAC access store error (PAC store access return code)

There was an error trying to access the PAC store.
System Action:
The client is rejected.
Resolution:
Check that the PAC store can be accessed.
Module:
dfhzai
Destination:
Console Standard error
Parent topic: CASCL0020 - CASCL0039


CASCS - CICS Communications Error Messages

  • CASCS1000 - CASCS1019
  • CASCS1100 - CASCS1119
  • CASCS1120 - CASCS1139
  • CASCS1500 - CASCS1519
  • CASCS2000 - CASCS2019
  • CASCS3000 - CASCS3019
  • CASCS3020 - CASCS3039
  • CASCS5000 - CASCS5019
  • CASCS5040 - CASCS5059
  • CASCS5060 - CASCS5079
  • CASCS5100 - CASCS5119
Parent topic: Enterprise Server Error Messages


CASCS1000 - CASCS1019

  • CASCS1001S Receive allocate for trans-id, insufficient local storage.
    Inbound allocate for transaction trans-id failed because it could not acquire sufficient process storage to issue the receive allocate.
  • CASCS1002E Receive allocate for trans-id, communications error comms-primary-RC.
    Inbound allocate for transaction trans-id failed because of a communications error.
  • CASCS1003S Inbound TR for trans-id, terminal term-id not on system system-id.
    Inbound transaction routing of transaction trans-id failed because the terminal term-id is not owned by the remote system system-id.
  • CASCS1004S Receive allocate for trans-id, insufficient local storage.
    Inbound allocate for transaction trans-id failed because it could not acquire sufficient process storage to store the transmitted data.
  • CASCS1006E Receive for trans-id from system system-id failed, RC = comms-primary-RC.
    Inbound transaction trans-id from system system-id failed with a primary communications return code of comms-primary-RC.
  • CASCS1007E Request for terminal-id definition for trans-id, error RC = comms-primary-RC.
    The terminal definition for terminal-id was requested from the remote system while trying to process transaction trans-id.
  • CASCS1008E Install of shipped terminal-id definition failed, error RC = return-code.
    The install for terminal definition for terminal-id was rejected.
  • CASCS1009S Terminal ship install for transaction trans-id, getmain error.
    The install for terminal definition failed to acquire local storage during execution of transaction trans-id.
  • CASCS1010E Invalid terminal definition received from system system-id.
    A terminal definition was requested from system system-id.
  • CASCS1011E Route of transaction trans-id to system system-id is not supported.
    Outbound transaction routing of transaction trans-id to system system-id is not supported because there is no communications buffer allocated.
  • CASCS1012E Comms error x'comms-primary-RC' during route of trans-id to system system-id.
    Outbound transaction routing of transaction trans-id to system system-id failed with a communications return-code of comms-primary-RC.
  • CASCS1013E System system-id is not found for transaction trans-id (SYSIDERR).
    Outbound transaction routing of transaction trans-id failed because system system-id is not defined.
  • CASCS1014E System system-id out of service, transaction trans-id (SYSIDERR).
    Outbound transaction routing of transaction trans-id failed because system system-id is marked out of service.
  • CASCS1015E System system-id not acquired, transaction trans-id (SYSIDERR).
    Outbound transaction routing of transaction trans-id failed because system system-id is not acquired.
  • CASCS1016E System system-id invalid type, transaction trans-id (SYSIDERR).
    Outbound transaction routing of transaction trans-id failed because system system-id is not defined as a connection.
  • CASCS1017E Error for trans-id from system system-id, NOTAUTH, User ID = user-id.
    Inbound transaction trans-id from system system-id failed security check for user user-id.
  • CASCS1018E Error for trans-id from system system-id, USERIDERR, User ID = user-id.
    Inbound transaction trans-id from system system-id failed security check for user user-id.
Parent topic: CASCS - CICS Communications Error Messages


CASCS1001S Receive allocate for trans-id, insufficient local storage.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1002E Receive allocate for trans-id, communications error comms-primary-RC.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1003S Inbound TR for trans-id, terminal term-id not on system system-id.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1004S Receive allocate for trans-id, insufficient local storage.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1006E Receive for trans-id from system system-id failed, RC = comms-primary-RC.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1007E Request for terminal-id definition for trans-id, error RC = comms-primary-RC.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1008E Install of shipped terminal-id definition failed, error RC = return-code.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1009S Terminal ship install for transaction trans-id, getmain error.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1010E Invalid terminal definition received from system system-id.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1011E Route of transaction trans-id to system system-id is not supported.

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.
Module:
dfhebms (issued in dfheserv)
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1012E Comms error x'comms-primary-RC' during route of trans-id to system system-id.

Outbound transaction routing of transaction trans-id to system system-id failed with a communications return-code of comms-primary-RC.

Common values for comms-primary-RC are:

  x'0003' Allocation error (SYSIDERR)
  x'000f' Conversation failure - retry
  x'0010' Conversation failure - no retry

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.

System Action:
The transaction is abnormally terminated.
Resolution:
Correct the communications error and retry the operation.
Module:
dfhebms (issued in dfheserv)
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1013E System system-id is not found for transaction trans-id (SYSIDERR).

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.
Module:
dfhebms (issued in dfheserv)
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1014E System system-id out of service, transaction trans-id (SYSIDERR).

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.
Module:
dfhebms (issued in dfheserv)
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1015E System system-id not acquired, transaction trans-id (SYSIDERR).

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.
Module:
dfhebms (issued in dfheserv)
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1016E System system-id invalid type, transaction trans-id (SYSIDERR).

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.
Module:
dfhebms (issued in dfheserv)
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1017E Error for trans-id from system system-id, NOTAUTH, User ID = user-id.

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.
Module:
dfhebms (issued in dfhecics)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1018E Error for trans-id from system system-id, USERIDERR, User ID = user-id.

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.
Module:
dfhebms (issued in dfhecics)
Destination:
TDQ CSMT.
Parent topic: CASCS1000 - CASCS1019


CASCS1100 - CASCS1119

  • CASCS1100W CCI error CCI-error in TX CCI Gateway
    An error occurred in the CCI communications of the TX CCI gateway.
  • CASCS1101W CCI error: CCI-error-text
    An error occurred in the CCI communications of the TX CCI gateway.
  • CASCS1102E registration error for system net-name
    An error occurred in registering system net-name.
  • CASCS1103E Local storage allocation error
    An error occurred allocating local process storage.
  • CASCS1104I TX (CCI-protocol) CCI gateway initialized successfully on port CCI-port
    The TX CCI gateway initialized successfully on specified port, remote requesters can now connect to the region.
  • CASCS1105S TX CCI gateway failed to initialize, reason = reason-code
    The TX CCI gateway failed to initialize successfully .
  • CASCS1106S TX CCI gateway failed to initialize, reason = reason-code
    The TX CCI gateway failed to initialize successfully .
  • CASCS1107W Activate for connection to system remote-region failed, reason = reason-code
    The TX CCI gateway failed to connect to remote-region.
  • CASCS1108I TX (CCI-protocol) CCI gateway shutdown initiated
    The TX CCI gateway serving the CCI-protocol is shutting down.
  • CASCS1109I Connection remote-region (sysid sys-id) is activated contention winner
    The TX CCI gateway successfully connected to remote-region.
  • CASCS1110I Connection remote-region (sysid sys-id) is activated contention loser
    The TX CCI gateway successfully connected to remote-region.
  • CASCS1111E Bind for connection remote-region rejected, reason - reason-code
    The TX CCI gateway failed to connect to region remote-region.
  • CASCS1112E Bind for connection remote-region rejected by partner, reason - reason-code
    The TX CCI gateway failed to connect to region remote-region.
  • CASCS1113S CCI protocol error, NetBios Requester not started
    The TX CCI gateway detected a CCI protocol error.
  • CASCS1114E Load of CCI protocol module for module-name failed
    An error occurred loading the protocol support module module-name.
  • CASCS1115E CCI protocol module for module-name failed signature check: CCI-signature-string
    The signature check for CCI protocol support module module-name failed.
  • CASCS1116I CCI protocol module module-name code signature: CCI-signature-string
    The signature check string for CCI protocol support module module-name is CCI-signature-string.
  • CASCS1117I Connection to remote-region (sysid sys-id) lost (protocol CCI-transport)
    The TX CCI gateway connection to remote-region is lost.
  • CASCS1118W remote-region (sysid sys-id) abnormally terminated, connection lost (protocol CCI-transport)
    The TX CCI gateway connection to remote-region is lost due to an abnormal termination on sysid sys-id.
  • CASCS1119I Bind for connection remote-region rejected, contending bind will continue
    The TX CCI gateway received an bind from region remote-region.
Parent topic: CASCS - CICS Communications Error Messages


CASCS1100W CCI error CCI-error in TX CCI Gateway

An error occurred in the CCI communications of the TX 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.

Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1101W CCI error: CCI-error-text

An error occurred in the CCI communications of the TX CCI gateway.

CCI-error-text is returned from CCI. This message will be generated prior to message TXCS1100W for CCI error return code 9.

Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1102E registration error for system net-name

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1103E Local storage allocation error

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1104I TX (CCI-protocol) CCI gateway initialized successfully on port CCI-port

The TX CCI gateway initialized successfully on specified port, remote requesters can now connect to the region.

The CCI network protocol supported is CCI-protocol.

Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1105S TX CCI gateway failed to initialize, reason = reason-code

The TX 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 TX process has the permissions required to access it.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1106S TX CCI gateway failed to initialize, reason = reason-code

The TX CCI gateway failed to initialize successfully .

The reason-code is from dfhgreqc.

System Action:
Process terminates.
Resolution:
Check that the associated region is active.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1107W Activate for connection to system remote-region failed, reason = reason-code

The TX CCI gateway failed to connect to remote-region.

The reason-code is 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1108I TX (CCI-protocol) CCI gateway shutdown initiated

The TX CCI gateway serving the CCI-protocol is shutting down.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1109I Connection remote-region (sysid sys-id) is activated contention winner

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1110I Connection remote-region (sysid sys-id) is activated contention loser

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1111E Bind for connection remote-region rejected, reason - reason-code

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1112E Bind for connection remote-region rejected by partner, reason - reason-code

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1113S CCI protocol error, NetBios Requester not started

The TX CCI gateway detected a CCI protocol error.
System Action:
The TX CCI gateway is terminated.
Resolution:
Start the net requester service on the workstation.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1114E Load of CCI protocol module for module-name failed

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1115E CCI protocol module for module-name failed signature check: CCI-signature-string

The signature check for CCI protocol support module module-name failed.

The signature found is CCI-signature-string.

System Action:
The CCI gateway will not initialize successfully.
Resolution:
Correct the CCI installation.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1116I CCI protocol module module-name code signature: CCI-signature-string

The signature check string for CCI protocol support module module-name is CCI-signature-string.

This is a documentation message.

System Action:
The CCI gateway will continue initialization.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1117I Connection to remote-region (sysid sys-id) lost (protocol CCI-transport)

The TX 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:
No user action is required. The system will attempt to re-establish any locally defined connections that are lost. If the target system is not expected to return to an available state the connection may be set out of service through the relevant SysC entry using the ESMAC interface.
Module:
casgate
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1118W remote-region (sysid sys-id) abnormally terminated, connection lost (protocol CCI-transport)

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1119I Bind for connection remote-region rejected, contending bind will continue

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1100 - CASCS1119


CASCS1120 - CASCS1139

  • CASCS1120W Activate for connection remote-region failed, reason = reason-code. Silent retry will continue
    The communications server failed to establish an ISC connection to peer system remote-region.
  • CASCS1121I IBM Universal Client connection remote-region (sysid sys-id) is activated contention winner
    The TX CCI gateway successfully connected to the IBM Universal Client identified by netname remote-region.
  • CASCS1122I Attempting to establish ISC connection sys-id to system remote-region
    The system is attempting to activate the connection (TCT) identified as sys-id to the region named remote-region.
  • CASCS1123I Duplicate netname presented by IBM Universal Client (netname)
    The client has made a connection request either from a machine with which a connection already exists or presenting a netname which is already in use.
  • CASCS1124I Connection to remote-region (sysid sys-id) releasing (protocol CCI-transport)
    The TX CCI gateway connection to remote-region is releasing.
  • CASCS1125I Connection to remote-region (sysid sys-id) releasing (protocol CCI-transport)
    The TX CCI gateway connection to remote-region is releasing.
  • 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.
  • CASCS1127I Connection to remote-region (sysid sys-id) lost (protocol CCI-transport)
    The TX CCI gateway connection to remote-region is lost.
  • CASCS1131S Error while processing region configuration file
    An error occurred whilst processing the region configuration file.
  • CASCS1132S Error region name undefined while processing configuration file
    An error occurred while processing the configuration file.
  • CASCS1133S Unrecognized line in configuration file, line = line-number
    An unrecognized line was found in the configuration file at the line shown.
  • CASCS1134S Can not find configuration file, reason = RC-1
    The configuration file could not be found.
  • CASCS1135S Error creating configuration save file, reason = RC-1
    An error occurred when creating the configuration save file.
  • CASCS1136S Error opening configuration file, reason = RC-1
    An error occurred when creating the configuration save file.
  • CASCS1137S Error reading configuration file, reason = RC-1
    An error occurred when reading the configuration save file.
  • CASCS1138S Error writing configuration file, reason = RC-1
    An error occurred when writing the configuration save file.
Parent topic: CASCS - CICS Communications Error Messages


CASCS1120W Activate for connection remote-region failed, reason = reason-code. Silent retry will continue

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1121I IBM Universal Client connection remote-region (sysid sys-id) is activated contention winner

The TX 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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1122I Attempting to establish ISC connection sys-id to system remote-region

The system is attempting to activate the connection (TCT) identified as sys-id to the region named remote-region.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1123I Duplicate netname presented by IBM Universal Client (netname)

The client has made a connection request either from a machine with which a connection already exists or presenting a netname which is already in use.
Module:
casgate
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1124I Connection to remote-region (sysid sys-id) releasing (protocol CCI-transport)

The TX 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.
Module:
casgate
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1125I Connection to remote-region (sysid sys-id) releasing (protocol CCI-transport)

The TX 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.
Module:
casgate
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


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: CASCS1120 - CASCS1139


CASCS1127I Connection to remote-region (sysid sys-id) lost (protocol CCI-transport)

The TX 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:
No user action is required. The system will attempt to re-establish any locally defined connections that are lost. If the target system is not expected to return to an available state the connection may be set out of service through the relevant SysC entry using the ESMAC interface.
Module:
casgate
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1131S Error while processing region configuration file

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1132S Error region name undefined while processing configuration file

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1133S Unrecognized line in configuration file, line = line-number

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1134S Can not find configuration file, reason = RC-1

The configuration file could not be found.
System Action:
The CCI gateway will not initialize successfully.
Resolution:
Make sure that TXDIR is set correctly and that the configuration file exists.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1135S Error creating configuration save file, reason = RC-1

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1136S Error opening configuration file, reason = RC-1

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1137S Error reading configuration file, reason = RC-1

An error occurred when reading the configuration save file.
System Action:
The CCI gateway will not initialize successfully.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1138S Error writing configuration file, reason = RC-1

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.
Module:
dfhtcci
Destination:
Console
Parent topic: CASCS1120 - CASCS1139


CASCS1500 - CASCS1519

  • CASCS1500I ES Communications Server initialized successfully
    The CAS gateway initialized successfully.
  • CASCS1501I ES Communications Server shutdown initiated
    The CAS gateway has started shutdown processing.
  • CASCS1502W Error init-error during ES Communications Server initialization
    The CAS gateway failed to initialize successfully.
Parent topic: CASCS - CICS Communications Error Messages


CASCS1500I ES Communications Server initialized successfully

The CAS gateway initialized successfully.

Remote requesters can now connect to the region.

Module:
hydra
Destination:
Console
Parent topic: CASCS1500 - CASCS1519


CASCS1501I ES Communications Server shutdown initiated

The CAS gateway has started shutdown processing.
Module:
hydra
Destination:
Console
Parent topic: CASCS1500 - CASCS1519


CASCS1502W Error init-error during ES Communications Server initialization

The CAS gateway failed to initialize successfully.
Module:
hydra
Destination:
Console
Parent topic: CASCS1500 - CASCS1519


CASCS2000 - CASCS2019

  • CASCS2001E Mirror transaction trans-ID at terminal term-ID datastream too short
    A systems data stream was received by the TX mirror transaction trans-ID that is logically too short to decode.
  • CASCS2002E Mirror transaction trans-ID at terminal term-ID an unsupported FMH
    A systems data stream was received by the TX mirror transaction trans-ID that is not supported.
  • CASCS2003E Transaction trans-ID at terminal term-ID received invalid structured field
    A systems data stream was received by the TX mirror transaction trans-ID that contained an invalid structured field.
  • CASCS2004E Invalid initiation of trans-ID at terminal term-ID.
    The systems transaction trans-ID was executed from an invalid terminal type.
Parent topic: CASCS - CICS Communications Error Messages


CASCS2001E Mirror transaction trans-ID at terminal term-ID datastream too short

A systems data stream was received by the TX 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.
Module:
dfhzcsmi
Destination:
TDQ CSMT.
Parent topic: CASCS2000 - CASCS2019


CASCS2002E Mirror transaction trans-ID at terminal term-ID an unsupported FMH

A systems data stream was received by the TX 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.
Module:
dfhzcsmi
Destination:
TDQ CSMT.
Parent topic: CASCS2000 - CASCS2019


CASCS2003E Transaction trans-ID at terminal term-ID received invalid structured field

A systems data stream was received by the TX 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.
Module:
dfhzcsmi
Destination:
TDQ CSMT.
Parent topic: CASCS2000 - CASCS2019


CASCS2004E Invalid initiation of trans-ID at terminal term-ID.

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.
Module:
dfhzcrsr
Destination:
User terminal and TDQ CSMT.
Parent topic: CASCS2000 - CASCS2019


CASCS3000 - CASCS3019

  • CASCS3001E Region region-name not found, allocate from partner partner-lu-alias for transaction transaction-id rejected
    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.
  • CASCS3002E Allocate for inbound transaction transaction-id, partner partner-lu-alias, region region-name failed, RC=return-code
    An inbound allocate was received from region-name for region partner-lu-alias.
Parent topic: CASCS - CICS Communications Error Messages


CASCS3001E Region region-name not found, allocate from partner partner-lu-alias for transaction transaction-id rejected

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: CASCS3000 - CASCS3019


CASCS3002E Allocate for inbound transaction transaction-id, partner partner-lu-alias, region region-name failed, RC=return-code

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: CASCS3000 - CASCS3019


CASCS3020 - CASCS3039

  • CASCS3031I Connection connection-id, netname netname, LUA LU-alias, PLUA partner-LU-alias installed
    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 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.
Parent topic: CASCS - CICS Communications Error Messages


CASCS3031I Connection connection-id, netname netname, LUA LU-alias, PLUA partner-LU-alias installed

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: CASCS3020 - CASCS3039


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: CASCS3020 - CASCS3039


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: CASCS3020 - CASCS3039


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: CASCS3020 - CASCS3039


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: CASCS3020 - CASCS3039


CASCS3036E GLM MFCS return code received for the start listener request (sysid 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: CASCS3020 - CASCS3039


CASCS5000 - CASCS5019

  • CASCS5001I Communications interface instance-number initialization started
    The region communications interface initialization process has started.
  • CASCS5002S Communications interface not running in multi-threaded mode
    The region interface initialization process does not have the required underlying thread support.
  • CASCS5003I Communications interface instance-number initialization complete
    The region interface initialization process has completed.
  • CASCS5004S Communications interface instance-number registration failed, reason = reason-code
    The region interface initialization process failed registering the master session.
  • CASCS5005S Communications interface storage allocation error
    The communications interface experienced a problem allocating control blocks in local storage.
  • CASCS5006I casgate-message
    The region interface initialization process issued a message.
  • CASCS5007I Communications interface instance-number termination started
    The region communications interface is terminating.
  • CASCS5008I Communications interface instance-number termination complete
    The region communications interface has terminated.
  • CASCS5009E Communications interface client registration failed, reason = reason-code
    Client registration failed for a new client session.
  • CASCS5010I Universal Client sessions maximum exceeded defaulting to 127
    The maximum number of sessions supported for Universal Client connections is 127.
  • CASCS5011W Failed to open port port number for TCPIPSERVICE TCPIPSERVICE name
    MFCS failed to open the port for the TCPIPSERVICE TCPIPSERVICE name.
  • CASCS5012E casgate-error-message
    The region interface initialization process issued an error message.
Parent topic: CASCS - CICS Communications Error Messages


CASCS5001I Communications interface instance-number initialization started

The region communications interface initialization process has started.
Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5002S Communications interface not running in multi-threaded mode

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: CASCS5000 - CASCS5019


CASCS5003I Communications interface instance-number initialization complete

The region interface initialization process has completed.
Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5004S Communications interface instance-number registration failed, reason = reason-code

The region interface initialization process failed registering 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: CASCS5000 - CASCS5019


CASCS5005S Communications interface storage allocation error

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: CASCS5000 - CASCS5019


CASCS5006I casgate-message

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: CASCS5000 - CASCS5019


CASCS5007I Communications interface instance-number termination started

The region communications interface is terminating.
Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5008I Communications interface instance-number termination complete

The region communications interface has terminated.
Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5009E Communications interface client registration failed, reason = reason-code

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: CASCS5000 - CASCS5019


CASCS5010I Universal Client sessions maximum exceeded defaulting to 127

The maximum number of sessions supported for Universal Client connections is 127.

The value of the region configuration item TX_UNICLI_SESSIONS exceeds this limit.

Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5011W Failed to open port port number for TCPIPSERVICE TCPIPSERVICE name

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.
Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5012E casgate-error-message

The region interface initialization process issued an error message.

The text is casgate-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casgate
Destination:
Console
Parent topic: CASCS5000 - CASCS5019


CASCS5040 - CASCS5059

  • CASCS5050I HA VSAM Group role: server-role, with adjacent nodes: adjacent-nodes
    This server is part of an HA VSAM group configured for role server-role.
  • CASCS5051E HA VSAM Group configuration node count mismatch for node error-node
    The configuration on error-node error-node does not match the local node.
  • CASCS5052E HA VSAM Group configuration mismatch for node error-node
    The configuration on error-node error-node does not match the local node.
  • CASCS5053E HA VSAM Primary node error-node restarted after previous check
    The node error-node has been restarted since the previous check.
  • CASCS5054W HA VSAM group role of Primary is being assumed
    This node is assuming the role of Primary because it cannot see the Primary and at least one other Secondary agrees that the Primary is no longer available.
  • CASCS5055E HA VSAM configuration received from error-node is invalid
    The configuration and status received is of an invalid length and cannot be processed.
  • CASCS5056I ES SNA Communications Process restart in progress
    The ES SNA Communications process has been restarted and recovery operations are in progress.
  • CASCS5057I ES SNA Communications process (PID:process-id) recovery initiated
    The ES SNA Communications process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASCS5058I ES SNA Communications Process initialization complete
    The ES SNA Communications Process has completed initialization.
  • CASCS5059I ES SNA Communications Process termination started
    The ES SNA Communications Process is terminating.
Parent topic: CASCS - CICS Communications Error Messages


CASCS5050I HA VSAM Group role: server-role, with adjacent nodes: adjacent-nodes

This server is part of an HA VSAM group configured for role server-role.

The adjacent nodes configured for this group are adjacent-nodes.

System Action:
Server continues initialization.
Resolution:
No user action is required.
Module:
casgate
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5051E HA VSAM Group configuration node count mismatch for node error-node

The configuration on error-node error-node does not match the local node.

The node counts are different.

System Action:
The error-node is disabled.
Resolution:
The configurations for the error-node should be corrected such that it matches the local configuration.
Module:
casgate
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5052E HA VSAM Group configuration mismatch for node error-node

The configuration on error-node error-node does not match the local node.

The node counts are different.

System Action:
The error-node is disabled.
Resolution:
The configurations for the error-node should be corrected such that it matches the local configuration.
Module:
casgate
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5053E HA VSAM Primary node error-node restarted after previous check

The node error-node has been restarted since the previous check.
System Action:
The reporting node may be disabled.
Resolution:
The error-node will need to be recovered.
Module:
casgate
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5054W HA VSAM group role of Primary is being assumed

This node is assuming the role of Primary because it cannot see the Primary and at least one other Secondary agrees that the Primary is no longer available.
System Action:
This node assumes the role of Primary.
Resolution:
Verify that the old Primary node is disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5055E HA VSAM configuration received from error-node is invalid

The configuration and status received is of an invalid length and cannot be processed.
System Action:
The data is discarded.
Resolution:
Verify that the partner node is at the same code level as this node.
Module:
casgate
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5056I ES SNA Communications Process restart in progress

The ES SNA Communications process has been restarted and recovery operations are in progress.
Module:
cassna
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5057I ES SNA Communications process (PID:process-id) recovery initiated

The ES SNA Communications process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
cassna
Destination:
Console and standard error.
Parent topic: CASCS5040 - CASCS5059


CASCS5058I ES SNA Communications Process initialization complete

The ES SNA Communications Process has completed initialization.
Module:
cassna
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5059I ES SNA Communications Process termination started

The ES SNA Communications Process is terminating.
Module:
cassna
Destination:
Console
Parent topic: CASCS5040 - CASCS5059


CASCS5060 - CASCS5079

  • CASCS5060S ES SNA Communications Process registration failed, reason = reason-code
    The ES SNA Communications Process failed registration.
  • CASCS5061I ES SNA Communications Process termination complete
    The ES SNA Communications Process has terminated.
  • CASCS5062I sna-service-message
    The ES SNA Communications Process issued a message.
  • CASCS5063I ES SNA Communications Process initialization started
    The server ES SNA Communications Process initialization has started.
  • CASCS5064S ES SNA Communications Process is not running in multi-threaded mode
    The ES SNA Communications Process has not started with the required underlying thread support.
  • CASCS5065I ES SNA Communications initiating service for pool or LU pool or LU name
    The ES SNA Communications Process is initiating listener services for LU pool or LU pool or LU name.
  • CASCS5066I ES SNA Communications service for pool or LU pool or LU name has stopped
    Listener services for LU pool or LU pool or LU name has stopped.
  • CASCS5067I HA VSAM Fileshare listeners are set active. RC error-code
    The Fileshare listeners have been set to active.
  • CASCS5068I HA VSAM Fileshare listeners are set disabled. RC error-code
    The Fileshare listeners have been set to disabled.
  • CASCS5069W HA VSAM partner update received from remote-ES-NETNAME. HA VSAM is not enabled.
    The partner ES remote-ES-NETNAME is configured for this ES to participate in its HA VSAM groupe but this ES has not enabled HA VSAM support.
  • CASCS5070I HA VSAM Group Primary node is now group-node
    The group-node node is now Primary for this group.
  • CASCS5071W HA VSAM node group-node is now disabled
    The group-node node is now disabled.
  • CASCS5072W HA VSAM node group-node is now disabled
    The group-node node is now disabled.
  • CASCS5073W HA VSAM node group-node is now disabled
    The group-node node is now disabled.
  • CASCS5074I HA VSAM Standby node error-node restarted after previous check
    The node error-node has been restarted since the previous check.
  • CASCS5075W HA VSAM degraded to solo operation
    There are no longer any Hot Standby nodes active for this HA VSAM group.
  • CASCS5076I HA VSAM Primary node is activating
    The last required Hot Standby node is reported active for this HA VSAM group and this node is activating its role of Primary for this group.
  • CASCS5077W HA VSAM node error-node restarted as disabled after previous check
    The error-node has restarted and is disabled.
  • CASCS5078W HA VSAM node disabled at the request of primary
    The primary disabled this node, due to a lack of responsiveness.
  • CASCS5079E sna-service-error-message
    The ES SNA Communications Process issued an error message.
Parent topic: CASCS - CICS Communications Error Messages


CASCS5060S ES SNA Communications Process registration failed, reason = reason-code

The ES SNA Communications Process failed registration.

The reason code is reason-code.

System Action:
The ES SNA Communications Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5061I ES SNA Communications Process termination complete

The ES SNA Communications Process has terminated.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5062I sna-service-message

The ES SNA Communications Process issued a message.

The text is sna-service-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5063I ES SNA Communications Process initialization started

The server ES SNA Communications Process initialization has started.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5064S ES SNA Communications Process is not running in multi-threaded mode

The ES SNA Communications Process has not started with the required underlying thread support.
System Action:
The ES SNA Communications Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casmqb
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5065I ES SNA Communications initiating service for pool or LU pool or LU name

The ES SNA Communications Process is initiating listener services for LU pool or LU pool or LU name.
System Action:
Listener services initiated.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5066I ES SNA Communications service for pool or LU pool or LU name has stopped

Listener services for LU pool or LU pool or LU name has stopped.
System Action:
Listener services terminated.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5067I HA VSAM Fileshare listeners are set active. RC error-code

The Fileshare listeners have been set to active.

The operation return code is error-code".

System Action:
The Fileshare listeners are set active.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5068I HA VSAM Fileshare listeners are set disabled. RC error-code

The Fileshare listeners have been set to disabled.

The operation return code is error-code".

System Action:
The Fileshare listeners are set disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5069W HA VSAM partner update received from remote-ES-NETNAME. HA VSAM is not enabled.

The partner ES remote-ES-NETNAME is configured for this ES to participate in its HA VSAM groupe but this ES has not enabled HA VSAM support.
System Action:
The update is discarded.
Resolution:
Correct HA VSAM configuration on this ES or on the partner ES.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5070I HA VSAM Group Primary node is now group-node

The group-node node is now Primary for this group.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5071W HA VSAM node group-node is now disabled

The group-node node is now disabled.
System Action:
The node is disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5072W HA VSAM node group-node is now disabled

The group-node node is now disabled.
System Action:
The node is disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5073W HA VSAM node group-node is now disabled

The group-node node is now disabled.
System Action:
The node is disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5074I HA VSAM Standby node error-node restarted after previous check

The node error-node has been restarted since the previous check.
Resolution:
The error-node will need to be recovered.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5075W HA VSAM degraded to solo operation

There are no longer any Hot Standby nodes active for this HA VSAM group.
Resolution:
Redundancy should be restored at the appropriate time.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5076I HA VSAM Primary node is activating

The last required Hot Standby node is reported active for this HA VSAM group and this node is activating its role of Primary for this group.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5077W HA VSAM node error-node restarted as disabled after previous check

The error-node has restarted and is disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5078W HA VSAM node disabled at the request of primary

The primary disabled this node, due to a lack of responsiveness.
Resolution:
Check the network connection between this node and the primary.
Module:
casgate
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5079E sna-service-error-message

The ES SNA Communications Process issued an error message.

The text is sna-service-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
cassna
Destination:
Console
Parent topic: CASCS5060 - CASCS5079


CASCS5100 - CASCS5119

  • CASCS5100I info-msg
    An informational message generated from a Communications Server.
  • CASCS5101W warning-msg
    A warning message generated from a Communications Server.
  • CASCS5102E error-msg
    An error message generated from a Communications Server.
  • CASCS5103S severe-error-msg
    A severe error message generated from a Communications Server.
  • CASCS5104S severe-error-msg
    A severe error message generated from a Communications Server.
  • CASCS5105I ES Admin system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced
    A dump of the ES mfcs/casgate process was generated with a DUMPCODE of dump-code.
  • CASCS5106W HA VSAM node group-node has been disabled by user
    The group-node node is now disabled.
Parent topic: CASCS - CICS Communications Error Messages


CASCS5100I info-msg

An informational message generated from a Communications Server.
System Action:
None.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5100 - CASCS5119


CASCS5101W warning-msg

A warning message generated from a Communications Server.
System Action:
None.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5100 - CASCS5119


CASCS5102E error-msg

An error message generated from a Communications Server.
System Action:
None.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5100 - CASCS5119


CASCS5103S severe-error-msg

A severe error message generated from a Communications Server.
System Action:
None.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5100 - CASCS5119


CASCS5104S severe-error-msg

A severe error message generated from a Communications Server.
System Action:
None.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5100 - CASCS5119


CASCS5105I ES Admin system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced

A dump of the ES mfcs/casgate process was generated with a DUMPCODE of dump-code.

The caller was dump-caller and it was written to DATASET dump-dataset in response to an administrative interface request.

System Action:
The ES mfcs/casgate process produces a system dump.
Module:
casgate
Destination:
System Console
Parent topic: CASCS5100 - CASCS5119


CASCS5106W HA VSAM node group-node has been disabled by user

The group-node node is now disabled.
System Action:
The node is disabled.
Module:
casgate
Destination:
Console
Parent topic: CASCS5100 - CASCS5119


CASCT - CICS Supplied Transactions Error Messages

  • CASCT0000 - CASCT0019
  • CASCT0020 - CASCT0039
  • CASCT0040 - CASCT0059
  • CASCT0060 - CASCT0079
  • CASCT0080 - CASCT0099
  • CASCT0100 - CASCT0119
  • CASCT0200 - CASCT0219
  • CASCT0240 - CASCT0259
  • CASCT0300 - CASCT0319
  • CASCT0320 - CASCT0339
  • CASCT0340 - CASCT0359
  • CASCT0360 - CASCT0379
  • CASCT0400 - CASCT0419
  • CASCT0500 - CASCT0519
  • CASCT0540 - CASCT0559
  • CASCT0600 - CASCT0619
  • CASCT0700 - CASCT0719
  • CASCT0720 - CASCT0739
  • CASCT0740 - CASCT0759
  • CASCT0800 - CASCT0819
  • CASCT1000 - CASCT1019
  • CASCT2000 - CASCT2019
  • CASCT2100 - CASCT2119
  • CASCT2200 - CASCT2219
  • CASCT2300 - CASCT2319
  • CASCT2400 - CASCT2419
  • CASCT2420 - CASCT2439
  • CASCT2440 - CASCT2459
  • CASCT2460 - CASCT2479
  • CASCT3000 - CASCT3019
  • CASCT5000 - CASCT5019
  • CASCT5100 - CASCT5119
  • CASCT6000 - CASCT6019
  • CASCT6100 - CASCT6119
Parent topic: Enterprise Server Error Messages


CASCT0000 - CASCT0019

  • 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 '_'.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


CASCT0000S No messages found

No errors or informational messages have been detected for this screen.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT0000 - CASCT0019


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: CASCT0000 - CASCT0019


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: CASCT0000 - CASCT0019


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: CASCT0000 - CASCT0019


CASCT0020 - CASCT0039

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0020 - CASCT0039


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: CASCT0020 - CASCT0039


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: CASCT0020 - CASCT0039


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: CASCT0020 - CASCT0039


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: CASCT0020 - CASCT0039


CASCT0040 - CASCT0059

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0040 - CASCT0059


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: CASCT0040 - CASCT0059


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: CASCT0040 - CASCT0059


CASCT0060 - CASCT0079

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0060 - CASCT0079


CASCT0080 - CASCT0099

  • CASCT0080E More than 1 FROM and TO selection
    You have selected more than 1 FROM and more than 1 TO.
  • CASCT0081E More than 1 FROM selection
    You have selected more than 1 FROM item.
  • CASCT0082E More than 1 TO selection
    You have selected more than 1 TO item.
  • CASCT0085E Remote file FROM/TO entry
    You have selected a FROM/TO file that is marked as REMOTE.
  • 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.
  • CASCT0095W Copy option warnings, see line message(s)
    Copy options have warnings, see line messages for details.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0080 - CASCT0099


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: CASCT0080 - CASCT0099


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: CASCT0080 - CASCT0099


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: CASCT0080 - CASCT0099


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: CASCT0080 - CASCT0099


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: CASCT0080 - CASCT0099


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: CASCT0080 - CASCT0099


CASCT0100 - CASCT0119

  • CASCT0100E Record length error
    Requested record length is in error.
Parent topic: CASCT - CICS Supplied Transactions 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 - CASCT0119


CASCT0200 - CASCT0219

  • 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.
  • CASCT0210E Init key valid only when adding a record
    You can only initialize a record when you are adding it.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0200 - CASCT0219


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: CASCT0200 - CASCT0219


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: CASCT0200 - CASCT0219


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: CASCT0200 - CASCT0219


CASCT0240 - CASCT0259

  • CASCT0250E Illogic
    The request for a record is logically impossible.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0240 - CASCT0259


CASCT0300 - CASCT0319

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0300 - CASCT0319


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: CASCT0300 - CASCT0319


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: CASCT0300 - CASCT0319


CASCT0320 - CASCT0339

  • CASCT0325E SYSIDERR, EIBRESP =EIBRESP EIBRESP2 =EIBRESP2
    The file you are trying to access has encountered a SYSIDERR.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


CASCT0325E SYSIDERR, EIBRESP =EIBRESP EIBRESP2 =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: CASCT0320 - CASCT0339


CASCT0340 - CASCT0359

  • CASCT0350E File IO error, EIBRESP =EIBRESP EIBRESP2 =EIBRESP2
    The file you are trying to access has encountered a file I/O error.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


CASCT0350E File IO error, EIBRESP =EIBRESP EIBRESP2 =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: CASCT0340 - CASCT0359


CASCT0360 - CASCT0379

  • CASCT0360E Cannot currently traverse DUPKEYs backwards
    The alternate index that you are reading has duplicate keys.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0360 - CASCT0379


CASCT0400 - CASCT0419

  • CASCT0400E Record already on file
    The record you are trying to add is already on file.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0400 - CASCT0419


CASCT0500 - CASCT0519

  • CASCT0500E Error occurred while rewriting record
    An error occurred while trying to update the record.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0500 - CASCT0519


CASCT0540 - CASCT0559

  • CASCT0550E Error occurred while reading for update
    An error occurred while trying to update the record.
  • CASCT0555E Record modified since last read: update aborted
    The record has changed since last being read.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0540 - CASCT0559


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: CASCT0540 - CASCT0559


CASCT0600 - CASCT0619

  • CASCT0600E Error occurred while reading TS queue
    An error occurred while trying to read a TS queue.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0600 - CASCT0619


CASCT0700 - CASCT0719

  • CASCT0700E Error occurred while deleting record
    An error occurred while deleting a record.
  • CASCT0710E FROM file name could not be located
    You have entered a file name which could not be found.
  • CASCT0715W File does not exist, will be created
    The file name you entered does not exist in the directory specified.
Parent topic: CASCT - CICS Supplied Transactions 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 - CASCT0719


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


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


CASCT0720 - CASCT0739

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0720 - CASCT0739


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: CASCT0720 - CASCT0739


CASCT0740 - CASCT0759

  • CASCT0750E Error occurred while adding record
    An error occurred while adding this record.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0740 - CASCT0759


CASCT0800 - CASCT0819

  • CASCT0800E Invalid line position
    You have pressed an INSERT/REMOVE line key but the cursor is not positioned in the text field.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT0800 - CASCT0819


CASCT1000 - CASCT1019

  • CASCT1000W No files match selection criteria
    No file(s) found for the data entered in the file ID field.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT1000 - CASCT1019


CASCT2000 - CASCT2019

  • 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.
Parent topic: CASCT - CICS Supplied Transactions 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 - CASCT2019


CASCT2001W Wrapped

You have wrapped around to either the first page or last page available.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT2000 - CASCT2019


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


CASCT2100 - CASCT2119

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2100 - CASCT2119


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: CASCT2100 - CASCT2119


CASCT2200 - CASCT2219

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2200 - CASCT2219


CASCT2300 - CASCT2319

  • 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.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2300 - CASCT2319


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: CASCT2300 - CASCT2319


CASCT2400 - CASCT2419

  • CASCT2400I Top of file reached
    The beginning of the file has been reached, no more records available in this direction.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2400 - CASCT2419


CASCT2420 - CASCT2439

  • CASCT2425I Top of record reached
    The beginning of the record has been reached, no more pages available in this direction.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2420 - CASCT2439


CASCT2440 - CASCT2459

  • CASCT2450I Bottom of file reached
    The end of the file has been reached, no more records available in this direction.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2440 - CASCT2459


CASCT2460 - CASCT2479

  • CASCT2475I Bottom of record reached
    The end of the record has been reached, no more pages available in this direction.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT2460 - CASCT2479


CASCT3000 - CASCT3019

  • CASCT3000I Search string not found
    The string entered in the search could not be found.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT3000 - CASCT3019


CASCT5000 - CASCT5019

  • CASCT5000I Update successful
    Update of this record was successful.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


CASCT5000I Update successful

Update of this record was successful.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5000 - CASCT5019


CASCT5100 - CASCT5119

  • CASCT5100I Add successful
    Add of this record was successful.
  • CASCT5110I Page(s) added
    The specified number of pages were added successfully.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


CASCT5100I Add successful

Add of this record was successful.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5100 - CASCT5119


CASCT5110I Page(s) added

The specified number of pages were added successfully.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT5100 - CASCT5119


CASCT6000 - CASCT6019

  • CASCT6000I Delete successful
    The delete of this record was successful.
  • CASCT6010I Pages(s) deleted
    The specified number of pages were deleted successfully.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


CASCT6000I Delete successful

The delete of this record was successful.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT6000 - CASCT6019


CASCT6010I Pages(s) deleted

The specified number of pages were deleted successfully.
Module:
dfhzdfdm
Destination:
standard out
Parent topic: CASCT6000 - CASCT6019


CASCT6100 - CASCT6119

  • CASCT6100W Delete requested, press delete key again
    Delete of this record has been requested.
  • CASCT6110W Exit edit without saving? If so, press exit again
    You have pressed the exit key without first saving.
Parent topic: CASCT - CICS Supplied Transactions Error Messages


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: CASCT6100 - CASCT6119


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: CASCT6100 - CASCT6119


CASCV - Enterprise Server Verification Utility Error Messages

  • CASCV0000 - CASCV0019
  • CASCV0020 - CASCV0039
  • CASCV0040 - CASCV0059
  • CASCV0060 - CASCV0079
  • CASCV0080 - CASCV0099
  • CASCV0100 - CASCV0119
  • CASCV0120 - CASCV0139
  • CASCV0140 - CASCV0159
Parent topic: Enterprise Server Error Messages


CASCV0000 - CASCV0019

  • CASCV0001I See step step identifier for details
    A step during the stage encountered a potential issue.
  • CASCV0002S Module stage module name unavailable
    Failed to load the verification stage module.
  • CASCV0003S Unable to get stage version
    Unable to retieve version from stage module.
  • CASCV0004S Stage version: stage version does not match casverify version: casverify version
    Stage module is incompatible with casverify.
  • CASCV0005S Unexpected error: stage return code during stage setup
    A stage returned an unexpected return code during setup.
  • CASCV0006S No execution procedure set
    The stage module provided no execution entry.
  • CASCV0007S Stage unreachable to execute
    Call to stage execution entry failed.
  • CASCV0008S Stage contains invalid dependency: invlaid stage id
    The dependecy for the stage is invalid.
  • CASCV0009I Skipped due to dependency: stage id
    The stage was skipped due to the state of the dependent stage.
  • CASCV0010I STDOUT: standard output message
    Message written to Standard Output.
  • CASCV0011W STDERR: standard error message
    Message written to Standard Error.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0001I See step step identifier for details

A step during the stage encountered a potential issue.
Resolution:
Investigate given step.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0002S Module stage module name unavailable

Failed to load the verification stage module.
System Action:
Skip stage.
Resolution:
Verify the given stage module is loadable. Contact support.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0003S Unable to get stage version

Unable to retieve version from stage module.
System Action:
Skip stage.
Resolution:
Correct the stage module if it is custom. Ensure casverify is executed with a compatible version of the product.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0004S Stage version: stage version does not match casverify version: casverify version

Stage module is incompatible with casverify.
System Action:
Skip stage.
Resolution:
Ensure casverify is executed with a compatible version of the product.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0005S Unexpected error: stage return code during stage setup

A stage returned an unexpected return code during setup.
System Action:
Skip stage.
Resolution:
Correct the stage module if it is custom. Contact support.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0006S No execution procedure set

The stage module provided no execution entry.
System Action:
Skip stage.
Resolution:
Correct the stage module if it is custom. Contact support.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0007S Stage unreachable to execute

Call to stage execution entry failed.
System Action:
Skip stage.
Resolution:
Correct the stage module if it is custom. Contact support.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0008S Stage contains invalid dependency: invlaid stage id

The dependecy for the stage is invalid.
System Action:
Skip stage.
Resolution:
Correct the stage module if it is custom. Contact support.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0009I Skipped due to dependency: stage id

The stage was skipped due to the state of the dependent stage.
System Action:
Skip stage.
Resolution:
Verify if this is indended behavior.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0010I STDOUT: standard output message

Message written to Standard Output.
Resolution:
Check output for any errors.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0011W STDERR: standard error message

Message written to Standard Error.
Resolution:
Check output for any errors.
Module:
casverify
Destination:
Console
Parent topic: CASCV0000 - CASCV0019


CASCV0020 - CASCV0039

  • CASCV0020W COBDIR contains trailing separator
    A trailing path separator was found on the COBDIR environment variable.
  • CASCV0021I Successfully setup Configuration Block
    ES Configuration Block has setup sucessfully.
  • CASCV0022S Failed to setup Configuration Block
    ES Configuration Block failed setup.
  • CASCV0023I Successfully retrieved configuration from MFDS
    ES Configuration has been sucessfully retrieved from MF Directory Server.
  • CASCV0024S Error retrieving configuration from MFDS RC: cascfg return code (return code detail)
    An error occurred whilst retrieving the ES configuration from the MF Directory Server.
  • CASCV0025W System directory is not set. Using default location
    System directory is not set for the ES region.
  • CASCV0026W System directory: "system directory path" contains a trailing separator
    A trailing path separator was found on the system directory for the ES region.
  • CASCV0027I System directory set to "system directory path"
    System directory path resolved for the ES region.
  • CASCV0028S Environment block is too large
    The ES Environment block for the ES region exceeds the maximum length.
  • CASCV0029W No environment block found
    No ES Environment block provided for the ES region.
  • CASCV0030S Error loading module name
    Failed to load a module.
  • CASCV0031I Nothing set for region mfConfigManagerData. Using default configuration
    No advanced configuration is applied for the region.
  • CASCV0032I Configuration Store has setup successfully
    The configuration manager configuration store was setup successfully.
  • CASCV0033I Verifying folder-only path: "path pointing to folder"
    Checks for a directories existance at some user inputted path.
  • CASCV0034I Verifying file-only path: "path pointing to file"
    Checks for a file existance at some user inputted path.
  • CASCV0035I Verifying flexible path: "path pointing to file or folder"
    Checks that a user inputted path contains either a directory or file.
  • CASCV0036E No path specified
    The user inputted path hasn't been specified.
  • CASCV0037S Invalid State: error message
    Invalid state occured.
  • CASCV0038E Non-existant path: "bad path"
    Path doesn't point to existing destination.
  • CASCV0039E Path not pointing to path type: "path"
    Path's destination doesn't match expected path type.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0020W COBDIR contains trailing separator

A trailing path separator was found on the COBDIR environment variable.

In some situations this can cause load errors.

Resolution:
Remove trailing separator.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0021I Successfully setup Configuration Block

ES Configuration Block has setup sucessfully.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0022S Failed to setup Configuration Block

ES Configuration Block failed setup.
System Action:
End stage.
Resolution:
Verify product integrity. Contact support.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0023I Successfully retrieved configuration from MFDS

ES Configuration has been sucessfully retrieved from MF Directory Server.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0024S Error retrieving configuration from MFDS RC: cascfg return code (return code detail)

An error occurred whilst retrieving the ES configuration from the MF Directory Server.
System Action:
End stage.
Resolution:
Verify state of MF Directory Server.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0025W System directory is not set. Using default location

System directory is not set for the ES region.
System Action:
Using default system directory.
Resolution:
Verify if this is intended.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0026W System directory: "system directory path" contains a trailing separator

A trailing path separator was found on the system directory for the ES region.

In some situations this can cause IO errors.

Resolution:
Remove trailing separator.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0027I System directory set to "system directory path"

System directory path resolved for the ES region.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0028S Environment block is too large

The ES Environment block for the ES region exceeds the maximum length.
System Action:
End stage.
Resolution:
Reduce length of the ES Environment block.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0029W No environment block found

No ES Environment block provided for the ES region.
Resolution:
Verify ES region configuration.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0030S Error loading module name

Failed to load a module.
System Action:
End stage.
Resolution:
Verify product integrity.
Module:
cascpvsr
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0031I Nothing set for region mfConfigManagerData. Using default configuration

No advanced configuration is applied for the region.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0032I Configuration Store has setup successfully

The configuration manager configuration store was setup successfully.
Module:
verify_cascfg
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0033I Verifying folder-only path: "path pointing to folder"

Checks for a directories existance at some user inputted path.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0034I Verifying file-only path: "path pointing to file"

Checks for a file existance at some user inputted path.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0035I Verifying flexible path: "path pointing to file or folder"

Checks that a user inputted path contains either a directory or file.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0036E No path specified

The user inputted path hasn't been specified.
Resolution:
Input a path.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0037S Invalid State: error message

Invalid state occured.
Resolution:
Contact support.
Module:
cascpvsr
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0038E Non-existant path: "bad path"

Path doesn't point to existing destination.
Resolution:
Resolve why the path doesn't exist.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0039E Path not pointing to path type: "path"

Path's destination doesn't match expected path type.
Resolution:
Decide whether to choose a different path; or change it from either folder to file, or file to folder.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0020 - CASCV0039


CASCV0040 - CASCV0059

  • CASCV0040E Encountered COBRTcobol runtime return code for path: "path"
    Path IO requested encountered runtime error.
  • CASCV0041E Function function name encountered internal RC:function return code for path: "path"
    Path IO requested encountered internal error.
  • CASCV0042E Function function name returned internal RC:function return code
    Function returned an internal RC.
  • CASCV0043E No permission type permissions for "path"
    The file or folder at that path needs the correct permissions.
  • CASCV0044I "path" has permission type permissions
    The file or folder at that path has the correct permissions.
  • CASCV0045E issue prefix-prefixed path: "path"
    The platform does not support or configurable path cannot use the prefix.
  • CASCV0046I Environment variable "environment variable name" is set to "environment variable value"
    The value of a significant environment variable was reported.
  • CASCV0051I Start of XA resource name XA Interface load and open check
    Begin the process of loading and opening the XA Switch module.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0040E Encountered COBRTcobol runtime return code for path: "path"

Path IO requested encountered runtime error.
Resolution:
Act based on corresponding runtime error in documentation.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0041E Function function name encountered internal RC:function return code for path: "path"

Path IO requested encountered internal error.
Resolution:
Check that the path is in the correct format, otherwise contact support.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0042E Function function name returned internal RC:function return code

Function returned an internal RC.
Resolution:
If possible, act on the function's return code, otherwise contact support.
Module:
cascpvsr
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0043E No permission type permissions for "path"

The file or folder at that path needs the correct permissions.
Resolution:
Update the permissions of the file/folder pointed to by the path specified, or alter the path.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0044I "path" has permission type permissions

The file or folder at that path has the correct permissions.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0045E issue prefix-prefixed path: "path"

The platform does not support or configurable path cannot use the prefix.
Resolution:
Either alter the path or change platform this is ran on.
Module:
cascpvsc
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0046I Environment variable "environment variable name" is set to "environment variable value"

The value of a significant environment variable was reported.
Module:
cascpvsr
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0051I Start of XA resource name XA Interface load and open check

Begin the process of loading and opening the XA Switch module.
Module:
verify_xaswmod
Destination:
Console
Parent topic: CASCV0040 - CASCV0059


CASCV0060 - CASCV0079

  • CASCV0060I User-inputted SIT: "startup initialization table"
    Log of the SIT inputted by the user.
  • CASCV0061I No SIT specified, defaulting to "default startup initialization table"
    Logs that the default SIT is being used.
  • CASCV0062I iFileshare is configured for use
    Intent to enable iFileshare was detected.
  • CASCV0063W Resource Definition file path not pointed to DB for PAC
    It is recommended that the dfhdrdat is stored in a database and shared between the PAC members.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0060I User-inputted SIT: "startup initialization table"

Log of the SIT inputted by the user.
Module:
verify_cicscfg
Destination:
Console
Parent topic: CASCV0060 - CASCV0079


CASCV0061I No SIT specified, defaulting to "default startup initialization table"

Logs that the default SIT is being used.
Module:
verify_cicscfg
Destination:
Console
Parent topic: CASCV0060 - CASCV0079


CASCV0062I iFileshare is configured for use

Intent to enable iFileshare was detected.
Module:
verify_cicscfg
Destination:
Console
Parent topic: CASCV0060 - CASCV0079


CASCV0063W Resource Definition file path not pointed to DB for PAC

It is recommended that the dfhdrdat is stored in a database and shared between the PAC members.
Resolution:
Store the file in the DB and ensure recoverability, point to it via use of sql:// prefix.
Module:
verify_cicscfg
Destination:
Console
Parent topic: CASCV0060 - CASCV0079


CASCV0080 - CASCV0099

  • CASCV0080I Successfully loaded support modules
    Managed to load the modules to check JES configurations.
  • CASCV0082I Directory used for the creation of dataset will be created at region startup
    If Default Allocated Dataset location does not exist, it will be created when the region is started.
  • CASCV0083I The set up for the spool file directory depends on the catalog directory
    The specific spool file will be created in the same directory as the catalog.
  • CASCV0084I System procedure library is not available
    The system procedure library is not set up in ESCWA.
  • CASCV0085W Cannot check catalog format. catalog or default allocated dataset does not exist.
    Either one of the defined catalogs doesn't exist or the default allocated dataset location is not set up.
  • CASCV0086I No user defined catalogs are available
    There are no user defined catalogs in ESCWA.
  • CASCV0087E Spool path is not defined
    The JES facility did not return any spool directory.
  • CASCV0088W Cannot validate entry. Catalog is not open.
    Cannot validate whether system procedure library is defined in the catalog, as the catalog should be open, but it is not.
  • CASCV0089I Catalog is set up correctly.
    Catalog is set up correctly.
  • CASCV0090E Failed to mvscatio operation catalog. Output from mvscatio: mvscatio output
    An operation regarding the catalog has failed.
  • CASCV0091I dsname is set up properly in the catalog.
    System procedure library is in the correct format and it exist in the catalog.
  • CASCV0092E Invalid dataset organization for catalog entry dsname
    The organization of the dataset is in the wrong.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0080I Successfully loaded support modules

Managed to load the modules to check JES configurations.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0082I Directory used for the creation of dataset will be created at region startup

If Default Allocated Dataset location does not exist, it will be created when the region is started.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0083I The set up for the spool file directory depends on the catalog directory

The specific spool file will be created in the same directory as the catalog.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0084I System procedure library is not available

The system procedure library is not set up in ESCWA.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0085W Cannot check catalog format. catalog or default allocated dataset does not exist.

Either one of the defined catalogs doesn't exist or the default allocated dataset location is not set up.
Resolution:
Check whether the catalog or the folder exist in the location specified by ESCWA.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0086I No user defined catalogs are available

There are no user defined catalogs in ESCWA.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0087E Spool path is not defined

The JES facility did not return any spool directory.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0088W Cannot validate entry. Catalog is not open.

Cannot validate whether system procedure library is defined in the catalog, as the catalog should be open, but it is not.
Resolution:
Check whether you can open the catalog.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0089I Catalog is set up correctly.

Catalog is set up correctly.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0090E Failed to mvscatio operation catalog. Output from mvscatio: mvscatio output

An operation regarding the catalog has failed.

This can be due to wrong format of the catalog, or due to entry not existing in it.

Resolution:
Check for the format of the catalog, or if the entry requested exists.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0091I dsname is set up properly in the catalog.

System procedure library is in the correct format and it exist in the catalog.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0092E Invalid dataset organization for catalog entry dsname

The organization of the dataset is in the wrong.
Module:
verify_jescfg
Destination:
Console
Parent topic: CASCV0080 - CASCV0099


CASCV0100 - CASCV0119

  • CASCV0100I Loaded ESM Configuration: "esm name"
    Logs all ESMs loaded for SAFMGR initialisation.
  • CASCV0101F Failed to allocate local allocation size bytes (error type)
    An attempt to allocate the ESM chain failed for local memory.
  • CASCV0102I ESF Request type request for user "user". API RC: ESF API return code, Return Code: ESF return code, Reason Code: ESF reason code
    The ESF returned an error code with the provided ESF API and ESF return and reason codes.
  • CASCV0103I ESMAC/CICS/IMS/JES default user types Default user: default-user
    Displays the default user for every specific type.
  • CASCV0104I User ID "default-user" is authenticated.
    The default user has been validated.
  • CASCV0105E User Userid not authorized to start ES instance: "Region name".
    The supplied user has not the credentials to start ES.
  • CASCV0106I User Userid is authorized to start ES instance: "Region name".
    The supplied user has the correct credentials to start an ES instance.
  • CASCV0107I ESF Auth request for resource "Resource" from resource class "Resource class".
    Specifying the resource and resource class for which an authorization request has been issued.
  • CASCV0108I No user specified, assuming role of default user "Operator User".
    Specifying user that will be assumed in startup.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0100I Loaded ESM Configuration: "esm name"

Logs all ESMs loaded for SAFMGR initialisation.
Module:
verify_extsec
Destination:
Console
Parent topic: CASCV0100 - CASCV0119


CASCV0101F Failed to allocate local allocation size bytes (error type)

An attempt to allocate the ESM chain failed for local memory.
System Action:
Stops processing.
Resolution:
Check encountered issue, if not fixable contact support.
Module:
cascpvsr
Destination:
Console
Parent topic: CASCV0100 - CASCV0119


CASCV0102I ESF Request type request for user "user". API RC: ESF API return code, Return Code: ESF return code, Reason Code: ESF reason code

The ESF returned an error code with the provided ESF API and ESF return and reason codes.
System Action:
None.
Resolution:
Find out more about the return codes and analyse the result.
Module:
verify_extsec
Destination:
Console
Parent topic: CASCV0100 - CASCV0119


CASCV0103I ESMAC/CICS/IMS/JES default user types Default user: default-user

Displays the default user for every specific type.
System Action:
None.
Resolution:
None.
Module:
verify_extsec
Destination:
Console
Parent topic: CASCV0100 - CASCV0119


CASCV0104I User ID "default-user" is authenticated.

The default user has been validated.
System Action:
None.
Resolution:
None.
Module:
verify_extsec
Destination:
Console
Parent topic: CASCV0100 - CASCV0119


CASCV0105E User Userid not authorized to start ES instance: "Region name".

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:
verify_extsec
Destination:
System Console and standard error.
Parent topic: CASCV0100 - CASCV0119


CASCV0106I User Userid is authorized to start ES instance: "Region name".

The supplied user has the correct credentials to start an ES instance.
Module:
verify_extsec
Destination:
System Console and standard error.
Parent topic: CASCV0100 - CASCV0119


CASCV0107I ESF Auth request for resource "Resource" from resource class "Resource class".

Specifying the resource and resource class for which an authorization request has been issued.
Module:
verify_extsec
Destination:
System Console and standard error.
Parent topic: CASCV0100 - CASCV0119


CASCV0108I No user specified, assuming role of default user "Operator User".

Specifying user that will be assumed in startup.
Module:
verify_extsec
Destination:
System Console and standard error.
Parent topic: CASCV0100 - CASCV0119


CASCV0120 - CASCV0139

  • CASCV0120S PAC name is not specified, while at least one SOR is defined.
    The SOR configuration is non-empty, while the PAC name is.
  • CASCV0121S No SOR is defined, while PAC name is provided.
    The PAC name is non-empty, while the SOR configuration is.
  • CASCV0122I Name of PAC is a valid PAC name
    Provided PAC name is valid.
  • CASCV0123E Coherence string used by SOR Environment variable is empty
    Provided Coherence connection string is empty.
  • CASCV0124I Coherence connection string is the defined Coherence connection string
    Provided Coherence connection string is non-empty.
  • CASCV0125E SOR name did not provide an host name at end point.
    Provided host name in the field is empty.
  • CASCV0126E SOR name did not provide a valid port number at end point.
    Provided port number in the field is either out of bounds, or not numeric.
  • CASCV0127I SOR SOR name defined a Redis Server end point at Redis server host name port Redis server port number
    The SOR has a defined end point at the provided address.
  • CASCV0128I SOR SOR name will use the address at Redis server host name port Redis server port number to connect to Redis Server
    The SOR will use the specified address to connect to Redis.
  • CASCV0129E Invalid SOR connection string specified in SOR Environment variable. SOR will be ignored.
    The connection string, defined by the SOR is not defined properly.
  • CASCV0130E Region uses more than one PSOR
    More than one PSOR is defined in the SOR configuration string.
  • CASCV0131E Unsupported type for SOR Model type: SOR name. SOR must be only of type Redis or Coherence.
    PSOR must be only of type Redis or Coherence.
  • CASCV0132W SOR configuration string specifies unknown model type.
    The SOR configuration string contains a model type that is not expected.
  • CASCV0133I PAC PAC name uses SOR name as PSOR
    The PAC has a defined PSOR.
  • CASCV0134S Process could not connect to PSOR PSOR name
    The process could not connect to the PSOR TS/TD queues hosted in this SOR will be inaccessible whilst disconnected.
  • CASCV0135W CasPAC store does not contain a PACUID.
    PACUID is not defined in caspac.
  • CASCV0136I Cannot obtain ES product version from the PSOR.
    ES product version is not found in the PSOR.
  • CASCV0137I CasPAC store does not exist in the PSOR.
    CasPAC store is not defined in the PSOR.
  • CASCV0138W CasPAC record key is not defined in CasPAC store.
    Cannot find the pac record key in a PAC.
  • CASCV0139I Number of Regions in the PAC: Number of regions in PAC
    Displays the number of regions from the CasPAC records.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0120S PAC name is not specified, while at least one SOR is defined.

The SOR configuration is non-empty, while the PAC name is.
System Action:
PAC stage stops execution.
Resolution:
Check PAC definition.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0121S No SOR is defined, while PAC name is provided.

The PAC name is non-empty, while the SOR configuration is.
System Action:
PAC stage stops execution.
Resolution:
Check SOR definition.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0122I Name of PAC is a valid PAC name

Provided PAC name is valid.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0123E Coherence string used by SOR Environment variable is empty

Provided Coherence connection string is empty.
System Action:
Region cannot start.
Resolution:
Check Coherence connection string.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0124I Coherence connection string is the defined Coherence connection string

Provided Coherence connection string is non-empty.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0125E SOR name did not provide an host name at end point.

Provided host name in the field is empty.
Resolution:
Check SOR configuration.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0126E SOR name did not provide a valid port number at end point.

Provided port number in the field is either out of bounds, or not numeric.
Resolution:
Check SOR configuration.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0127I SOR SOR name defined a Redis Server end point at Redis server host name port Redis server port number

The SOR has a defined end point at the provided address.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0128I SOR SOR name will use the address at Redis server host name port Redis server port number to connect to Redis Server

The SOR will use the specified address to connect to Redis.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0129E Invalid SOR connection string specified in SOR Environment variable. SOR will be ignored.

The connection string, defined by the SOR is not defined properly.
Resolution:
Check your PAC configuration.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0130E Region uses more than one PSOR

More than one PSOR is defined in the SOR configuration string.
Resolution:
Check PAC configuration string.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0131E Unsupported type for SOR Model type: SOR name. SOR must be only of type Redis or Coherence.

PSOR must be only of type Redis or Coherence.
Resolution:
Check PAC configuration string.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0132W SOR configuration string specifies unknown model type.

The SOR configuration string contains a model type that is not expected.
Resolution:
Check SOR configuration string.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0133I PAC PAC name uses SOR name as PSOR

The PAC has a defined PSOR.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0134S Process could not connect to PSOR PSOR name

The process could not connect to the PSOR TS/TD queues hosted in this SOR will be inaccessible whilst disconnected.

If this is a PSOR then we will retry for a period of time.

System Action:
Exit stage check.
Resolution:
Check the Scale Out Repository and that it is accessible.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0135W CasPAC store does not contain a PACUID.

PACUID is not defined in caspac.
System Action:
Exit stage check.
Resolution:
Check in PAC store if PACUID is defined.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0136I Cannot obtain ES product version from the PSOR.

ES product version is not found in the PSOR.
Resolution:
Check in PAC store whether version is defined.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0137I CasPAC store does not exist in the PSOR.

CasPAC store is not defined in the PSOR.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0138W CasPAC record key is not defined in CasPAC store.

Cannot find the pac record key in a PAC.

Check if it is defined in the CASPAC store.

System Action:
Exit stage check.
Resolution:
Check in PAC store if the specified key is defined.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0139I Number of Regions in the PAC: Number of regions in PAC

Displays the number of regions from the CasPAC records.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0120 - CASCV0139


CASCV0140 - CASCV0159

  • CASCV0140W PAC_Starting is in state: Started/Starting/Failed/Shutdown
    Displays the value of the PAC_Starting key in CasPAC records.
  • CASCV0141I PAC sequence number: Value of PACSeqNumber
    Displays the value of the PACSeqNumber key in CasPAC records.
  • CASCV0142S PAC has been started in an unknown startup mode
    PAC is started in a mode that is not defined.
  • CASCV0143I ES product version from PSOR: Product version found in the PSOR.
    Displays the PAC product version, in case we cannot find the installed version.
  • CASCV0144I Cannot obtain ES product version.
    ES product version cannot be found.
  • CASCV0145I ES product version on disk: Product version.
    Displays the ES product version found on disk.
  • CASCV0146I PAC-wide configuration from PSOR applied to the Configuration Store successfully.
    Managed to update the Configuration Store, given the information from the PAC.
  • CASCV0147I Message from verification stage.
    The verification stage did not execute due to the specified reason.
Parent topic: CASCV - Enterprise Server Verification Utility Error Messages


CASCV0140W PAC_Starting is in state: Started/Starting/Failed/Shutdown

Displays the value of the PAC_Starting key in CasPAC records.
Resolution:
Check if PAC is started normally.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0141I PAC sequence number: Value of PACSeqNumber

Displays the value of the PACSeqNumber key in CasPAC records.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0142S PAC has been started in an unknown startup mode

PAC is started in a mode that is not defined.
System Action:
Exit stage check.
Resolution:
Check if PAC can be started in correct mdoe.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0143I ES product version from PSOR: Product version found in the PSOR.

Displays the PAC product version, in case we cannot find the installed version.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0144I Cannot obtain ES product version.

ES product version cannot be found.
Resolution:
Check if product version for product is available.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0145I ES product version on disk: Product version.

Displays the ES product version found on disk.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0146I PAC-wide configuration from PSOR applied to the Configuration Store successfully.

Managed to update the Configuration Store, given the information from the PAC.
Module:
verify_sorcfg
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASCV0147I Message from verification stage.

The verification stage did not execute due to the specified reason.
Module:
cascpverify
Destination:
Console
Parent topic: CASCV0140 - CASCV0159


CASDB - IMS Database Control Error Messages

  • CASDB5000 - CASDB5019
  • CASDB5020 - CASDB5039
  • CASDB5040 - CASDB5059
  • CASDB5060 - CASDB5079
Parent topic: Enterprise Server Error Messages


CASDB5000 - CASDB5019

  • 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.
  • 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.
  • 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.
  • CASDB5012E ims-control-error-message
    The IMS DB Control Process issued an error message.
Parent topic: CASDB - IMS Database Control Error Messages


CASDB5001I IMS DB Control Process initialization started

The server IMS DB Control Process initialization has started.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5000 - CASDB5019


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: CASDB5000 - CASDB5019


CASDB5003I IMS DB Control Process initialization complete

The IMS DB Control Process has completed initialization.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5000 - CASDB5019


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: CASDB5000 - CASDB5019


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: CASDB5000 - CASDB5019


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: CASDB5000 - CASDB5019


CASDB5007I IMS DB Control Process termination started

The IMS DB Control Process is terminating.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5000 - CASDB5019


CASDB5008I IMS DB Control Process termination complete

The IMS DB Control Process has terminated.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5000 - CASDB5019


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: CASDB5000 - CASDB5019


CASDB5012E ims-control-error-message

The IMS DB Control Process issued an error message.

The text is ims-control-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5000 - CASDB5019


CASDB5020 - CASDB5039

  • CASDB5039I IMS DB system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced
    A system dump of the IMS DB process was generated with a DUMPCODE of dump-code.
Parent topic: CASDB - IMS Database Control Error Messages


CASDB5039I IMS DB system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced

A system dump of the IMS DB process was generated with a DUMPCODE of dump-code.

The caller was dump-caller and it was written to DATASET dump-dataset in response to a /DUMP DB command.

System Action:
The ES mfcs/casgate process produces a system dump.
Module:
casdbc
Destination:
System Console
Parent topic: CASDB5020 - CASDB5039


CASDB5040 - CASDB5059

  • CASDB5054I IMS DB control process (PID:process-id) recovery initiated
    The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • 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.
Parent topic: CASDB - IMS Database Control Error Messages


CASDB5054I IMS DB control process (PID:process-id) recovery initiated

The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
casdbc
Destination:
Console and standard error.
Parent topic: CASDB5040 - CASDB5059


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 produces a dump.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5040 - CASDB5059


CASDB5060 - CASDB5079

  • 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.
Parent topic: CASDB - IMS Database Control 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 available.
Resolution:
Check the message issued by the DLI engine and the reason code.
Module:
casdbc
Destination:
Console
Parent topic: CASDB5060 - CASDB5079


CASDU - CICS Dump Control Error Messages

  • CASDU0000 - CASDU0019
Parent topic: Enterprise Server Error Messages


CASDU0000 - CASDU0019

  • CASDU0001W File Access error 9/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.
  • CASDU0006I Failure report file (Failure-report-filename) created
    An error occurred which resulted in the creation of a failure report.
  • CASDU0007W Unable to create failure report file (Failure-report-filename)
    An error occurred, but the system was unable to create the report file.
  • CASDU0008W Trace buffer full. A system or local trace trace was lost
    The trace buffer which is written by the monitor thread is full and a trace was lost.
  • CASDU0009I Trace flags modified. Active flags: Active trace flags
    Trace flags were modified.
  • CASDU0010I Active flags cont: Active trace flags - continued from DU0009I
    Trace flags were modified - continued from DU0009I.
Parent topic: CASDU - CICS Dump Control Error Messages


CASDU0001W File Access error 9/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: CASDU0000 - CASDU0019


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: CASDU0000 - CASDU0019


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: CASDU0000 - CASDU0019


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: CASDU0000 - CASDU0019


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: CASDU0000 - CASDU0019


CASDU0006I Failure report file (Failure-report-filename) created

An error occurred which resulted in the creation of a failure report.
System Action:
The system will have generated the failure report in the "system" directory.
Resolution:
Inspect the created report to find out more about the failure.
Module:
casreport
Destination:
Console and standard error
Parent topic: CASDU0000 - CASDU0019


CASDU0007W Unable to create failure report file (Failure-report-filename)

An error occurred, but the system was unable to create the report file.
Resolution:
Check the report generation settings.
Module:
casreport
Destination:
Console and standard error
Parent topic: CASDU0000 - CASDU0019


CASDU0008W Trace buffer full. A system or local trace trace was lost

The trace buffer which is written by the monitor thread is full and a trace was lost.
Module:
cassi
Destination:
Console
Parent topic: CASDU0000 - CASDU0019


CASDU0009I Trace flags modified. Active flags: Active trace flags

Trace flags were modified.
Module:
cassi
Destination:
Console
Parent topic: CASDU0000 - CASDU0019


CASDU0010I Active flags cont: Active trace flags - continued from DU0009I

Trace flags were modified - continued from DU0009I.
Module:
cassi
Destination:
Console
Parent topic: CASDU0000 - CASDU0019


CASFC - CICS File Control Error Messages

  • CASFC0000 - CASFC0019
Parent topic: Enterprise Server Error Messages


CASFC0000 - CASFC0019

  • CASFC0001I ES Fileshare services initialized
    The Fileshare facility is initialized and ready to accept requests.
  • CASFC0002I ES Fileshare terminated
    The Fileshare facility has terminated normally.
  • CASFC0003S ES Fileshare initialization terminated abnormally
    The Fileshare facility terminated during initialization.
  • CASFC0004S ES Fileshare critical storage error
    The Fileshare facility encountered a local storage failure that was not recoverable.
  • CASFC0005I ES Fileshare services message fileshare-message
    This message in standard Fileshare format.
  • CASFC0006I ES Fileshare current directory set to current-directory
    The effective current directory for Fileshare function is set to current-directory.
  • CASFC0007I ES Fileshare service process (PID:process-id) recovery initiated
    The integrated Fileshare process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASFC0008I Error accessing file (filename) group (group) - status=(file status1,file status2). File marked as closed and disabled.
    An error occurred while accessing the file.
  • CASFC0009I User (user-id) requested (request type) on file (filename) group (file group name) from Tran (trans-id) Program (program) Terminal (terminal-id).
    Logging username, filename and all open ,close ,enabled and disabled requests on a CICS files.
  • CASFC0010I Transaction (Transaction id) task number (Task number) user (User name) waiting for shared use of dataset (Dataset name).
    The dataset is locked exclusive in the ES cluster.
  • CASFC0011I Transaction (Transaction id) task number (Task number) user (User name) required datasets have been acquired. Execution resumed.
    Transaction execution resumes after dataset acquired.
  • CASFC0012E User (User name) not authorized to access dataset name (Dataset name) class checked is DATASET.
    The user does not have authority to access the dataset name.
  • CASFC0013E Failed to update PSOR version of FCT filename. Attempted action was request type. Check status of PSOR.
    An update to the local FCT was not reflected in the PSOR copy.
  • CASFC0014E Failed to update PSOR version of FCT filename. Check status of PSOR.
    An update to the local FCT was not reflected in the PSOR copy.
  • CASFC0015E Failed to update PSOR version of IMS DB record dbdname. Attempted action was request type. Check status of PSOR.
    An update to the local IMS DB record was not reflected in the PSOR copy.
Parent topic: CASFC - CICS File Control Error Messages


CASFC0001I ES Fileshare services initialized

The Fileshare facility is initialized and ready to accept requests.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0002I ES Fileshare terminated

The Fileshare facility has terminated normally.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0003S ES 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:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0004S ES Fileshare critical storage error

The Fileshare facility encountered a local storage failure that was not recoverable.
System Action:
The region is terminated abnormally.
Resolution:
Make sure there is enough memory available to the system.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0005I ES Fileshare services message fileshare-message

This message in standard Fileshare format.
Resolution:
Consult separate Fileshare message documentation.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0006I ES Fileshare current directory set to current-directory

The effective current directory for Fileshare function is set to current-directory.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0007I ES Fileshare service process (PID:process-id) recovery initiated

The integrated Fileshare process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFC0000 - CASFC0019


CASFC0008I Error accessing file (filename) group (group) - status=(file status1,file status2). File marked as closed and disabled.

An error occurred 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: CASFC0000 - CASFC0019


CASFC0009I User (user-id) requested (request type) on file (filename) group (file group name) from Tran (trans-id) Program (program) Terminal (terminal-id).

Logging username, filename and all open ,close ,enabled and disabled requests on a CICS files.
Module:
dfhesysp
Destination:
CSFL
Parent topic: CASFC0000 - CASFC0019


CASFC0010I Transaction (Transaction id) task number (Task number) user (User name) waiting for shared use of dataset (Dataset name).

The dataset is locked exclusive in the ES cluster.
System Action:
If this is unexpected, verify locks on the GLM using the caslock command.
Module:
dfhefctl
Destination:
console
Parent topic: CASFC0000 - CASFC0019


CASFC0011I Transaction (Transaction id) task number (Task number) user (User name) required datasets have been acquired. Execution resumed.

Transaction execution resumes after dataset acquired.
Module:
dfhefctl
Destination:
console
Parent topic: CASFC0000 - CASFC0019


CASFC0012E User (User name) not authorized to access dataset name (Dataset name) class checked is DATASET.

The user does not have authority to access the dataset name.
Resolution:
check user authority for the class DATASET and the corresponding dataset name.
Module:
dfhefctl
Destination:
console
Parent topic: CASFC0000 - CASFC0019


CASFC0013E Failed to update PSOR version of FCT filename. Attempted action was request type. Check status of PSOR.

An update to the local FCT was not reflected in the PSOR copy.
Resolution:
Check PSOR is accessible.
Module:
casafile, dfhesysp
Destination:
console, CSFL
Parent topic: CASFC0000 - CASFC0019


CASFC0014E Failed to update PSOR version of FCT filename. Check status of PSOR.

An update to the local FCT was not reflected in the PSOR copy.
Resolution:
Check PSOR is accessible.
Module:
dfhefctl
Destination:
console, CSFL
Parent topic: CASFC0000 - CASFC0019


CASFC0015E Failed to update PSOR version of IMS DB record dbdname. Attempted action was request type. Check status of PSOR.

An update to the local IMS DB record was not reflected in the PSOR copy.
Resolution:
Check PSOR is accessible.
Module:
casdbc, casmpr
Destination:
console, CSFL
Parent topic: CASFC0000 - CASFC0019


CASFD - CICS Dump Formatter Error Messages

  • CASFD0000 - CASFD0019
Parent topic: Enterprise Server Error Messages


CASFD0000 - CASFD0019

  • CASFD0001I Offline dump request issued for server region-name
    The offline dump requester issued a dump request for region region-name.
  • CASFD0002S Offline dump requestor failed to find region region-name
    The offline dump requester failed in its attempt to contact the region.
  • CASFD0003S Offline dump requester failed locate region files directory
    The offline dump requester failed in its attempt to change to the region's directories.
  • CASFD0004S TXDIR directory not found
    The offline dump requester failed in its attempt to change to the root Transaction System directory.
  • CASFD0005S Region directory not found
    The offline dump requester failed in its attempt to change to the region's directories.
  • CASFD0006S Other set environment failure
    The offline dump requester failed in its attempt to set environment variables.
  • CASFD0007S Offline dump requester failed to find requester. Region region-name
    The offline dump requester failed to find the requester support module.
  • CASFD0008S IMS dump request for region region-name cannot be issue without locking shared memory
    The offline dump requester failed to issue the IMS dump request because the parameter to not locked the shared memory was used.
  • CASFD0009S IMS not active on region region-name
    The offline dump requester could not issue an IMS dump request for region region-name.
  • CASFD0010I Dump/Trace format complete
    The offline dump/trace format request is complete.
  • CASFD0011I Formatted Dump/Trace output file: output-file-name
    The output from the offline dump/trace format request was written to the output file output-file-name.
  • CASFD0012E Input Dump/Trace dataset not found
    No input dump/trace dataset could be located.
  • CASFD0013I IMS dump request issued for region region-name
    The offline dump requester issued an IMS dump request for region region-name.
  • CASFD0014E Input Dump/Trace dataset does not match the current environment (Bitism)
    The input Dump/Trace dataset was not generated on the same bitism environment.
  • CASFD0015E Offline dump requestor failed to access DUMP file for region region-name
    The offline dump requester failed in its attempt to access the dump file.
  • CASFD0016S IMS dump request for region region-name cannot be issued without locking shared memory
    The offline dump requester failed to issue the castsc dump request because the parameter to not locked the shared memory was used.
  • CASFD0017S castsc is not active on region region-name
    The offline dump requester could not issue a castsc dump request for region region-name.
  • CASFD0018I castsc dump request issued for region region-name
    The offline dump requester issued a castsc dump request for region region-name.
Parent topic: CASFD - CICS Dump Formatter Error Messages


CASFD0001I Offline dump request issued for server region-name

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.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0002S Offline dump requestor failed to find region region-name

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.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0003S Offline dump requester failed locate region files directory

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.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0004S TXDIR directory not found

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 TXDIR specification and retry the operation.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0005S Region directory not found

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.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0006S Other set environment failure

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.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0007S Offline dump requester failed to find requester. Region region-name

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.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0008S IMS dump request for region region-name cannot be issue without locking shared memory

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.
Module:
dfhgtrtd
Destination:
standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0009S IMS not active on region region-name

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.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0010I Dump/Trace format complete

The offline dump/trace format request is complete.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0011I Formatted Dump/Trace output file: output-file-name

The output from the offline dump/trace format request was written to the output file output-file-name.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0012E Input Dump/Trace dataset not found

No input dump/trace dataset could be located.

Dump/Trace dataset names:

     dfhauxta.rec - aux trace 'a' dataset
     dfhauxtb.rec - aux trace 'b' dataset
     dfhdumpa.rec - dump      'a' dataset
     dfhdumpb.rec - dump      'b' dataset
     dfhdumpx.rec - dump      'x' dataset
Resolution:
Check the location of the dump/trace datasets and retry.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0013I IMS dump request issued for region region-name

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.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0014E Input Dump/Trace dataset does not match the current environment (Bitism)

The input Dump/Trace dataset was not generated on the same bitism environment.
Resolution:
Check your current environment.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0015E Offline dump requestor failed to access DUMP file for region region-name

The offline dump requester failed in its attempt to access the dump file.
System Action:
The dump request failed.
Resolution:
Check that the file exist or is not locked in the region's workarea.
Module:
dfhgtrtd
Destination:
Console and standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0016S IMS dump request for region region-name cannot be issued without locking shared memory

The offline dump requester failed to issue the castsc 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.
Module:
dfhgtrtd
Destination:
standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0017S castsc is not active on region region-name

The offline dump requester could not issue a castsc dump request for region region-name.

The castsc process is not currently active for the region.

System Action:
The dump request is aborted.
Resolution:
Correct the installation setup and retry the operation.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFD0018I castsc dump request issued for region region-name

The offline dump requester issued a castsc dump request for region region-name.

The dump went to the normal region dump dataset.

System Action:
The dump request is issued.
Module:
dfhgdup
Destination:
Standard error.
Parent topic: CASFD0000 - CASFD0019


CASFF - CICS File Finder Error Messages

  • CASFF0000 - CASFF0019
Parent topic: Enterprise Server Error Messages


CASFF0000 - CASFF0019

  • 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 invalid.
Parent topic: CASFF - CICS File Finder 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: CASFF0000 - CASFF0019


CASFF0002I Searching for the location of 'file-name'

The file 'file-name' is being searched for.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF0000 - CASFF0019


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: CASFF0000 - CASFF0019


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: CASFF0000 - CASFF0019


CASFF0005I Failed to find 'file-name'

The file 'file-name' was not found on the search path.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF0000 - CASFF0019


CASFF0006S Invalid parameter on command line : command-line

The command line parameter command-line is invalid.
Module:
dfhff
Destination:
standard error
Parent topic: CASFF0000 - CASFF0019


CASFS - Fileshare Error Messages

  • CASFS5000 - CASFS5019
  • CASFS5020 - CASFS5039
  • CASFS5040 - CASFS5059
  • CASFS5060 - CASFS5079
Parent topic: Enterprise Server Error Messages


CASFS5000 - CASFS5019

  • CASFS5001I Fileshare Control Process initialization started
    The server Fileshare Control Process initialization has started.
  • CASFS5002S Fileshare Control Process is not running in multi-threaded mode
    The Fileshare Control Process has not started with the required underlying thread support.
  • CASFS5003I Fileshare Control Process initialization complete; Role is node-type
    The Fileshare Control Process has completed initialization.
  • CASFS5004S Fileshare Control Process registration failed, reason = reason-code
    The Fileshare Control Process failed registration.
  • CASFS5005S Fileshare Control Process storage allocation error
    The Fileshare Control Process experienced a problem allocating control blocks in local storage.
  • CASFS5006I fs-control-message
    The Fileshare Control Process issued a message.
  • CASFS5007I Fileshare Control Process termination started
    The Fileshare Control Process is terminating.
  • CASFS5008I Fileshare Control Process termination complete
    The Fileshare Control Process has terminated.
  • CASFS5011I Fileshare Control Process restart in progress
    The IMS TM Control process has been restarted and recovery operations are in progress.
  • CASFS5012I Fileshare Control Process current directory set to current-directory
    The effective current directory for Fileshare function is set to current-directory.
  • CASFS5013S Fileshare Control Process user user-id signon error-text
    User user-id signon failed for reason error-text.
  • CASFS5014E fs-control-error-message
    The Fileshare Control Process issued an error message.
Parent topic: CASFS - Fileshare Error Messages


CASFS5001I Fileshare Control Process initialization started

The server Fileshare Control Process initialization has started.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5002S Fileshare Control Process is not running in multi-threaded mode

The Fileshare Control Process has not started with the required underlying thread support.
System Action:
The Fileshare Control Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5003I Fileshare Control Process initialization complete; Role is node-type

The Fileshare Control Process has completed initialization.
System Action:
as a node-type node.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5004S Fileshare Control Process registration failed, reason = reason-code

The Fileshare Control Process failed registration.

The reason code is reason-code.

System Action:
The Fileshare Control Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5005S Fileshare Control Process storage allocation error

The Fileshare Control Process experienced a problem allocating control blocks in local storage.
System Action:
The Fileshare Control Process is terminated.
Resolution:
Notify Micro Focus Support.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5006I fs-control-message

The Fileshare Control Process issued a message.

The text is fs-control-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5007I Fileshare Control Process termination started

The Fileshare Control Process is terminating.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5008I Fileshare Control Process termination complete

The Fileshare Control Process has terminated.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5011I Fileshare Control Process restart in progress

The IMS TM Control process has been restarted and recovery operations are in progress.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5012I Fileshare Control Process current directory set to current-directory

The effective current directory for Fileshare function is set to current-directory.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFS5000 - CASFS5019


CASFS5013S Fileshare Control Process user user-id signon error-text

User user-id signon failed for reason error-text.
System Action:
The user signon is rejected.
Resolution:
Correct the credentials and retry the operation.
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFS5000 - CASFS5019


CASFS5014E fs-control-error-message

The Fileshare Control Process issued an error message.

The text is fs-control-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5000 - CASFS5019


CASFS5020 - CASFS5039

  • CASFS5039I Fileshare process generated a dump to dump dataset dump-dataset
    A dump of the Fileshare process was requested and this dump was generated to the dump-dataset dump dataset.
Parent topic: CASFS - Fileshare Error Messages


CASFS5039I Fileshare process generated a dump to dump dataset dump-dataset

A dump of the Fileshare process was requested and this dump was generated to the dump-dataset dump dataset.
System Action:
The Fileshare process produces a dump.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5020 - CASFS5039


CASFS5040 - CASFS5059

  • CASFS5054I Fileshare control process (PID:process-id) recovery initiated
    The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASFS5059I Fileshare process generated a dump to dump dataset dump-dataset
    A dump of the Fileshare process was requested and this dump was generated to the dump-dataset dump dataset.
Parent topic: CASFS - Fileshare Error Messages


CASFS5054I Fileshare control process (PID:process-id) recovery initiated

The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
casfshr
Destination:
Console and standard error.
Parent topic: CASFS5040 - CASFS5059


CASFS5059I Fileshare process generated a dump to dump dataset dump-dataset

A dump of the Fileshare process was requested and this dump was generated to the dump-dataset dump dataset.
System Action:
The Fileshare process produces a dump.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5040 - CASFS5059


CASFS5060 - CASFS5079

  • CASFS5060S Fileshare Control Process engine failed to initialize, reason = reason-code
    The Fileshare Control Process failed to initialize the core file handler engine.
  • CASFS5061I Fileshare control HA VSAM Primary node preparation complete
    The Fileshare Control Process has completed initialization for HA VSAM Hot Standby processing.
  • CASFS5062I Fileshare control HA VSAM Hot Standby node preparation complete
    The Fileshare Control Process has completed initialization. for HA VSAM Hot Standby processing.
  • CASFS5063E Fileshare control HA VSAM assignment as role failed. Return code = return-code
    The Fileshare Control Process failed in its attempt to assign itself itself the role of role.
  • CASFS5064S Fileshare control HA VSAM replication has failed. RC=return-code
    The Fileshare Control Replication Process has failed.
  • CASFS5065W Fileshare Control Process initialization failed. HA VSAM is disabled.
    The Fileshare Control Process has completed initialization but HA VSAM functionality is disabled.
  • CASFS5066I Fileshare internal control process initialized
    The Fileshare Control Process has completed initialization for HA VSAM Hot Standby processing.
  • CASFS5067I Fileshare T-Log update transmission completed. Next sequence number is sequence-number
    The Fileshare Control Process has received the complete T-Log update transmission and the next replication sequence number is sequence-number.
  • CASFS5068I Fileshare T-Log update for node-name starting from log offset sequence-numberis requested.
    The Fileshare Control Process has received a request for a T-Log update for node node-name starting from log offset sequence-number.
  • CASFS5069I Fileshare T-Log update for node-name ended at log offset sequence-number
    The Fileshare Control Process has completed the request to transmit T-Log updates for node node-name transmission and the next replication broadcast sequence number is sequence-number.
  • CASFS5070I Fileshare T-Log update requested starting from log offset sequence-number
    The Fileshare Control Process is requesting a T-Log update from the Primary node starting from log offset sequence-number.
  • CASFS5071I Fileshare T-Log update for Node-name canceled at user request
    The requested log shipment has been canceled by the user exit.
  • CASFS5072I Fileshare user exit procedure successfully loaded
    The provided user exit proc was successfully loaded.
  • CASFS5073I Fileshare alternate working directory Directory specified
    The user has specified the above working directory for the fileshare process.
  • CASFS5074W Fileshare T-Log update for Node-name failed return-code Return-code
    The requested log shipment has failed due to an unexpected error.
  • CASFS5075W HA VSAM partner Node-name requires a manual log update.
    The requested log shipment has failed because of an inconsistency between the log data.
  • CASFS5076E HA VSAM node requires a manual log update.
    The requested log shipment has failed because of an inconsistency between the log data.
Parent topic: CASFS - Fileshare Error Messages


CASFS5060S Fileshare Control Process engine failed to initialize, reason = reason-code

The Fileshare Control Process failed to initialize the core file handler engine.

The reason code is reason-code.

System Action:
The Fileshare Control Process is terminated and Fileshare functionality is not available.
Resolution:
Check the message issued by the file handler engine and the reason code.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5061I Fileshare control HA VSAM Primary node preparation complete

The Fileshare Control Process has completed initialization for HA VSAM Hot Standby processing.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5062I Fileshare control HA VSAM Hot Standby node preparation complete

The Fileshare Control Process has completed initialization. for HA VSAM Hot Standby processing.

All ES processing is suspended except for ESMAC and replication activity.

Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5063E Fileshare control HA VSAM assignment as role failed. Return code = return-code

The Fileshare Control Process failed in its attempt to assign itself itself the role of role.

The return code from the iFileshare component is return-code.

Resolution:
Correct the issue indicated by the return-code if possible and retry the operation.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5064S Fileshare control HA VSAM replication has failed. RC=return-code

The Fileshare Control Replication Process has failed.

A delivered packet was rejected with a return code of return-code.

System Action:
The node is disabled.
Resolution:
Correct the issue indicated by the return-code if possible and restart the node.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5065W Fileshare Control Process initialization failed. HA VSAM is disabled.

The Fileshare Control Process has completed initialization but HA VSAM functionality is disabled.
System Action:
HA VSAM functionality is disabled.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5066I Fileshare internal control process initialized

The Fileshare Control Process has completed initialization for HA VSAM Hot Standby processing.

All ES processing is suspended except for ESMAC and replication activity.

Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5067I Fileshare T-Log update transmission completed. Next sequence number is sequence-number

The Fileshare Control Process has received the complete T-Log update transmission and the next replication sequence number is sequence-number.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5068I Fileshare T-Log update for node-name starting from log offset sequence-numberis requested.

The Fileshare Control Process has received a request for a T-Log update for node node-name starting from log offset sequence-number.
System Action:
The requested T-Log entries will be transmitted to the requesting node.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5069I Fileshare T-Log update for node-name ended at log offset sequence-number

The Fileshare Control Process has completed the request to transmit T-Log updates for node node-name transmission and the next replication broadcast sequence number is sequence-number.
System Action:
The requested T-Log entry transmissions have been transmitted to the requesting node.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5070I Fileshare T-Log update requested starting from log offset sequence-number

The Fileshare Control Process is requesting a T-Log update from the Primary node starting from log offset sequence-number.
System Action:
The request is sent to the Primary node.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5071I Fileshare T-Log update for Node-name canceled at user request

The requested log shipment has been canceled by the user exit.
System Action:
The shipment is canceled.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5072I Fileshare user exit procedure successfully loaded

The provided user exit proc was successfully loaded.
System Action:
The exit will be called at various points.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5073I Fileshare alternate working directory Directory specified

The user has specified the above working directory for the fileshare process.
System Action:
Fileshare will attempt to use this as a working directory.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5074W Fileshare T-Log update for Node-name failed return-code Return-code

The requested log shipment has failed due to an unexpected error.
System Action:
The shipment is canceled.
Resolution:
Check the console log to determine the cause of the error.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5075W HA VSAM partner Node-name requires a manual log update.

The requested log shipment has failed because of an inconsistency between the log data.
System Action:
The shipment is canceled and the requesting node is disabled.
Resolution:
Create a copy of the primary transaction log and data files and copy them over to the failed node before re-attempting recovery.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASFS5076E HA VSAM node requires a manual log update.

The requested log shipment has failed because of an inconsistency between the log data.
System Action:
The shipment is canceled and the requesting node is disabled.
Resolution:
Create a copy of the primary transaction log and data files and copy them over to the failed node before re-attempting recovery.
Module:
casfshr
Destination:
Console
Parent topic: CASFS5060 - CASFS5079


CASIP - CICS IMS Message Processing Error Messages

  • CASIP0000 - CASIP0019
  • CASIP0020 - CASIP0039
  • CASIP5000 - CASIP5019
Parent topic: Enterprise Server Error Messages


CASIP0000 - CASIP0019

  • CASIP0005I 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.
  • CASIP0006I IMS Message Processing Region initialization started
    IMS Message Processing process initialization started.
  • CASIP0009I IMS Message Processing Region termination complete.
    The message processing region has terminated normally.
  • CASIP0010I Debug IMS Message Processing Region termination complete.
    The debug message processing region has terminated normally.
  • CASIP0011S 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.
  • CASIP0012S 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.
  • CASIP0013I IMS Message Processing Region IMS-MPR-Nameregistered for classes "IMS-Classesname"IMS-MPR-PWFI
    The IMS Message Processing region named IMS-MPR-Name registered with the control region and is configured to support classes IMS-MPR-PWFI.
Parent topic: CASIP - CICS IMS Message Processing Error Messages


CASIP0005I 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: CASIP0000 - CASIP0019


CASIP0006I IMS Message Processing Region initialization started

IMS Message Processing process initialization started.
Module:
dfheini1
Destination:
ES Console
Parent topic: CASIP0000 - CASIP0019


CASIP0009I 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: CASIP0000 - CASIP0019


CASIP0010I 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: CASIP0000 - CASIP0019


CASIP0011S 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: CASIP0000 - CASIP0019


CASIP0012S 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:
Make sure there is enough memory available to the system.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP0000 - CASIP0019


CASIP0013I IMS Message Processing Region IMS-MPR-Nameregistered for classes "IMS-Classesname"IMS-MPR-PWFI

The IMS Message Processing region named IMS-MPR-Name registered with the control region and is configured to support classes IMS-MPR-PWFI.

The region may or may not be named (IMS-MPR-Name). If PWFI is specified (IMS-MPR-PWFI), the region is configured for PWFI (Pseudo Wait for Input) dispatch behavior.

Module:
casmpr
Destination:
ES Console
Parent topic: CASIP0000 - CASIP0019


CASIP0020 - CASIP0039

  • CASIP0023I 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".
  • CASIP0024E IMS support not enabled; Start for MPR rejected
    The requested MPR (Message Processing Region) was not started because IMS support is not enabled.
  • CASIP0025S IMS Message Processing Region Control registration failed
    The message processing region has terminated because the required TM Control support was not available or disabled.
  • CASIP0026I IMS Transaction tran-id completed but exceeded its threshold of elapsed time threshold in seconds seconds
    A transaction completed but exceeded its time threshold.
  • CASIP0031S IMS Message Formatting Services local memory allocation error return code.
    Message Formatting Services has terminated attempting to allocate local storage.
Parent topic: CASIP - CICS IMS Message Processing Error Messages


CASIP0023I 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: CASIP0020 - CASIP0039


CASIP0024E 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: CASIP0020 - CASIP0039


CASIP0025S 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:
Check that the TM Control process has started properly.
Module:
casmpr
Destination:
System Console and standard error.
Parent topic: CASIP0020 - CASIP0039


CASIP0026I IMS Transaction tran-id completed but exceeded its threshold of elapsed time threshold in seconds 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: CASIP0020 - CASIP0039


CASIP0031S IMS Message Formatting Services local memory allocation error return code.

Message Formatting Services has terminated attempting to allocate local storage.
System Action:
The process terminates normally.
Resolution:
Make sure there is enough memory available to the system.
Module:
casmfs
Destination:
System Console and standard error.
Parent topic: CASIP0020 - CASIP0039


CASIP5000 - CASIP5019

  • CASIP5006I casgate-message
    The MPR IPC process issued a message.
Parent topic: CASIP - CICS IMS Message Processing Error Messages


CASIP5006I 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: CASIP5000 - CASIP5019


CASIS - CICS Web Interface Error Messages

  • CASIS0100 - CASIS0119
  • CASIS0120 - CASIS0139
  • CASIS0720 - CASIS0739
  • CASIS0740 - CASIS0759
Parent topic: Enterprise Server Error Messages


CASIS0100 - CASIS0119

  • CASIS0101I date time applid tranid The CICS Web Interface alias program DFHWBA detected a failure in program DFHWBBLI. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice
    Program DFHWBBLI has returned an error response to the alias.
Parent topic: CASIS - CICS Web Interface Error Messages


CASIS0101I date time applid tranid The CICS Web Interface alias program DFHWBA detected a failure in program DFHWBBLI. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice

Program DFHWBBLI has returned an error response to the alias.
System Action:
The request is abandoned. The error response returned by program DFHWBBLI is returned to the Web Browser in an HTTP response.
Resolution:
Check program DFHWBBLI and the programs which it calls.
Module:
dfhwbxn
Destination:
web error program
Parent topic: CASIS0100 - CASIS0119


CASIS0120 - CASIS0139

  • CASIS0120I date time applid tranid The CICS Web Interface program DFHWBBLI cannot link to program program name. EIBRESP: EIBRESP. EIBRESP2 EIBRESP2. TCPIPSERVICE: tcpipservice
    Program DFHWBBLI used an EXEC CICS LINK but was unable to link to the given program and an EIB response was returned.
Parent topic: CASIS - CICS Web Interface Error Messages


CASIS0120I date time applid tranid The CICS Web Interface program DFHWBBLI cannot link to program program name. EIBRESP: EIBRESP. EIBRESP2 EIBRESP2. TCPIPSERVICE: tcpipservice

Program DFHWBBLI used an EXEC CICS LINK but was unable to link to the given program and an EIB response was returned.
System Action:
The link is abandoned.
Resolution:
Ensure that the program definition is correct.
Module:
dfhwbxn
Destination:
web error program
Parent topic: CASIS0120 - CASIS0139


CASIS0720 - CASIS0739

  • CASIS0723I date time applid tranid The CICS Web analyzer program returned an error response. Program name: program name. RESPONSE response. REASON: reason. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice
    As part of its normal processing of a request, CICS Web attach processing invokes the user replaceable analyzer to tailor the required actions.
  • CASIS0727I date time applid tranid CICS Web Interface attach processing could not attach the requested alias transaction tranid. Userid: userid. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice
    Web attach processing could not attach a new task with the requested alias transaction ID tranid.
Parent topic: CASIS - CICS Web Interface Error Messages


CASIS0723I date time applid tranid The CICS Web analyzer program returned an error response. Program name: program name. RESPONSE response. REASON: reason. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice

As part of its normal processing of a request, CICS Web attach processing invokes the user replaceable analyzer to tailor the required actions.

This program returns RESPONSE and REASON values.

System Action:
An error response is sent to the client and processing of the request is terminated.
Resolution:
Examine the RESPONSE and REASON code values in the message to determine the cause of the error.
Module:
dfhwbxn
Destination:
web error program
Parent topic: CASIS0720 - CASIS0739


CASIS0727I date time applid tranid CICS Web Interface attach processing could not attach the requested alias transaction tranid. Userid: userid. Host IP address: hostaddr. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice

Web attach processing could not attach a new task with the requested alias transaction ID tranid.
System Action:
An error response is sent to the client and processing of the request is terminated.
Resolution:
Ensure that the alias transaction ID supplied by the analyzer user replaceable program has been defined to CICS. Alternatively if a URIMAP is being used to supply the alias transaction, ensure that the URIMAP and the tranaction have been installed.
Module:
dfhwbxn
Destination:
web error program
Parent topic: CASIS0720 - CASIS0739


CASIS0740 - CASIS0759

  • CASIS0759I date time applid tranid An attempt to access static data data has failed because the resource is not found. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice
    The CICS document template or HFS file identified by data cannot be found.
Parent topic: CASIS - CICS Web Interface Error Messages


CASIS0759I date time applid tranid An attempt to access static data data has failed because the resource is not found. Client IP address: clientaddr. TCPIPSERVICE: tcpipservice

The CICS document template or HFS file identified by data cannot be found.
System Action:
The request is rejected with a HTTP/1.1 404 response.
Resolution:
Ensure that the required resources are defined and installed.
Module:
dfhwbxn
Destination:
web error program
Parent topic: CASIS0740 - CASIS0759


CASJC - CICS Journal Control Error Messages

  • CASJC0000 - CASJC0019
Parent topic: Enterprise Server Error Messages


CASJC0000 - CASJC0019

  • 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: CASJC - CICS Journal Control 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: CASJC0000 - CASJC0019


CASJC0002I Journal control terminated

The journal control facility has terminated normally.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC0000 - CASJC0019


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: CASJC0000 - CASJC0019


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:
Make sure there is enough memory available to the system.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC0000 - CASJC0019


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: CASJC0000 - CASJC0019


CASJC0012I Extra-Partition TD terminated

The Extra-Partition TD facility has terminated normally.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC0000 - CASJC0019


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: CASJC0000 - CASJC0019


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:
Make sure there is enough memory available to the system.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC0000 - CASJC0019


CASJC0015S Journal control failed - local storage allocation error

The Journal control program could not allocate the required local storage buffering.
System Action:
The process is terminated abnormally.
Resolution:
Make sure there is enough memory available to the system.
Module:
dfhgjcp
Destination:
Console and standard error.
Parent topic: CASJC0000 - CASJC0019


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: CASJC0000 - CASJC0019


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: CASJC0000 - CASJC0019


CASKC - CICS Task Control Error Messages

  • CASKC0000 - CASKC0019
  • CASKC0020 - CASKC0039
  • CASKC0040 - CASKC0059
  • CASKC0200 - CASKC0219
  • CASKC0300 - CASKC0319
  • CASKC1000 - CASKC1019
  • CASKC2000 - CASKC2019
  • CASKC5000 - CASKC5019
  • CASKC6000 - CASKC6019
  • CASKC6020 - CASKC6039
  • CASKC6040 - CASKC6059
Parent topic: Enterprise Server Error Messages


CASKC0000 - CASKC0019

  • CASKC0000E Invalid transaction ID 'trans-id', please re-submit.
    Transaction trans-id is not defined in the region Program Control Table (PCT).
  • CASKC0001E Transaction trans-id abend abend-codeabend-description. Backout Successful.
    Transaction trans-id abnormally terminated with abend code abend-code.
  • CASKC0002E PLTPI processing module failed to load.
    The system supplied module "dfhzplt.gnt" was not accessible.
  • CASKC0003I SEP process-id shutdown complete.
    The server process process-id has shutdown normally.
  • CASKC0004W Error attempting to start SEP
    The region manager requested that a CICS server process be started and received an error response.
  • CASKC0005W Error attempting to stop a SEP
    The region manager attempted to close a CICS server process and received an error.
  • CASKC0006E Abend ASRA - Transaction abend
    A CICS API server abended during a transaction.
  • CASKC0007W Shared memory storage constrained
    The system shared memory resource limit has been reached.
  • CASKC0008I Shared memory storage constraint ended
    The system has now enough free shared storage to re-acquire the shared storage cushion.
  • CASKC0009E PCT entry transid disabled, cannot execute transaction
    The PCT entry transid is currently marked as disabled.
  • CASKC0010I Debug SEP shutdown due to client disconnection.
    The animation server has shutdown normally.
  • CASKC0011I Failed to trigger transaction transid on terminal termid for destination destid.
    The destination specified triggering of the transaction on a terminal other than the current terminal in single tasking mode.
  • CASKC0012W MQOPEN for queue queue-name ended with reason code: reason-code.
    The system attempted to read an MQ queue record from the queue queue-name.
  • CASKC0013E MQOPEN for queue queue-name input failed-reason code: reason-code.
    The system attempted to read an MQ queue record from the queue queue-name.
  • CASKC0014E MQGET for queue queue-name failed to return a record.
    The system attempted to read an MQ queue record from the queue queue-name.
  • CASKC0015E MQGET for queue queue-name ended with reason code: reason-code.
    The system attempted to read an MQ queue record from the queue queue-name.
  • CASKC0016E MQCLOSE for queue queue-name ended with reason code: reason-code.
    The system attempted to read an MQ queue record from the queue queue-name.
  • CASKC0017E Service Request Handler request-handler-name register failed, reason: reason-code.
    The system attempted to register the request-handler-name request handler.
  • CASKC0018E Service (service-name) IDT load failed reason code: reason-code.
    The system attempted load the Interface Definition Table (IDT) for Service service-name.
  • CASKC0019E Service (service-name) IDT read failed reason code: reason-code.
    The system attempted to load the Interface Definition Table (IDT) for Service service-name.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC0000E Invalid transaction ID 'trans-id', please re-submit.

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.
Module:
dfheserv
Destination:
User terminal
Parent topic: CASKC0000 - CASKC0019


CASKC0001E Transaction trans-id abend abend-codeabend-description. Backout Successful.

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.
Module:
dfheserv
Destination:
User terminal, TDQ CSMT and console.log.
Parent topic: CASKC0000 - CASKC0019


CASKC0002E PLTPI processing module failed to load.

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0003I SEP process-id shutdown complete.

The server process process-id has shutdown normally.
System Action:
The process terminates normally.
Resolution:
None.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0004W Error attempting to start SEP

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.
Module:
casmgr
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0005W Error attempting to stop a SEP

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.
Module:
casmgr
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0006E Abend ASRA - Transaction abend

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.
Module:
casmgr
Destination:
Terminal
Parent topic: CASKC0000 - CASKC0019


CASKC0007W Shared memory storage constrained

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 memory pages on the ESCWA General Properties page.
Module:
casmgr
Destination:
System Console.
Parent topic: CASKC0000 - CASKC0019


CASKC0008I Shared memory storage constraint ended

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.
Module:
casmgr
Destination:
System Console.
Parent topic: CASKC0000 - CASKC0019


CASKC0009E PCT entry transid disabled, cannot execute transaction

The PCT entry transid 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: CASKC0000 - CASKC0019


CASKC0010I Debug SEP shutdown due to client disconnection.

The animation server has shutdown normally.

The shutdown was implicitly requested by closing the associated terminal.

System Action:
The process terminates normally.
Resolution:
None.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0011I Failed to trigger transaction transid on terminal termid for destination destid.

The destination specified triggering of the transaction on a terminal other than the current terminal in single tasking mode.
System Action:
None.
Resolution:
None.
Module:
dfhetstd
Destination:
System Console and CSMT td queue.
Parent topic: CASKC0000 - CASKC0019


CASKC0012W MQOPEN for queue queue-name ended with reason code: reason-code.

The system attempted to read an MQ queue record from the queue queue-name.

The MQ open operation 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 initiation queue listener.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0013E MQOPEN for queue queue-name input failed-reason code: reason-code.

The system attempted to read an MQ queue record from the queue queue-name.

The MQ open operation 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 initiation queue listener.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0014E MQGET for queue queue-name failed to return a record.

The system attempted to read an MQ queue record from the queue queue-name.

The read operation failed to return a record.

System Action:
Transaction aborted.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE initiation queue listener.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0015E MQGET for queue queue-name ended with reason code: reason-code.

The system attempted to read an MQ queue record from the queue queue-name.

The read operation failed with reason code reason-code.

System Action:
Transaction aborted.
Resolution:
Resolve the configuration mismatch and restart the associated ASEE initiation queue listener.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0016E MQCLOSE for queue queue-name ended with reason code: reason-code.

The system attempted to read an MQ queue record from the queue queue-name.

The close operation for the queue failed with reason code reason-code. This error should not occur.

System Action:
None.
Resolution:
Report error to Micro Focus.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0017E Service Request Handler request-handler-name register failed, reason: reason-code.

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:
Check the RTS documentation for the returned error, correct and re-register the handler.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0018E Service (service-name) IDT load failed reason code: reason-code.

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 hexadecimal 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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0019E Service (service-name) IDT read failed reason code: reason-code.

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0000 - CASKC0019


CASKC0020 - CASKC0039

  • CASKC0020E Service (service-name) get IDT storage failed reason code: reason-code.
    The system attempted to load the Interface Definition Table (IDT) for Service service-name.
  • CASKC0021E Service (service-name) IDT read failed reason code: reason-code.
    The system attempted to load the Interface Definition Table (IDT) for Service service-name.
  • CASKC0022E MQCONN for queue manager queue-manager-name failed-reason code: reason-code.
    The system could not connect to the queue-manager-name queue manager.
  • CASKC0023E Unable to locate request-handler-name Service Request Handler for request request
    The system could not locate a definition for the request-handler-name request handler.
  • CASKC0024E No response from request-handler-name Service Request Handler; RC=return-code
    The request handler did not generate a response to an input request.
  • CASKC0025I info-msg
    A message has been generated processing a service.
  • CASKC0026E error-msg
    A message has been generated processing a service.
  • CASKC0027E error-msg
    A message has been generated processing a service.
  • CASKC0028E error-msg
    A message has been generated processing a service.
  • CASKC0029E Error error-msg processing service request
    A message has been generated processing a service.
  • CASKC0030S Unable to load dynamic IDT generation support module
    One of the essential system modules failed to load.
  • CASKC0031E Service (service-name) IDT load failed - file not found. RC reason-code
    The system attempted load the Interface Definition Table (IDT) but failed to locate the file.
  • CASKC0032I WebSphere MQ !Queue Manager Name SUBSYSTEM security switch set OFF, profile 'Security profile found' found
    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 WebSphere MQ !Queue Manager Name SUBSYSTEM security switch set ON, profile 'Security profile found' not found
    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 WebSphere MQ !Queue Manager Name Type security security switch set ON, profile 'Security profile found' not found
    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 for type Type security.
  • CASKC0035I WebSphere MQ !Queue Manager Name Type security security switch set OFF, profile 'Security profile found' found
    A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned off for type Type security.
  • CASKC0036E Invalid esmac module requested: esmac requested module
    An invalid esmac module has been requested.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC0020E Service (service-name) get IDT storage failed reason code: reason-code.

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0020 - CASKC0039


CASKC0021E Service (service-name) IDT read failed reason code: reason-code.

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0020 - CASKC0039


CASKC0022E MQCONN for queue manager queue-manager-name failed-reason code: reason-code.

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0020 - CASKC0039


CASKC0023E Unable to locate request-handler-name Service Request Handler for request request

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0020 - CASKC0039


CASKC0024E No response from request-handler-name Service Request Handler; RC=return-code

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0020 - CASKC0039


CASKC0025I info-msg

A message has been generated processing a service.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0026E error-msg

A message has been generated processing a service.
System Action:
None.
Module:
dfheserv, casbat, casmpr
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0027E error-msg

A message has been generated processing a service.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0028E error-msg

A message has been generated processing a service.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0029E Error error-msg processing service request

A message has been generated processing a service.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0030S Unable to load dynamic IDT generation support module

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.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0031E Service (service-name) IDT load failed - file not found. RC reason-code

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.
Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC0020 - CASKC0039


CASKC0032I WebSphere MQ !Queue Manager Name SUBSYSTEM security switch set OFF, profile 'Security profile found' found

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.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0033I WebSphere MQ !Queue Manager Name SUBSYSTEM security switch set ON, profile 'Security profile found' not found

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.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0034I WebSphere MQ !Queue Manager Name Type security security switch set ON, profile 'Security profile found' not found

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 for type Type security.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0035I WebSphere MQ !Queue Manager Name Type security security switch set OFF, profile 'Security profile found' found

A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned off for type Type security.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0036E Invalid esmac module requested: esmac requested module

An invalid esmac module has been requested.
System Action:
None.
Resolution:
Review the esmac request.
Module:
cashtsrv
Destination:
System Console
Parent topic: CASKC0020 - CASKC0039


CASKC0040 - CASKC0059

  • CASKC0040I admin-msg
    A remote client entered a message to the active system.
  • CASKC0041E Transaction trans-id abend abend-codeabend-description.
    Transaction trans-id abnormally terminated with abend code abend-code.
  • CASKC0042I Transaction trans-id abend abend-codeabend-description. Backout Successful.
    Transaction trans-id abnormally terminated with abend code abend-code.
  • CASKC0043E system-id Transaction trans-id failed with abend ASRA. Updates to local recoverable resources backed out.
    Transaction trans-id abnormally terminated with abend code ASRA.
  • CASKC0044S ES failed to authorize CICS Default user default-user
    ES failed to authorize the CICS Default user during initialization.
  • CASKC0045I User (user-id) requested (request type) on Transaction (trans-id for request) from Tran (active trans-id) Program (active program) Terminal(terminal id).
    Logging all enabled and disabled 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.
  • CASKC0049I Cancellation of Program (program-id for request) by user (user-id) - Return-code(return-code).
    Cancellation of the specified program was attempted by the named user.
  • CASKC0050S IMS DB Control process ABENDed and ES shutdown is configured
    The IMS DB Control failed and ES is configured to shutdown immediately when this happens. i.e the environment variable ES_IMS_STOP_ON_DB_FAIL=Y is set to Y or y.
  • CASKC0051E A storage violation was detected during task number task number.
    On deallocation of local memory, we detected a storage violation for task number task number.
  • CASKC0052S One or more core process(es) terminated prior to initialization - shutting region down
    one or more core CAS processes terminated before PIP1 has completed.
  • CASKC0053E MFDBFH could not recover Region database or datastore url, RC return code.
    A call to MFDBFH recover the datastores or the region failed.
  • CASKC0054I WebSphere MQ !Queue Manager Name SUBSYSTEM security switch set ON, profile 'Security profile found' found
    A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned on.
  • CASKC0055I WebSphere MQ !Queue Manager Name Type security security switch set ON, profile 'Security profile found' found
    A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned on for type Type security.
  • CASKC0056E Program program name abend abend-codeabend-description.
    Transaction program name abnormally terminated with abend code abend-code.
  • CASKC0057I WebSphere MQ !Queue Manager Name Type security security switch set OFF, class 'Security Resource Class' not defined
    The security resource class Security Resource Class is not defined and security for WebSphere MQ has been turned off for type Type security.
  • CASKC0058W Process process-id soft-kill issued and hard-kill is disabled.
    Soft kill has been issued but hard kill is disabled.
  • CASKC0059S Process process-id of the process that is killed hard-killed because it was stuck.
    Process soft-kill failed and was hard-killed.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC0040I admin-msg

A remote client entered a message to the active system.
System Action:
None.
Module:
casasys
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0041E Transaction trans-id abend abend-codeabend-description.

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.
Module:
casmgr
Destination:
console.log
Parent topic: CASKC0040 - CASKC0059


CASKC0042I Transaction trans-id abend abend-codeabend-description. Backout Successful.

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.
Module:
dfheserv
Destination:
User terminal ,TDQ CSMT and console.log.
Parent topic: CASKC0040 - CASKC0059


CASKC0043E system-id Transaction trans-id failed with abend ASRA. Updates to local recoverable resources backed out.

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.
Module:
dfhebms
Destination:
User terminal ,TDQ CSMT and console.log.
Parent topic: CASKC0040 - CASKC0059


CASKC0044S ES failed to authorize CICS 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 CICS user.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0045I User (user-id) requested (request type) on Transaction (trans-id for request) from Tran (active trans-id) Program (active program) Terminal(terminal id).

Logging all enabled and disabled requests for CICS transactions.
Module:
dfhesysp
Destination:
CSKL
Parent topic: CASKC0040 - CASKC0059


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: CASKC0040 - CASKC0059


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: CASKC0040 - CASKC0059


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:
casmgr
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0049I Cancellation of Program (program-id for request) by user (user-id) - Return-code(return-code).

Cancellation of the specified program was attempted by the named user.

The result of this operation is given by the Return-code.

Module:
casatran
Destination:
CSMT and console.log
Parent topic: CASKC0040 - CASKC0059


CASKC0050S IMS DB Control process ABENDed and ES shutdown is configured

The IMS DB Control failed and ES is configured to shutdown immediately when this happens. i.e the environment variable ES_IMS_STOP_ON_DB_FAIL=Y is set to Y or y.
System Action:
Enterprise Server does an immediate shutdown.
Resolution:
Recover the IMS DB databases and restart the Enterprise Server.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0051E A storage violation was detected during task number task number.

On deallocation of local memory, we detected a storage violation for task number task number.
System Action:
SEP will be recycled.
Resolution:
Check the dump file for further info.
Module:
dfheserv
Destination:
TDQ CSMT and console.log.
Parent topic: CASKC0040 - CASKC0059


CASKC0052S One or more core process(es) terminated prior to initialization - shutting region down

one or more core CAS processes terminated before PIP1 has completed.

The region shuts down in this scenario.

System Action:
Enterprise Server does an immediate shutdown.
Resolution:
Check console for relevant messages. If none, Contact Customer Support with relevant diagnostics.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0053E MFDBFH could not recover Region database or datastore url, RC return code.

A call to MFDBFH recover the datastores or the region failed.
Resolution:
Recover using DBFHADMIN command, the issue might be a lost connection to the database.
Module:
casmgr or cassi
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0054I WebSphere MQ !Queue Manager Name SUBSYSTEM security switch set ON, profile 'Security profile found' found

A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned on.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0055I WebSphere MQ !Queue Manager Name Type security security switch set ON, profile 'Security profile found' found

A security profile Security profile found for Queue Manager Queue Manager Name has been found and security for WebSphere MQ has been turned on for type Type security.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0056E Program program name abend abend-codeabend-description.

Transaction program name 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.
Module:
casmgr
Destination:
console.log
Parent topic: CASKC0040 - CASKC0059


CASKC0057I WebSphere MQ !Queue Manager Name Type security security switch set OFF, class 'Security Resource Class' not defined

The security resource class Security Resource Class is not defined and security for WebSphere MQ has been turned off for type Type security.
System Action:
None.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0058W Process process-id soft-kill issued and hard-kill is disabled.

Soft kill has been issued but hard kill is disabled.
Resolution:
Check if the process did not terminate and decide what to do, either hard-kill it or not.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0059S Process process-id of the process that is killed hard-killed because it was stuck.

Process soft-kill failed and was hard-killed.
System Action:
nothing.
Resolution:
Correct the cause of the abnormal termination and re-submit the request.
Module:
casmgr
Destination:
System Console
Parent topic: CASKC0040 - CASKC0059


CASKC0200 - CASKC0219

  • CASKC0211E Transaction trans-id abend ASOS. Transaction cannot be queued as we are short on storage.
    Failure to queue the transaction for Tranclass as we are short on storage.
  • CASKC0212W Transaction trans-id has been attached with unknown tranclass tranclass-name
    Transaction trans-id has just been attached.
  • CASKC0213E Transaction trans-id abend AKCC. Purge threshold of its TRANCLASS has been reached. Backout successful.
    Transaction trans-id has been purged due to TRANCLASS PURGETHRESH constraints.
  • CASKC0214E Transaction trans-id abend AEIJ on XA start failure.
    Failure on xa start error requested by environment variable.
  • CASKC0215I User user-id issued PERFORM SHUTDOWN IMMEDIATE and/or DUMP as specifiedwith PLT-SD suffix PLT-SD suffix
    The user user-id initiated shutdown with the noted modifiers.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC0211E Transaction trans-id abend ASOS. Transaction cannot be queued as we are short on storage.

Failure to queue the transaction for Tranclass as we are short on storage.
System Action:
Transaction is abended.
Resolution:
Verify the state of the region and see if other transactions are not holding the system.
Module:
dfheserv
Destination:
Terminal end user & CSMT
Parent topic: CASKC0200 - CASKC0219


CASKC0212W Transaction trans-id has been attached with unknown tranclass tranclass-name

Transaction trans-id has just been attached.

It is defined as belonging to tranclass tranclass-name but tranclass-name does not exist. This message is only issued the first time transaction trans-id is attached with the unknown tranclass.

System Action:
The attach of transaction transid proceeds as normal but without being subject to any tranclass scheduling constraints.
Resolution:
If transaction transid should belong to tranclass tranclass-name, install that tranclass. If not, modify the transaction definition for trans-id as appropriate, and reinstall.
Module:
castsc
Destination:
System Console
Parent topic: CASKC0200 - CASKC0219


CASKC0213E Transaction trans-id abend AKCC. Purge threshold of its TRANCLASS has been reached. Backout successful.

Transaction trans-id has been purged due to TRANCLASS PURGETHRESH constraints.
System Action:
The transaction is abended and the transaction dump has been suppressed.
Resolution:
Resubmit the transaction. The cause of the abend may be a temporary stress condition in the system. If the problem persists, determine why the TRANCLASS purge threshold has been reached. Ensure that PURGETHRESH has been specified correctly. Also, ensure that the MAXACTIVE value of the TRANCLASS has not been set too low. Transactions attached after the MAXACTIVE limit has been reached are immediately queued subject to the PURGETHRESH limit. If PURGETHRESH and MAXACTIVE are set correctly, look for a more general problem which has caused a decrease in the capacity of the system to execute transactions in the TRANCLASS. The decrease might, for example, be caused by a connected CICS region which processes requests for transactions in the TRANCLASS, if this connected region has slowed down.
Module:
dfheserv
Destination:
Terminal end user & CSMT
Parent topic: CASKC0200 - CASKC0219


CASKC0214E Transaction trans-id abend AEIJ on XA start failure.

Failure on xa start error requested by environment variable.
System Action:
Transaction is abended.
Resolution:
Verify the state of the active XA entries in this region.
Module:
dfheserv
Destination:
Terminal end user & CSMT
Parent topic: CASKC0200 - CASKC0219


CASKC0215I User user-id issued PERFORM SHUTDOWN IMMEDIATE and/or DUMP as specifiedwith PLT-SD suffix PLT-SD suffix

The user user-id initiated shutdown with the noted modifiers.
System Action:
System Shutdown is initiated.
Module:
dfhesysp
Destination:
Console, Terminal & CSMT
Parent topic: CASKC0200 - CASKC0219


CASKC0300 - CASKC0319

  • CASKC0300E ES Thread Create for entry point "thread-entry-point-name" failed (RC: return-code) in module module.
    An ES threaded service process attempted to start a special purpose thread.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC0300E ES Thread Create for entry point "thread-entry-point-name" failed (RC: return-code) in module module.

An ES threaded service process attempted to start a special purpose thread.

The thread create operation reported an error.

Resolution:
Check the documentation for return-code values for Thread-control routines.
Module:
cascptrd
Destination:
System Console and standard error.
Parent topic: CASKC0300 - CASKC0319


CASKC1000 - CASKC1019

  • CASKC1000I ES concurrent request limit: client-count
    During startup the maximum number of concurrent requests is logged.
  • CASKC1001W Warning: Allocated license limit exceeded client-count times
    The number of active client requests exceeded the licensed maximum client-count times.
  • CASKC1002I ES allocated license limit: client-count-limit units, peak usage: client-count-actual units
    During shutdown the maximum number of concurrent requests is logged against the actual recorded peak.
  • CASKC1003I Feature feature-name license not available
    A request for a license of the referenced type was made to the license server.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC1000I ES concurrent request limit: client-count

During startup the maximum number of concurrent requests is logged.
Module:
casmgr
Destination:
System Console and standard error.
Parent topic: CASKC1000 - CASKC1019


CASKC1001W Warning: Allocated license limit exceeded client-count times

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.
Module:
casmgr
Destination:
System Console and standard error.
Parent topic: CASKC1000 - CASKC1019


CASKC1002I ES allocated license limit: client-count-limit units, peak usage: client-count-actual units

During shutdown the maximum number of concurrent requests is logged against the actual recorded peak.
Module:
casmgr
Destination:
System Console and standard error.
Parent topic: CASKC1000 - CASKC1019


CASKC1003I Feature feature-name license not available

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.

Module:
dfheserv
Destination:
System Console and standard error.
Parent topic: CASKC1000 - CASKC1019


CASKC2000 - CASKC2019

  • CASKC2000S Failed to DEQ on QNAME QNAME and RNAME RNAME
    We failed to release the RNAME resource for the QNAME.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC2000S Failed to DEQ on QNAME QNAME and RNAME RNAME

We failed to release the RNAME resource for the QNAME.
Resolution:
Action the message.
Module:
dfhgreq
Destination:
Console
Parent topic: CASKC2000 - CASKC2019


CASKC5000 - CASKC5019

  • CASKC5006I message
    The SEP, Batch Initiator or IMS MPR process issued a message.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC5006I message

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.
Module:
cascpsrv
Destination:
Console
Parent topic: CASKC5000 - CASKC5019


CASKC6000 - CASKC6019

  • CASKC6001S Unable to kill process process-id, recovery initiated
    A process was looping or hung and exceeded the specified task timeout.
  • CASKC6002I JOBjob-number terminated due to exceeding TIME parameter: number of seconds seconds
    A process was looping or hung and exceeded the specified TIME parameter on the JOB or STEP card.
  • CASKC6003I Transaction tran-id has exceeded its threshold of elapsed time threshold in seconds seconds
    A transaction exceeded its time threshold and is still running.
  • CASKC6004I Transaction tran-id completed but exceeded its threshold of elapsed time threshold in seconds seconds
    A transaction completed but exceeded its time threshold.
  • CASKC6005I IMS Transaction tran-id has exceeded its threshold of elapsed time threshold in seconds seconds
    An IMS transaction exceeded its time threshold and is still running.
  • CASKC6006I A Web Service has timed out
    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.
  • CASKC6009W JOBjob-number exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6010W JOBjob-number exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6011W JOBjob-number exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6012W JOBjob-number exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6013W JOBjob-number exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6014W JOBjob-number exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6015W IMS transaction IMS transaction exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6016W IMS transaction IMS transaction exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6017W IMS transaction IMS transaction exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6018W IMS transaction IMS transaction exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6019W IMS transaction IMS transaction exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC6001S Unable to kill process process-id, recovery initiated

A process was looping or hung and exceeded the specified task timeout.

The attempt to kill the process apparently 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: CASKC6000 - CASKC6019


CASKC6002I JOBjob-number terminated due to exceeding TIME parameter: number of seconds seconds

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.
Module:
casmgr or cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6003I Transaction tran-id has exceeded its threshold of elapsed time threshold in seconds seconds

A transaction exceeded its time threshold and is still running.
System Action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded.
Module:
casmgr or cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6004I Transaction tran-id completed but exceeded its threshold of elapsed time threshold in seconds seconds

A transaction completed but exceeded its time threshold.
System Action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded.
Module:
dfheserv
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6005I IMS Transaction tran-id has exceeded its threshold of elapsed time threshold in seconds seconds

An IMS transaction exceeded its time threshold and is still running.
System Action:
Warning message logged.
Resolution:
Investigate why threshold was exceeded.
Module:
casmgr or cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6006I A Web Service has timed out

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.
Module:
cashtsrv
Destination:
Console and standard error
Parent topic: CASKC6000 - CASKC6019


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 or cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


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 apparently 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: CASKC6000 - CASKC6019


CASKC6009W JOBjob-number exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6010W JOBjob-number exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6011W JOBjob-number exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6012W JOBjob-number exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6013W JOBjob-number exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6014W JOBjob-number exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6015W IMS transaction IMS transaction exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6016W IMS transaction IMS transaction exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6017W IMS transaction IMS transaction exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6018W IMS transaction IMS transaction exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6019W IMS transaction IMS transaction exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6000 - CASKC6019


CASKC6020 - CASKC6039

  • CASKC6020W IMS transaction IMS transaction exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6021W CICS transaction CICS transaction exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6022W CICS transaction CICS transaction exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6023W CICS transaction CICS transaction exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6024W CICS transaction CICS transaction exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6025W CICS transaction CICS transaction exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6026W CICS transaction CICS transaction exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6027I Enterprise Server time keeper daemon initialized
    The time keeper daemon has started.
  • CASKC6028I Enterprise Server time keeper daemon terminating
    The time keeper daemon is shutting down.
  • CASKC6029I Enterprise Server time keeper daemon already active
    The time keeper daemon is already running.
  • CASKC6030W CGI program CGI program exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6031W CGI program CGI program exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6032W CGI program CGI program exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6033W CGI program CGI program exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.
    A process exceeded the specified threshold value specified.
  • CASKC6034W CGI program CGI program exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.
    A process exceeded the specified threshold value specified.
  • CASKC6035W CGI program CGI program exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.
    A process exceeded the specified threshold value specified.
  • CASKC6036I Enterprise Server recovery MFDBFH daemon initialized
    The recovery MFDBFH daemon has started.
  • CASKC6037I Enterprise Server recovery MFDBFH daemon terminating
    The recovery MFDBFH daemon is shutting down.
  • CASKC6038I Enterprise Server recovery MFDBFH daemon already active
    The recovery MFDBFH daemon is already running.
  • CASKC6039E Enterprise Server recovery MFDBFH daemon could not load casmfdbfh
    The CAS interface to MFDBFH could not be loaded.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC6020W IMS transaction IMS transaction exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6021W CICS transaction CICS transaction exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6022W CICS transaction CICS transaction exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6023W CICS transaction CICS transaction exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6024W CICS transaction CICS transaction exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6025W CICS transaction CICS transaction exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6026W CICS transaction CICS transaction exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6027I Enterprise Server time keeper daemon initialized

The time keeper daemon has started.
System Action:
Log message and terminate the process.
Resolution:
n/a.
Module:
castkpd
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6028I Enterprise Server time keeper daemon terminating

The time keeper daemon is shutting down.
System Action:
Log message and terminate the process.
Resolution:
n/a.
Module:
castkpd
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6029I Enterprise Server time keeper daemon already active

The time keeper daemon is already running.
System Action:
Log message and terminate the process.
Resolution:
n/a.
Module:
castkpd
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6030W CGI program CGI program exceeded CPU threshold limit of CPU threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6031W CGI program CGI program exceeded MEM threshold limit of MEM threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6032W CGI program CGI program exceeded ELAPSED time threshold limit of ELAPSED time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6033W CGI program CGI program exceeded CPU purge threshold limit of CPU purge threshold ms. Actual: Actual CPU usage ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6034W CGI program CGI program exceeded MEM purge threshold limit of MEM purge threshold kb. Actual: Actual MEM usage kb.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6035W CGI program CGI program exceeded ELAPSED purge time threshold limit of ELAPSED purge time threshold ms. Actual: Actual ELAPSED time ms.

A process exceeded the specified threshold value specified.
System Action:
Log message and terminate the process.
Resolution:
Investigate why the processing limit was exceeded.
Module:
cascpmth
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6036I Enterprise Server recovery MFDBFH daemon initialized

The recovery MFDBFH daemon has started.
System Action:
Log message and terminate the process.
Resolution:
n/a.
Module:
casrecdb
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6037I Enterprise Server recovery MFDBFH daemon terminating

The recovery MFDBFH daemon is shutting down.
System Action:
Log message and terminate the process.
Resolution:
n/a.
Module:
casrecdb
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6038I Enterprise Server recovery MFDBFH daemon already active

The recovery MFDBFH daemon is already running.
System Action:
Log message and terminate the process.
Resolution:
n/a.
Module:
casrecdb
Destination:
System Console
Parent topic: CASKC6020 - CASKC6039


CASKC6039E Enterprise Server recovery MFDBFH daemon could not load casmfdbfh

The CAS interface to MFDBFH could not be loaded.
Module:
casrecdb
Destination:
Console
Parent topic: CASKC6020 - CASKC6039


CASKC6040 - CASKC6059

  • CASKC6041E Failed to clean-up leftover ITR records in the PSOR
    Error has occurred during recovery processing preventing all related ITR records in the CasITR store from being removed.
Parent topic: CASKC - CICS Task Control Error Messages


CASKC6041E Failed to clean-up leftover ITR records in the PSOR

Error has occurred during recovery processing preventing all related ITR records in the CasITR store from being removed.
Resolution:
Check the state of the PSOR.
Module:
casmgr
Destination:
Console
Parent topic: CASKC6040 - CASKC6059


CASMG - Error Message File Error Messages

  • CASMG0000 - CASMG0019
  • CASMG9980 - CASMG9999
Parent topic: Enterprise Server Error Messages


CASMG0000 - CASMG0019

  • CASMG0001I application display text
    A display upon console message - informational.
Parent topic: CASMG - Error Message File Error Messages


CASMG0001I application display text

A display upon console message - informational.
System Action:
None.
Module:
dfheserv, cabat, casmpr
Destination:
System Console
Parent topic: CASMG0000 - CASMG0019


CASMG9980 - CASMG9999

  • CASMG9999E <message number>, <message insert> , <message insert> ...
    The system could not locate a message in the message file so displayed a standard message number.
Parent topic: CASMG - Error Message File 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 on line help for information on the missing message.
Module:
<any>
Destination:
STDOUT
Parent topic: CASMG9980 - CASMG9999


CASMQ - Trigger Monitor Error Messages

  • CASMQ1000 - CASMQ1019
  • CASMQ1020 - CASMQ1039
  • CASMQ5000 - CASMQ5019
  • CASMQ5040 - CASMQ5059
  • CASMQ5060 - CASMQ5079
  • CASMQ5080 - CASMQ5099
Parent topic: Enterprise Server Error Messages


CASMQ1000 - CASMQ1019

  • CASMQ1001I Connection to WebSphere MQ re-established.
    The WebSphere MQ trigger monitor program (CKTI) has re-established the connection to the MQ server.
  • 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.
  • 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.
  • 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.
  • 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
    he 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 - Trigger Monitor 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: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


CASMQ1008I IMS Trigger Monitor initialization completed

The IMS WebSphere MQ Trigger Monitor successfully initialized.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1000 - CASMQ1019


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: CASMQ1000 - CASMQ1019


CASMQ1010I IMS Trigger Monitor terminated

The IMS WebSphere MQ Trigger Monitor terminated.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1000 - CASMQ1019


CASMQ1011E Unexpected error while connecting to queue manager queue-manager-name in 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 terminated.
Resolution:
Ensure that the Queue Manager in the Trigger Monitor startup JCL is correct.
Module:
csq4trmn
Destination:
Console
Parent topic: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - 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: CASMQ1000 - CASMQ1019


CASMQ1020 - CASMQ1039

  • 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.
  • CASMQ1029E error-msg
    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 - Trigger Monitor 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 - CASMQ1039


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


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


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


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


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


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


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


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


CASMQ1029E error-msg

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


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


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


CASMQ5000 - CASMQ5019

  • 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.
  • 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.
  • 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.
  • CASMQ5009W ES MQ Service Process Error binding to MFDS
    An error occurred whilst binding to the MF Directory Server.
  • CASMQ5010W ES MQ Service Process Error (error-message) retrieving ES configuration from MFDS
    An error occurred whilst retrieving the ES configuration from the MF Directory Server.
  • CASMQ5011I ES MQ Service Process restart in progress
    The IMS TM Control process has been restarted and recovery operations are in progress.
  • CASMQ5012E mqb-service-error-message
    The ES MQ Service Process issued an error message.
Parent topic: CASMQ - Trigger Monitor Error Messages


CASMQ5001I ES MQ Service Process initialization started

The server ES MQ Service Process initialization has started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


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: CASMQ5000 - CASMQ5019


CASMQ5003I ES MQ Service Process initialization complete

The ES MQ Service Process has completed initialization.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


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: CASMQ5000 - CASMQ5019


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: CASMQ5000 - CASMQ5019


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: CASMQ5000 - CASMQ5019


CASMQ5007I ES MQ Service Process termination started

The ES MQ Service Process is terminating.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


CASMQ5008I ES MQ Service Process termination complete

The ES MQ Service Process has terminated.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


CASMQ5009W ES MQ Service Process Error binding to MFDS

An error occurred whilst binding to the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


CASMQ5010W ES MQ Service Process Error (error-message) retrieving ES configuration from MFDS

An error occurred whilst retrieving the ES configuration from the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


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: CASMQ5000 - CASMQ5019


CASMQ5012E mqb-service-error-message

The ES MQ Service Process issued an error message.

The text is mqb-service-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5000 - CASMQ5019


CASMQ5040 - CASMQ5059

  • 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.
Parent topic: CASMQ - Trigger Monitor 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: CASMQ5040 - CASMQ5059


CASMQ5060 - CASMQ5079

  • 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 listener name for MQ-Queue-Manager requested
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ Queue listener name on manager MQ-Queue-Manager.
  • CASMQ5062I ES MQ Listener MQ Queue listener name for MQ-Queue-Manager stopped
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ Queue listener name on manager MQ-Queue-Manager.
  • CASMQ5063E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager failed, reason: MQ reason code
    The ES MQ Service Process is starting to listen for messages to initiation queue MQ Queue listener name on manager MQ-Queue-Manager.
  • CASMQ5064E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager open failed, reason: MQ reason code
    The WebSphere MQ trigger monitor task failed to connect to the MQ Queue listener name queue manager.
  • CASMQ5065E ES MQ Queue Manager queue-manager-name security failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASMQ5066E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager initialization failed, reason: MQ reason code
    The WebSphere MQ trigger monitor task failed to connect to the MQ-Queue-Manager queue manager.
  • CASMQ5067E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager connection lost, reason: MQ reason code, retrying...
    The WebSphere MQ trigger monitor task failed to connect to the MQ-Queue-Manager queue manager.
  • CASMQ5069I ES MQ Listener MQ Queue listener name for MQ-Queue-Manager connected
    The ES MQ Service Process is starting to listen for messages to initiation queue on manager MQ-Queue-Manager.
  • CASMQ5070E ES MQ Listener MQ Queue listener name Queue Manager MQ-Queue-Manager connect failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed to connect to the MQ-Queue-Manager 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.
  • CASMQ5072I ES MQ system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced
    A dump of the ES MQ process was generated with a DUMPCODE of dump-code.
  • 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.
  • 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 - Trigger Monitor Error Messages


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: CASMQ5060 - CASMQ5079


CASMQ5061I ES MQ Listener MQ Queue listener name for MQ-Queue-Manager requested

The ES MQ Service Process is starting to listen for messages to initiation queue MQ Queue listener name on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5060 - CASMQ5079


CASMQ5062I ES MQ Listener MQ Queue listener name for MQ-Queue-Manager stopped

The ES MQ Service Process is starting to listen for messages to initiation queue MQ Queue listener name on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5060 - CASMQ5079


CASMQ5063E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager failed, reason: MQ reason code

The ES MQ Service Process is starting to listen for messages to initiation queue MQ Queue listener name on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5060 - CASMQ5079


CASMQ5064E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager open failed, reason: MQ reason code

The WebSphere MQ trigger monitor task failed to connect to the MQ Queue listener 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: CASMQ5060 - CASMQ5079


CASMQ5065E ES MQ Queue Manager queue-manager-name security 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: CASMQ5060 - CASMQ5079


CASMQ5066E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager initialization failed, reason: MQ reason code

The WebSphere MQ trigger monitor task failed to connect to the MQ-Queue-Manager 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: CASMQ5060 - CASMQ5079


CASMQ5067E ES MQ Listener MQ Queue listener name for MQ-Queue-Manager connection lost, reason: MQ reason code, retrying...

The WebSphere MQ trigger monitor task failed to connect to the MQ-Queue-Manager 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: CASMQ5060 - CASMQ5079


CASMQ5069I ES MQ Listener MQ Queue listener name for MQ-Queue-Manager connected

The ES MQ Service Process is starting to listen for messages to initiation queue on manager MQ-Queue-Manager.
System Action:
The MQ listener thread is started.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5060 - CASMQ5079


CASMQ5070E ES MQ Listener MQ Queue listener name Queue Manager MQ-Queue-Manager connect failed, reason: failure-reason

The WebSphere MQ trigger monitor task failed to connect to the MQ-Queue-Manager 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: CASMQ5060 - 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: CASMQ5060 - CASMQ5079


CASMQ5072I ES MQ system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced

A dump of the ES MQ process was generated with a DUMPCODE of dump-code.

The caller was dump-caller and it was written to DATASET dump-dataset.

System Action:
The ES MQ service process produces an ES system dump.
Module:
casmqb
Destination:
Console
Parent topic: CASMQ5060 - 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: CASMQ5060 - 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: CASMQ5060 - 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: CASMQ5060 - 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: CASMQ5060 - 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: CASMQ5060 - 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: CASMQ5060 - 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: CASMQ5060 - CASMQ5079


CASMQ5080 - CASMQ5099

  • CASMQ5080I ES MQ Queue Manager default-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.
  • 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.
  • CASMQ5088I ES MQ service process (PID:process-id) recovery initiated
    The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASMQ5089W ES MQ listener queue name not specified
    A MQ listener has been specified without a valid queue name.
Parent topic: CASMQ - Trigger Monitor Error Messages


CASMQ5080I ES MQ Queue Manager default-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 - CASMQ5099


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


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


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


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


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


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


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


CASMQ5088I ES MQ service process (PID:process-id) recovery initiated

The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
casmqb
Destination:
Console and standard error.
Parent topic: CASMQ5080 - CASMQ5099


CASMQ5089W ES MQ listener queue name not specified

A MQ listener has been specified without a valid queue name.
Resolution:
Check MQ listener configuration.
Module:
casmqb
Destination:
Console and standard error.
Parent topic: CASMQ5080 - CASMQ5099


CASMS - CICS Trigger Monitor Error Messages

  • CASMS0000 - CASMS0019
Parent topic: Enterprise Server Error Messages


CASMS0000 - CASMS0019

  • 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.
  • 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.
  • CASMS0012I About to delete mapset mapset-name, press <ENTER> to confirm
    A delete request was issued for the mapset named, this message requests confirmation.
  • 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: CASMS - CICS Trigger Monitor 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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


CASMS0011E Internal processing error return-code

The transaction encountered an internal processing error.

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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


CASMS0014I transid transaction complete

The transaction completed normally.
Module:
dfhzcmap
Destination:
Terminal
Parent topic: CASMS0000 - CASMS0019


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: CASMS0000 - CASMS0019


CASOP - CICS User Messages to Console

  • CASOP0000 - CASOP0019
  • CASOP1000 - CASOP1019
  • CASOP1900 - CASOP1919
Parent topic: Enterprise Server Error Messages


CASOP0000 - CASOP0019

  • 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.
  • 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.
  • 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.
  • 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.
Parent topic: CASOP - CICS User Messages to Console


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: CASOP0000 - CASOP0019


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: CASOP0000 - CASOP0019


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: CASOP0000 - CASOP0019


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: CASOP0000 - CASOP0019


CASOP1000 - CASOP1019

  • 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.
Parent topic: CASOP - CICS User Messages to Console


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: CASOP1000 - CASOP1019


CASOP1900 - CASOP1919

  • 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.
  • 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: CASOP - CICS User Messages to Console


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: CASOP1900 - CASOP1919


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: CASOP1900 - CASOP1919


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: CASOP1900 - CASOP1919


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: CASOP1900 - CASOP1919


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: CASOP1900 - CASOP1919


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: CASOP1900 - CASOP1919


CASPA - Scale-Out Performance and Availability Cluster Error Messages

  • CASPA1000 - CASPA1019
  • CASPA2060 - CASPA2079
  • CASPA2100 - CASPA2119
  • CASPA3000 - CASPA3019
Parent topic: Enterprise Server Error Messages


CASPA1000 - CASPA1019

  • CASPA1000W Process could not connect to Scale Out Repository SOR name. RC=Return code from SOR connect
    The process could not connect to the SOR TS/TD queues hosted in this SOR will be inaccessible whilst disconnected.
  • CASPA1001I Process connected to Scale Out Repository SOR name.
    The process can now connect to the SOR.
  • CASPA1002E Process could not connect to PSOR PSOR name. Retrying connection...
    The process could not connect to the PSOR TS/TD queues hosted in this SOR will be inaccessible whilst disconnected.
Parent topic: CASPA - Scale-Out Performance and Availability Cluster Error Messages


CASPA1000W Process could not connect to Scale Out Repository SOR name. RC=Return code from SOR connect

The process could not connect to the SOR TS/TD queues hosted in this SOR will be inaccessible whilst disconnected.
System Action:
Will retry the connection at queue access time.
Resolution:
Check the Scale Out Repository and that it is accessible.
Module:
cascpstr
Destination:
Console
Parent topic: CASPA1000 - CASPA1019


CASPA1001I Process connected to Scale Out Repository SOR name.

The process can now connect to the SOR.
System Action:
Access to the SOR will now be resumed.
Resolution:
Work can now be directed to the region hosting this process.
Module:
cascpstr
Destination:
Console
Parent topic: CASPA1000 - CASPA1019


CASPA1002E Process could not connect to PSOR PSOR name. Retrying connection...

The process could not connect to the PSOR TS/TD queues hosted in this SOR will be inaccessible whilst disconnected.

If this is a PSOR then we will retry for a period of time.

System Action:
Will retry the connect.
Resolution:
Check the Scale Out Repository and that it is accessible.
Module:
SEPs/Initiators/MPRs
Destination:
Console
Parent topic: CASPA1000 - CASPA1019


CASPA2060 - CASPA2079

  • CASPA2065E Region lost connection to Redis server Redis server name at Redis server address port Redis port number
    The region lost the connection to Redis.
  • CASPA2066I PAC has been switched to Operating mode operating mode
    The working mode for this PAC has been switched.
  • CASPA2068W Region received an ITR but at least one SEP failed to process it. Type=Type of ITR, Action=Action on ITR, Resource=Resource, ITR RC=ITR return code
    The request for the ITR failed.
  • CASPA2069E Region lost connection to Coherence using Coherence connection string
    The region lost the connection to Coherence.
Parent topic: CASPA - Scale-Out Performance and Availability Cluster Error Messages


CASPA2065E Region lost connection to Redis server Redis server name at Redis server address port Redis port number

The region lost the connection to Redis.
System Action:
will try to reconnect.
Resolution:
check the Redis server.
Module:
casras
Destination:
Console
Parent topic: CASPA2060 - CASPA2079


CASPA2066I PAC has been switched to Operating mode operating mode

The working mode for this PAC has been switched.
System Action:
The specified working mode will take effect.
Module:
casras
Destination:
Console
Parent topic: CASPA2060 - CASPA2079


CASPA2068W Region received an ITR but at least one SEP failed to process it. Type=Type of ITR, Action=Action on ITR, Resource=Resource, ITR RC=ITR return code

The request for the ITR failed.
Resolution:
Contact Micro Focus Customer Support.
Module:
casras
Destination:
Console
Parent topic: CASPA2060 - CASPA2079


CASPA2069E Region lost connection to Coherence using Coherence connection string

The region lost the connection to Coherence.
System Action:
will try to reconnect.
Resolution:
check the Coherence cluster.
Module:
casras
Destination:
Console
Parent topic: CASPA2060 - CASPA2079


CASPA2100 - CASPA2119

  • CASPA2100W PAC ITR wait fail on ITR type for Resource name: No ITR records found in PSOR. Check other regions in PAC for ITR failures.
    The issuer of a PAC ITR failed to retrieve any ITR records from the PSOR.
  • CASPA2101W PAC ITR wait fail on ITR type for Resource name: Unexpected number of PAC ITR records found in PSOR. Check other regions in PAC for ITR failures.
    The issuer of a PAC ITR detected an unexpected number of ITR records in the PSOR.
  • CASPA2102W PAC ITR wait fail on ITR type for Resource name: At least one process failed to process the ITR. Check other regions in PAC for ITR failures.
    The issuer of a PAC ITR detected that at least one process failed to process the ITR.
  • CASPA2103W PAC ITR wait fail on ITR type for Resource name: Unknown error returned on the ITR.
    Received an unknown return code.
  • CASPA2104E ITR type error for Resource name: ITR not sent to Region name and host because it has not pinged the PAC SOR for Duration since last ping from region seconds.
    ITR record for resource Resource name not created in PSOR for region Region name and host because it has not pinged PSOR for more than Duration since last ping from region seconds.
  • CASPA2105S Region cannot be started because an incompatible record (Record type) was found in the PSOR.
    The current region failed to start as an incompatible record was located in the PSOR.
  • CASPA2106E Error trying to synchronize Load module type (CICS, JES, etc) load modules from PAC PAC Name CasLOADS for this region. Error code Return code from synchronization.
    The current region failed to synchronize load modules from the PAC.
  • CASPA2107E CASPAC store is locked. Retrying
    CASPAC store is locked. possibly by another region or caspac command line.
  • CASPA2108E Failed to get a lock on CASPAC store. RC=RC.
    CASPAC store is locked. possibly by another region or caspac command line.
  • CASPA2109W PAC ITR wait fail on ITR type for Resource name: Issuer disconnected.
    Issuer of ITR exited prior to remote PAC regions proxessing the ITR.
  • CASPA2110W PAC ITR wait fail on ITR type for Resource name: DCA disabled.
    A problem occurred whilst waiting on an ITR which resulted in the DCA being disabled.
Parent topic: CASPA - Scale-Out Performance and Availability Cluster Error Messages


CASPA2100W PAC ITR wait fail on ITR type for Resource name: No ITR records found in PSOR. Check other regions in PAC for ITR failures.

The issuer of a PAC ITR failed to retrieve any ITR records from the PSOR.
Resolution:
Check console logs of the PAC regions.
Module:
dfhgreq
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2101W PAC ITR wait fail on ITR type for Resource name: Unexpected number of PAC ITR records found in PSOR. Check other regions in PAC for ITR failures.

The issuer of a PAC ITR detected an unexpected number of ITR records in the PSOR.
Resolution:
Check console logs of the PAC regions.
Module:
dfhgreq
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2102W PAC ITR wait fail on ITR type for Resource name: At least one process failed to process the ITR. Check other regions in PAC for ITR failures.

The issuer of a PAC ITR detected that at least one process failed to process the ITR.
Resolution:
Check console logs of the PAC regions.
Module:
dfhgreq
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2103W PAC ITR wait fail on ITR type for Resource name: Unknown error returned on the ITR.

Received an unknown return code.
Resolution:
Contact Micro Focus Customer Support.
Module:
dfhgreq
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2104E ITR type error for Resource name: ITR not sent to Region name and host because it has not pinged the PAC SOR for Duration since last ping from region seconds.

ITR record for resource Resource name not created in PSOR for region Region name and host because it has not pinged PSOR for more than Duration since last ping from region seconds.
System Action:
The referenced region will be ignored and hence will not process the request for the resource.
Resolution:
See PAC documentation.
Module:
casstore
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2105S Region cannot be started because an incompatible record (Record type) was found in the PSOR.

The current region failed to start as an incompatible record was located in the PSOR.
System Action:
Shutdown the region.
Resolution:
Check the version of your PAC members is compatible.
Module:
casstore
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2106E Error trying to synchronize Load module type (CICS, JES, etc) load modules from PAC PAC Name CasLOADS for this region. Error code Return code from synchronization.

The current region failed to synchronize load modules from the PAC.
Resolution:
All regions in a PAC need to be able to synchronize load modules, check the error.
Module:
casras
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2107E CASPAC store is locked. Retrying

CASPAC store is locked. possibly by another region or caspac command line.
System Action:
The process retries again to acquire lock.
Resolution:
check the other regions in the PAC if a lock is being held. Contact support.
Module:
cascd
Destination:
System Console
Parent topic: CASPA2100 - CASPA2119


CASPA2108E Failed to get a lock on CASPAC store. RC=RC.

CASPAC store is locked. possibly by another region or caspac command line.
System Action:
The process will not try again.
Resolution:
check the other regions in the PAC if anyone is holding the lock. Contact support.
Module:
cascd
Destination:
System Console
Parent topic: CASPA2100 - CASPA2119


CASPA2109W PAC ITR wait fail on ITR type for Resource name: Issuer disconnected.

Issuer of ITR exited prior to remote PAC regions proxessing the ITR.
Resolution:
Contact Micro Focus Customer Support.
Module:
dfhgreq
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA2110W PAC ITR wait fail on ITR type for Resource name: DCA disabled.

A problem occurred whilst waiting on an ITR which resulted in the DCA being disabled.
Resolution:
Contact Micro Focus Customer Support.
Module:
dfhgreq
Destination:
Console
Parent topic: CASPA2100 - CASPA2119


CASPA3000 - CASPA3019

  • CASPA3000W Failure on PAC ITR close of extra-partition TD queue TD queue name. RC=Error code from PAC ITR
    At least one region failed to close the file.
Parent topic: CASPA - Scale-Out Performance and Availability Cluster Error Messages


CASPA3000W Failure on PAC ITR close of extra-partition TD queue TD queue name. RC=Error code from PAC ITR

At least one region failed to close the file.
System Action:
DCT marked closed.
Resolution:
Investigate and fix reason for close failure. Contact support.
Module:
cassi
Destination:
System Console
Parent topic: CASPA3000 - CASPA3019


CASPC - CICS Program Control Error Messages

  • CASPC0000 - CASPC0019
Parent topic: Enterprise Server Error Messages


CASPC0000 - CASPC0019

  • 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.
  • CASPC0003I CRUN usage: CRUN {program-name}
    No input was supplied with the transaction.
  • CASPC0004I COMMAREA passed to CRUN
    A COMMAREA was passed to the supplied transaction CRUN.
  • CASPC0005E Failed to update PSOR version of PCT PCT name. Check status of PSOR.
    An update to the local PCT was not reflected in the PSOR copy.
Parent topic: CASPC - CICS Program Control 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: CASPC0000 - CASPC0019


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: CASPC0000 - CASPC0019


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: CASPC0000 - CASPC0019


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: CASPC0000 - CASPC0019


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: CASPC0000 - CASPC0019


CASPC0005E Failed to update PSOR version of PCT PCT name. Check status of PSOR.

An update to the local PCT was not reflected in the PSOR copy.
Resolution:
Check PSOR is accessible.
Module:
dfheserv
Destination:
console, CSFL
Parent topic: CASPC0000 - CASPC0019


CASPI - WebSphere Error Messages

  • CASPI0100 - CASPI0119
  • CASPI0300 - CASPI0319
  • CASPI0400 - CASPI0419
  • CASPI0440 - CASPI0459
  • CASPI0500 - CASPI0519
  • CASPI0700 - CASPI0719
  • CASPI0900 - CASPI0919
  • CASPI0940 - CASPI0959
  • CASPI0980 - CASPI0999
  • CASPI1000 - CASPI1019
  • CASPI1560 - CASPI1579
  • CASPI4920 - CASPI4939
  • CASPI9640 - CASPI9659
Parent topic: Enterprise Server Error Messages


CASPI0100 - CASPI0119

  • CASPI0110E Date Time Applid An attempt to start transaction CPIH by something other than an attach request from web domain has been made. This is not allowed.
    An attempt has been made to start transaction CPIH by some method other than a transaction attach from web domain.
  • CASPI0111E Date Time Applid Tranid Call to WebSphere MQ function MQ function returned with reason code MQ reason code. Transaction abended.
    A WebSphere MQ function call issued by transaction CPIL was unsuccessful and has set a non-zero reason code.
  • CASPI0112E Date Time Applid Tranid Unable to locate URIMAP to match HOST Hostname and PATH Pathname. Unable to process inbound MQ message.
    A WebSphere MQ message has been received on queue hostname and with targetService pathname, but no match was found when attempting to locate a URIMAP with this host and path.
  • CASPI0113E Date Time Applid Tranid URIMAP urimapname has been located for HOST hostname and PATH pathname, but does not have USAGE(PIPELINE). Unable to process inbound MQ message.
    A WebSphere MQ message has been received on queue hostname and with targetService pathname, and a matching URIMAP urimapname was found.
  • CASPI0114E Date Time Applid Tranid The pipeline MQ transport mechanism failed because a call to WebSphere MQ function MQ function returned with reason code MQ reason_code.
    A WebSphere MQ function call issued by the pipeline MQ transport mechanism was unsuccessful and has set a non-zero reason code.
  • CASPI0115I Date Time Applid Tranid The service provider pipeline has returned a response message to the MQ transport, but the inbound request did not expect a response. The response message is ignored.
Parent topic: CASPI - WebSphere Error Messages


CASPI0110E Date Time Applid An attempt to start transaction CPIH by something other than an attach request from web domain has been made. This is not allowed.

An attempt has been made to start transaction CPIH by some method other than a transaction attach from web domain.

Transaction CPIH is a system task and cannot be entered from a terminal.

System Action:
The CPIH transaction has not been started.
Resolution:
Do not attempt to enter CPIH from a terminal or from any other device. CICS will start the transaction if a PIPELINE request is made via a TCP/IP attached client. No user action is required.
Module:
dfhpidsh
Destination:
CPIO TD queue
Parent topic: CASPI0100 - CASPI0119


CASPI0111E Date Time Applid Tranid Call to WebSphere MQ function MQ function returned with reason code MQ reason code. Transaction abended.

A WebSphere MQ function call issued by transaction CPIL was unsuccessful and has set a non-zero reason code.

The transaction CPIL is used to start a PIPELINE for a message received from WebSphere MQ.

System Action:
The transaction is abended with abend code APIJ.
Resolution:
Check the WebSphere MQ reason code in the MQ documentation.
Module:
dfhpilsq
Destination:
CPIO TD queue
Parent topic: CASPI0100 - CASPI0119


CASPI0112E Date Time Applid Tranid Unable to locate URIMAP to match HOST Hostname and PATH Pathname. Unable to process inbound MQ message.

A WebSphere MQ message has been received on queue hostname and with targetService pathname, but no match was found when attempting to locate a URIMAP with this host and path.

No pipeline processing can be done for this WebSphere MQ mes.

System Action:
The inbound message is placed on the Dead Letter Queue and a report message is sent to the ReplyTo queue.
Resolution:
Define and install a suitable URIMAP to match this combination of host and path which will identify the PIPELINE (and optionally WEBSERVICE) to process requests using this combination of queue name and targetService.
Module:
dfhpilsq
Destination:
CPIO TD queue
Parent topic: CASPI0100 - CASPI0119


CASPI0113E Date Time Applid Tranid URIMAP urimapname has been located for HOST hostname and PATH pathname, but does not have USAGE(PIPELINE). Unable to process inbound MQ message.

A WebSphere MQ message has been received on queue hostname and with targetService pathname, and a matching URIMAP urimapname was found.

However, this URIMAP was not defined with USAGE(PIPELINE). Therefore, no pipeline processing can be.

System Action:
The inbound message is placed on the Dead Letter Queue and a report message is sent to the ReplyTo queue.
Resolution:
Define and install a suitable URIMAP to match this combination of host and path with USAGE(PIPELINE) which will identify the PIPELINE (and optionally WEBSERVICE) to process requests using this combination of queue name and targetServic.
Module:
dfhpilsq
Destination:
CPIO TD queue
Parent topic: CASPI0100 - CASPI0119


CASPI0114E Date Time Applid Tranid The pipeline MQ transport mechanism failed because a call to WebSphere MQ function MQ function returned with reason code MQ reason_code.

A WebSphere MQ function call issued by the pipeline MQ transport mechanism was unsuccessful and has set a non-zero reason code.
System Action:
The pipeline MQ transport mechanism returns an exception response to the pipeline manager which performs further error processing.
Resolution:
Check the WebSphere MQ reason code in the MQ CICSPlex SM Messages and Codes manual.
Module:
dfhpitq1
Destination:
CPIO TD queue
Parent topic: CASPI0100 - CASPI0119


CASPI0115I Date Time Applid Tranid The service provider pipeline has returned a response message to the MQ transport, but the inbound request did not expect a response. The response message is ignored.

System Action:
The response is ignored by the WebSphere MQ transport module. The transport module returns control to the pipeline manager with no error indication, and pipeline processing will complete normally.
Resolution:
Check the definitions of the web service in the service requester and service provider and ensure that both indicate one-way request, or both indicate a reply is expected.
Module:
dfhpitq1
Destination:
CPIO TD queue
Parent topic: CASPI0100 - CASPI0119


CASPI0300 - CASPI0319

  • CASPI0300E Date Time Applid CICS could not invoke WEBSERVICE WebService because it was unable to find container container_name.
    The WEBSERVICE WebService could not be invoked because the container container_name was not found.
Parent topic: CASPI - WebSphere Error Messages


CASPI0300E Date Time Applid CICS could not invoke WEBSERVICE WebService because it was unable to find container container_name.

The WEBSERVICE WebService could not be invoked because the container container_name was not found.

An exception response from the program which gets the container was received.

System Action:
An exception response will be returned to the exec interface module which requested the INVOKE WEBSERVICE.
Resolution:
None.
Module:
dfhpildsq dfhpitq1
Destination:
CPIO TD queue
Parent topic: CASPI0300 - CASPI0319


CASPI0400 - CASPI0419

  • CASPI0400E Date Time Applid Tranid The CICS pipeline HTTP transport mechanism failed to send a request because Reason Error. Problem occurred for URI URI.
    The CICS pipeline HTTP transport mechanism was unable to successfully handle the outbound request because of described reason.
  • CASPI0403E Date Time Applid Tranid The CICS pipeline HTTP transport mechanism failed to receive a response because Reason Error. Problem occurred for URI URI.
    The CICS pipeline HTTP transport mechanism did not successfully receive a response to the outbound request due to the reason indicated in the message.
  • CASPI0404E Date Time Applid Tranid A failure occurred in the CICS pipeline HTTP transport mechanism for PIPELINE Pipeline WEBSERVICE Web Service Name.
    A failure occurred in the CICS pipeline HTTP transport mechanism for the named PIPELINE and WEBSERVICE.
  • CASPI0406E Date Time Applid Tranid INVOKE SERVICE was unsuccessful due to a failure on WEB CONVERSE with EIBRESP EIBRESP and EIBRESP2 EIBRESP2.
    INVOKE SERVICE was unsuccessful due to a failure on WEB CONVERSE with EIBRESP EIBRESP and EIBRESP2 EIBRESP2.
  • CASPI0410W Date Time Applid Tranid Failure to write SOAPAction header in the CICS pipeline HTTP transport mechanism for PIPELINE Pipeline WEBSERVICE Web Service Name.
    Failed to write the SOAPAction header.
Parent topic: CASPI - WebSphere Error Messages


CASPI0400E Date Time Applid Tranid The CICS pipeline HTTP transport mechanism failed to send a request because Reason Error. Problem occurred for URI URI.

The CICS pipeline HTTP transport mechanism was unable to successfully handle the outbound request because of described reason.
System Action:
The request is not sent. Error processing will continue.
Resolution:
check that the URI specified as input is correct and valid.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0400 - CASPI0419


CASPI0403E Date Time Applid Tranid The CICS pipeline HTTP transport mechanism failed to receive a response because Reason Error. Problem occurred for URI URI.

The CICS pipeline HTTP transport mechanism did not successfully receive a response to the outbound request due to the reason indicated in the message.
System Action:
The request is abandoned. Error processing will continue.
Resolution:
For a timeout error: Investigate why the remote server failed to respond in a timely manner. Consider changing the RESPWAIT value for the pipeline which processes these web service requests.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0400 - CASPI0419


CASPI0404E Date Time Applid Tranid A failure occurred in the CICS pipeline HTTP transport mechanism for PIPELINE Pipeline WEBSERVICE Web Service Name.

A failure occurred in the CICS pipeline HTTP transport mechanism for the named PIPELINE and WEBSERVICE.
System Action:
The request is not sent. Error processing continues.
Resolution:
Check subsequent messages for more details and correct any problems for the named PIPELINE and WEBSERVICE.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0400 - CASPI0419


CASPI0406E Date Time Applid Tranid INVOKE SERVICE was unsuccessful due to a failure on WEB CONVERSE with EIBRESP EIBRESP and EIBRESP2 EIBRESP2.

INVOKE SERVICE was unsuccessful due to a failure on WEB CONVERSE with EIBRESP EIBRESP and EIBRESP2 EIBRESP2.
System Action:
The request is not sent. Error processing continues.
Resolution:
Check all values passed to INVOKE SERVICE and correct any problems. Check the EIBRESP values for WEB CONVERSE.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0400 - CASPI0419


CASPI0410W Date Time Applid Tranid Failure to write SOAPAction header in the CICS pipeline HTTP transport mechanism for PIPELINE Pipeline WEBSERVICE Web Service Name.

Failed to write the SOAPAction header.
System Action:
The SOAPAction header is not sent with the SOAP request.
Resolution:
Check subsequent messages for more details and correct any problems for the named PIPELINE and WEBSERVICE.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0400 - CASPI0419


CASPI0440 - CASPI0459

  • CASPI0453E Date Time Applid Tranid The CICS transport manager encountered an error while trying to use URIMAP urimapname.
    The CICS transport manager was unable to use the URIMAP named in the message.
  • CASPI0454E Date Time Applid Tranid The CICS transport manager encountered an error while trying to use provider pipeline pipeline_name.
    The CICS transport manager was unable to use the provider pipeline named in the message.
Parent topic: CASPI - WebSphere Error Messages


CASPI0453E Date Time Applid Tranid The CICS transport manager encountered an error while trying to use URIMAP urimapname.

The CICS transport manager was unable to use the URIMAP named in the message.
System Action:
Error processing continues.
Resolution:
Ensure that the URIMAP is defined as USAGE=PIPELINE and is enabled.
Module:
dfhpilsq
Destination:
CPIO TD queue
Parent topic: CASPI0440 - CASPI0459


CASPI0454E Date Time Applid Tranid The CICS transport manager encountered an error while trying to use provider pipeline pipeline_name.

The CICS transport manager was unable to use the provider pipeline named in the message.
System Action:
Error processing continues.
Resolution:
Ensure that the pipeline is a provider pipeline and that the PIPELINE resource is enabled.
Module:
dfhpilsq
Destination:
CPIO TD queue
Parent topic: CASPI0440 - CASPI0459


CASPI0500 - CASPI0519

  • CASPI0500E Date Time Applid Tranid The CICS Pipeline Manager DFHPIPM encountered an error while trying to link to program Program. reason. PIPELINE: Pipeline.
    The CICS Pipeline Manager, DFHPIPM, was unable to link to the given program, or the linked program abended.
  • CASPI0501E Date Time Applid Tranid The CICS Pipeline Manager cannot proceed as the pipeline is unusable. reason. PIPELINE: Pipeline.
    The CICS Pipeline Manager DFHPIPM was unable to begin processing as the pipeline it has been invoked for is unusable.
  • CASPI0504E Date Time Applid Tranid The CICS Pipeline Manager has failed to communicate with a service provider due to an error in the underlying transport. TRANSPORT: Transport, PIPELINE: Pipeline.
    The CICS Pipeline Manager DFHPIPM failed to communicate with a service provider due to an error in the underlying transport.
  • CASPI0506E Date Time Applid Tranid The CICS Pipeline Manager has failed to communicate with a remote server due to an invalid URI scheme being specified. URI: Uri, PIPELINE: Pipeline.
    The CICS Pipeline Manager DFHPIPM failed to communicate with a remote server as a URI with an invalid scheme was provided.
  • CASPI0508E Date Time Applid The pipeline manager is unable to create or join a request stream because it is unable to reach the target for transaction: Tranid with userid: Userid.
    The pipeline manager is unable to create or join a request stream because it is unable to reach the target for transaction.
Parent topic: CASPI - WebSphere Error Messages


CASPI0500E Date Time Applid Tranid The CICS Pipeline Manager DFHPIPM encountered an error while trying to link to program Program. reason. PIPELINE: Pipeline.

The CICS Pipeline Manager, DFHPIPM, was unable to link to the given program, or the linked program abended.
System Action:
The link is abandoned. Error processing will continue.
Resolution:
Ensure that the program can be found.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0500 - CASPI0519


CASPI0501E Date Time Applid Tranid The CICS Pipeline Manager cannot proceed as the pipeline is unusable. reason. PIPELINE: Pipeline.

The CICS Pipeline Manager DFHPIPM was unable to begin processing as the pipeline it has been invoked for is unusable.
System Action:
In the requester case the transaction is abended with abend code APIB. In the provider case the transaction is abended with abend code API1.
Resolution:
Correct the problem identified in the message.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0500 - CASPI0519


CASPI0504E Date Time Applid Tranid The CICS Pipeline Manager has failed to communicate with a service provider due to an error in the underlying transport. TRANSPORT: Transport, PIPELINE: Pipeline.

The CICS Pipeline Manager DFHPIPM failed to communicate with a service provider due to an error in the underlying transport.
System Action:
The request is abandoned. Error processing will continue.
Resolution:
Check the previous messages issued by the transport to identify the cause of the problem.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0500 - CASPI0519


CASPI0506E Date Time Applid Tranid The CICS Pipeline Manager has failed to communicate with a remote server due to an invalid URI scheme being specified. URI: Uri, PIPELINE: Pipeline.

The CICS Pipeline Manager DFHPIPM failed to communicate with a remote server as a URI with an invalid scheme was provided.

Before CICS can make and a request to a remote server it must be provided with a URI identifying that server.

System Action:
The request is abandoned. Error processing will continue.
Resolution:
Correct either the application logic or the configuration file so that a URI with a supported scheme is provided.
Module:
cascws
Destination:
CPIO TD queue
Parent topic: CASPI0500 - CASPI0519


CASPI0508E Date Time Applid The pipeline manager is unable to create or join a request stream because it is unable to reach the target for transaction: Tranid with userid: Userid.

The pipeline manager is unable to create or join a request stream because it is unable to reach the target for transaction.

For ES to link to the application, a valid transaction needs to be provided.

System Action:
The request is abandoned. Error processing will continue.
Resolution:
Ensure that the transaction is installed and enabled in the system.
Module:
dfhpisn1
Destination:
CPIO TD queue
Parent topic: CASPI0500 - CASPI0519


CASPI0700 - CASPI0719

  • CASPI0703I Date Time Applid Userid PIPELINE Pipeline is about to scan the WSDIR directory.
    A scan is about to begin for pipeline <pipeline>.
  • CASPI0704I Date Time Applid Userid PIPELINE Pipeline Implicit scan has completed. Number of wsbind files found in the WSDIR directory: Number of wsbind files found. Number of successful WEBSERVICE creates: Number of wsbind files ok. Number of failed WEBSERVICE creates: Number of wsbind files in error.
  • CASPI0710I Date Time Applid userid PIPELINE (pipeline) was successfully discarded.
    PIPELINE has been removed from the system using the DISCARD command.
Parent topic: CASPI - WebSphere Error Messages


CASPI0703I Date Time Applid Userid PIPELINE Pipeline is about to scan the WSDIR directory.

A scan is about to begin for pipeline <pipeline>.

This will cause a WebService to be created for each of any wsbind files found in the directory specified in the WSDIR parameter of the pipeline.

Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0700 - CASPI0719


CASPI0704I Date Time Applid Userid PIPELINE Pipeline Implicit scan has completed. Number of wsbind files found in the WSDIR directory: Number of wsbind files found. Number of successful WEBSERVICE creates: Number of wsbind files ok. Number of failed WEBSERVICE creates: Number of wsbind files in erro

CASPI0704I Date Time Applid Userid PIPELINE Pipeline Implicit scan has completed. Number of wsbind files found in the WSDIR directory: Number of wsbind files found. Number of successful WEBSERVICE creates: Number of wsbind files ok. Number of failed WEBSERVICE creates: Number of wsbind files in error.

Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0700 - CASPI0719


CASPI0710I Date Time Applid userid PIPELINE (pipeline) was successfully discarded.

PIPELINE has been removed from the system using the DISCARD command.
System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CPIO TD queue
Parent topic: CASPI0700 - CASPI0719


CASPI0900 - CASPI0919

  • CASPI0901I Date Time Applid Userid New WEBSERVICE Webservice is being created during a scan against PIPELINE Pipeline.
    A new WSBIND file has been discovered on disk during a scan.
  • CASPI0902I Date Time Applid Userid New WEBSERVICE Webservice is being updated during a scan against PIPELINE Pipeline.
    A new WSBIND file has been discovered on disk during a scan.
  • CASPI0903I Date Time Applid Userid New URIMAP Urimap is being created during a scan against PIPELINE Pipeline for WEBSERVICE Webservice.
    A new URIMAP resource is being installed during a scan of a PIPELINE.
  • CASPI0904I Date Time Applid Userid URIMAP Urimap could not be created for WEBSERVICE Webservice in PIPELINE Pipeline. The URI that could not be allocated is: 'Uri'.
    An attempt to automatically create a URIMAP for a scanned WEBSERVICE failed.
  • CASPI0910I Date Time Applid Userid WEBSERVICE Webservice within PIPELINE Pipeline has been created.
    A WEBSERVICE has been created by the scan Pipeline.
  • CASPI0912I Date Time Applid userid WEBSERVICE (webservice) was successfully discarded.
    WEBSERVICE has been removed from the system using the DISCARD command.
  • CASPI0913I Date Time Applid userid WEBSERVICE (webservice) is being discarded.
    WEBSERVICE has been placed in the DISCARDING state.
  • CASPI0914E Date Time Applid Userid WEBSERVICE Webservice is UNUSABLE because: Reason.
    The WEBSERVICE failed to complete initialization.
  • CASPI0915I Date Time Applid Userid WEBSERVICE Webservice is now INSERVICE and is ready for use.
    The WEBSERVICE has completed initialization and is ready for use.
  • CASPI0916E Date Time Applid Userid WEBSERVICE Webservice within PIPELINE Pipeline was not created because it clashes with another WEBSERVICE of the same name in PIPELINE Pipeline.
Parent topic: CASPI - WebSphere Error Messages


CASPI0901I Date Time Applid Userid New WEBSERVICE Webservice is being created during a scan against PIPELINE Pipeline.

A new WSBIND file has been discovered on disk during a scan.

A corresponding CICS WEBSERVICE resource is being automatically created.

Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0902I Date Time Applid Userid New WEBSERVICE Webservice is being updated during a scan against PIPELINE Pipeline.

A new WSBIND file has been discovered on disk during a scan.

A corresponding CICS WEBSERVICE resource is being automatically updated.

Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0903I Date Time Applid Userid New URIMAP Urimap is being created during a scan against PIPELINE Pipeline for WEBSERVICE Webservice.

A new URIMAP resource is being installed during a scan of a PIPELINE.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0904I Date Time Applid Userid URIMAP Urimap could not be created for WEBSERVICE Webservice in PIPELINE Pipeline. The URI that could not be allocated is: 'Uri'.

An attempt to automatically create a URIMAP for a scanned WEBSERVICE failed.

This is probably because the URI specified in the wsbind file is already in use by another URIMAP.

Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0910I Date Time Applid Userid WEBSERVICE Webservice within PIPELINE Pipeline has been created.

A WEBSERVICE has been created by the scan Pipeline.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0912I Date Time Applid userid WEBSERVICE (webservice) was successfully discarded.

WEBSERVICE has been removed from the system using the DISCARD command.
System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0913I Date Time Applid userid WEBSERVICE (webservice) is being discarded.

WEBSERVICE has been placed in the DISCARDING state.

When no longer in use, it will be discarded.

System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0914E Date Time Applid Userid WEBSERVICE Webservice is UNUSABLE because: Reason.

The WEBSERVICE failed to complete initialization.
System Action:
The WEBSERVICE has been put into the UNUSABLE state.
Resolution:
Check for the reason of the error and correct it.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0915I Date Time Applid Userid WEBSERVICE Webservice is now INSERVICE and is ready for use.

The WEBSERVICE has completed initialization and is ready for use.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0916E Date Time Applid Userid WEBSERVICE Webservice within PIPELINE Pipeline was not created because it clashes with another WEBSERVICE of the same name in PIPELINE Pipeline.

System Action:
The WEBSERVICE is not CREATED, the PIPELINE SCAN processing continues.
Resolution:
Rename the wsbind file and retry the operation.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI0900 - CASPI0919


CASPI0940 - CASPI0959

  • CASPI0950W Date Time Applid userid Attempt to discard URIMAP (urimap) failed. RC: return code
    Attempt to discard URIMAP during discard of a WEBSERVICE failed with TMP return code.
  • CASPI0951W Date Time Applid userid Attempt to discard WEBSERVICE (urimap) failed. RC: return code
    Attempt to discard WEBSERVICE failed with TMP return code.
  • CASPI0952W Date Time Applid userid Attempt to discard PIPELINE (urimap) failed. RC: return code
    Attempt to discard PIPELINE failed .
Parent topic: CASPI - WebSphere Error Messages


CASPI0950W Date Time Applid userid Attempt to discard URIMAP (urimap) failed. RC: return code

Attempt to discard URIMAP during discard of a WEBSERVICE failed with TMP return code.
System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CPIO TD queue
Parent topic: CASPI0940 - CASPI0959


CASPI0951W Date Time Applid userid Attempt to discard WEBSERVICE (urimap) failed. RC: return code

Attempt to discard WEBSERVICE failed with TMP return code.
System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CPIO TD queue
Parent topic: CASPI0940 - CASPI0959


CASPI0952W Date Time Applid userid Attempt to discard PIPELINE (urimap) failed. RC: return code

Attempt to discard PIPELINE failed .
System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CPIO TD queue
Parent topic: CASPI0940 - CASPI0959


CASPI0980 - CASPI0999

  • CASPI0997E Date Time Applid Tranid Pipeline The CICS pipeline manager has encountered an error: reason.
    The Pipeline Manager encountered a problem whilst attempting to process a message.
Parent topic: CASPI - WebSphere Error Messages


CASPI0997E Date Time Applid Tranid Pipeline The CICS pipeline manager has encountered an error: reason.

The Pipeline Manager encountered a problem whilst attempting to process a message.

This might be due to one of the following:

A configuration error or an unexpected event.
An abandoned connection attempt due to an exceeded DTIMEOUT. This causes message PI0400 to be issued.
An exceeded RESPWAIT timeout while waiting for a response.
An unexpected response from a handler program on the pipeline.
Resolution:
Examine the trace and any prior messages to determine why the Pipeline Manager failed.
Module:
dfhpipm
Destination:
CPIO TD queue
Parent topic: CASPI0980 - CASPI0999


CASPI1000 - CASPI1019

  • CASPI1007E Date Time Applid TaskId XML or JSON to data transformation failed because of incorrect input (Cause of error Error Qualifier) for Webservice or Bundle Webservice or Bundle name.
    CICS has failed to convert some XML or JSON data into application data.
  • CASPI1008E Date Time Applid TaskId XML or JSON generation failed because of incorrect input (Cause of error Error Qualifier) for Webservice or Bundle Webservice or Bundle name.
    CICS has failed to generate XML or JSON due to a problem with the data received from the CICS application.
  • CASPI1009E Date Time Applid TaskId XML or JSON to data transformation failed. A conversion error (Cause of error) occurred when converting field Error Qualifier for Webservice or Bundle Webservice or Bundle name.
    CICS has failed to convert some XML or JSON data into application data.
  • CASPI1010E Date Time Applid TaskId XML or JSON generation failed. A conversion error (Cause of error) occurred when converting field Error Qualifier for Webservice or Bundle Webservice or Bundle name.
    CICS has failed to convert some XML or JSON data into application data.
Parent topic: CASPI - WebSphere Error Messages


CASPI1007E Date Time Applid TaskId XML or JSON to data transformation failed because of incorrect input (Cause of error Error Qualifier) for Webservice or Bundle Webservice or Bundle name.

CICS has failed to convert some XML or JSON data into application data.
System Action:
Process halts.
Resolution:
Examine the Error Qualifier and the input XML or JSON and correct the error.
Module:
dfhpitp
Destination:
CPIO TD queue
Parent topic: CASPI1000 - CASPI1019


CASPI1008E Date Time Applid TaskId XML or JSON generation failed because of incorrect input (Cause of error Error Qualifier) for Webservice or Bundle Webservice or Bundle name.

CICS has failed to generate XML or JSON due to a problem with the data received from the CICS application.
System Action:
The XML or JSON conversion process halts.
Resolution:
Examine the exception trace entry for further information. Correct the CICS application to ensure that the data presented to CICS is appropriate to be converted into XML or JSON.
Module:
dfhpitp
Destination:
CPIO TD queue
Parent topic: CASPI1000 - CASPI1019


CASPI1009E Date Time Applid TaskId XML or JSON to data transformation failed. A conversion error (Cause of error) occurred when converting field Error Qualifier for Webservice or Bundle Webservice or Bundle name.

CICS has failed to convert some XML or JSON data into application data.
System Action:
Process halts.
Resolution:
Examine the Error Qualifier and the input XML or JSON and correct the error.
Module:
dfhpitp
Destination:
CPIO TD queue
Parent topic: CASPI1000 - CASPI1019


CASPI1010E Date Time Applid TaskId XML or JSON generation failed. A conversion error (Cause of error) occurred when converting field Error Qualifier for Webservice or Bundle Webservice or Bundle name.

CICS has failed to convert some XML or JSON data into application data.
System Action:
Process halts.
Resolution:
Examine the Error Qualifier and the input XML or JSON and correct the error.
Module:
dfhpitp
Destination:
CPIO TD queue
Parent topic: CASPI1000 - CASPI1019


CASPI1560 - CASPI1579

  • CASPI1570I Date Time Applid userid URIMAP (urimap) was successfully discarded.
    URIMAP has been removed from the system using the DISCARD command.
Parent topic: CASPI - WebSphere Error Messages


CASPI1570I Date Time Applid userid URIMAP (urimap) was successfully discarded.

URIMAP has been removed from the system using the DISCARD command.
System Action:
System continues normally.
Resolution:
None.
Module:
ESMAC and dfhesysp
Destination:
CWBO TD queue
Parent topic: CASPI1560 - CASPI1579


CASPI4920 - CASPI4939

  • CASPI4937E Date Time Applid userid The installation of BUNDLE Bundle Name failed because a manifest was not found.
    BUNDLE resource name cannot be installed because a manifest was not found.
  • CASPI4938W Date Time Applid userid BUNDLE Bundle Name has been installed as disabled because one or more of its associated resources failed to install.
    One or more of BUNDLE resource name's associated resources have failed to install properly.
Parent topic: CASPI - WebSphere Error Messages


CASPI4937E Date Time Applid userid The installation of BUNDLE Bundle Name failed because a manifest was not found.

BUNDLE resource name cannot be installed because a manifest was not found.
System Action:
The resource is not installed.
Resolution:
Ensure that the root directory specified in the BUNDLEDIR is correct.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI4920 - CASPI4939


CASPI4938W Date Time Applid userid BUNDLE Bundle Name has been installed as disabled because one or more of its associated resources failed to install.

One or more of BUNDLE resource name's associated resources have failed to install properly.
System Action:
The resource is installed as disabled.
Resolution:
Examine any error messages issued on the log to determine the cause of the installation failure of any associated resources.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI4920 - CASPI4939


CASPI9640 - CASPI9659

  • CASPI9640I Date Time Applid WEBSERVICE WebService should be installed into a PIPELINE Pipeline that uses SOAP version soap version.
    The webService is marked as unusable because it was installed as part of a pipeline which does not support the version specified in the wsbind.
Parent topic: CASPI - WebSphere Error Messages


CASPI9640I Date Time Applid WEBSERVICE WebService should be installed into a PIPELINE Pipeline that uses SOAP version soap version.

The webService is marked as unusable because it was installed as part of a pipeline which does not support the version specified in the wsbind.
System Action:
The WEBSERVICE has been put into the UNUSABLE state.
Resolution:
Move the wsbind from the wsdir folder specified for pipeline to the appropriate one.
Module:
dfhpipl
Destination:
CPIO TD queue
Parent topic: CASPI9640 - CASPI9659


CASRA - CICS Resource Definition API Error Messages

  • CASRA0000 - CASRA0019
  • CASRA0020 - CASRA0039
  • CASRA0040 - CASRA0059
  • CASRA0060 - CASRA0079
  • CASRA0080 - CASRA0099
  • CASRA0100 - CASRA0119
  • CASRA0120 - CASRA0139
  • CASRA0140 - CASRA0159
  • CASRA0160 - CASRA0179
  • CASRA0180 - CASRA0199
  • CASRA1000 - CASRA1019
  • CASRA1020 - CASRA1039
  • CASRA1100 - CASRA1119
  • CASRA1200 - CASRA1219
  • CASRA1300 - CASRA1319
  • CASRA1320 - CASRA1339
  • CASRA1500 - CASRA1519
Parent topic: Enterprise Server Error Messages


CASRA0000 - CASRA0019

  • CASRA0001E Field field-name is invalid
    The field name contained a value that was invalid.
  • 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.
  • 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 - CICS Resource Definition API 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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: CASRA0000 - 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 - CICS Resource Definition API 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 - CASRA0059

  • CASRA0040E Remote terminal ID specified but no remote system ID specified
    If a remote terminal id 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 - CICS Resource Definition API Error Messages


CASRA0040E Remote terminal ID specified but no remote system ID specified

If a remote terminal id 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 - CASRA0059


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


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


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


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


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


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


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


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


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


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


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


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


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


CASRA0060 - CASRA0079

  • 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 Unrecognized field identifier
    The field identifier passed into the function was not recognized.
  • 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.
Parent topic: CASRA - CICS Resource Definition API 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 - CASRA0079


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


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


CASRA0063S Unrecognized field identifier

The field identifier passed into the function was not recognized.
Resolution:
Pass a valid field identifier on the function call.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0079


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


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


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


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


CASRA0071I The list does not contain any groups

The list does not contain any groups.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0079


CASRA0072I No more groups in the list

No more groups in the list.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0079


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


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


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


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


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


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


CASRA0079E SYNCLEVEL WRONG

SYNCLEVEL.
Resolution:
SYNCLEVEL.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA0060 - CASRA0079


CASRA0080 - CASRA0099

  • 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 - CICS Resource Definition API Error Messages


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: CASRA0080 - CASRA0099


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: CASRA0080 - CASRA0099


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: CASRA0080 - CASRA0099


CASRA0100 - CASRA0119

  • 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.
  • CASRA0112E Invalid values in HFSFILE field
    The values entered in the HFSFILE field are incorrect.
  • CASRA0113E Invalid values in TSQUEUE field
    The values entered in the TSQUEUE field are incorrect.
  • CASRA0114E Invalid values in TDQUEUE field
    The values entered in the TDQUEUE field are incorrect.
  • CASRA0115E Invalid values in PROGRAM field
    The values entered in the PROGRAM field are incorrect.
  • CASRA0116E Invalid values in EXITPRG field
    The values entered in the EXITPRG field are incorrect.
  • CASRA0117E Invalid values in DDNAME field
    The values entered in the DDNAME field are incorrect.
  • CASRA0118E Invalid values in MEMBERNAME field
    The values entered in the MEMBERNAME field are incorrect.
  • CASRA0119E Invalid values in TYPE field
    The values entered in the TYPE field can only be (EBCDIC|ASCII|BINARY).
Parent topic: CASRA - CICS Resource Definition API 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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


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: CASRA0100 - CASRA0119


CASRA0120 - CASRA0139

  • CASRA0120E Invalid values in TEMPLATENAME field
    The values entered in the TEMPLATENAME field are incorrect.
  • CASRA0121E Invalid values in DOCTEMPLATE field
    The values entered in the DOCTEMPLATE field are incorrect.
  • CASRA0122E FILE|TSQUEUE|TDQUEUE|PROGRAM|EXITPGM|HFSFILE OR MEMBERNAME must be specified
    All the option fields are empty.
  • CASRA0123E Option The attribute at fault conflicts with other option and is ignored
    The specified option conflicts with another one.
  • CASRA0124E Option The attribute at fault conflicts with other option and is ignored
    The specified option conflicts with an other one.
  • CASRA0125E Invalid values in TYPE field
    The values entered in the TYPE field are incorrect.
  • CASRA0126E Invalid values in NAME field
    The values entered in the NAME field are incorrect.
  • CASRA0127E Invalid values in CLASS field
    The values entered in the CLASS field are incorrect.
  • 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.
  • 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.
  • 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.
  • 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.
  • CASRA0138E Field MAXACTIVE is not valid
    the value specified for MAXACTIVE is not valid.
  • CASRA0139E Field PURGETHRESH is not valid
    the value specified for PURGETHRESH is not valid.
Parent topic: CASRA - CICS Resource Definition API Error Messages


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


CASRA0123E Option The attribute at fault 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: CASRA0120 - CASRA0139


CASRA0124E Option The attribute at fault 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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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.

For example, 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: CASRA0120 - CASRA0139


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.

For example, protocol ECI does not recognize the URM attribute.

Resolution:
Remove the meaningless options to stop this message from being returned.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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.

For example, 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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


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: CASRA0120 - CASRA0139


CASRA0138E Field MAXACTIVE is not valid

the value specified for MAXACTIVE is not valid.
Resolution:
Correct the MAXACTIVE value for TRANCLASS.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0120 - CASRA0139


CASRA0139E Field PURGETHRESH is not valid

the value specified for PURGETHRESH is not valid.
Resolution:
Correct the PURGETHRESH value for TRANCLASS.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0120 - CASRA0139


CASRA0140 - CASRA0159

  • CASRA0140W Usage(PIPELINE) implies TRANSACTION. The default value has been assumed
    The TRANSACTION field is empty, so the default TRANSACTION is assumed.
  • CASRA0141E Use of Usage(PIPELINE) option implies PIPELINE option must be specified
    The PIPELINE field is empty.
  • CASRA0142E Invalid values in ENQNAME field
    The values entered in the ENQNAME field are incorrect.
  • CASRA0143E Invalid values in ENQSCOPE field
    The values entered in the ENQSCOPE field are incorrect.
  • CASRA0144E Invalid value in STATUS field
    The value entered in the STATUS field is incorrect.
  • CASRA0145E ENQMODEL value must be specified
    ENQMODEL value is not specified.
  • CASRA0146E Invalid values in TSMODEL field
    The values entered in the TSMODEL field are incorrect.
  • CASRA0147E Invalid values in LOCATION field
    The values entered in the LOCATION field are incorrect.
  • CASRA0148E Invalid values in PREFIX field
    The values entered in the PREFIX field are incorrect.
  • CASRA0149E Invalid values in XPREFIX field
    The values entered in the XPREFIX field are incorrect.
  • CASRA0150E Invalid value in EXPIRYINT field
    The value entered in the EXPIRYINT field is incorrect.
  • CASRA0151E Invalid value in RECOVERY field
    The value entered in the RECOVERY field is incorrect.
  • CASRA0152E Invalid values in POOLNAME field
    The value entered in the POOLNAME field are incorrect.
  • CASRA0153E Invalid values in REMOTESYSTEM field
    The value entered in the REMOTESYSTEM field are incorrect.
  • CASRA0154E Invalid values in REMOTEPREFIX field
    The value entered in the REMOTEPREFIX field are incorrect.
  • CASRA0155E Invalid values in XREMOTEPFX field
    The value entered in the XREMOTEPFX field are incorrect.
  • CASRA0156E Invalid values in SECURITY field
    The value entered in the SECURITY field are incorrect.
  • CASRA0157E Option The attribute at fault conflicts with an other option and is ignored
    The specified option conflicts with another one.
  • CASRA0158E REMOTEPREFIX and PREFIX must be the same length
    The length of the value entered in the REMOTEPREFIX does not match the length of the value entered in PREFIX.
  • CASRA0159E REMOTEPREFIX and XPREFIX must be the same length
    The length of the value entered in the REMOTEPREFIX does not match the length of the value entered in XPREFIX.
Parent topic: CASRA - CICS Resource Definition API Error Messages


CASRA0140W Usage(PIPELINE) implies TRANSACTION. The default value has been assumed

The TRANSACTION field is empty, so the default TRANSACTION is assumed.
Resolution:
None or specify a custom TRANSACTION.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0141E Use of Usage(PIPELINE) option implies PIPELINE option must be specified

The PIPELINE field is empty.
Resolution:
Specify a PIPELINE.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0142E Invalid values in ENQNAME field

The values entered in the ENQNAME field are incorrect.

Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ?, ; < >.

Resolution:
Correct the ENQNAME field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0143E Invalid values in ENQSCOPE field

The values entered in the ENQSCOPE field are incorrect.

Accepted values: A-Z 0-9 $ @ #.

Resolution:
Correct the ENQSCOPE field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0144E Invalid value in STATUS field

The value entered in the STATUS field is incorrect.

Accepted values: ENABLED | DISABLED.

Resolution:
Correct the STATUS field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0145E ENQMODEL value must be specified

ENQMODEL value is not specified.
Resolution:
Enter the ENQMODEL value.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0146E Invalid values in TSMODEL field

The values entered in the TSMODEL field are incorrect.

Accepted values: A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ?, ; < >.

Resolution:
Correct the TSMODEL field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0147E Invalid values in LOCATION field

The values entered in the LOCATION field are incorrect.

Accepted values: AUXILIARY | MAIN.

Resolution:
Correct the LOCATION field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0148E Invalid values in PREFIX field

The values entered in the PREFIX field are incorrect.

Accepted values: A-Z a-z 0-9 $ @ # . / - + _ % & ? ! : | " = ?, ; < >.

Resolution:
Correct the PREFIX field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0149E Invalid values in XPREFIX field

The values entered in the XPREFIX field are incorrect.

Accepted values are up to 32 characters in HEX.

Resolution:
Correct the XPREFIX field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0150E Invalid value in EXPIRYINT field

The value entered in the EXPIRYINT field is incorrect.

Accepted values are: 0 or a number < 15001.

Resolution:
Correct the EXPIRYINT field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0151E Invalid value in RECOVERY field

The value entered in the RECOVERY field is incorrect.

Accepted values are: YES | NO.

Resolution:
Correct the RECOVERY field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0152E Invalid values in POOLNAME field

The value entered in the POOLNAME field are incorrect.

Accepted values are: A-Z 0-9 $ @ # _.

Resolution:
Correct the POOLNAME field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0153E Invalid values in REMOTESYSTEM field

The value entered in the REMOTESYSTEM field are incorrect.

Accepted values are: A-Z 0-9 $ @ #.

Resolution:
Correct the REMOTESYSTEM field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0154E Invalid values in REMOTEPREFIX field

The value entered in the REMOTEPREFIX field are incorrect.

Accepted values are: A-Z a-z 0-9 $ @ # . / - + _ % & ? ! : | " = ?, ; < >.

Resolution:
Correct the REMOTEPREFIX field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0155E Invalid values in XREMOTEPFX field

The value entered in the XREMOTEPFX field are incorrect.

Accepted values are up to 32 characters in HEX.

Resolution:
Correct the XREMOTEPFX field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0156E Invalid values in SECURITY field

The value entered in the SECURITY field are incorrect.

Accepted values are YES or NO.

Resolution:
Correct the SECURITY field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0157E Option The attribute at fault conflicts with an 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: CASRA0140 - CASRA0159


CASRA0158E REMOTEPREFIX and PREFIX must be the same length

The length of the value entered in the REMOTEPREFIX does not match the length of the value entered in PREFIX.
Resolution:
Correct the REMOTEPREFIX and PREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0159E REMOTEPREFIX and XPREFIX must be the same length

The length of the value entered in the REMOTEPREFIX does not match the length of the value entered in XPREFIX.
Resolution:
Correct the REMOTEPREFIX and XPREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0140 - CASRA0159


CASRA0160 - CASRA0179

  • CASRA0160E Use of REMOTEPREFIX option implies PREFIX or XPREFIX option must be specified
    REMOTEPREFIX was used but no PREFIX or XPREFIX was used.
  • CASRA0161E XREMOTEPFX and XPREFIX must be the same length
    The length of the value entered in the XREMOTEPFX does not match the length of the value entered in XPREFIX.
  • CASRA0162E Invalid phrase specified
    The snt phrase contains invalid characters.
  • CASRA0163E Invalid Fully Qualified Partner name specified
    The Fully Qualified Partner Name is made of the NETWORK ID followed the PARTNER name separated by a '.' .
  • CASRA0164E Invalid value in EXPIRYINTMIN field
    The value entered in the EXPIRYINTMIN field is incorrect.
  • CASRA0165E XREMOTEPFX and PREFIX must be the same length
    The length of the value entered in the XREMOTEPFX does not match the length of the value entered in PREFIX.
  • CASRA0166E Generic characters must be in the same position in REMOTEPREFIX and PREFIX
    Generic characters were not in the same position in the REMOTEPREFIX and PREFIX fields.
  • CASRA0167E Generic characters must be in the same position in REMOTEPREFIX and XPREFIX
    Generic characters were not in the same position in the REMOTEPREFIX and XPREFIX fields.
  • CASRA0168E Generic characters must be in the same position in XREMOTEPFX and PREFIX
    Generic characters were not in the same position in the XREMOTEPFX and PREFIX fields.
  • CASRA0169E Generic characters must be in the same position in XREMOTEPFX and XPREFIX
    Generic characters were not in the same position in the XREMOTEPFX and XPREFIX fields.
  • CASRA0170E Use of XREMOTEPFX option implies PREFIX or XPREFIX option must be specified
    XREMOTEPFX was used but no PREFIX or XPREFIX was used.
  • CASRA0171E Use of REMOTEPREFIX option implies REMOTESYSTEM option must be specified
    REMOTEPREFIX was used but REMOTESYSTEM was not specified.
  • CASRA0172E Use of XREMOTEPFX option implies REMOTESYSTEM option must be specified
    XREMOTEPFX was used but REMOTESYSTEM was not specified.
  • CASRA0173E Invalid values in THRESHOLD name field
    The values entered in the THRESHOLD name field are incorrect.
  • CASRA0174E Invalid values in THRESHOLD resource type field
    The values entered in the THRESHOLD resource type field are incorrect.
  • CASRA0175E Invalid values in THRESHOLD Stepname field
    The values entered in the THRESHOLD Stepname field are incorrect.
  • CASRA0176E Invalid values in THRESHOLD JES Classes field
    The values entered in the THRESHOLD JES Classes field are incorrect.
  • CASRA0177E Invalid values in THRESHOLD CPU warning field
    The values entered in the THRESHOLD CPU warning field are incorrect.
  • CASRA0178E Invalid values in THRESHOLD CPU purge field
    The values entered in the THRESHOLD CPU purge field are incorrect.
  • CASRA0179E Invalid values in THRESHOLD MEM warning field
    The values entered in the THRESHOLD MEM warning field are incorrect.
Parent topic: CASRA - CICS Resource Definition API Error Messages


CASRA0160E Use of REMOTEPREFIX option implies PREFIX or XPREFIX option must be specified

REMOTEPREFIX was used but no PREFIX or XPREFIX was used.
Resolution:
Correct the options.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0161E XREMOTEPFX and XPREFIX must be the same length

The length of the value entered in the XREMOTEPFX does not match the length of the value entered in XPREFIX.
Resolution:
Correct the XREMOTEPFX and XPREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0162E Invalid phrase specified

The snt phrase contains invalid characters.
Resolution:
Correct the phrase fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0163E Invalid Fully Qualified Partner name specified

The Fully Qualified Partner Name is made of the NETWORK ID followed the PARTNER name separated by a '.' .
Resolution:
Correct the Fully Qualified Partner Name fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0164E Invalid value in EXPIRYINTMIN field

The value entered in the EXPIRYINTMIN field is incorrect.

Accepted values are: 0 or a number < 900001.

Resolution:
Correct the EXPIRYINTMIN field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0165E XREMOTEPFX and PREFIX must be the same length

The length of the value entered in the XREMOTEPFX does not match the length of the value entered in PREFIX.
Resolution:
Correct the XREMOTEPFX and PREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0166E Generic characters must be in the same position in REMOTEPREFIX and PREFIX

Generic characters were not in the same position in the REMOTEPREFIX and PREFIX fields.
Resolution:
Correct the REMOTEPREFIX and PREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0167E Generic characters must be in the same position in REMOTEPREFIX and XPREFIX

Generic characters were not in the same position in the REMOTEPREFIX and XPREFIX fields.
Resolution:
Correct the REMOTEPREFIX and XPREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0168E Generic characters must be in the same position in XREMOTEPFX and PREFIX

Generic characters were not in the same position in the XREMOTEPFX and PREFIX fields.
Resolution:
Correct the XREMOTEPFX and PREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0169E Generic characters must be in the same position in XREMOTEPFX and XPREFIX

Generic characters were not in the same position in the XREMOTEPFX and XPREFIX fields.
Resolution:
Correct the XREMOTEPFX and XPREFIX fields.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0170E Use of XREMOTEPFX option implies PREFIX or XPREFIX option must be specified

XREMOTEPFX was used but no PREFIX or XPREFIX was used.
Resolution:
Correct the options.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0171E Use of REMOTEPREFIX option implies REMOTESYSTEM option must be specified

REMOTEPREFIX was used but REMOTESYSTEM was not specified.
Resolution:
Add a REMOTESYSTEM.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0172E Use of XREMOTEPFX option implies REMOTESYSTEM option must be specified

XREMOTEPFX was used but REMOTESYSTEM was not specified.
Resolution:
Add a REMOTESYSTEM.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0173E Invalid values in THRESHOLD name field

The values entered in the THRESHOLD name field are incorrect.

Accepted characters: A-Z 0-9 $ @ # * % Exception - catch all value of '*'.

Resolution:
Correct the THRESHOLD name field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0174E Invalid values in THRESHOLD resource type field

The values entered in the THRESHOLD resource type field are incorrect.

CICS, JES, IMS.

Resolution:
Correct the THRESHOLD resource type field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0175E Invalid values in THRESHOLD Stepname field

The values entered in the THRESHOLD Stepname field are incorrect.

Accepted values: A-Z 0-9 $ @ # *.

Resolution:
Correct the THRESHOLD Stepname field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0176E Invalid values in THRESHOLD JES Classes field

The values entered in the THRESHOLD JES Classes field are incorrect.

Accepted values: A-Z 0-9.

Resolution:
Correct the THRESHOLD JES Classes name field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0177E Invalid values in THRESHOLD CPU warning field

The values entered in the THRESHOLD CPU warning field are incorrect.

Accepted values: 0-9.

Resolution:
Correct the THRESHOLD CPU warning field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0178E Invalid values in THRESHOLD CPU purge field

The values entered in the THRESHOLD CPU purge field are incorrect.

Accepted values: 0-9.

Resolution:
Correct the THRESHOLD CPU purge field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0179E Invalid values in THRESHOLD MEM warning field

The values entered in the THRESHOLD MEM warning field are incorrect.

Accepted values: 0-9.

Resolution:
Correct the THRESHOLD MEM warning field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0160 - CASRA0179


CASRA0180 - CASRA0199

  • CASRA0180E Invalid values in THRESHOLD MEM purge field
    The values entered in the THRESHOLD MEM purge field are incorrect.
  • CASRA0181E Invalid values in THRESHOLD ELAPSED warning field
    The values entered in the THRESHOLD ELAPSED warning field are incorrect.
  • CASRA0182E Invalid values in THRESHOLD ELAPSED purge field
    The values entered in the THRESHOLD ELAPSED purge field are incorrect.
  • CASRA0183E THRESHOLD name invalid for default values, use only (=CIC,=JES,=IMS)
    The value entered in the THRESHOLD name field for a default type are incorrect.
  • CASRA0184E THRESHOLD resource type invalid for specified name
    The value entered in the THRESHOLD name field for a default type does not match the resource type.
  • CASRA0185E ENQSCOPE value Scope value is only valid with _SHAREDMEM(YES)
    ENQSCOPE value is only valid with _SHAREDMEM(YES).
  • CASRA0186W ENQSCOPE value changed to Modified scope value because _SHAREDMEM(YES)
    ENQSCOPE changed because _SHAREDMEM(YES).
Parent topic: CASRA - CICS Resource Definition API Error Messages


CASRA0180E Invalid values in THRESHOLD MEM purge field

The values entered in the THRESHOLD MEM purge field are incorrect.

Accepted values: 0-9.

Resolution:
Correct the THRESHOLD MEM purge field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA0181E Invalid values in THRESHOLD ELAPSED warning field

The values entered in the THRESHOLD ELAPSED warning field are incorrect.

Accepted values: 0-9.

Resolution:
Correct the THRESHOLD ELAPSED warning field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA0182E Invalid values in THRESHOLD ELAPSED purge field

The values entered in the THRESHOLD ELAPSED purge field are incorrect.

Accepted values: 0-9.

Resolution:
Correct the THRESHOLD ELAPSED purge field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA0183E THRESHOLD name invalid for default values, use only (=CIC,=JES,=IMS)

The value entered in the THRESHOLD name field for a default type are incorrect.

Accepted values: =CIC, =JES, =IMS.

Resolution:
Correct the default THRESHOLD name field.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA0184E THRESHOLD resource type invalid for specified name

The value entered in the THRESHOLD name field for a default type does not match the resource type.

Accepted values: =CIC (CICS), =JES (JES), =IMS (IMS).

Resolution:
Correct the default THRESHOLD name field or the resource type.
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA0185E ENQSCOPE value Scope value is only valid with _SHAREDMEM(YES)

ENQSCOPE value is only valid with _SHAREDMEM(YES).
Resolution:
Either change the value for ENQSCOPE or use _SHAREDMEM(YES).
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA0186W ENQSCOPE value changed to Modified scope value because _SHAREDMEM(YES)

ENQSCOPE changed because _SHAREDMEM(YES).
Module:
dfhrmsg
Destination:
Standard Error
Parent topic: CASRA0180 - CASRA0199


CASRA1000 - 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.
  • 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.
  • 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 - CICS Resource Definition API 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - CASRA1019


CASRA1016E Duplicate record found

An attempt was made to add a record that already exists in the resource file being operated on.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - 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: CASRA1000 - CASRA1019


CASRA1020 - CASRA1039

  • 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.
  • 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.
  • 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 - CICS Resource Definition API 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 - CASRA1039


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


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


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


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


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


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


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


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


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


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


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


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


CASRA1100 - CASRA1119

  • 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.
  • 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.
  • 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 - CICS Resource Definition API 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: CASRA1100 - CASRA1119


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: CASRA1100 - CASRA1119


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: CASRA1100 - CASRA1119


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: CASRA1100 - CASRA1119


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: CASRA1100 - CASRA1119


CASRA1200 - CASRA1219

  • CASRA1201S Initialization failure
    A required support module was not present.
  • 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 - CICS Resource Definition API Error Messages


CASRA1201S Initialization failure

A required support module was not present.
Resolution:
Investigate the cause of the missing module - dfh0cfg.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


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: CASRA1200 - CASRA1219


CASRA1300 - 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 is 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 - CICS Resource Definition API 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: CASRA1300 - CASRA1319


CASRA1302E The PASSWORD entered is 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - 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: CASRA1300 - CASRA1319


CASRA1320 - CASRA1339

  • 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 - CICS Resource Definition API 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 - CASRA1339


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


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


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


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


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


CASRA1500 - CASRA1519

  • CASRA1501S An unrecognized error has occurred - file may be corrupt
    An error occurred which has not been recognized.
  • 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.
  • CASRA1504E The record is locked by another process
    An attempt was made to process a record that is locked by another process.
  • 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 occurred
    A mis-match error has occurred.
  • CASRA1509E Failed to create resource definition file ((substDir$))$!Failed to create temporary 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.
  • CASRA1512E The resource definition file ((substDir$)) is already open$!Temporary resource definition ((substDir$)) file is already open
    Attempt to open a resource definition file failed because the file was already 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 I/O error ((substFS$)) was encountered accessing the temporary resource definition file ((substDir$))
    An IO error occurred while processing the current record.
Parent topic: CASRA - CICS Resource Definition API Error Messages


CASRA1501S An unrecognized error has occurred - file may be corrupt

An error occurred which has not been recognized.

The resource definition file may be corrupt.

Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


CASRA1503E Duplicate record found

An attempt was made to add a record that already exists in the resource file being operated on.
Module:
dfhrapi
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


CASRA1508S A mis-match error has occurred

A mis-match error has occurred.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


CASRA1509E Failed to create resource definition file ((substDir$))$!Failed to create temporary resource definition file ((substDir$))

An attempt to create a new resource definition file failed.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


CASRA1511S Initialization failure

A required support module was not present.
Resolution:
Verify installation.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


CASRA1512E The resource definition file ((substDir$)) is already open$!Temporary resource definition ((substDir$)) file is already open

Attempt to open a resource definition file failed because the file was already open.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


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: CASRA1500 - CASRA1519


CASRA1515E An I/O error ((substFS$)) was encountered accessing the resource definition file ((substDir$))$!An I/O error ((substFS$)) was encountered accessing the temporary resource definition file ((substDir$))

An IO error occurred while processing the current record.
Module:
RDOWrapper
Destination:
Standard Error
Parent topic: CASRA1500 - CASRA1519


CASRB - Miscellaneous Error Messages

  • CASRB0000 - CASRB0019
  • CASRB0020 - CASRB0039
  • CASRB0040 - CASRB0059
  • CASRB0060 - CASRB0079
  • CASRB0080 - CASRB0099
Parent topic: Enterprise Server Error Messages


CASRB0000 - 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.
  • 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.
Parent topic: CASRB - Miscellaneous Error Messages


CASRB0001I No resource records found

There were no records of the specified type to list.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - CASRB0019


CASRB0004I Record added

The record was successfully added to the file.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - CASRB0019


CASRB0005E Resource name is invalid

The resource name entered was invalid.
Resolution:
Correct the resource name.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - CASRB0019


CASRB0006I Record updated

The record has been successfully updated.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - CASRB0019


CASRB0007I Record deleted

The record has been successfully deleted.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - CASRB0019


CASRB0008I Read only access allowed

The record has been successfully deleted.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - CASRB0019


CASRB0011E Group name is invalid

The group name entered was invalid.
Resolution:
Correct the resource name.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - CASRB0019


CASRB0012I Group deleted

The group has been successfully deleted.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - CASRB0019


CASRB0013I No group records found

There where no records of the specified type to list.
Module:
dfhrdef
Destination:
Standard Error
Parent topic: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - 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: CASRB0000 - CASRB0019


CASRB0020 - CASRB0039

  • CASRB0020I Upgrading file filespec
    Informational message to indicate the full filespec of the Resource Definition Facility (RDF) file being upgraded.
  • 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.
  • CASRB0025I Upgrade log file: filespec
    Informational message to indicate the full filespec 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.
  • CASRB0027I Added resource-type group group entry resource
    The named Resource Definition Facility (RDF) entry was successfully added.
  • CASRB0028I Checking supplied system entries
    The Resource Definition file upgrade utility (dfhrdef).
  • 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.
  • CASRB0030I Adding/updating resource-type entries
    The Resource Definition file upgrade utility (dfhrdef) is beginning to upgrade resource-type entries.
  • 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.
  • CASRB0033F Resource file version not compatible with dfherdio
    The Resource Definition I/O module is incompatible with the RDF file you are using.
  • CASRB0034F Resource file not at the same level as dfherdio
    The resource file version is not compatible with the version of dfherdio.
  • 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.
  • CASRB0039W Security is already enabled - no change made
    You have requested that RDF security be enabled, but it is already enabled.
Parent topic: CASRB - Miscellaneous Error Messages


CASRB0020I Upgrading file filespec

Informational message to indicate the full filespec 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 filespec 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).
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 dfherdio

The resource file version is not compatible with the version of dfherdio.
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 Micro Focus Customer 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.
  • CASRB0047I An unaltered SYSAD userid exists-- security default is disabled.
    The system is upgrading an older RDF file by adding security configuration details.
  • CASRB0048I Userid has SNT-Update authority-- security default is enabled.
    The system is upgrading an older RDF file by adding security configuration details.
  • CASRB0049I No users with SNT-Update authority-- security default is disabled.
    The system is upgrading an older RDF file by adding security configuration details.
  • 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.
  • CASRB0055I Upgraded resource-type group group entry resource
    The named Resource Definition Facility (RDF) entry was successfully upgraded.
  • 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.
  • 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.
  • 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.
Parent topic: CASRB - Miscellaneous 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 Micro Focus Customer 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 Userid 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.
  • 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-TD-name now new-recoverable-TS/TD-name.
    The name of the FS-ID for recoverable TS/TD has changed.
Parent topic: CASRB - Miscellaneous 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 specify 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-TD-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


CASRB0080 - CASRB0099

  • CASRB0080E COMMAND NOT EXECUTED. ALL IS INVALID BECAUSE A RESOURCE-TYPE KEYWORD WAS SPECIFIED.
    ALL cannot be specified if a resource has been specified.
Parent topic: CASRB - Miscellaneous Error Messages


CASRB0080E COMMAND NOT EXECUTED. ALL IS INVALID BECAUSE A RESOURCE-TYPE KEYWORD WAS SPECIFIED.

ALL cannot be specified if a resource has been specified.
Resolution:
remove option "ALL" or the resource specified from the command.
Module:
dfhrdtup
Destination:
Standard Error
Parent topic: CASRB0080 - CASRB0099


CASRD - CICS Resource Definition DFHRDEF Error Messages

  • CASRD0000 - CASRD0019
  • CASRD0020 - CASRD0039
  • CASRD0040 - CASRD0059
  • CASRD1000 - CASRD1019
  • CASRD1020 - CASRD1039
  • CASRD1040 - CASRD1059
Parent topic: Enterprise Server Error Messages


CASRD0000 - CASRD0019

  • CASRD0001E resource-type entry resource-name is busy. Group group-name will be partially installed
    The resource-type entry resource-name is locked with an ENQ.
  • CASRD0002E resource-type name resource-name is busy. Group group-name will not be installed
    The resource-type name resource-name is locked with an ENQ.
  • CASRD0003S Group group-name is not found, install request rejected, reason reason-code
    The group group-name is not found in the active resource definition file.
  • CASRD0004I Resource definition group group-name install initiated from (facility-id)
    Group group-name install is initiated from terminal or facility facility-id.
  • CASRD0005E Group group-name is not installed, check messages in TS queue TS-queue-name
    Validation errors were found when preparing to install group group-name.
  • CASRD0006E Group group-name is installed with errors, check messages in TS queue TS-queue-name
    Validation of group was successful but portions of the install failed for group group-name.
  • CASRD0007I Resource definition group group-name is successfully installed
    The group group-name has been successfully installed.
  • CASRD0008I resource-type entry resource-name from group group-name replaced existing definition
    The resource definition for resource-type entry resource-name from group group-name has replaced the previous definition in the current system.
  • CASRD0009I resource-type entry resource-name from group group-name installed
    The resource definition for resource-type entry resource-name from group group-name is installed in the current system.
  • CASRD0010E resource-type entry resource-name from group group-name install failed, reason: reason-code
    The resource definition for resource-type entry resource-name from group group-name failed to install.
  • CASRD0011S Resource definition file open error, reason reason-code
    The resource definition file is not accessible.
  • CASRD0012W resource-type entry resource-name from group group-name not supported
    The resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0013W resource-type entry resource-name from group group-name delete failed, reason reason-code
    An attempt was made to delete the resource-type entry resource-name in preparation for re-installing it from group group-name.
  • CASRD0014W resource-type entry resource-name from group group-name install failed, reason reason-code
    An attempt was made to install the resource-type entry resource-name from group group-name after deleting the previous definition.
  • CASRD0015W resource-type entry resource-name from group group-name not recognized
    The resource type resource-type (resource resource-name, group group-name) is not recognized.
  • CASRD0016W resource-type entry resource-name from group group-name not supported
    The resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0017W resource-type entry resource-name from group group-name not recognized
    The resource type resource-type (resource resource-name, group group-name) is not recognized.
  • CASRD0018E resource-type entry resource-name from group group-name not CLOSED and either UNENABLED or DISABLED
    The resource definition for resource-type entry resource-name is not installable.
  • CASRD0019E Extra-partition resource-type entry resource-name from group group-name not CLOSED
    The resource definition for resource-type entry resource-name is not installable.
Parent topic: CASRD - CICS Resource Definition DFHRDEF Error Messages


CASRD0001E resource-type entry resource-name is busy. Group group-name will be partially installed

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0002E resource-type name resource-name is busy. Group group-name will not be installed

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0003S Group group-name is not found, install request rejected, reason reason-code

The group group-name is not found in the active resource definition file.

The reason is reason-code. Common reasons are:

  0  The group name was not in the file or contained no resources
  2  The group name was not in the file or contained no resources
  4  The first record in the group is locked

The reason code is the return code from a get first request to the resource definition file access module.

System Action:
The request is rejected.
Resolution:
Verify that the proper group is being installed.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0004I Resource definition group group-name install initiated from (facility-id)

Group group-name install is initiated from terminal or facility facility-id.
System Action:
Continue operation.
Module:
dfhzcins
Destination:
console, TD queue CRDI
Parent topic: CASRD0000 - CASRD0019


CASRD0005E Group group-name is not installed, check messages in TS queue TS-queue-name

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.
Module:
dfhzcins
Destination:
terminal, console, TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0006E Group group-name is installed with errors, check messages in TS queue TS-queue-name

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.
Module:
dfhzcins
Destination:
terminal, console, TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0007I Resource definition group group-name is successfully installed

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.
Module:
dfhzcins
Destination:
terminal, console, TD queue CRDI
Parent topic: CASRD0000 - CASRD0019


CASRD0008I resource-type entry resource-name from group group-name replaced existing definition

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0009I resource-type entry resource-name from group group-name installed

The resource definition for resource-type entry resource-name from group group-name is installed in the current system.
System Action:
Continue.
Module:
dfhzins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0010E resource-type entry resource-name from group group-name install failed, reason: reason-code

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.

   6  duplicate     Should have been caught in validation
   7  no space      There is not enough shared memory to install
                    the resource.
  10  duplicate netname
  11  netname invalid
  12  duplicate partner LU alias
  13  partner LU alias invalid
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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0011S Resource definition file open error, reason reason-code

The resource definition file is not accessible.

The open request failed. The reason is reason-code. Common reasons are:

  5  file not found
  8  mismatch

The reason code is the return code from an open request to the resource definition file access module.

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0012W resource-type entry resource-name from group group-name not supported

The resource type resource-type (resource resource-name, group group-name) is not supported.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0013W resource-type entry resource-name from group group-name delete failed, reason reason-code

An attempt was made to delete the resource-type entry resource-name in 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:

  10  duplicate netname
  11  netname invalid
  12  duplicate partner LU alias
  13  partner LU alias invalid
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0014W resource-type entry resource-name from group group-name install failed, reason reason-code

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:

   6  duplicate     Should have been caught in validation
   7  no space      There is not enough shared memory to install
                    the resource.
  10  duplicate netname
  11  netname invalid
  12  duplicate partner LU alias
  13  partner LU alias invalid
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0015W resource-type entry resource-name from group group-name not recognized

The resource type resource-type (resource resource-name, group group-name) is not recognized.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0016W resource-type entry resource-name from group group-name not supported

The resource type resource-type (resource resource-name, group group-name) is not supported.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0017W resource-type entry resource-name from group group-name not recognized

The resource type resource-type (resource resource-name, group group-name) is not recognized.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0018E resource-type entry resource-name from group group-name not CLOSED and either UNENABLED or DISABLED

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0019E Extra-partition resource-type entry resource-name from group group-name not CLOSED

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0000 - CASRD0019


CASRD0020 - CASRD0039

  • CASRD0020E Replace is not supported for general terminal resource-name
    The resource definition for terminal resource-name is not installable.
  • CASRD0021E Replace is not supported for ECI requester resource-name
    The resource definition for terminal resource-name is not installable.
  • CASRD0022E Replace is not supported for SURROGATE terminal resource-name
    The resource definition for terminal resource-name is not installable.
  • CASRD0023E Replace is not supported for SESSION definition resource-name
    The resource definition for terminal resource-name is not installable.
  • CASRD0024E Replace is not supported for definition resource-name, type not recognized
    The resource definition for terminal resource-name is not installable.
  • CASRD0025E 3270 resource-type entry resource-name from group group-name is not out of service and/or it is in use
    The resource definition for resource-type entry resource-name is not installable.
  • CASRD0026E Connection resource-type entry resource-name from group group-name is not out of service and/or it is in use
    The resource definition for resource-type entry resource-name is not installable.
  • CASRD0027E Conversion table definition file open error, reason reason-code
    The data conversion table definition file is not accessible.
  • CASRD0028W resource-type entry resource-name from group group-name not supported
    The resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0029W CVT type resource-type entry resource-name from group group-name not recognized
    The CVT resource type resource-type (resource resource-name, group group-name) is not supported.
  • CASRD0030E resource-type entry resource-name is busy. CVT definition not installed, group group-name
    The resource-type entry resource-name is locked with an ENQ.
  • CASRD0031I resource-type entry resource-name from group group-name installed
    The CVT definition for resource-type entry resource-name from group group-name is installed in the current system.
  • CASRD0032E resource-type entry resource-name from group group-name install failed, reason reason-code
    An attempt was made to install the resource-type entry resource-name from group group-name.
  • CASRD0033E resource-type entry resource-name from group group-name install local storage error: reason-code
    An attempt was made to install the resource-type entry resource-name from group group-name.
  • CASRD0034W resource-type entry resource-name from group group-name is ZERO length table
    An attempt was made to install the resource-type entry resource-name from group group-name.
  • CASRD0035W resource-type entry resource-name from group group-name, base resource not found
    An attempt was made to install the resource-type entry resource-name from group group-name.
  • CASRD0036W resource-type entry resource-name from group group-name, free of old table failed, reason reason-code
    During install of the resource-type entry resource-name, group group-name, a free main for the old table definition failed.
  • CASRD0037E resource-type entry resource-name from group group-name, not installed, type invalid
    A conversion table entry of type resource-type (entry resource-name, group group-name) is invalid.
  • CASRD0038E resource-type entry resource-name from group group-name, not installed, not supported
    A conversion table entry of type resource-type (entry resource-name, group group-name) is not currently supported.
  • CASRD0039E Invalid input for install of group group-name, error parameter: error-parameter
    Extra parameter or invalid parameter in install request for group group-name.
Parent topic: CASRD - CICS Resource Definition DFHRDEF Error Messages


CASRD0020E Replace is not supported for general terminal resource-name

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0021E Replace is not supported for ECI requester resource-name

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0022E Replace is not supported for SURROGATE terminal resource-name

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0023E Replace is not supported for SESSION definition resource-name

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0024E Replace is not supported for definition resource-name, type not recognized

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0025E 3270 resource-type entry resource-name from group group-name is not out of service and/or it is in use

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0026E Connection resource-type entry resource-name from group group-name is not out of service and/or it is in use

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0027E Conversion table definition file open error, reason reason-code

The data conversion table definition file is not accessible.

The open request failed. The reason is reason-code. Common reasons are:

  5  file not found
  8  mismatch

The reason code is the return code from an open request to the CVT definition file access module.

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0028W resource-type entry resource-name from group group-name not supported

The resource type resource-type (resource resource-name, group group-name) is not supported.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0029W CVT type resource-type entry resource-name from group group-name not recognized

The CVT resource type resource-type (resource resource-name, group group-name) is not supported.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0030E resource-type entry resource-name is busy. CVT definition not installed, group group-name

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0031I resource-type entry resource-name from group group-name installed

The CVT definition for resource-type entry resource-name from group group-name is installed in the current system.
System Action:
Continue.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0032E resource-type entry resource-name from group group-name install failed, reason reason-code

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:

   6  duplicate     Should have been caught in validation
   7  no space      There is not enough shared memory to install
                    the resource.
System Action:
Continue, the CVT definition is not installed.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0033E resource-type entry resource-name from group group-name install local storage error: reason-code

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0034W resource-type entry resource-name from group group-name is ZERO length table

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0035W resource-type entry resource-name from group group-name, base resource not found

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0036W resource-type entry resource-name from group group-name, free of old table failed, reason reason-code

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0037E resource-type entry resource-name from group group-name, not installed, type invalid

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0038E resource-type entry resource-name from group group-name, not installed, not supported

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.
Module:
dfhzcins
Destination:
TD queue CRDI, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0039E Invalid input for install of group group-name, error parameter: error-parameter

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0020 - CASRD0039


CASRD0040 - CASRD0059

  • CASRD0040E resource-type entry resource-name from group group-name not found
    The resource type resource-type (resource resource-name, group group-name) is not found.
  • CASRD0041E Read of resource-type entry resource-name from group group-name failed, reason reason-code
    The READ for resource type resource-type (resource resource-name, group group-name) failed for reason reason-code.
  • CASRD0042E resource-type name resource-name in group group-name is busy. Resource will not be installed
    The resource-type name resource-name is locked with an ENQ.
  • CASRD0043E Resource type resource-type not recognized
    The resource type that you are trying to install is not recognized.
  • CASRD0044E Keyword GROUP expected - found keyword. Resource will not be installed
    The GROUP keyword for the resource that you are trying to install is not recognized.
  • CASRD0045E Closing single quote missing or mismatched. resource-name Resource will not be installed
    The hexadecimal value entered for the transaction had a single quote missing or mismatched.
  • CASRD0046E Closing double quote missing or mismatched. resource-name Resource will not be installed
    The hexadecimal value entered for the transaction had a double quote missing or mismatched.
  • CASRD0047E resource-type entry resource-name not DISABLED
    The resource definition for resource-type entry resource-name is not installable.
  • CASRD0048E resource-type entry resource-name already open
    The resource definition for resource-type entry resource-name is not installable.
  • CASRD0049E Opening resource-type resource-name has failed because port port number is in use
    The resource definition for resource-type entry resource-name is not installable.
  • CASRD0050E resource-type resource-name not installed as it maps the same URI as URIMAP2
    The URIMAP resource-name cannot be installed as it maps to the same HOST and PATH plus optional TCPIPSERVICE as URIMAP2.
  • CASRD0051E resource-type resource-name not installed as it contains the same TEMPLATENAME as DOCTEMPLATE2
    The DOCTEMPLATE resource-name cannot be installed as it contains the same TEMPLATENAME as DOCTEMPLATE2.
  • CASRD0052E resource-type resource-name not installed as Current Userid is not a surrogate of URIMAP Userid or is not authorized.
    The Current Userid Current Userid is not a surrogate of user URIMAP Userid or has not enough power the resource cannot be installed.
  • CASRD0053E resource-type entry resource-name not installed. Resource already exists
    The resource definition for resource-type entry resource-name is not installable because it is a duplicate of one that already exists.
  • CASRD0054E BUNDLE entry bundle name not installed. Bundle directory does not exist.
    The bundle definition for bundle name is not installable because the bundle directory does not exist.
  • CASRD0055W BUNDLE entry bundle name installed as disabled. Associated JSONTRANFRM install failed.
    The bundle definition for bundle name was installed but is disabled because the associated JSONTRANFRM resource install failed.
  • CASRD0056E resource-type entry resource-name not installed. cipher xml error xml return-code
    The resource definition for resource-type entry resource-name is not installable because of an issue with cipher xml.
Parent topic: CASRD - CICS Resource Definition DFHRDEF Error Messages


CASRD0040E resource-type entry resource-name from group group-name not found

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0041E Read of resource-type entry resource-name from group group-name failed, reason reason-code

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0042E resource-type name resource-name in group group-name is busy. Resource will not be installed

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0043E Resource type resource-type not recognized

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0044E Keyword GROUP expected - found keyword. Resource will not be installed

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0045E Closing single quote missing or mismatched. resource-name Resource will not be installed

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0046E Closing double quote missing or mismatched. resource-name Resource will not be installed

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.
Module:
dfhzcins
Destination:
terminal, TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0047E resource-type entry resource-name not DISABLED

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0048E resource-type entry resource-name already open

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0049E Opening resource-type resource-name has failed because port port number is in use

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0050E resource-type resource-name not installed as it maps the same URI as URIMAP2

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0051E resource-type resource-name not installed as it contains the same TEMPLATENAME as DOCTEMPLATE2

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0052E resource-type resource-name not installed as Current Userid is not a surrogate of URIMAP Userid or is not authorized.

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.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0053E resource-type entry resource-name not installed. Resource already exists

The resource definition for resource-type entry resource-name is not installable because it is a duplicate of one that already exists.
System Action:
Continue, the resource will not be installed.
Resolution:
Discard the resource and retry the operation.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0054E BUNDLE entry bundle name not installed. Bundle directory does not exist.

The bundle definition for bundle name is not installable because the bundle directory does not exist.
System Action:
Continue, the resource will not be installed.
Resolution:
Discard the resource and retry the operation.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0055W BUNDLE entry bundle name installed as disabled. Associated JSONTRANFRM install failed.

The bundle definition for bundle name was installed but is disabled because the associated JSONTRANFRM resource install failed.
System Action:
Continue, the resource will be installed as disabled.
Resolution:
Discard the resource and retry the operation.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD0056E resource-type entry resource-name not installed. cipher xml error xml return-code

The resource definition for resource-type entry resource-name is not installable because of an issue with cipher xml.
System Action:
Continue, the resource will not be installed.
Resolution:
Discard the resource, check cipher xml and retry the operation.
Module:
dfhzcins
Destination:
TS queue CEBR{facility-name}
Parent topic: CASRD0040 - CASRD0059


CASRD1000 - CASRD1019

  • CASRD1000I Service (service-name) added successfully
    The service was added successfully.
  • CASRD1001I Service (service-name) updated successfully
    The service was updated successfully.
  • CASRD1002I Service (service-name) deleted successfully
    The service was deleted successfully.
  • CASRD1005E Add request for Service (service-name) failed, RC = return-code
    An unsuccessful request was made to add the named service.
  • CASRD1006E Update request for Service (service-name) failed, RC = return-code
    An unsuccessful request was made to update the named service.
  • CASRD1007E Delete request for Service (service-name) failed, RC = return-code
    An unsuccessful request was made to delete the named service.
  • CASRD1008I Unrecognized administration request for Service (service-name)
    An unrecognized administration request was made for the named service.
  • CASRD1010I Request Handler (request-handler-name) added successfully
    The request handler was added successfully.
  • CASRD1011I Request Handler (request-handler-name) updated successfully
    The request handler was updated successfully.
  • CASRD1012I Request Handler (request-handler-name) deleted successfully
    The request handler was deleted successfully.
  • CASRD1015E Add request for Request Handler (request-handler-name) failed, RC = return-code
    An unsuccessful request was made to add the named request handler.
  • CASRD1016E Update request for Request Handler (request-handler-name) failed, RC = return-code
    An unsuccessful request was made to update the named request handler.
  • CASRD1017E Delete request for Request Handler (request-handler-name) failed, RC = return-code
    An unsuccessful request was made to delete the named request handler.
  • CASRD1018I Unrecognized administration request for Request Handler (request-handler-name)
    An unrecognized administration request was made for the named request handler.
Parent topic: CASRD - CICS Resource Definition DFHRDEF Error Messages


CASRD1000I Service (service-name) added successfully

The service was added successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1001I Service (service-name) updated successfully

The service was updated successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1002I Service (service-name) deleted successfully

The service was deleted successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1005E Add request for Service (service-name) failed, RC = return-code

An unsuccessful request was made to add the named service.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1006E Update request for Service (service-name) failed, RC = return-code

An unsuccessful request was made to update the named service.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1007E Delete request for Service (service-name) failed, RC = return-code

An unsuccessful request was made to delete the named service.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1008I Unrecognized administration request for Service (service-name)

An unrecognized administration request was made for the named service.
System Action:
Reject the request.
Resolution:
Check the product installation.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1010I Request Handler (request-handler-name) added successfully

The request handler was added successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1011I Request Handler (request-handler-name) updated successfully

The request handler was updated successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1012I Request Handler (request-handler-name) deleted successfully

The request handler was deleted successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1015E Add request for Request Handler (request-handler-name) failed, RC = return-code

An unsuccessful request was made to add the named request handler.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1016E Update request for Request Handler (request-handler-name) failed, RC = return-code

An unsuccessful request was made to update the named request handler.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1017E Delete request for Request Handler (request-handler-name) failed, RC = return-code

An unsuccessful request was made to delete the named request handler.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1018I Unrecognized administration request for Request Handler (request-handler-name)

An unrecognized administration request was made for the named request handler.
System Action:
Reject the request.
Resolution:
Check the product installation.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1000 - CASRD1019


CASRD1020 - CASRD1039

  • CASRD1030I Package (package-name) added successfully
    The package was added successfully.
  • CASRD1031I Package (package-name) updated successfully
    The package was updated successfully.
  • CASRD1032I Package (package-name) deleted successfully
    The package was deleted successfully.
  • CASRD1035E Add request for Package (package-name) failed, RC = return-code
    An unsuccessful request was made to add the named package.
  • CASRD1036E Update request for Package (package-name) failed, RC = return-code
    An unsuccessful request was made to update the named package.
  • CASRD1037E Delete request for Package (package-name) failed, RC = return-code
    An unsuccessful request was made to delete the named package.
  • CASRD1038I Unrecognized administration request for Package (package-name)
    An unrecognized administration request was made for the named package.
  • CASRD1039E Unrecognized ES service administration request
    A request to add, update or delete a service failed due to an unrecognized service definition.
Parent topic: CASRD - CICS Resource Definition DFHRDEF Error Messages


CASRD1030I Package (package-name) added successfully

The package was added successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1031I Package (package-name) updated successfully

The package was updated successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1032I Package (package-name) deleted successfully

The package was deleted successfully.
System Action:
None.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1035E Add request for Package (package-name) failed, RC = return-code

An unsuccessful request was made to add the named package.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1036E Update request for Package (package-name) failed, RC = return-code

An unsuccessful request was made to update the named package.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1037E Delete request for Package (package-name) failed, RC = return-code

An unsuccessful request was made to delete the named package.

Possible values for return-code are:

  -1      error in definition
  -2      duplicate
  -3      install error
  -4      request mismatch
  -5      in use
  -6      not found
  -7      delete error
  -8      update error
  -9      resource busy
  -10     resource still referenced
  -999    implementation error
System Action:
No updates made.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1038I Unrecognized administration request for Package (package-name)

An unrecognized administration request was made for the named package.
System Action:
Reject the request.
Resolution:
Check the product installation.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1039E Unrecognized ES service administration request

A request to add, update or delete a service failed due to an unrecognized service definition.
System Action:
Reject the administration request.
Resolution:
Check the CAS components are compatible.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1020 - CASRD1039


CASRD1040 - CASRD1059

  • CASRD1040E Unrecognized ES request handler administration request
    A request to add, update or delete a request handler failed due to an unrecognized request handler definition.
  • CASRD1041E Unrecognized ES package administration request
    A request to add, update or delete a package failed due to an unrecognized package definition.
  • CASRD1042I The lock held on Dataset name has been removed by caslock
    The caslock utility has removed a file lock on the specified file.
Parent topic: CASRD - CICS Resource Definition DFHRDEF Error Messages


CASRD1040E Unrecognized ES request handler administration request

A request to add, update or delete a request handler failed due to an unrecognized request handler definition.
System Action:
Reject the administration request.
Resolution:
Check the CAS components are compatible.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1040 - CASRD1059


CASRD1041E Unrecognized ES package administration request

A request to add, update or delete a package failed due to an unrecognized package definition.
System Action:
Reject the administration request.
Resolution:
Check the CAS components are compatible.
Module:
casasrvc
Destination:
Console
Parent topic: CASRD1040 - CASRD1059


CASRD1042I The lock held on Dataset name has been removed by caslock

The caslock utility has removed a file lock on the specified file.
Module:
caslocka
Destination:
Console
Parent topic: CASRD1040 - CASRD1059


CASRM - CICS Resource Manager Control Error Messages

  • CASRM0000 - CASRM0019
Parent topic: Enterprise Server Error Messages


CASRM0000 - CASRM0019

  • 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: CASRM - CICS Resource Manager Control 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: CASRM0000 - CASRM0019


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:
Check the return code and correct the issue.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM0000 - CASRM0019


CASRM0003I ODBC resource manager terminated

The ODBC resource manager facility has terminated normally.
Module:
dfhgodbc
Destination:
Console and standard error.
Parent topic: CASRM0000 - CASRM0019


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: CASRM0000 - CASRM0019


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: CASRM0000 - CASRM0019


CASRS - CASRAS Process Error Messages

  • CASRS2000 - CASRS2019
  • CASRS2040 - CASRS2059
  • CASRS2060 - CASRS2079
  • CASRS2100 - CASRS2119
Parent topic: Enterprise Server Error Messages


CASRS2000 - CASRS2019

  • CASRS2003I ES RAS Process initialization complete
    The ES RAS Process has completed initialization.
  • CASRS2006I ras-service-message
    The ES RAS/Scale Out Process issued a message.
  • CASRS2012E ras-service-error-message
    The ES RAS/Scale Out Process issued an error message.
Parent topic: CASRS - CASRAS Process Error Messages


CASRS2003I ES RAS Process initialization complete

The ES RAS Process has completed initialization.
Module:
casras
Destination:
Console
Parent topic: CASRS2000 - CASRS2019


CASRS2006I ras-service-message

The ES RAS/Scale Out Process issued a message.

The text is ras-service-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casras
Destination:
Console
Parent topic: CASRS2000 - CASRS2019


CASRS2012E ras-service-error-message

The ES RAS/Scale Out Process issued an error message.

The text is ras-service-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
casras
Destination:
Console
Parent topic: CASRS2000 - CASRS2019


CASRS2040 - CASRS2059

  • CASRS2056I ES RAS Process restart in progress
    The ES RAS/Scale Out process has been restarted and recovery operations are in progress.
  • CASRS2057I ES RAS Process (PID:process-id) recovery initiated
    The ES RAS/Scale Out Process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASRS2058I ES RAS Process initialization complete
    The ES RAS/Scale Out Process has completed initialization.
  • CASRS2059I ES RAS Process termination started
    The ES RAS/Scale Out Process is terminating.
Parent topic: CASRS - CASRAS Process Error Messages


CASRS2056I ES RAS Process restart in progress

The ES RAS/Scale Out process has been restarted and recovery operations are in progress.
Module:
casras
Destination:
Console
Parent topic: CASRS2040 - CASRS2059


CASRS2057I ES RAS Process (PID:process-id) recovery initiated

The ES RAS/Scale Out Process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
casras
Destination:
Console and standard error.
Parent topic: CASRS2040 - CASRS2059


CASRS2058I ES RAS Process initialization complete

The ES RAS/Scale Out Process has completed initialization.
Module:
casras
Destination:
Console
Parent topic: CASRS2040 - CASRS2059


CASRS2059I ES RAS Process termination started

The ES RAS/Scale Out Process is terminating.
Module:
casras
Destination:
Console
Parent topic: CASRS2040 - CASRS2059


CASRS2060 - CASRS2079

  • CASRS2060I ES RAS Process registration failed, reason = reason-code
    The ES RAS/Scale Out Process failed registration.
  • CASRS2061I ES RAS Process termination complete
    The ES RAS/Scale Out Process has terminated.
  • CASRS2063I ES RAS Process initialization started
    The server ES RAS/Scale Out Process initialization has started.
  • CASRS2064S ES RAS Process is not running in multi-threaded mode
    The ES RAS/Scale Out Process has not started with the required underlying thread support.
  • CASRS2066I Region reconnected to Redis server Redis server name at Redis server address port Redis port number
    The region reconnected to Redis.
  • CASRS2067I Region successfully processed a newcopy for program program-id
    The request to load a new copy of program-id was successful.
  • CASRS2068I Region successfully processed a phasein for program program-id
    The request to phasein of program-id was successful.
  • CASRS2069I Region successfully processed a close for FCT FCT name
    The request to close FCT FCT name was successful.
  • CASRS2070I Region successfully processed a cancel for program program-id
    The request to cancel program program-id was successful.
  • CASRS2071I Region successfully processed a get rescount for program program-id
    The request to get the rescount for the program program-id was successful.
  • CASRS2072I Region reconnected to Coherence using Coherence connection string
    The region reconnected to Coherence.
  • CASRS2073I Region successfully processed a close for DCT DCT name
    The request to close DCT DCT name was successful.
  • CASRS2074I Region successfully processed a discard for program program-id
    The request to discard program program-id was successful.
  • CASRS2075I Region successfully processed a close for IMS DB program-id
    The request to stop IMS database program-id was successful.
Parent topic: CASRS - CASRAS Process Error Messages


CASRS2060I ES RAS Process registration failed, reason = reason-code

The ES RAS/Scale Out Process failed registration.

The reason code is reason-code.

System Action:
The ES Scale Out Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2061I ES RAS Process termination complete

The ES RAS/Scale Out Process has terminated.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2063I ES RAS Process initialization started

The server ES RAS/Scale Out Process initialization has started.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2064S ES RAS Process is not running in multi-threaded mode

The ES RAS/Scale Out Process has not started with the required underlying thread support.
System Action:
The ES RAS/Scale Out Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2066I Region reconnected to Redis server Redis server name at Redis server address port Redis port number

The region reconnected to Redis.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2067I Region successfully processed a newcopy for program program-id

The request to load a new copy of program-id was successful.
System Action:
A new copy of the program is loaded.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2068I Region successfully processed a phasein for program program-id

The request to phasein of program-id was successful.
System Action:
A new copy of the program is being phased in.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2069I Region successfully processed a close for FCT FCT name

The request to close FCT FCT name was successful.
System Action:
All SEPs have closed the file.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2070I Region successfully processed a cancel for program program-id

The request to cancel program program-id was successful.
System Action:
The requested program was canceled.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2071I Region successfully processed a get rescount for program program-id

The request to get the rescount for the program program-id was successful.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2072I Region reconnected to Coherence using Coherence connection string

The region reconnected to Coherence.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2073I Region successfully processed a close for DCT DCT name

The request to close DCT DCT name was successful.
System Action:
castsc has closed the file.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2074I Region successfully processed a discard for program program-id

The request to discard program program-id was successful.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2075I Region successfully processed a close for IMS DB program-id

The request to stop IMS database program-id was successful.
Module:
casras
Destination:
Console
Parent topic: CASRS2060 - CASRS2079


CASRS2100 - CASRS2119

  • CASRS2105I Number of load modules synchronized from the PAC CasLOADS Load module type (CICS, JES, etc) module(s) were synchronized from PAC PAC Name CasLOADS.
    The current region downloaded and stored new load modules from the PAC.
  • CASRS2106E Thread Thread name could not connect to Redis server Redis server name at Redis server address port Redis port number, RC=Return code from connection attempt
    The thread failed to connect to the Redis server.
  • CASRS2107E Error changing state of ITR record in PSOR to "State of ITR" RC=PSOR Return code. Type=Type of ITR, Action=Action on ITR, Resource=Resource
    An error occurred whilst attempting to update the state of an ITR in the PSOR.
Parent topic: CASRS - CASRAS Process Error Messages


CASRS2105I Number of load modules synchronized from the PAC CasLOADS Load module type (CICS, JES, etc) module(s) were synchronized from PAC PAC Name CasLOADS.

The current region downloaded and stored new load modules from the PAC.
Module:
casras
Destination:
Console
Parent topic: CASRS2100 - CASRS2119


CASRS2106E Thread Thread name could not connect to Redis server Redis server name at Redis server address port Redis port number, RC=Return code from connection attempt

The thread failed to connect to the Redis server.
Module:
casras
Destination:
Console
Parent topic: CASRS2100 - CASRS2119


CASRS2107E Error changing state of ITR record in PSOR to "State of ITR" RC=PSOR Return code. Type=Type of ITR, Action=Action on ITR, Resource=Resource

An error occurred whilst attempting to update the state of an ITR in the PSOR.
Resolution:
Contact Micro Focus Customer Support.
Module:
casras
Destination:
Console
Parent topic: CASRS2100 - CASRS2119


CASSE - CICS Security Error Messages

  • CASSE0000 - CASSE0019
  • CASSE0020 - CASSE0039
  • CASSE0040 - CASSE0059
  • CASSE0100 - CASSE0119
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.
  • CASSE0004I Signon complete at term-id, for user user-id. Password unchanged.
    user-id has successfully completed signon at terminal term-id.
  • 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.
  • 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.
  • 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.
  • CASSE0019W Unexpected signon failure
    An expected error occurred processing the signon request.
Parent topic: CASSE - CICS Security 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:
user-id access authority is granted at terminal term-id.
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:
user-id access authority is granted at terminal term-id and the password has been changed for user-id.
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:
user-id access authority is granted at terminal term-id.
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:
user-id access authority is granted at terminal term-id.
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:
user-id access authority is granted at terminal term-id and the password has been changed for user-id.
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:
user-id access authority is granted at terminal term-id.
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:
user-id access authority is granted at terminal term-id.
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:
user-id access authority is granted at terminal term-id.
Resolution:
None.
Module:
dfhzcesg
Destination:
User terminal and TDQ CSCS
Parent topic: CASSE0000 - CASSE0019


CASSE0019W Unexpected signon failure

An expected error occurred 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 - CASSE0039

  • 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 "Userid" invalid or password incorrect, region terminating
    The associated user ID was invalid or the supplied password was incorrect.
  • CASSE0033E User Userid not authorized to start ES "Region name", region terminating.
    The supplied user has not the credentials to start ES.
  • CASSE0034E PLTPI user "Userid" invalid, region terminating.
    The supplied PLTPI user is invalid.
  • CASSE0035E User "Userid" is not a surrogate user of PLTPI user "PLTPI Userid", region terminating.
    The supplied user has not the credentials to run PLTPI processing.
  • CASSE0036E User ID "Userid" invalid or password incorrect.
    The associated user ID was invalid or the supplied password was incorrect.
  • CASSE0037I User "Userid" deleted SNT entry "SNT Entry".
    The SNT entry has been deleted in ESMAC by user.
  • CASSE0038I User "Userid" modified SNT entry "SNT Entry".
    The SNT entry has been modified in ESMAC by user.
Parent topic: CASSE - CICS Security 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 - CASSE0039


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


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.

The options are as follows:

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 behavior.
Module:
dfheexin
Destination:
Console
Parent topic: CASSE0020 - CASSE0039


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


CASSE0032E User ID "Userid" 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 - CASSE0039


CASSE0033E User Userid not authorized to start ES "Region name", 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 - CASSE0039


CASSE0034E PLTPI user "Userid" 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 - CASSE0039


CASSE0035E User "Userid" is not a surrogate user of PLTPI user "PLTPI Userid", 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 - CASSE0039


CASSE0036E User ID "Userid" 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 - CASSE0039


CASSE0037I User "Userid" deleted SNT entry "SNT Entry".

The SNT entry has been deleted in ESMAC by user.
System Action:
None.
Module:
casrdo93
Destination:
CSCS TDQ.
Parent topic: CASSE0020 - CASSE0039


CASSE0038I User "Userid" modified SNT entry "SNT Entry".

The SNT entry has been modified in ESMAC by user.
System Action:
None.
Module:
casrdo93
Destination:
CSCS TDQ.
Parent topic: CASSE0020 - CASSE0039


CASSE0040 - CASSE0059

  • CASSE0050I Success-message
    The ESF update request was successful.
  • CASSE0051E Error-message
    The ESF update request was unsuccessful.
Parent topic: CASSE - CICS Security Error Messages


CASSE0050I Success-message

The ESF update request was successful.
System Action:
ESF update processed.
Module:
casaesfu
Destination:
System Console
Parent topic: CASSE0040 - CASSE0059


CASSE0051E Error-message

The ESF update request was unsuccessful.
System Action:
ESF update rejected.
Module:
casaesfu
Destination:
System Console
Parent topic: CASSE0040 - CASSE0059


CASSE0100 - CASSE0119

  • 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.
Parent topic: CASSE - CICS Security Error Messages


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: CASSE0100 - CASSE0119


CASSI - CICS System Initialization Error Messages

  • CASSI0000 - CASSI0019
  • CASSI0020 - CASSI0039
  • CASSI1000 - CASSI1019
  • CASSI1400 - CASSI1419
  • CASSI1420 - CASSI1439
  • CASSI1440 - CASSI1459
  • CASSI1460 - CASSI1479
  • CASSI1500 - CASSI1519
  • CASSI1600 - CASSI1619
  • CASSI1700 - CASSI1719
  • CASSI1720 - CASSI1739
  • CASSI1740 - CASSI1759
  • CASSI1800 - CASSI1819
  • CASSI1820 - CASSI1839
  • CASSI1840 - CASSI1859
  • CASSI1860 - CASSI1879
  • CASSI1880 - CASSI1899
  • CASSI1900 - CASSI1919
  • CASSI2000 - CASSI2019
  • CASSI2100 - CASSI2119
  • CASSI2140 - CASSI2159
  • CASSI2200 - CASSI2219
  • CASSI4000 - CASSI4019
  • CASSI4100 - CASSI4119
  • CASSI5000 - CASSI5019
  • CASSI5020 - CASSI5039
  • CASSI5040 - CASSI5059
  • CASSI6000 - CASSI6019
  • CASSI7000 - CASSI7019
  • CASSI8000 - CASSI8019
  • CASSI9000 - CASSI9019
  • CASSI9020 - CASSI9039
  • CASSI9040 - CASSI9059
Parent topic: Enterprise Server Error Messages


CASSI0000 - CASSI0019

  • CASSI0000I Server manager initialization started
    A region has started its initialization phase.
  • CASSI0001I Region will use SYSID SYSID, local CCSID Local CCSID and ascii CCSID local ASCII CCSID
    In the region manager's initialization phase the SIT has been read and the region will use the SYSID specified in that SIT with the local CCSID specified.
  • CASSI0002F Unable to create shared memory, reason = return-code
    In the region manager's initialization phase the shared memory creation failed.
  • CASSI0003F Unable to create semaphore, reason = return-code
    In the region manager's initialization phase the semaphore creation failed.
  • CASSI0004S PLTPI list 'PLTPI-list-name' could not be found
    The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-name which was specified in the SIT for the starting region could not be located in any of the groups installed to the system.
  • CASSI0005S Requested SIT 'SIT-name' could not be found
    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 Error opening RDO file, reason = rdi-file-request-result, subcodes (fcd-stat-byte-1,fcd-stat-byte-2)
    Whilst attempting to open the resource definition file an error occurred.
  • CASSI0007S Error closing RDO file, reason = rdi-file-request-result, subcodes (fcd-stat-byte-1,fcd-stat-byte-2)
    An error occurred whilst closing the resource definition file.
  • CASSI0008W Warning: shared memory re-attach failure
    After successfully creating and attaching to the shared memory a re-attach call failed.
  • CASSI0009S Error registering storage-type with requested AMODE
    An error occurred when attempting to register the storage of the specified type using the AMODE selected in the SIT.
  • CASSI0010S Error registering storage-type with requested AMODE
    An error occurred when attempting to register the storage of the specified type using the AMODE selected in the SIT.
  • CASSI0011I External security manager configured, external shutdown will require sign on
    An external security manager is configured for the region therefore external shutdown of the region will require sign on.
  • CASSI0012I Region running in Bitism bit mode
    The region bitism mode.
  • CASSI0013W Warning: Failed to allocate Extended User Storage Area
    The OS refused the memory allocation request which included the configured Extended User Storage Area.
  • CASSI0014I Console message user exit CASMGUEX active
    The console message user exit CASMGUEX which can be used to manage which messages are displayed has been detected and loaded.
  • CASSI0015I ES support for CICS WEBSERVICES is enabled
    CICS WEBSERVICES support is enabled for Enterprise Server.
  • CASSI0016W ES_HA_VSAM configuration invalid.
    The HA VSAM configuration environment variable initial character was not a valid command character.
  • CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables Source CCSID to Target CCSID not found
    CICS WEBSERVICES support is disabled for Enterprise Server because the CCSID tables specified were not found.
  • CASSI0018S ES Fileshare service process terminated during initialization and will not be restarted
    The Fileshare service process terminated during initialization and a restart will not be attempted because it is expected to fail again for the same reason.
  • CASSI0019I Region running with futex() based shared memory locking
    Displayed when using the futex function to manage shared memory access contention.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI0000I Server manager initialization started

A region has started its initialization phase.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0001I Region will use SYSID SYSID, local CCSID Local CCSID and ascii CCSID local ASCII CCSID

In the region manager's initialization phase the SIT has been read and the region will use the SYSID specified in that SIT with the local CCSID specified.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0002F Unable to create shared memory, reason = return-code

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0003F Unable to create semaphore, reason = return-code

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0004S PLTPI list 'PLTPI-list-name' could not be found

The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-name which 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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0005S Requested SIT 'SIT-name' could not be found

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0006S Error opening RDO file, reason = rdi-file-request-result, subcodes (fcd-stat-byte-1,fcd-stat-byte-2)

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0007S Error closing RDO file, reason = rdi-file-request-result, subcodes (fcd-stat-byte-1,fcd-stat-byte-2)

An error occurred whilst closing the resource definition file.
System Action:
None.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0008W Warning: shared memory re-attach failure

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0009S Error registering storage-type with requested AMODE

An error occurred 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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0010S Error registering storage-type with requested AMODE

An error occurred 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.
Module:
dfheserv
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0011I External security manager configured, external shutdown will require sign on

An external security manager is configured for the region therefore external shutdown of the region will require sign on.
System Action:
None.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0012I Region running in Bitism bit mode

The region bitism mode.
System Action:
None.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0013W Warning: Failed to allocate Extended User Storage Area

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:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0014I Console message user exit CASMGUEX active

The console message user exit CASMGUEX which can be used to manage which messages are displayed has been detected and loaded.
System Action:
None.
Resolution:
None.
Module:
dfh0msg
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0015I ES support for CICS WEBSERVICES is enabled

CICS WEBSERVICES support is enabled for Enterprise Server.
System Action:
ES behavior supports CICS WEBSERVICES.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI0000 - CASSI0019


CASSI0016W ES_HA_VSAM configuration invalid.

The HA VSAM configuration environment variable initial character was not a valid command character.
System Action:
The configuration will be ignored.
Resolution:
Check your configuration.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables Source CCSID to Target CCSID not found

CICS WEBSERVICES support is disabled for Enterprise Server because the CCSID tables specified were not found.
System Action:
The region will start but the option will be disabled.
Resolution:
Check your configuration.
Module:
dfhginit
Destination:
Console.
Parent topic: CASSI0000 - CASSI0019


CASSI0018S ES Fileshare service process terminated during initialization and will not be restarted

The Fileshare service process terminated during initialization and a restart will not be attempted because it is expected to fail again for the same reason.
System Action:
ES will start if no critical files are being handled by this process. Otherwise, ES will shutdown.
Resolution:
Resolve the problem with the Fileshare service process and restart the system.
Module:
casmgr
Destination:
Console.
Parent topic: CASSI0000 - CASSI0019


CASSI0019I Region running with futex() based shared memory locking

Displayed when using the futex function to manage shared memory access contention.
System Action:
None.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI0000 - CASSI0019


CASSI0020 - CASSI0039

  • CASSI0020S Error creating monitoring thread thread name return code CBL_CREATE_THREAD return-code
    An error occurred when attempting to create the monitoring thread for this process.
  • CASSI0021E Unable to attach to shared memory, reason = return-code
    The process could not attach to share memory.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI0020S Error creating monitoring thread thread name return code CBL_CREATE_THREAD return-code

An error occurred when attempting to create the monitoring thread for this process.
System Action:
The region will not be started.
Resolution:
Check the documentation for the return code.
Module:
dfheserv casbat casmpr
Destination:
Console and standard error.
Parent topic: CASSI0020 - CASSI0039


CASSI0021E Unable to attach to shared memory, reason = return-code

The process could not attach to share memory.
System Action:
As a the process cannot attach to the share memory the process stops.
Resolution:
None.
Module:
dfhgreqi
Destination:
Console and standard error.
Parent topic: CASSI0020 - CASSI0039


CASSI1000 - CASSI1019

  • CASSI1000I Server Manager initialization completed successfully
    The region manager has successfully completed its initialization phase.
  • CASSI1001S Server manager initialization failure
    The region manager failed during its initialization phase.
  • CASSI1002S Server manager initialization failure, no valid license found
    The region manager failed the license check during its initialization phase.
  • CASSI1003W Server manager initialization error, no MSS license found
    The region manager failed the CICS license check during its initialization phase.
  • CASSI1004W Warning: insufficient license units. Requested: Requested-license-count Available: Available-license-count
    The requested number of licenses were not available at initialization.
  • CASSI1005E Error license-status or license system message requesting license
    An error occurred requesting additional licenses.
  • CASSI1006E Error license-status returning license
    An error occurred returning licenses.
  • CASSI1007E Error: Unable to determine CES message length return code from CBL_CES_GET_ERROR_MSG_LEN return code from CES request
    An error occurred requesting licenses from CES but the length of the text of the message cannot be retrieved from CES.
  • CASSI1008E Error: Could not retrieve CES message return code from CBL_CES_GET_ERROR_MSG return code from CES request
    An error occurred requesting licenses from CES but the text of the message cannot be retrieved from CES.
  • CASSI1009E Error from CES: text of the message from CES return code from CES request
    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.
  • CASSI1016E Licensing error: license system message
    A licensing system error occurred.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1000I Server Manager initialization completed successfully

The region manager has successfully completed its initialization phase.
System Action:
None.
Resolution:
None.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1001S Server manager initialization failure

The region manager failed during its initialization phase.
System Action:
None.
Resolution:
None.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1002S Server manager initialization failure, no valid license found

The region manager failed the license check during its initialization phase.
System Action:
None.
Resolution:
None.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1003W Server manager initialization error, no MSS license found

The region manager failed the CICS license check during its initialization phase.
System Action:
None.
Resolution:
None.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1004W Warning: insufficient license units. Requested: Requested-license-count Available: Available-license-count

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.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1005E Error license-status or license system message requesting license

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.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1006E Error license-status returning license

An error occurred returning licenses.
System Action:
Licenses will not be returned.
Resolution:
Check that the licensing software is installed and configured correctly.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1007E Error: Unable to determine CES message length return code from CBL_CES_GET_ERROR_MSG_LEN return code from CES request

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.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1008E Error: Could not retrieve CES message return code from CBL_CES_GET_ERROR_MSG return code from CES request

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.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1009E Error from CES: text of the message from CES return code from CES request

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.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


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


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


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


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


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


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


CASSI1016E Licensing error: license system message

A licensing system error occurred.
System Action:
Depends on error.
Resolution:
Message will indicate action.
Module:
casmgr
Destination:
Console and standard error.
Parent topic: CASSI1000 - CASSI1019


CASSI1400 - CASSI1419

  • CASSI1400S Temporary storage/transient data file name TS-TD-name is illegal
    The name of the temporary storage/transient data file as specified in the SIT is illegal.
  • CASSI1401S Error connecting to Fileshare server FS-server for TS/TD file
    While attempting to initialize the temporary storage or transient data file an error occurred while connecting with the Fileshare server FS-server.
  • CASSI1402S Run time error rts-error while initializing TS/TD file
    While attempting to initialize the temporary storage or transient data file a run time error occurred.
  • CASSI1403S Error initializing TS/TD file filename, reason = (file-status-byte-1,file-status-byte-2)
    While attempting to initialize the temporary storage or transient data file a file access error occurred.
  • CASSI1404S Error locating TS/TD file, reason = locate-status
    While attempting to locate the temporary storage or transient data file an error occurred.
  • CASSI1405S Failed on re-index check for non-recoverable TS file TXTSNR, reason = failure reason, file status(file-status-byte-1,file-status-byte-2)
    Failed to add an alternate index to TXTSNR.
  • CASSI1406I Warm start of TS non-recoverable queues successfully upgraded TXTSNR to include an alternate index
    An old format TXTSNR file, which had a single key, was used on a warm start of non-recoverable TS queues.
  • CASSI1410S Failed to 'exec' animate server, rc = return-code
    The attempt to start a CICS API server under animator control failed due to an error in DosExecPgm.
  • CASSI1411E Error, could not inform REM of animate server termination, rc = return-code
    The attempt to inform the region manager of the animate server's termination failed due to an error in DosExecPgm.
  • CASSI1412S Failed to 'exec' animate server, rc = return-code
    The attempt to start a CICS API server under animator control failed due to an error in execlp.
  • CASSI1413S Error calling '$COBDIR\cli.lbr'
    The attempt to start a CICS API server under animator control failed due to $COBDIR\cli.lbr not being found.
  • CASSI1414S Error calling '$COBDIR\cobcli.lbr'
    The attempt to start a CICS API server under animator control failed due to $COBDIR\cobcli.lbr not being found.
  • CASSI1415E Error loading dfheini1
    An error occurred loading dfheini1.
  • CASSI1416S Error calling '$COBDIR\anim2.lbr'
    The attempt to start a CICS API server under GUI animator control failed due to $COBDIR\anim2.lbr not being found.
  • CASSI1417S Animate option animate-option for resource resource-name invalid
    The attempt to start a CICS API server under animator control in the single process region failed due to an illegal command line.
  • CASSI1418S Error, can not start GUI animator from non graphical session
    The attempt to start a CICS API server under GUI animator control failed as the program was not running as a graphical application.
  • CASSI1419S Error calling '$COBDIR\mfcsi.lbr'
    The attempt to start a CICS API server under GUI animator control failed due to $COBDIR\mfcsi.lbr not being found.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1400S Temporary storage/transient data file name TS-TD-name is illegal

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.
Module:
dfheini1(dfhcptdi)
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1401S Error connecting to Fileshare server FS-server for TS/TD file

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.
Module:
dfheini1(dfhcptdi)
Destination:
Console
Parent topic: CASSI1400 - CASSI1419


CASSI1402S Run time error rts-error while initializing TS/TD file

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.
Module:
dfheini1(dfhcptdi)
Destination:
Console
Parent topic: CASSI1400 - CASSI1419


CASSI1403S Error initializing TS/TD file filename, reason = (file-status-byte-1,file-status-byte-2)

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.
Module:
dfheini1(dfhcptdi)
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1404S Error locating TS/TD file, reason = locate-status

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.
Module:
dfheini1(dfhcptdi)
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1405S Failed on re-index check for non-recoverable TS file TXTSNR, reason = failure reason, file status(file-status-byte-1,file-status-byte-2)

Failed to add an alternate index to TXTSNR.
System Action:
Temp Storage file needs to be re-indexed. Region initialization will be unsuccessful.
Resolution:
Check if TXTSNR is corrupted or cold start temporary storage. Contact technical support.
Module:
dfheini1
Destination:
Console
Parent topic: CASSI1400 - CASSI1419


CASSI1406I Warm start of TS non-recoverable queues successfully upgraded TXTSNR to include an alternate index

An old format TXTSNR file, which had a single key, was used on a warm start of non-recoverable TS queues.
System Action:
Temp Storage file was successfully upgraded to include an alternate index.
Resolution:
Note: The upgraded file cannot be used on earlier versions of the product.
Module:
dfheini1
Destination:
Console
Parent topic: CASSI1400 - CASSI1419


CASSI1410S Failed to 'exec' animate server, rc = return-code

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1411E Error, could not inform REM of animate server termination, rc = return-code

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1412S Failed to 'exec' animate server, rc = return-code

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1413S Error calling '$COBDIR\cli.lbr'

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1414S Error calling '$COBDIR\cobcli.lbr'

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1415E Error loading dfheini1

An error occurred loading dfheini1.

Either the module dfheini1.gnt is not in $TXDIR/lib or the environment variable TXDIR is not properly set.

System Action:
Client initialization is terminated.
Resolution:
Correct TXDIR or the location of dfheini1.gnt and retry.
Module:
dfheserv
Destination:
Standard out
Parent topic: CASSI1400 - CASSI1419


CASSI1416S Error calling '$COBDIR\anim2.lbr'

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1417S Animate option animate-option for resource resource-name invalid

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1418S Error, can not start GUI animator from non graphical session

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1419S Error calling '$COBDIR\mfcsi.lbr'

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI1400 - CASSI1419


CASSI1420 - CASSI1439

  • CASSI1420S Temporary storage/transient data file name TS-TD-name is illegal
    The name of the temporary storage/transient data file as specified in the SIT is illegal.
  • CASSI1421S Error connecting to Fileshare server FS-server for TS/TD file
    While attempting to initialize the temporary storage or transient data file an error occurred while connecting with the Fileshare server FS-server.
  • CASSI1422S Run time error rts-error while initializing TS/TD file
    While attempting to initialize the temporary storage or transient data file a run time error occurred.
  • CASSI1423S Error initializing TS/TD file filename, reason = (file-status-byte-1,file-status-byte-2)
    While attempting to initialize the temporary storage or transient data file a file access error occurred.
  • CASSI1424S Error locating TS/TD file, reason = locate-status
    While attempting to locate the temporary storage or transient data file an error occurred.
  • CASSI1425I TS recoverable / non-recoverable cold / warm started
    The temporary storage recoverable/non-recoverable has been cold/warm started.
  • CASSI1426I TD recoverable / non-recoverable cold / warm started
    The transient data recoverable/non-recoverable has been cold/warm started.
  • CASSI1427E Error TS recoverable / non-recoverable could not be cold / warm started
    The temporary storage recoverable/non-recoverable could not be cold/warm started.
  • CASSI1428E Error TD recoverable / non-recoverable could not be cold / warm started
    The transient data recoverable/non-recoverable could not be cold/warm started.
  • CASSI1429I Region connected to Redis server Redis server name at Redis server address port Redis port number
    The region successfully connected to Redis.
  • CASSI1430E Region could not connect to Redis server Redis server name at Redis server address port Redis port number, RC=Return code from connection attempt
    The region failed to connect to Redis.
  • CASSI1431I PAC PAC Name starting.
    The region is the first region participating in the specified PAC.
  • CASSI1432I Joining PAC PAC Name.
    The region is joining the specified PAC.
  • CASSI1433I Leaving PAC PAC Name.
    The region is leaving the specified PAC.
  • CASSI1434E This region cannot join PAC PAC Name because the current operating system Operating system of the current ES region does not match the PAC operating system Operating system of the PAC.
    The current region operating system is different from the PAC operating system.
  • CASSI1435I Number of load modules synchronized from the PAC CasLOADS Load module type (CICS, JES, etc) module(s) were synchronized from PAC PAC Name CasLOADS.
    The current region downloaded and stored new load modules from the PAC.
  • CASSI1436E Error trying to synchronize Load module type (CICS, JES, etc) load modules from PAC PAC Name CasLOADS for this region. Error code Return code from synchronization.
    The current region failed to synchronize load modules from the PAC.
  • CASSI1437S Region cannot be started as we could not connect to PAC PAC Name.
    The current region failed to connect to the PAC.
  • CASSI1438S Region cannot be started as we could not get a new Member count for PAC PAC Name. Error code Return code.
    The current region failed to get a new member count in the PAC.
  • CASSI1439S Region cannot be started as the name of the PAC PAC Name is not alphanumeric.
    The current region failed to start as the PAC name is not alphanumeric.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1420S Temporary storage/transient data file name TS-TD-name is illegal

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.
Module:
dfhginit(dfhcptdi)
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1421S Error connecting to Fileshare server FS-server for TS/TD file

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.
Module:
dfhginit(dfhcptdi)
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1422S Run time error rts-error while initializing TS/TD file

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.
Module:
dfhginit(dfhcptdi)
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1423S Error initializing TS/TD file filename, reason = (file-status-byte-1,file-status-byte-2)

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.
Module:
dfhginit(dfhcptdi)
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1424S Error locating TS/TD file, reason = locate-status

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.
Module:
dfhginit(dfhcptdi)
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1425I TS recoverable / non-recoverable cold / warm started

The temporary storage recoverable/non-recoverable has been cold/warm started.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1426I TD recoverable / non-recoverable cold / warm started

The transient data recoverable/non-recoverable has been cold/warm started.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1427E Error TS recoverable / non-recoverable could not be cold / warm started

The temporary storage recoverable/non-recoverable could not be cold/warm started.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1428E Error TD recoverable / non-recoverable could not be cold / warm started

The transient data recoverable/non-recoverable could not be cold/warm started.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1420 - CASSI1439


CASSI1429I Region connected to Redis server Redis server name at Redis server address port Redis port number

The region successfully connected to Redis.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1430E Region could not connect to Redis server Redis server name at Redis server address port Redis port number, RC=Return code from connection attempt

The region failed to connect to Redis.
Resolution:
Check that the Redis server is up and running and that the specified address and port are correct.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1431I PAC PAC Name starting.

The region is the first region participating in the specified PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1432I Joining PAC PAC Name.

The region is joining the specified PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1433I Leaving PAC PAC Name.

The region is leaving the specified PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1434E This region cannot join PAC PAC Name because the current operating system Operating system of the current ES region does not match the PAC operating system Operating system of the PAC.

The current region operating system is different from the PAC operating system.
System Action:
Shutdown the region.
Resolution:
All regions in a PAC need to be on the same operating system.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1435I Number of load modules synchronized from the PAC CasLOADS Load module type (CICS, JES, etc) module(s) were synchronized from PAC PAC Name CasLOADS.

The current region downloaded and stored new load modules from the PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1436E Error trying to synchronize Load module type (CICS, JES, etc) load modules from PAC PAC Name CasLOADS for this region. Error code Return code from synchronization.

The current region failed to synchronize load modules from the PAC.
System Action:
Shutdown the region.
Resolution:
All regions in a PAC need to be able to synchronize load modules.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1437S Region cannot be started as we could not connect to PAC PAC Name.

The current region failed to connect to the PAC.
System Action:
Shutdown the region.
Resolution:
All regions in a PAC need to be able to connect to the PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1438S Region cannot be started as we could not get a new Member count for PAC PAC Name. Error code Return code.

The current region failed to get a new member count in the PAC.
System Action:
Shutdown the region.
Resolution:
All regions in a PAC need to be able to get a member count in the PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1439S Region cannot be started as the name of the PAC PAC Name is not alphanumeric.

The current region failed to start as the PAC name is not alphanumeric.
System Action:
Shutdown the region.
Resolution:
Change the PAC name to be alphanumeric.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1420 - CASSI1439


CASSI1440 - CASSI1459

  • CASSI1440I Region connected to datastore Datastore name at SQL server host
    The region successfully connected to the datastore.
  • CASSI1441I Region created and connected to datastore Datastore name at SQL server host
    The region successfully created and connected to the datastore.
  • CASSI1442E Region could not connect to datastore Datastore name at server SQL server host - server not found
    The region failed to connect to the datastore because the server was not found.
  • CASSI1443E Region could not connect to datastore Datastore name at server SQL server host - datastore not found
    The region failed to connect to the datastore because it was not found.
  • CASSI1444E Region could not connect to datastore Datastore name at SQL server host - IO error
    The region failed to connect to the datastore because of an IO error.
  • CASSI1445E Region could not connect to datastore Datastore name at SQL server host - Unknown error
    The region failed to connect to the datastore for an unknown reason.
  • CASSI1446E Region could not join the PAC as the current product (PAC version Product PAC version) is incompatible with the PAC version Current PAC version
    The region cannot join the current started PAC.
  • CASSI1447E Region cannot be started because MFDBFH region initialization failed or no cross region database configured.
    The current region failed to start as the region initialization for MFDBFH failed a cross region database is not configured.
  • CASSI1448W Manager process requested cold start operation could not complete successfully.
    The initialization for the manager process cannot complete the requested start operation, as such it will be restarted.
  • CASSI1449I Region PAC UUID Region PAC UUID.
    The region PAC UUID used for identification purposes in a PAC.
  • CASSI1450E Error loading casmfdbfh
    The CAS interface to MFDBFH could not be loaded.
  • CASSI1451E Exception on initial call to casmfdbfh
    There was an exception on the call to the CAS interface to MFDBFH.
  • CASSI1452E Error initializing casmfdbfh. RC=Return code from initialization attempt
    The CAS interface to MFDBFH could not be initialized.
  • CASSI1453S Region configuration error, PAC defined with no PSOR
    The region is configured to use PAC but no PSOR has been defined.
  • CASSI1454I ES support for CICS TRANCLASS MaxActive is enabled
    CICS TRANCLASS MaxActive is enabled for Enterprise Server.
  • CASSI1455E Region cannot be started because MFDBFH region region name could not be found in the configuration file.
    The current region failed to start as the region initialization for MFDBFH failed a region database with that name is not configured.
  • CASSI1456E Invalid SOR type specified in SOR Environment variable. SOR will be ignored.
    An invalid SOR type was specified for the SOR before the end point connection.
  • CASSI1457W No SOR name specified in SOR Environment variable. SOR will be ignored.
    A SOR needs a name just after the first = in the environment variable.
  • CASSI1458W MFDBFH LOCK management support is implicit in the PAC, ES_LOCKDB bypassed.
    MFDBFH LOCKDB management is implicit in the PAC.
  • CASSI1459W ES_LOCKDB group name LOCKDB group name is not alphanumeric, ES_LOCKDB value rejected.
    LOCKDB name must be alphanumeric.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1440I Region connected to datastore Datastore name at SQL server host

The region successfully connected to the datastore.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1441I Region created and connected to datastore Datastore name at SQL server host

The region successfully created and connected to the datastore.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1442E Region could not connect to datastore Datastore name at server SQL server host - server not found

The region failed to connect to the datastore because the server was not found.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1443E Region could not connect to datastore Datastore name at server SQL server host - datastore not found

The region failed to connect to the datastore because it was not found.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1444E Region could not connect to datastore Datastore name at SQL server host - IO error

The region failed to connect to the datastore because of an IO error.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1445E Region could not connect to datastore Datastore name at SQL server host - Unknown error

The region failed to connect to the datastore for an unknown reason.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1446E Region could not join the PAC as the current product (PAC version Product PAC version) is incompatible with the PAC version Current PAC version

The region cannot join the current started PAC.
Resolution:
Restart the whole PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1447E Region cannot be started because MFDBFH region initialization failed or no cross region database configured.

The current region failed to start as the region initialization for MFDBFH failed a cross region database is not configured.

When using a PAC a cross region database is mandatory.

System Action:
Shutdown the region.
Resolution:
Check your MFDBFH configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1448W Manager process requested cold start operation could not complete successfully.

The initialization for the manager process cannot complete the requested start operation, as such it will be restarted.
System Action:
Terminate and restart the manager process using a different start mode.
Resolution:
None.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1449I Region PAC UUID Region PAC UUID.

The region PAC UUID used for identification purposes in a PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1450E Error loading casmfdbfh

The CAS interface to MFDBFH could not be loaded.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1451E Exception on initial call to casmfdbfh

There was an exception on the call to the CAS interface to MFDBFH.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1452E Error initializing casmfdbfh. RC=Return code from initialization attempt

The CAS interface to MFDBFH could not be initialized.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1453S Region configuration error, PAC defined with no PSOR

The region is configured to use PAC but no PSOR has been defined.
System Action:
Shutdown the region.
Resolution:
Check your configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1454I ES support for CICS TRANCLASS MaxActive is enabled

CICS TRANCLASS MaxActive is enabled for Enterprise Server.
System Action:
ES behavior is modified to support TRANCLASS MaxActive.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1455E Region cannot be started because MFDBFH region region name could not be found in the configuration file.

The current region failed to start as the region initialization for MFDBFH failed a region database with that name is not configured.
System Action:
Shutdown the region.
Resolution:
Check your MFDBFH configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1456E Invalid SOR type specified in SOR Environment variable. SOR will be ignored.

An invalid SOR type was specified for the SOR before the end point connection.
System Action:
Shutdown the region.
Resolution:
Check your PAC configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1457W No SOR name specified in SOR Environment variable. SOR will be ignored.

A SOR needs a name just after the first = in the environment variable.
Resolution:
Check your PAC configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1458W MFDBFH LOCK management support is implicit in the PAC, ES_LOCKDB bypassed.

MFDBFH LOCKDB management is implicit in the PAC.
Resolution:
remove the unnecessary environment variable.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1459W ES_LOCKDB group name LOCKDB group name is not alphanumeric, ES_LOCKDB value rejected.

LOCKDB name must be alphanumeric.
System Action:
correct ES_LOCKDB environment variable.
Resolution:
none.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1440 - CASSI1459


CASSI1460 - CASSI1479

  • CASSI1460I MFDBFH LOCK management enabled across ES group LOCKDB name.
    MFDBFH will orchestrate lock/enq for all members of the ES group.
  • CASSI1461E Region cannot be started because MFDBFH server server name could not be found in the configuration file.
    The current region failed to start as the region initialization for MFDBFH failed a server with that name is not configured.
  • CASSI1462I Region connected to Coherence using Coherence connection string
    The region successfully connected to Coherence.
  • CASSI1463E Region could not connect to Coherence using Coherence connection string, RC=Return code from connection attempt
    The region failed to connect to Coherence.
  • CASSI1464E Region cannot be started because MFDBFH region is in an invalid state.
    The current region failed to start as the region initialization for MFDBFH failed with an invalid region state.
  • CASSI1465S Region cannot be started as the name of the PAC PAC Name is not permitted.
    The current region failed to start as the PAC name is not permitted.
  • CASSI1466I Process connected to SOR SOR server name at SOR server address port SOR port number
    The region successfully connected to the SOR.
  • CASSI1467E Process shutting down because it could not connect to PSOR PSOR server name at PSOR address after Amount of retry time seconds.
    The process failed to connect to the PSOR.
  • CASSI1468E Region shutting down because it could not connect to SOR PSOR server name.
    The region failed to connect to SOR.
  • CASSI1469I Micro Focus Database File Handler support is requested
    Support for the Micro Focus Database File Handler has been requested and task synchronization actions will be executed.
  • CASSI1470W Synchronize of Load module type (CICS, JES, etc) load modules failed due to bad environment. Check configured program load directory for the failing type.
    Synchronize of load modules failed due to no load directory in environment.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1460I MFDBFH LOCK management enabled across ES group LOCKDB name.

MFDBFH will orchestrate lock/enq for all members of the ES group.
System Action:
None.
Resolution:
None.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1461E Region cannot be started because MFDBFH server server name could not be found in the configuration file.

The current region failed to start as the region initialization for MFDBFH failed a server with that name is not configured.
System Action:
Shutdown the region.
Resolution:
Check your MFDBFH configuration.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1462I Region connected to Coherence using Coherence connection string

The region successfully connected to Coherence.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1463E Region could not connect to Coherence using Coherence connection string, RC=Return code from connection attempt

The region failed to connect to Coherence.
Resolution:
Check that the Coherence cluster is up and running, that Java is installed and coherence.jar is on CLASSPATH.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1464E Region cannot be started because MFDBFH region is in an invalid state.

The current region failed to start as the region initialization for MFDBFH failed with an invalid region state.
System Action:
Shutdown the region.
Resolution:
Check your MFDBFH region state using dbfhadmin command.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1465S Region cannot be started as the name of the PAC PAC Name is not permitted.

The current region failed to start as the PAC name is not permitted.
System Action:
Shutdown the region.
Resolution:
Change the PAC name to be valid.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1466I Process connected to SOR SOR server name at SOR server address port SOR port number

The region successfully connected to the SOR.
Module:
dfheini1
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1467E Process shutting down because it could not connect to PSOR PSOR server name at PSOR address after Amount of retry time seconds.

The process failed to connect to the PSOR.
System Action:
Process will shutdown.
Resolution:
Check that the PSOR is up and running and can be connected to.
Module:
dfheini1
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1468E Region shutting down because it could not connect to SOR PSOR server name.

The region failed to connect to SOR.
System Action:
Region will shutdown.
Resolution:
Check that the SOR is up and running and can be connected to.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1469I Micro Focus Database File Handler support is requested

Support for the Micro Focus Database File Handler has been requested and task synchronization actions will be executed.
Module:
dfhcpism
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1470W Synchronize of Load module type (CICS, JES, etc) load modules failed due to bad environment. Check configured program load directory for the failing type.

Synchronize of load modules failed due to no load directory in environment.
System Action:
Warning message. Synchronization of load modules will not work in this region.
Resolution:
Check program path for for failing type. E.g. CICS transaction path, JES Program Path.
Module:
dfheserv
Destination:
Console
Parent topic: CASSI1460 - CASSI1479


CASSI1500 - CASSI1519

  • CASSI1500I SEP initialization started
    A TX CICS API server has started its initialization phase.
  • CASSI1501I Event Manager initialization started
    The Event Manager Process has started its initialization phase.
  • CASSI1502S Event Manager Process registration failed, reason = reason-code
    The Event Manager Process failed registration.
  • CASSI1503I Event Manager initialization complete
    The Event Manager Process has completed its initialization phase.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1500I SEP initialization started

A TX CICS API server has started its initialization phase.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1500 - CASSI1519


CASSI1501I Event Manager initialization started

The Event Manager Process has started its initialization phase.
Module:
casevmgr
Destination:
Console and standard error
Parent topic: CASSI1500 - CASSI1519


CASSI1502S Event Manager Process registration failed, reason = reason-code

The Event Manager Process failed registration.

The reason code is reason-code.

System Action:
The Event Manager Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
casevmgr
Destination:
Console
Parent topic: CASSI1500 - CASSI1519


CASSI1503I Event Manager initialization complete

The Event Manager Process has completed its initialization phase.
Module:
casevmgr
Destination:
Console and standard error
Parent topic: CASSI1500 - CASSI1519


CASSI1600 - CASSI1619

  • CASSI1600I SEP initialization completed successfully
    A TX CICS API server has successfully completed its initialization phase.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1600I SEP initialization completed successfully

A TX CICS API server has successfully completed its initialization phase.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1600 - CASSI1619


CASSI1700 - CASSI1719

  • CASSI1700I Server initialization unsuccessful, reason = return-code
  • CASSI1701S Failed to allocate server Comms Buffer, reason = return-code
    A problem occurred allocating memory for the server communications buffer used for peer to peer data flows.
  • CASSI1702S Error return-code during initialization of server PCA
    An error occurred whilst initializing the server's PCA.
  • CASSI1703S TCA registration of server failed, reason = tca-return-flag
    The registration of the server's TCA failed, the server will not complete its initialization.
  • CASSI1704S Attempt to run EBCDIC CICS with ASCII DL/I rejected
    None.
  • CASSI1705S Attempt to run ASCII CICS with EBCDIC DL/I rejected
    None.
  • CASSI1706I Animation initialization for terminal transaction successful
    The server is registered as a debug server for terminal transaction.
  • CASSI1707I Animation initialization for ALL transaction successful
    The server is registered as a debug server for transaction.
  • CASSI1708S Animation initialization unsuccessful, reason = RC
    The animation initialization was unsuccessful.
  • CASSI1709S Initialization error: another server already active
    An error occurred whilst starting a single user development region.
  • CASSI1710S Error extended-file-status starting single user server, run time lock not acquired
    An error occurred whilst starting a single user development region.
  • CASSI1711S Initialization error: another server already active
    An error occurred whilst starting a region, a single user region was already running.
  • CASSI1712S Error runtime-lock-status starting server, run time lock not acquired
    An error occurred whilst starting a region.
  • CASSI1713S Error, failed to open resource definition file
    An error occurred on initial access to the resource definition file while initializing a single task region.
  • CASSI1714S Error, failed to acquire dynamic subpool memory
    An error occurred allocating memory for the dynamic subpool while initializing a single task region.
  • CASSI1715S Error, bad resource definition file version
    The version of the resource definition file is not recognized.
  • CASSI1716S Error, resource definition file version newer than this system
    The version of the resource definition file is not recognized.
  • CASSI1717S Error, resource definition file version older than this system
    The version of the resource definition file is not recognized.
  • CASSI1718I Loading single process system 3270 DBCS support (version-number)
    The 3270 emulation for DBCS and SI/SO is being loaded.
  • CASSI1719I Loading single process system 3270 support (version-number)
    The 3270 emulation for a single process system is being loaded.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1700I Server initialization unsuccessful, reason = return-code

Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1701S Failed to allocate server Comms Buffer, reason = return-code

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1702S Error return-code during initialization of server PCA

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1703S TCA registration of server failed, reason = tca-return-flag

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1704S Attempt to run EBCDIC CICS with ASCII DL/I rejected

None.
Module:
None
Destination:
None
Parent topic: CASSI1700 - CASSI1719


CASSI1705S Attempt to run ASCII CICS with EBCDIC DL/I rejected

None.
Module:
None
Destination:
None
Parent topic: CASSI1700 - CASSI1719


CASSI1706I Animation initialization for terminal transaction successful

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1707I Animation initialization for ALL transaction successful

The server is registered as a debug server for transaction.
System Action:
All work for the above resource will be routed to this server.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1708S Animation initialization unsuccessful, reason = RC

The animation initialization was unsuccessful.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1709S Initialization error: another server already active

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1710S Error extended-file-status starting single user server, run time lock not acquired

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, <project-name>\system, is read-only.

System Action:
The single user region will not initialize successfully.
Resolution:
Ensure that the directory <project-name>\system is not read-only.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1711S Initialization error: another server already active

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.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1712S Error runtime-lock-status starting server, run time lock not acquired

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.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1713S Error, failed to open resource definition file

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1714S Error, failed to acquire dynamic subpool memory

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1715S Error, bad resource definition file version

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1716S Error, resource definition file version newer than this system

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1717S Error, resource definition file version older than this system

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1718I Loading single process system 3270 DBCS support (version-number)

The 3270 emulation for DBCS and SI/SO is being loaded.
System Action:
Continue.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1719I Loading single process system 3270 support (version-number)

The 3270 emulation for a single process system is being loaded.
System Action:
Continue.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1700 - CASSI1719


CASSI1720 - CASSI1739

  • CASSI1720S Requested SIT 'SIT-name' could not be found
    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 Requested startup list startup-list not found
    The startup list specified in the SIT could not be located in the resource definition file.
  • CASSI1722S Requested startup list startup-list is empty
    The startup list specified in the SIT did not contain any groups/resources in the resource definition file.
  • CASSI1723S Requested startup list startup-list is invalid
    The startup list specified in the SIT is invalid.
  • CASSI1724S PLTPI list 'PLTPI-list-name' could not be found
    The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-name which was specified in the SIT for the starting region could not be located in any of the groups installed to the system.
  • CASSI1725S Requested startup list startup-list not found
    The startup list specified in the SIT could not be located in the resource definition file.
  • CASSI1726S Requested startup list startup-list is empty
    The startup list specified in the SIT did not contain any groups/resources in the resource definition file.
  • CASSI1727S Requested startup list startup-list is invalid
    The startup list specified in the SIT is invalid.
  • CASSI1728S Logon to database manager selected failed for reason detailed
    The system tried to log on to DB manager selected and failed to connect for the reason shown by the sqlcode detailed.
  • CASSI1729I Logon to database manager DBM completed successfully
    The logon request was successful.
  • CASSI1730S Failed to locate LBR for DB manager selected
    The system failed to locate the LBR required for loading for DB manager selected.
  • CASSI1731S Failed to locate LBR for product-name
    The system failed to locate the LBR required for loading the MF IMS product.
  • CASSI1732W product-name warning messages issued, return code = IMS return code
    The system received a return code other than 0 from initialization of the IMS product.
  • CASSI1733S product-name error - see $IMSWRK\IMSMTO.LOG, IMS rc = IMS return code
    The system received a return code other than 0 from initialization of the IMS product.
  • CASSI1734I product-name Logon Successful
    The system has successfully logged on to the Micro Focus IMS emulation product.
  • CASSI1735S Failed to load support module: Support module name
    The system failed to load the named support module at initialization.
  • CASSI1736S Integrated support for Database system name or IMS system name not available on this O/S
    The RDO file SIT indicator is set to request connection to a particular database system automatically at start up time.
  • CASSI1737W product-name error - see MCO370.LOG, MF/370 rc = MF/370 return code
    The system received a return code other than 0 from initialization of the MF/370 product.
  • CASSI1738I product-name support loaded successfully
    The MF/370 support is loaded at system initialization if present/required.
  • CASSI1739W MVS Control block initialization failure, rc=return-code
    A non zero response was returned when trying to initialize the MVS control blocks.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1720S Requested SIT 'SIT-name' could not be found

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1721S Requested startup list startup-list not found

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1722S Requested startup list startup-list is empty

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1723S Requested startup list startup-list is invalid

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1724S PLTPI list 'PLTPI-list-name' could not be found

The Program Load Table Pre-Initialization (PLTPI) list PLTPI-list-name which 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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1725S Requested startup list startup-list not found

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1726S Requested startup list startup-list is empty

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1727S Requested startup list startup-list is invalid

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.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1728S Logon to database manager selected failed for reason detailed

The system tried to log on to DB manager selected and 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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1729I Logon to database manager DBM completed successfully

The logon request was successful.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1730S Failed to locate LBR for DB manager selected

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1731S Failed to locate LBR for product-name

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1732W product-name warning messages issued, return code = IMS return code

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1733S product-name error - see $IMSWRK\IMSMTO.LOG, IMS rc = IMS return code

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1734I product-name Logon Successful

The system has successfully logged on to the Micro Focus IMS emulation product.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1735S Failed to load support module: Support module name

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 $TXDIR/lib.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1736S Integrated support for Database system name or IMS system name not available on this O/S

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1737W product-name error - see MCO370.LOG, MF/370 rc = MF/370 return code

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1738I product-name support loaded successfully

The MF/370 support is loaded at system initialization if present/required.

This operation was successful.

System Action:
Region initialization will continue.
Resolution:
None.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1739W MVS Control block initialization failure, rc=return-code

A non zero response was returned when trying to initialize the MVS control blocks.
System Action:
Region initialization will continue.
Resolution:
None.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1720 - CASSI1739


CASSI1740 - CASSI1759

  • CASSI1740W product-name initialization failure (RC = IMS return code) see IMS log
    The system received a return code other than 0 from initialization of the IMS product.
  • CASSI1741S Error starting debug server
    The registration of the server's TCA failed, the debug server will not complete its initialization.
  • CASSI1742S Error starting debug server, terminal terminal-id not active
    The registration of the server's TCA failed as the requested 3270 terminal was not active in the region.
  • CASSI1743S Error starting debug server, transaction transaction-id not found
    The registration of the server's TCA failed as the requested non-facility transaction ID was not installed in the region.
  • CASSI1744I product-name support loaded successfully
    The PL/I support is loaded at system initialization if present/required.
  • CASSI1745E Error loading product-name support (cannot find module-name)
    The PL/I support is loaded at system initialization if present/required.
  • CASSI1746W Error loading resident module support
    The system module required to support resident programs and user exits could not be loaded.
  • CASSI1747W Group Group name specified in startup list not found
    The startup list contains a group that is not defined in the CICS resource definition file.
  • CASSI1748W Error accessing Directory ES_SNATRC_DIR: error message
    The directory set up in the environment variable cannot be accessed.
  • CASSI1749I Processing resources in startup list startup-list
    The startup list (or lists GRPLIST) specified in the SIT is being processed.
  • CASSI1750W MFASM support disabled in 64bit environment
    The MFASM engine was attempted to be setup, but can only operate in 32 bit ES environments.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1740W product-name initialization failure (RC = IMS return code) see IMS log

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1741S Error starting debug server

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1740 - CASSI1759


CASSI1742S Error starting debug server, terminal terminal-id not active

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1740 - CASSI1759


CASSI1743S Error starting debug server, transaction transaction-id not found

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI1740 - CASSI1759


CASSI1744I product-name support loaded successfully

The PL/I support is loaded at system initialization if present/required.

This operation was successful.

System Action:
Region initialization will continue.
Resolution:
None.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1745E Error loading product-name support (cannot find module-name)

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1746W Error loading resident module support

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.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1747W Group Group name 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: CASSI1740 - CASSI1759


CASSI1748W Error accessing Directory ES_SNATRC_DIR: error message

The directory set up in the environment variable cannot be accessed.
System Action:
Region initialization will continue.
Resolution:
Check the value of the environment variable.
Module:
dfheini1
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1749I Processing resources in startup list startup-list

The startup list (or lists GRPLIST) specified in the SIT is being processed.
System Action:
None. Region initialization will continue.
Resolution:
None.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1750W MFASM support disabled in 64bit environment

The MFASM engine was attempted to be setup, but can only operate in 32 bit ES environments.
System Action:
Region initialization will continue without MFASM support.
Resolution:
Ensure the correct bitism and ES_MFASM_SUPPORT is not enabled for 64 bit.
Module:
dfhginit
Destination:
Console and standard error.
Parent topic: CASSI1740 - CASSI1759


CASSI1800 - CASSI1819

  • CASSI1800S Error while processing global configuration file
    An error occurred whilst processing the global configuration file.
  • CASSI1801S Error while processing region configuration file
    An error occurred whilst processing the region configuration file.
  • CASSI1802I Dynamic debug attachment permitted
    The server allows remote debuggers to attach.
  • CASSI1803I Dynamic debugger attached. cobdebugremote on port Port number
    A remote debug session has started.
  • CASSI1804I Dynamic debugger attach failed. Reason = Reason code
    An attempt to start a remote debug session has failed.
  • CASSI1805I Dynamic debugger reattached.
    A remote debug session has started.
  • CASSI1806I Dynamic debugger detached.
    A remote debug session has stopped.
  • CASSI1807I Dynamic debug initialization failed.
    The system was unable to load the support required to allow remote debugging.
  • CASSI1808I Remote debugger attached. Cobremotedaemon on port Port number
    A remote debug session has started.
  • CASSI1809I Dynamic debugger attached. Cobdebugremote on port Port number
    A remote debug session has started.
  • CASSI1810W Dynamic debugger port retrieval failed
    An attempt to start a dynamic debug session has failed.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1800S Error while processing global configuration file

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.
Module:
dfhtxs
Destination:
Console
Parent topic: CASSI1800 - CASSI1819


CASSI1801S Error while processing region configuration file

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.
Module:
dfheini1
Destination:
Console
Parent topic: CASSI1800 - CASSI1819


CASSI1802I Dynamic debug attachment permitted

The server allows remote debuggers to attach.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1819


CASSI1803I Dynamic debugger attached. cobdebugremote on port Port number

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


CASSI1804I Dynamic debugger attach failed. Reason = Reason code

An attempt to start a remote debug session has failed.

The reason indicates the return code from the spawning of the cobremotedaemon process.

Module:
casdbgfn
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1819


CASSI1805I Dynamic debugger reattached.

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


CASSI1806I Dynamic debugger detached.

A remote debug session has stopped.

The cobdebugremote process is listening on the displayed port.

Module:
casdbgfn
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1819


CASSI1807I Dynamic debug initialization failed.

The system was unable to load the support required to allow remote debugging.
Resolution:
With task control tracing the entry f603 indicates the reason code (last 2 bytes).
Module:
casdbgfn
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1819


CASSI1808I Remote debugger attached. Cobremotedaemon on port Port number

A remote debug session has started.

The cobremotedaemon process is listening on the displayed port.

Module:
casdbgfn
Destination:
Console and standard error
Parent topic: CASSI1800 - CASSI1819


CASSI1809I Dynamic debugger attached. Cobdebugremote on port Port number

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


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


CASSI1820 - CASSI1839

  • CASSI1839S Error config-error-code processing configuration file
    An error occurred when processing the configuration file.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1839S Error config-error-code processing configuration file

An error occurred when processing the configuration file.

Possible values of config-error-code are:

     09  - TXDIR invalid
     10  - Region files directory (~files/reg) does
           not exist
     11  - Error loading dfh0msg
     12  - Error loading dfh0utl?
     13  - Error loading dfhextfh
System Action:
The CICS server will not initialize successfully.
Resolution:
Correct the configuration file / command line and retry.
Module:
dfheini1
Destination:
Console
Parent topic: CASSI1820 - CASSI1839


CASSI1840 - CASSI1859

  • CASSI1840S Error while processing global configuration file
    An error occurred whilst processing the global configuration file.
  • CASSI1842S Error region name undefined while processing configuration file
    An error occurred whilst processing the configuration file.
  • CASSI1843S Unrecognized line in configuration file, line = line-number
    An unrecognized line was found in the configuration file at the line shown.
  • CASSI1844S Can not find configuration file, reason = RC
    The configuration file could not be found.
  • CASSI1845S Error creating configuration save file, reason = RC
    An error occurred when creating the configuration save file.
  • CASSI1846S Error opening configuration file, reason = RC
    An error occurred when creating the configuration save file.
  • CASSI1847S Error reading configuration file, reason = RC
    An error occurred when reading the configuration save file.
  • CASSI1848S Error writing configuration file, reason = RC
    An error occurred when writing the configuration save file.
  • CASSI1849S Error writing configuration file, TXLOCAL invalid
    An error occurred when writing the configuration save file, the directory specified in the TXLOCAL environment variable was invalid.
  • CASSI1851S Error while processing region configuration file
    An error occurred whilst processing the region configuration file.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1840S Error while processing global configuration file

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.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1842S Error region name undefined while processing configuration file

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.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1843S Unrecognized line in configuration file, line = line-number

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.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1844S Can not find configuration file, reason = RC

The configuration file could not be found.
System Action:
The console daemon or region manager will not initialize successfully.
Resolution:
Make sure that TXDIR is set correctly and that the configuration file exists.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1845S Error creating configuration save file, reason = RC

An error occurred when creating the configuration save file.
System Action:
The console daemon or region manager will not initialize successfully.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1846S Error opening configuration file, reason = RC

An error occurred when creating the configuration save file.
System Action:
The console daemon or region manager will not initialize successfully.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1847S Error reading configuration file, reason = RC

An error occurred when reading the configuration save file.
System Action:
The console daemon or region manager will not initialize successfully.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1848S Error writing configuration file, reason = RC

An error occurred when writing the configuration save file.
System Action:
The console daemon or region manager will not initialize successfully.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1849S Error writing configuration file, TXLOCAL invalid

An error occurred when writing the configuration save file, the directory specified in the TXLOCAL environment variable was invalid.
System Action:
The console daemon will not initialize successfully.
Resolution:
Check that the directory that is specified in TXLOCAL is valid and retry.
Module:
cascd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1851S Error while processing region configuration file

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.
Module:
dfhgtrtd
Destination:
Console
Parent topic: CASSI1840 - CASSI1859


CASSI1860 - CASSI1879

  • CASSI1860S Error while processing global configuration file
    An error occurred whilst processing the global configuration file.
  • CASSI1861S Error while processing region configuration file
    An error occurred whilst processing the region configuration file.
  • CASSI1870S Error while processing global configuration file
    An error occurred whilst processing the global configuration file.
  • CASSI1871S Error while processing region configuration file
    An error occurred whilst processing the region configuration file.
  • CASSI1872S Requested enterprise server instance already started
    An error occurred whilst processing the region configuration file.
  • CASSI1873S Daemon for this ES already running - do you want to connect to it?
    An error occurred whilst processing the region configuration file.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1860S Error while processing global configuration file

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.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1860 - CASSI1879


CASSI1861S Error while processing region configuration file

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.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI1860 - CASSI1879


CASSI1870S Error while processing global configuration file

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.
Module:
dfhecics
Destination:
Console
Parent topic: CASSI1860 - CASSI1879


CASSI1871S Error while processing region configuration file

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.
Module:
dfhecics
Destination:
Console
Parent topic: CASSI1860 - CASSI1879


CASSI1872S Requested enterprise server instance already started

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.
Module:
dfhecics
Destination:
Console
Parent topic: CASSI1860 - CASSI1879


CASSI1873S Daemon for this ES already running - do you want to connect to it?

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.
Module:
dfhecics
Destination:
Console
Parent topic: CASSI1860 - CASSI1879


CASSI1880 - CASSI1899

  • CASSI1880I IMS DLI database scale-out support requested
    Server IMS DLI database scale-out support is requested.
  • CASSI1881I IMS TM message queue scale-out support is requested
    The server allows remote debuggers to attach Server IMS TM message queue scale-out support has been requested.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1880I IMS DLI database scale-out support requested

Server IMS DLI database scale-out support is requested.

This may be reset later in server initilization if errors are encountered.

Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSI1880 - CASSI1899


CASSI1881I IMS TM message queue scale-out support is requested

The server allows remote debuggers to attach Server IMS TM message queue scale-out support has been requested.

This may be reset later in server initilization if errors are encountered.

Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSI1880 - CASSI1899


CASSI1900 - CASSI1919

  • CASSI1900S config-module: Error return-code connecting to server server-name
    An IPS error occurred attaching to the server.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI1900S config-module: Error return-code connecting to server server-name

An IPS error occurred attaching to the server.

Possible values for return-code are:

       1 - unable to obtain mutex
       2 - unable to attach to shared memory
       3 - unable to map shared memory
       9 - unexpected reason code
      10 - threaded runtime mismatch
      20 - unexpected error code
System Action:
Terminate the requesting process.
Resolution:
Check system IPC resources.
Module:
config-module(dfhcpcfp)
Destination:
Standard error
Parent topic: CASSI1900 - CASSI1919


CASSI2000 - CASSI2019

  • CASSI2000I 3270 printer initialization started
    The 3270 printer daemon has begun its initialization phase.
  • CASSI2001I 3270 printer initialization completed successfully
    The 3270 printer daemon has successfully completed its initialization phase.
  • CASSI2002S 3270 printer pca initialization failed, return code = return-code
    The 3270 printer daemon has failed to initialize its pca.
  • CASSI2003S 3270 printer initialization failed, error reading region configuration
    The 3270 printer daemon has failed to initialize as it could not read the region configuration file.
  • CASSI2004S 3270 printer initialization failed, registration error = return-code
    The 3270 printer daemon has failed to initialize as its registration failed.
  • CASSI2005S 3270 printer initialization failed, error reading global configuration
    The 3270 printer daemon has failed to initialize as it could not read the global configuration file.
  • CASSI2006I 3270 printer user exit DFHUPRNT installed successfully
    The 3270 printer daemon has successfully installed the user exit DFHUPRNT.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI2000I 3270 printer initialization started

The 3270 printer daemon has begun its initialization phase.
System Action:
Initialize the printer daemon.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2001I 3270 printer initialization completed successfully

The 3270 printer daemon has successfully completed its initialization phase.
System Action:
The printer daemon will now attempt to install all defined printers.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2002S 3270 printer pca initialization failed, return code = return-code

The 3270 printer daemon has failed to initialize its pca.
System Action:
The printer daemon will not initialize successfully.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2003S 3270 printer initialization failed, error reading region configuration

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.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2004S 3270 printer initialization failed, registration error = return-code

The 3270 printer daemon has failed to initialize as its registration failed.
System Action:
The printer daemon will not initialize successfully.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2005S 3270 printer initialization failed, error reading global configuration

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.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2006I 3270 printer user exit DFHUPRNT installed successfully

The 3270 printer daemon has successfully installed the user exit DFHUPRNT.
System Action:
This exit will be used for all print requests.
Module:
dfht3prt
Destination:
Console and standard error
Parent topic: CASSI2000 - CASSI2019


CASSI2100 - CASSI2119

  • CASSI2100E Error initializing 3270 terminal emulator
    An error occurred while attempting to initialize the 3270 terminal emulator.
  • CASSI2101E Error processing 3270 terminal command line
    An error occurred while processing the command line passed to the 3270 terminal emulator.
  • CASSI2102E Error, unsupported 3270 screen size
    An error occurred while attempting to initialize the 3270 terminal emulator.
  • CASSI2103E Error in registration of 3270 terminal
    An error occurred while initializing the 3270 terminal emulator.
  • CASSI2104E Error in auto-install of 3270 terminal
    An error occurred while initializing the 3270 terminal emulator.
  • CASSI2105I 3270 terminal initialization started
    The 3270 terminal has begun its initialization phase.
  • CASSI2106E Error invoking COBOL run time system
    The COBOL run time system could not be located.
  • CASSI2107E Error locating the 3270 thin client program
    The module dfht3270.gnt could not be located.
  • CASSI2108E Target region not found
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2109E Can not find dfh0cfg
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2110E Can not find dfh0msg
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2111E Error initializing global configuration area
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2112E Error retrieving global configuration
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2113E Error retrieving region configuration
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2114E Unknown initialization error, RC = Return code
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2115E Error, terminal setup failure
    An error occurred while attempting to connect the 3270 terminal emulator to the target region.
  • CASSI2116E Error loading dfhtinit
    An error occurred loading dfhtinit.
  • CASSI2117I 3270 client connecting to region
    This message is put on the screen to give information to the user in case the connect process takes an unexpected amount of time.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI2100E Error initializing 3270 terminal emulator

An error occurred while attempting to initialize the 3270 terminal emulator.
System Action:
Return to operating system prompt.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2101E Error processing 3270 terminal command line

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2102E Error, unsupported 3270 screen size

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2103E Error in registration of 3270 terminal

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2104E Error in auto-install of 3270 terminal

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2105I 3270 terminal initialization started

The 3270 terminal has begun its initialization phase.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2106E Error invoking COBOL run time system

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.
Module:
dfht3270.c
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2107E Error locating the 3270 thin client program

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.
Module:
dfht3270.c
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2108E Target region not found

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2109E Can not find dfh0cfg

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 $TXDIR/lib.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2110E Can not find dfh0msg

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 $TXDIR/lib.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2111E Error initializing global configuration area

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2112E Error retrieving global configuration

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2113E Error retrieving region configuration

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2114E Unknown initialization error, RC = Return code

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2115E Error, terminal setup failure

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.
Module:
dfht3270
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2116E Error loading dfhtinit

An error occurred loading dfhtinit.

Either the module dfhtinit.gnt is not in $TXDIR/lib or the environment variable TXDIR is not properly set.

System Action:
Client initialization is terminated.
Resolution:
Correct TXDIR or the location of dfhtinit.gnt and retry.
Module:
dfht3270, dfht32db (dfhcpt3p)
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2117I 3270 client connecting to region

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.
Module:
dfht3270, dfht32db (dfhcpt3p)
Destination:
Standard out
Parent topic: CASSI2100 - CASSI2119


CASSI2140 - CASSI2159

  • CASSI2150E Error loading dfhtinit
    An error occurred loading dfhtinit.
  • CASSI2151W Unable to change screen size, RC=return-code
    As part of terminal initialization the auto-install process modified the default terminal screen size.
  • CASSI2152W Unable to change screen size, RC=return-code
    As part of terminal initialization the auto-install process modified the default terminal screen size.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI2150E Error loading dfhtinit

An error occurred loading dfhtinit.

Either the module dfhtinit.gnt is not in $TXDIR/lib or the environment variable TXDIR is not properly set.

System Action:
Client initialization is terminated.
Resolution:
Correct TXDIR or the location of dfhtinit.gnt and retry.
Module:
dfhtasci
Destination:
Standard out
Parent topic: CASSI2140 - CASSI2159


CASSI2151W Unable to change screen size, RC=return-code

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.
Module:
dfht32sb/dfht32db (dfhcpt3t)
Destination:
Standard out
Parent topic: CASSI2140 - CASSI2159


CASSI2152W Unable to change screen size, RC=return-code

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.
Module:
dfhe3270/dfhe32db (dfhcpt3t)
Destination:
Standard out
Parent topic: CASSI2140 - CASSI2159


CASSI2200 - CASSI2219

  • CASSI2201I Spool service initialization completed successfully
    The spool service has successfully completed its initialization phase.
  • CASSI2202E Error during initialization of spool service
    Error.
  • CASSI2203E IO-operation error on file filename, RC = return-code. Job may not be submitted.
    A file I/O error has occurred while submitting JCL to the internal reader.
  • CASSI2204E IO-operation error on file filename, RC = return-code. Report may not be spooled.
    A file I/O error has occurred while writing a report to the spooler.
  • CASSI2205E Spool error on token token-value. Func = function, RC = return-code.
    An error has occurred while interfacing with the MFE MVS Jobstep Resource Manager.
  • CASSI2206E Spooling not supported as JES/SSTM not active
    Error.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI2201I Spool service initialization completed successfully

The spool service has successfully completed its initialization phase.
System Action:
None.
Module:
dfhgspol
Destination:
Console and standard error
Parent topic: CASSI2200 - CASSI2219


CASSI2202E Error during initialization of spool service

Error.
System Action:
None.
Module:
dfhgspol
Destination:
Console and standard error
Parent topic: CASSI2200 - CASSI2219


CASSI2203E IO-operation error on file filename, RC = return-code. Job may not be submitted.

A file I/O error has occurred while submitting JCL to the internal reader.
System Action:
Process terminates.
Module:
dfhespol
Destination:
Console and standard error
Parent topic: CASSI2200 - CASSI2219


CASSI2204E IO-operation error on file filename, RC = return-code. Report may not be spooled.

A file I/O error has occurred while writing a report to the spooler.
System Action:
Process terminates.
Module:
dfhespol
Destination:
Console and standard error
Parent topic: CASSI2200 - CASSI2219


CASSI2205E Spool error on token token-value. Func = function, RC = return-code.

An error has occurred while interfacing with the MFE MVS Jobstep Resource Manager.
System Action:
Process terminates.
Module:
dfhespol
Destination:
Console and standard error
Parent topic: CASSI2200 - CASSI2219


CASSI2206E Spooling not supported as JES/SSTM not active

Error.
System Action:
None.
Resolution:
Ensure that Enterprise Server is configured to use SSTM. Edit server's "Configuration Information": [ES-Environment] ES_SSTM_CICS=d:\sstmcics.jcl.
Module:
dfhgspol
Destination:
Console and standard error
Parent topic: CASSI2200 - CASSI2219


CASSI4000 - CASSI4019

  • CASSI4000W Error accessing project database, RC =return-code
    The project database is accessed at region initialization to retrieve the CICS system properties.
  • CASSI4001W Error retrieving project setting "project-setting", RC =return-code
    The project database is accessed at region initialization to retrieve the CICS system properties.
  • CASSI4002W Error (error-message) binding to MFDS
    An error occurred whilst binding to the MF Directory Server.
  • CASSI4003W Error (error-message) retrieving ES configuration from MFDS
    An error occurred whilst retrieving the ES configuration from the MF Directory Server.
  • CASSI4004W Error binding to MFDS, unable to load support module
    An error occurred whilst binding to the MF Directory Server.
  • CASSI4005I Retrieving ES configuration from MFDS (MFDS-address)
    The system successfully bound to MFDS-address.
  • CASSI4006I Single signon is cics-single-signon enforced for CICS clients and is ims-tm-single-signon enforced for IMS TM clients for this startup
    Single signon settings are reported for this ES instance.
  • CASSI4007I IMS MPRs (Message Processing Regions) will all be started as PWFI (Psuedo Wait for Input)
    MPR will behave as configured for PWFI for this instance of Enterprise Server.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI4000W Error accessing project database, RC =return-code

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.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4001W Error retrieving project setting "project-setting", RC =return-code

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.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4002W Error (error-message) binding to MFDS

An error occurred whilst binding to the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4003W Error (error-message) retrieving ES configuration from MFDS

An error occurred whilst retrieving the ES configuration from the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4004W Error binding to MFDS, unable to load support module

An error occurred whilst binding to the MF Directory Server.
System Action:
Continue initialization using defaults.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4005I Retrieving ES configuration from MFDS (MFDS-address)

The system successfully bound to MFDS-address.
System Action:
Continue initialization.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4006I Single signon is cics-single-signon enforced for CICS clients and is ims-tm-single-signon enforced for IMS TM clients for this startup

Single signon settings are reported for this ES instance.
System Action:
Continue initialization.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4007I IMS MPRs (Message Processing Regions) will all be started as PWFI (Psuedo Wait for Input)

MPR will behave as configured for PWFI for this instance of Enterprise Server.
System Action:
Continue initialization.
Module:
dfhcpism
Destination:
Console and standard error
Parent topic: CASSI4000 - CASSI4019


CASSI4100 - CASSI4119

  • CASSI4100I PLTPI Phase plt-phase Processing Starting
    Startup PLT processing is about to start using the %2$s list.
  • CASSI4101I PLTPI Phase plt-phase Enabling EZASOKET support
    Startup PLT processing is about to enable EZASOKET support.
  • CASSI4102I PLTPI Phase plt-phase Installing XA managers
    Startup PLT processing is about to install the XA managers defined.
  • CASSI4103I PLTPI starting JES Phase plt-phase
    Startup PLT processing is about to initialize JES support.
  • CASSI4104I PLTPI Phase plt-phase starting XA recovery program
    Startup PLT processing is about to invoke the XA recovery program.
  • CASSI4105I PLTPI Phase plt-phase starting TS/TD initialization program
    Startup PLT processing is about to invoke the TS/TD initialization program.
  • CASSI4106I PLTPI Phase plt-phase starting File initialization program
    Startup PLT processing is about to invoke the File initialization program.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI4100I PLTPI Phase plt-phase Processing Starting

Startup PLT processing is about to start using the %2$s list.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI4101I PLTPI Phase plt-phase Enabling EZASOKET support

Startup PLT processing is about to enable EZASOKET support.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI4102I PLTPI Phase plt-phase Installing XA managers

Startup PLT processing is about to install the XA managers defined.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI4103I PLTPI starting JES Phase plt-phase

Startup PLT processing is about to initialize JES support.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI4104I PLTPI Phase plt-phase starting XA recovery program

Startup PLT processing is about to invoke the XA recovery program.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI4105I PLTPI Phase plt-phase starting TS/TD initialization program

Startup PLT processing is about to invoke the TS/TD initialization program.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI4106I PLTPI Phase plt-phase starting File initialization program

Startup PLT processing is about to invoke the File initialization program.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI4100 - CASSI4119


CASSI5000 - CASSI5019

  • CASSI5000I PLTPI Phase plt-phase List(plt-name) Processing Started
    Startup PLT processing has started using the plt-name list.
  • CASSI5001I PLTPI Phase plt-phase - No PLT Specified
    Startup PLT processing was entered, but no list was specified.
  • CASSI5002S PLTPI - PLT List Open Error
    The Resource Definition file could not be opened to read the PLTPI program list table.
  • CASSI5003S PLTPI Phase plt-phase - PLT List Read Error
    The specified PLTPI program list table could not be found in the Resource Definition file.
  • CASSI5004S PLTPI Phase plt-phase - PLT List not in PPT
    The specified PLTPI program list table was not present in the installed PPT.
  • CASSI5005S PLTPI Phase plt-phase List(plt-name) Program=program abend
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTPI processing.
  • CASSI5006S PLTPI Phase plt-phase List(plt-name) PLT program program not found
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASSI5007E Severe shared memory storage constraint during region startup, region terminating
    The system shared memory resource limit has been reached.
  • CASSI5008E Severe error occurred during PLTPI processing, region terminating
    During PLTPI (phase 1) processing a severe error was detected, either a PLTPI program could not be loaded or an ABEND occurred The startup regime specified that the region initialization should be aborted.
  • CASSI5010I PLTPI Phase plt-phase List(plt-name) Processing Completed
    All run-once (phase 1) and all run-on-every-SEP (phase 2) PLT PI (Program List Table Post Initialization) programs have run on this SEP successfully.
  • 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.
  • CASSI5014S Severe error in ES Cluster negotiation with APPLID of ES Cluster manager. (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.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI5000I PLTPI Phase plt-phase List(plt-name) Processing Started

Startup PLT processing has started using the plt-name list.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5001I PLTPI Phase plt-phase - No PLT Specified

Startup PLT processing was entered, but no list was specified.
System Action:
Startup proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5002S PLTPI - PLT List Open Error

The Resource Definition file could not be opened to read the PLTPI program list table.
System Action:
PLT Processing is bypassed, startup continues.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5003S PLTPI Phase plt-phase - PLT List Read Error

The specified PLTPI program list table could not be found in the Resource Definition file.
System Action:
PLT Processing is bypassed, startup continues.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5004S PLTPI Phase plt-phase - PLT List not in PPT

The specified PLTPI program list table was not present in the installed PPT.
System Action:
PLT Processing is bypassed, startup continues.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5005S PLTPI Phase plt-phase List(plt-name) Program=program abend

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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5006S PLTPI Phase plt-phase List(plt-name) PLT program program not found

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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


CASSI5007E Severe shared memory storage constraint during region startup, region terminating

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.
Module:
dfheserv
Destination:
System Console.
Parent topic: CASSI5000 - CASSI5019


CASSI5008E Severe error occurred during PLTPI processing, region terminating

During PLTPI (phase 1) processing a severe error was detected, either a PLTPI program could not be loaded or an ABEND occurred The startup regime specified that the region initialization should be aborted.
System Action:
Stop the region.
Resolution:
Ensure that the PLTPI program is compiled and the load module is in the correct location or correct whatever is causing the abend.
Module:
dfhzplt
Destination:
System Console.
Parent topic: CASSI5000 - CASSI5019


CASSI5010I PLTPI Phase plt-phase List(plt-name) Processing Completed

All run-once (phase 1) and all run-on-every-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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5000 - CASSI5019


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


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


CASSI5014S Severe error in ES Cluster negotiation with APPLID of ES Cluster manager. (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 - CASSI5019


CASSI5020 - CASSI5039

  • CASSI5020I PLTPI Phase plt-phase List(plt-name) Processing Started
    Startup Phase 2 PLT processing has started using the plt-name list.
  • CASSI5021I PLTPI Phase plt-phase - No PLT Specified
    Startup Phase 2 PLT processing was entered, but no list was specified.
  • CASSI5022S PLTPI Phase 2 - PLT List Open Error
    The Resource Definition file could not be opened to read the PLTPI program list table.
  • CASSI5023S PLTPI Phase plt-phase - PLT List Read Error
    The specified PLTPI program list table could not be found in the Resource Definition file.
  • CASSI5024S PLTPI Phase plt-phase - PLT List not in PPT
    The specified PLTPI program list table was not present in the installed PPT.
  • CASSI5025S PLTPI Phase plt-phase List(plt-name) Program=program abend
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTPI processing.
  • CASSI5026S PLTPI Phase plt-phase List(plt-name) PLT program program not found
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASSI5030I PLTPI Phase phase List(plt-name) Processing Completed
    Startup Phase 2 PLT processing has completed successfully using the plt-name list.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI5020I PLTPI Phase plt-phase List(plt-name) Processing Started

Startup Phase 2 PLT processing has started using the plt-name list.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5021I PLTPI Phase plt-phase - No PLT Specified

Startup Phase 2 PLT processing was entered, but no list was specified.
System Action:
Startup proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5022S PLTPI Phase 2 - PLT List Open Error

The Resource Definition file could not be opened to read the PLTPI program list table.
System Action:
PLT Processing is bypassed, startup continues.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5023S PLTPI Phase plt-phase - PLT List Read Error

The specified PLTPI program list table could not be found in the Resource Definition file.
System Action:
PLT Processing is bypassed, startup continues.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5024S PLTPI Phase plt-phase - PLT List not in PPT

The specified PLTPI program list table was not present in the installed PPT.
System Action:
PLT Processing is bypassed, startup continues.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5025S PLTPI Phase plt-phase List(plt-name) Program=program abend

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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5026S PLTPI Phase plt-phase List(plt-name) PLT program program not found

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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5030I PLTPI Phase phase List(plt-name) Processing Completed

Startup Phase 2 PLT processing has completed successfully using the plt-name list.
System Action:
Startup proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5020 - CASSI5039


CASSI5040 - CASSI5059

  • CASSI5040I Active SEP memory strategy set to x'hex-memory-strategy', retain count rts-retain-count
    This reports the memory strategy and memory strategy retain count at the end of PLT-PI phase 1.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI5040I Active SEP memory strategy set to x'hex-memory-strategy', retain count rts-retain-count

This reports the memory strategy and memory strategy retain count at the end of PLT-PI phase 1.
System Action:
Startup proceeds normally.
Module:
dfhzplt
Destination:
Console
Parent topic: CASSI5040 - CASSI5059


CASSI6000 - CASSI6019

  • CASSI6000E WebSphere MQ gateway (CKTI) failed to initialize, reason: failure-reason
    The WebSphere MQ trigger monitor program (CKTI) failed to initialize successfully.
  • CASSI6001I WebSphere MQ gateway (CKTI) initialized successfully (initiation-queue)
    The WebSphere MQ trigger monitor program (CKTI) initialized successfully and is monitoring initiation-queue.
  • CASSI6002I SIT WebSphere MQ parameters override XAT entry XAT-resource-name in XAT-resource-group-name group
    The WebSphere MQ parameters specified in the current SIT will be used instead of the XAT entry.
  • CASSI6003E WebSphere MQ gateway ASEE connect failed, reason: failure-reason
    The WebSphere MQ trigger monitor program failed to connect to the ASEE environment.
  • CASSI6004E WebSphere MQ connect to queue-manager-name Queue Manager failed, reason: failure-reason
    The WebSphere MQ trigger monitor task failed to connect to the queue-manager-name queue manager.
  • CASSI6005I WebSphere MQ (CKTI) connecting to queue-manager-name for queue queue-name
    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 WebSphere MQ (CKTI) environment variable MQSERVER=environment-value
    The WebSphere MQ trigger monitor program (CKTI) client configuration MQSERVER environment variable value is environment-value.
  • CASSI6007I WebSphere MQ interface loaded successfully
    The WebSphere MQ support module has loaded successfully, no attempt was made to connect to the specified queue manager.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI6000E WebSphere MQ gateway (CKTI) failed to initialize, reason: failure-reason

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.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6001I WebSphere MQ gateway (CKTI) initialized successfully (initiation-queue)

The WebSphere MQ trigger monitor program (CKTI) initialized successfully and is monitoring initiation-queue.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6002I SIT WebSphere MQ parameters override XAT entry XAT-resource-name in XAT-resource-group-name group

The WebSphere MQ parameters specified in the current SIT will be used instead of the XAT entry.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6003E WebSphere MQ gateway ASEE connect failed, reason: failure-reason

The WebSphere MQ trigger monitor program failed to connect to the ASEE environment.
System Action:
Stop WebSphere MQ trigger monitor.
Resolution:
Check the reason code and correct problem if possible then restart the region.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6004E WebSphere MQ connect to queue-manager-name Queue Manager 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:
dfhtmqgw
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6005I WebSphere MQ (CKTI) connecting to queue-manager-name for queue queue-name

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.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6006I WebSphere MQ (CKTI) environment variable MQSERVER=environment-value

The WebSphere MQ trigger monitor program (CKTI) client configuration MQSERVER environment variable value is environment-value.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI6007I WebSphere MQ interface loaded successfully

The WebSphere MQ support module has loaded successfully, no attempt was made to connect to the specified queue manager.
Module:
dfhexa
Destination:
Console
Parent topic: CASSI6000 - CASSI6019


CASSI7000 - CASSI7019

  • CASSI7000I Connection definition SYSID used for local sysid
    During region initialization a connection definition was found where the netname matched the local applid.
  • CASSI7001I Connection port number port-number used for local CCI gateway
    During region initialization a connection definition was found where the netname matched the local applid.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI7000I Connection definition SYSID used for local sysid

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.

Module:
dfhcprdt
Destination:
Console
Parent topic: CASSI7000 - CASSI7019


CASSI7001I Connection port number port-number used for local CCI gateway

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.

Module:
dfhcprdt
Destination:
Console
Parent topic: CASSI7000 - CASSI7019


CASSI8000 - CASSI8019

  • CASSI8001I Enterprise Server "Enterprise server name" initiation completed
    The Enterprise Server region has started and caswait returned.
  • CASSI8002E Enterprise Server "Enterprise server name" termination during initiation phase
    During region initialization a termination was detected.
  • CASSI8003I Enterprise Server "Enterprise server name" termination completed
    The Enterprise Server region has terminated and caswait returned.
  • CASSI8004S config-module: Region "region-name" not active, RC = return-code
    An error occurred accessing the region configuration data.
  • CASSI8005S config-module: Error reading console daemon configuration data, RC = return-code
    An error occurred reading the console daemon's stored configuration data.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI8001I Enterprise Server "Enterprise server name" initiation completed

The Enterprise Server region has started and caswait returned.
Module:
caswait
Destination:
Console and standard error.
Parent topic: CASSI8000 - CASSI8019


CASSI8002E Enterprise Server "Enterprise server name" termination during initiation phase

During region initialization a termination was detected.
Resolution:
Check console.log for errors.
Module:
caswait
Destination:
Standard error.
Parent topic: CASSI8000 - CASSI8019


CASSI8003I Enterprise Server "Enterprise server name" termination completed

The Enterprise Server region has terminated and caswait returned.
Module:
caswait
Destination:
Standard error.
Parent topic: CASSI8000 - CASSI8019


CASSI8004S config-module: Region "region-name" not active, RC = return-code

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.
Module:
caswait
Destination:
Standard error
Parent topic: CASSI8000 - CASSI8019


CASSI8005S config-module: Error reading console daemon configuration data, RC = return-code

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.
Module:
caswait
Destination:
Standard error
Parent topic: CASSI8000 - CASSI8019


CASSI9000 - CASSI9019

  • CASSI9001E Command parameter error: parameter
    parameter is invalid for this command line.
  • CASSI9002E Command conflict error: cmd-parm
    cmd-parm conflicts with or duplicates preceding parameters on the command line.
  • CASSI9003E Command parameter error: parameter
    parameter is invalid for this command line.
  • CASSI9004S Failed to 'exec' debug server, rc = return-code
    The attempt to start a CICS API server under debugger control failed due to an error in DosExecPgm.
  • CASSI9005E Error, could not inform REM of debug server termination, rc = return-code
    The attempt to inform the region manager of the debug server's termination failed due to an error in DosExecPgm.
  • CASSI9006S Failed to 'exec' debug server, rc = return-code
    The attempt to start a CICS API server under debugger control failed due to an error in execlp.
  • CASSI9007S Debug option animate-option for resource resource-name invalid
    The attempt to start a CICS API server under debugger control in the single process region failed due to an illegal command line.
  • CASSI9008I Debug initialization for terminal transaction successful
    The server is registered as a debug server for terminal transaction.
  • CASSI9009I Debug initialization for ALL transaction successful
    The server is registered as a debug server for transaction.
  • CASSI9010S Debug initialization unsuccessful, reason = RC
    The debug initialization was unsuccessful.
  • CASSI9011S Active and server configured working modes do not match
    The server working mode does not match the current environment.
  • CASSI9012E JCL support failed to start. Error returned from casspool, RC=Return code from call to casspool
    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.
  • 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.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI9001E Command parameter error: parameter

parameter is invalid for this command line.
System Action:
Command processing terminates.
Module:
dfhcpcmd
Destination:
Console
Parent topic: CASSI9000 - CASSI9019


CASSI9002E Command conflict error: cmd-parm

cmd-parm conflicts with or duplicates preceding parameters on the command line.
System Action:
Command processing terminates.
Module:
dfhcpcmd
Destination:
Console
Parent topic: CASSI9000 - CASSI9019


CASSI9003E Command parameter error: parameter

parameter is invalid for this command line.
System Action:
Command processing terminates.
Module:
dfhcpcm2
Destination:
Console
Parent topic: CASSI9000 - CASSI9019


CASSI9004S Failed to 'exec' debug server, rc = return-code

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9005E Error, could not inform REM of debug server termination, rc = return-code

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9006S Failed to 'exec' debug server, rc = return-code

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9007S Debug option animate-option for resource resource-name invalid

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.
Module:
dfhecics
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9008I Debug initialization for terminal transaction successful

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.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9009I Debug initialization for ALL transaction successful

The server is registered as a debug server for transaction.
System Action:
All work for the above resource will be routed to this server.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9010S Debug initialization unsuccessful, reason = RC

The debug initialization was unsuccessful.
Module:
dfheini1
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9011S Active and server configured working modes do not match

The server working mode does not match the current environment.

Either an attempt has been made to start a server defined as 64-bit from a 32-bit COBOL run-time environment or a start of a 32-bit server has been requested from a 64-bit COBOL run-time environment.

System Action:
Server will not be started.
Resolution:
Check that both the server definition and the COBOL run-time environment from which CASSTART is being invoked are the same.
Module:
dfhginit
Destination:
Console and standard error
Parent topic: CASSI9000 - CASSI9019


CASSI9012E JCL support failed to start. Error returned from casspool, RC=Return code from call to casspool

JCL support is not enabled because call to casspool failed with the inserted return code.
Resolution:
Perform an install repair on your system.
Module:
casmgr
Destination:
ES Console
Parent topic: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


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: CASSI9000 - CASSI9019


CASSI9020 - CASSI9039

  • CASSI9020I Default RNLDEF created in Name of the file containing the RNL definitions (All SYSDSNs, SYSZDSNs, SYSVSAMs are Global resources).
    The file ESCLRNLs.cfg does not exist.
  • CASSI9021S RC RC attempting to create default RNLs file Name of the file containing the RNL definitions
    The default file ESCLRNLs.cfg could not be created.
  • CASSI9022E RC RC accessing RNLs file Name of the file containing the RNL definitions.
    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 Number 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.
  • CASSI9026I Region initializing in Cold/Warm/Configured startup mode.
    Indicates whether region has been started with cold or warm start option specified or whether it is starting as per configuration.
  • CASSI9027W Region initializing in Warm startup mode because PAC PAC Name is already active.
    Indicates that the region was asked to start Cold but has been started Warm because another region in this PAC is already active.
  • CASSI9028I Region waiting for PAC PAC Name to be initialized.
    Indicates that the region is waiting for this PAC to reach "started" status.
  • CASSI9029S Region cannot start because the SOR used by PAC name for the current region is already used by PAC name for the region using the SOR.
    Indicates that the region is attempting to share a SOR and this is not allowed for a PAC.
  • CASSI9030E GLM disabled for the region as it conflicts with the cross region database configuration
    The region is configured to use the GLM but also configured to use ENQ/DEQ in the cross region database.
  • CASSI9031S Region cannot start because we encountered error PSOR access return code accessing the PSOR.
    The region encountered an error trying to access the PSOR.
  • CASSI9032E Region cannot connect to the Redis server Redis server name at Redis server address port Redis port number is secured and no authentication was provided.
    Could not connect to the Redis server.
  • CASSI9033E Region cannot be started as the PAC failed to start.
    Could not join the PAC as the PAC failed to start.
  • CASSI9034E NQRNL option can not be supported without the JES support.
    If you want to use NQRNL you need to enable JES to your region.
  • CASSI9035W Invalid format of hex prefix detected in SOR model type SOR model list: SOR model list. This and subsequent models will be ignored.
    Invalid hex prefix detected.
  • CASSI9036I The TS/TD SOR exit has been enabled and will be used instead of SOR models.
    The TS/TD SOR exit TSTDRSUE has been enabled.
  • CASSI9037S Region cannot warm start because there is no PAC SOR. Ensure that the PAC has been cold started.
    Region warm starting but the PAC has not previously been cold started.
  • CASSI9038E Create process request failed with RC Return code and Errno Errno.
    Trying to send a create process to cascd failed with return code Return code and errno Errno.
  • CASSI9039I Monitor APIs supported on this platform.
    The RTS APIs for monitoring CPU, Memory and Elapsed time are supported on this platform.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI9020I Default RNLDEF created in Name of the file containing the RNL definitions (All SYSDSNs, SYSZDSNs, SYSVSAMs are Global resources).

The file ESCLRNLs.cfg does not exist.
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: CASSI9020 - CASSI9039


CASSI9021S RC RC attempting to create default RNLs file Name of the file containing the RNL definitions

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: CASSI9020 - CASSI9039


CASSI9022E RC RC accessing RNLs file Name of the file containing the RNL definitions.

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: CASSI9020 - CASSI9039


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: CASSI9020 - CASSI9039


CASSI9024I Number of records loaded RNLDEF loaded from Number 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: CASSI9020 - CASSI9039


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: CASSI9020 - CASSI9039


CASSI9026I Region initializing in Cold/Warm/Configured startup mode.

Indicates whether region has been started with cold or warm start option specified or whether it is starting as per configuration.
Resolution:
none.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9027W Region initializing in Warm startup mode because PAC PAC Name is already active.

Indicates that the region was asked to start Cold but has been started Warm because another region in this PAC is already active.
Resolution:
none.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9028I Region waiting for PAC PAC Name to be initialized.

Indicates that the region is waiting for this PAC to reach "started" status.
Resolution:
none.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9029S Region cannot start because the SOR used by PAC name for the current region is already used by PAC name for the region using the SOR.

Indicates that the region is attempting to share a SOR and this is not allowed for a PAC.
System Action:
region manager will stop.
Resolution:
Check the configuration of your PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9030E GLM disabled for the region as it conflicts with the cross region database configuration

The region is configured to use the GLM but also configured to use ENQ/DEQ in the cross region database.
System Action:
Disable the GLM option.
Resolution:
Check the configuration of your region.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9031S Region cannot start because we encountered error PSOR access return code accessing the PSOR.

The region encountered an error trying to access the PSOR.
System Action:
region manager will stop.
Resolution:
Check the configuration of your PAC and contact technical support with the error number.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9032E Region cannot connect to the Redis server Redis server name at Redis server address port Redis port number is secured and no authentication was provided.

Could not connect to the Redis server.
System Action:
region manager will stop if this was a PSOR.
Resolution:
Check the configuration of your PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9033E Region cannot be started as the PAC failed to start.

Could not join the PAC as the PAC failed to start.
System Action:
region manager will stop.
Resolution:
Check the PAC console messages to determine the issue.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9034E NQRNL option can not be supported without the JES support.

If you want to use NQRNL you need to enable JES to your region.
System Action:
region manager disable NQRNL option.
Resolution:
Enable JES support if you need NQRNL support.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9035W Invalid format of hex prefix detected in SOR model type SOR model list: SOR model list. This and subsequent models will be ignored.

Invalid hex prefix detected.
System Action:
SOR models after the invalid one are ignored.
Resolution:
Check the configuration of your SOR models.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9036I The TS/TD SOR exit has been enabled and will be used instead of SOR models.

The TS/TD SOR exit TSTDRSUE has been enabled.
System Action:
The exit will be called on queue access rather than using SOR models.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9037S Region cannot warm start because there is no PAC SOR. Ensure that the PAC has been cold started.

Region warm starting but the PAC has not previously been cold started.
System Action:
Region manager will stop.
Resolution:
Cold start a region in the PAC.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9038E Create process request failed with RC Return code and Errno Errno.

Trying to send a create process to cascd failed with return code Return code and errno Errno.
Resolution:
Check the return code and errno and contact technical support.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9039I Monitor APIs supported on this platform.

The RTS APIs for monitoring CPU, Memory and Elapsed time are supported on this platform.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9020 - CASSI9039


CASSI9040 - CASSI9059

  • CASSI9040I Monitor APIs not supported on this platform, RC Return code.
    The RTS APIs for monitoring CPU, Memory and Elapsed time returned an error on this platform.
  • CASSI9041E Region cannot connect to Coherence which is secured and no authentication was provided, using Coherence connection string
    Could not connect to the Coherence server.
  • CASSI9042W SOR model type SOR model list for SOR name exceeds max length. Models may be truncated.
    SOR model list exceeds max size of receiving buffer.
  • CASSI9043W Orphaned ITR found from previous instance of this region and removed. Type=Type of ITR, Action=Action on ITR, Resource=Resource
    An ITR was not completed properly on the previous instance of the region and was found orphaned.
  • CASSI9044I Failed MFDBFH recovery for (PID:process-id) has been now processed
    The recovery for a process that died and we failed to recover in MFDBFH has now been done successfully.
  • CASSI9045W Automatic check for PAC ITRs from previous instance of this region exited whilst waiting for MFCS to initialize
    MFCS has not set hostname in CSA so we cannot check for orphaned ITRs in PSOR for this region.
  • CASSI9046E Region cannot start because connection to Coherence at Coherence connection string failed.
    Could not connect to the Coherence server.
  • CASSI9047E Region cannot start because the connection to Redis server Redis server name failed.
    Could not connect to the Redis server.
  • CASSI9048E Failed to load MFDBFH support module
    MFDBFH.dll (or equivalent module name depending on operating system) could not be found / loaded into the process address space.
  • CASSI9049E Failed to register sql:// prefix with external file handler, RC=Return code
    MFDBFH failed to register itself with the external file handler.
  • CASSI9050E ES GLM or CLUSTER deprecated check the documentation and use LOCKDB or PAC configuration.
    ES Global Lock Manager or Cluster has been deprecated, the region can not start with this configuration.
  • CASSI9051I Region connected to Redis TLS server Redis server name at Redis server address port Redis port number
    The region successfully connected to TLS-enabled Redis.
  • CASSI9052E Region could not connect to Redis TLS server Redis server name at Redis server address port Redis port number, RC=Return code from connection attempt
    The region failed to connect to TLS-enabled Redis.
  • CASSI9053I Region SYSID changed Original SYSID defined in the SIT to New SYSID specified in the casstart command
    The SYSID was changed to the one specified on the command line.
  • CASSI9054I OpenTelemetry support is enabled
    OpenTelemetry support for this process is enabled.
  • CASSI9055I OpenTelemetry support is not configured
    OpenTelemetry support is disabled.
  • CASSI9056E Failed to initialize OpenTelemetry (Initialization error)
    OpenTelemetry wrapper failed to initialize due to specified error.
  • CASSI9057W Disabled iFileshare for PAC enabled region
    iFileshare should not be enabled for PAC regions.
Parent topic: CASSI - CICS System Initialization Error Messages


CASSI9040I Monitor APIs not supported on this platform, RC Return code.

The RTS APIs for monitoring CPU, Memory and Elapsed time returned an error on this platform.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9041E Region cannot connect to Coherence which is secured and no authentication was provided, using Coherence connection string

Could not connect to the Coherence server.
System Action:
region manager will stop if this was a PSOR.
Resolution:
Check the configuration of your PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9042W SOR model type SOR model list for SOR name exceeds max length. Models may be truncated.

SOR model list exceeds max size of receiving buffer.
System Action:
SOR model list truncated.
Resolution:
Check the configuration of your SOR models. Reduce list of prefixes or use exit TSTDSRUE.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9043W Orphaned ITR found from previous instance of this region and removed. Type=Type of ITR, Action=Action on ITR, Resource=Resource

An ITR was not completed properly on the previous instance of the region and was found orphaned.

The ITR has been removed from the CasITR store.

Resolution:
Contact Micro Focus Customer Support.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9044I Failed MFDBFH recovery for (PID:process-id) has been now processed

The recovery for a process that died and we failed to recover in MFDBFH has now been done successfully.
Module:
casmgr
Destination:
Console.
Parent topic: CASSI9040 - CASSI9059


CASSI9045W Automatic check for PAC ITRs from previous instance of this region exited whilst waiting for MFCS to initialize

MFCS has not set hostname in CSA so we cannot check for orphaned ITRs in PSOR for this region.
System Action:
No check for ITRs in PSOR performed.
Resolution:
Pssibility of orphaned ITRs in PSOR for this region. Contact Micro Focus Customer Support.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9046E Region cannot start because connection to Coherence at Coherence connection string failed.

Could not connect to the Coherence server.
System Action:
Region manager will stop.
Resolution:
Check the configuration of your PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9047E Region cannot start because the connection to Redis server Redis server name failed.

Could not connect to the Redis server.
System Action:
Region manager will stop.
Resolution:
Check the configuration of your PAC.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9048E Failed to load MFDBFH support module

MFDBFH.dll (or equivalent module name depending on operating system) could not be found / loaded into the process address space.
System Action:
Operations involving the Micro Focus database file handler will fail.
Module:
castmc
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9049E Failed to register sql:// prefix with external file handler, RC=Return code

MFDBFH failed to register itself with the external file handler.
System Action:
Operations involving the Micro Focus database file handler will fail.
Module:
castmc
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9050E ES GLM or CLUSTER deprecated check the documentation and use LOCKDB or PAC configuration.

ES Global Lock Manager or Cluster has been deprecated, the region can not start with this configuration.
System Action:
Region shutdown.
Resolution:
Check the documentation.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9051I Region connected to Redis TLS server Redis server name at Redis server address port Redis port number

The region successfully connected to TLS-enabled Redis.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9052E Region could not connect to Redis TLS server Redis server name at Redis server address port Redis port number, RC=Return code from connection attempt

The region failed to connect to TLS-enabled Redis.
Resolution:
Check that the TLS-enabled Redis server is up and running and that the specified address and port are correct and the certificate paths are correctly set.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9053I Region SYSID changed Original SYSID defined in the SIT to New SYSID specified in the casstart command

The SYSID was changed to the one specified on the command line.
Module:
dfhginit
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9054I OpenTelemetry support is enabled

OpenTelemetry support for this process is enabled.
System Action:
OpenTelemetry data will be exported based on the provided configuration file specified by the MFOTL_CONFIG environment variable.
Module:
dfhgreq, casgreqt
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9055I OpenTelemetry support is not configured

OpenTelemetry support is disabled.

This may be due to the MFOTL_CONFIG environment variable being unset.

Module:
dfhgreq, casgreqt
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9056E Failed to initialize OpenTelemetry (Initialization error)

OpenTelemetry wrapper failed to initialize due to specified error.
System Action:
OpenTelemetry output disabled.
Resolution:
For configuration errors ensure the file specified by the MFOTL_CONFIG environment variable is accessible and valid. The MFOTL_DEBUGLOG environment variable can be used to provide further information. For other errors please ensure product integrity and contact support.
Module:
dfhgreq, casgreqt
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSI9057W Disabled iFileshare for PAC enabled region

iFileshare should not be enabled for PAC regions.
System Action:
iFileshare configurations are ignored and disabled.
Resolution:
Unset ES_HA_VSAM and disable integrated Fileshare in the SIT to remove this warning.
Module:
casmgr
Destination:
Console
Parent topic: CASSI9040 - CASSI9059


CASSP - CICS Syncpoint and Recovery Services Error Messages

  • CASSP0000 - CASSP0019
Parent topic: Enterprise Server Error Messages


CASSP0000 - CASSP0019

  • CASSP0001W Failed to inform server manager of process death, reason = failure-code
    The console daemon detected a process's termination and attempted to inform the region manger of the event.
  • CASSP0002I Server manager informed of process termination, pinfo = process-type,process-id
    The console daemon detected a process's termination and successfully informed the region manger of the event.
  • CASSP0003E Process process-id termination recovery initiation failed: errno = error-number
    The daemon process responsible for initiating recovery for process-id failed trying to lock shared memory.
  • CASSP0004E Process process-id termination recovery initiation failed: RC = return-code
    The daemon process responsible for initiating recovery for process ID process-id failed trying to lock shared memory.
  • CASSP0010S Syncpoint failure - resource state unpredictable
    A syncpoint, either implied or requested via API has failed and the DB/file resource state is unpredictable.
  • CASSP0011S Syncpoint COMMIT failure - resource state unpredictable
    A COMMIT was requested and attempted against the configured resource managers.
  • CASSP0012S IMS has abended
    IMS has abended during the current transaction running.
  • CASSP0013S Syncpoint ROLLBACK failure - resource state unpredictable
    A ROLLBACK, either implied or requested via API and the ROLLBACK command to one or more resource managers failed.
  • CASSP0014S RTS-error-message
    The process terminated due to a COBOL RTS error.
  • CASSP0015S Syncpoint PREPARE failure - resource state unpredictable
    A PREPARE was requested and attempted against the configured resource managers.
  • CASSP0016S Syncpoint OTHER failure - resource state unpredictable
    A syncpoint was requested and attempted against the configured resource managers.
  • CASSP0017S Process thread hung with shared memory locked (this simulates an ES failure)
    This operation simulates an ES failure where shared memory is locked.
Parent topic: CASSP - CICS Syncpoint and Recovery Services Error Messages


CASSP0001W Failed to inform server manager of process death, reason = failure-code

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.

    1 - unknown process type termination detected
    2 - invalid process ID returned
    3 - could not connect to the region
    4 - could not allocate shared storage
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.
Module:
caspdied
Destination:
Console
Parent topic: CASSP0000 - CASSP0019


CASSP0002I Server manager informed of process termination, pinfo = process-type,process-id

The console daemon detected a process's termination and successfully informed the region manger of the event.

Process information details are described by pinfo as follows:

 process-type = S    server
      = D    debug server
      = P    3270 printer
      = G    CCI gateway
      = J    JCP
      = T    TDP
      = F    Fileshare
      = R    region manager
      = M    MQ gateway
      = L    Spooler
      = H    MFCS
 process-id = process ID of terminated process
System Action:
The region manager will take appropriate action to recover after the process's termination.
Module:
caspdied
Destination:
Console
Parent topic: CASSP0000 - CASSP0019


CASSP0003E Process process-id termination recovery initiation failed: errno = error-number

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.
Module:
caspdied
Destination:
Console
Parent topic: CASSP0000 - CASSP0019


CASSP0004E Process process-id termination recovery initiation failed: RC = return-code

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.
Module:
caspdied
Destination:
Console
Parent topic: CASSP0000 - CASSP0019


CASSP0010S Syncpoint failure - resource state unpredictable

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.
Module:
dfhesync
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0011S Syncpoint COMMIT failure - resource state unpredictable

A COMMIT was requested and attempted against the configured resource managers.

A bad response was returned by one or more resource managers. The other resource managers reported a successful COMMIT. The failing resource managers should COMMIT when the error is resolved.

System Action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed.
Module:
dfheserv
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0012S IMS has abended

IMS has abended during the current transaction running.
System Action:
The transaction and IMS will abend.
Resolution:
Investigate why IMS abended.
Module:
dfhesync
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0013S Syncpoint ROLLBACK failure - resource state unpredictable

A ROLLBACK, either implied or requested via API and the ROLLBACK command to one or more resource managers failed.

All other resource managers did a ROLLBACK.

System Action:
The transaction will abend.
Resolution:
Investigate why the ROLLBACK failed, investigate resource states and recover as required.
Module:
dfhesync
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0014S RTS-error-message

The process terminated due to a COBOL RTS error.
System Action:
Depending on the process type the system will restart the process.
Module:
cascperr
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0015S Syncpoint PREPARE failure - resource state unpredictable

A PREPARE was requested and attempted against the configured resource managers.

A bad response was returned by one or more resource managers. The other resource managers reported a successful COMMIT. The failing resource managers should ROLLBACK when the error is resolved.

System Action:
A ROLLBACK will be attempted and he transaction will ABEND.
Resolution:
Investigate why the PREPARE failed, investigate resource states and recover as required.
Module:
dfheserv
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0016S Syncpoint OTHER failure - resource state unpredictable

A syncpoint was requested and attempted against the configured resource managers.

A bad response was returned and the resource managers were rolled back to the previous syncpoint.

System Action:
The transaction will abend.
Resolution:
Investigate why the syncpoint failed and verify the data.
Module:
casmpr, casbat
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASSP0017S Process thread hung with shared memory locked (this simulates an ES failure)

This operation simulates an ES failure where shared memory is locked.

This should not occur except where this function is explicitly requested.

System Action:
The process will hang with shared memory locked.
Resolution:
Kill this process to allow ES to continue.
Module:
dfhgreq, casgreqt
Destination:
Console and standard error.
Parent topic: CASSP0000 - CASSP0019


CASST - CICS Region Termination Error Messages

  • CASST0000 - CASST0019
  • CASST0020 - CASST0039
  • CASST4000 - CASST4019
  • CASST4020 - CASST4039
  • CASST4080 - CASST4099
  • CASST4100 - CASST4119
  • CASST5000 - CASST5019
  • CASST5020 - CASST5039
  • CASST5200 - CASST5219
  • CASST5220 - CASST5239
  • CASST6000 - CASST6019
Parent topic: Enterprise Server Error Messages


CASST0000 - CASST0019

  • CASST0000I Server manager termination started
    The region manager has started its termination phase.
  • CASST0001I Server manager termination completed successfully
    The region manager has completed its termination phase.
  • CASST0002W Error attaching to ES region-name
    While attempting to shutdown a region an error occurred trying to attach to the region.
  • CASST0003W Invalid attempt to shutdown ES region-name externally
    An attempt was made to shutdown a region externally which is marked as having external shutdown disabled.
  • CASST0004W External shutdown request for ES server-name by user user name was rejected, reason=reason
    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 Shutdown of ES region-name starting
    The shutdown program is starting to shutdown the region.
  • CASST0006I Closing region with TRANSID=transid
    The shutdown program is starting to shutdown the region by scheduling the transaction specified.
  • CASST0007I Abending ES region-name
    The shutdown program is starting to shutdown the region by abending all region processes.
  • CASST0008W User not authorized to run shutdown transaction transid
    An attempt to shutdown a region externally via a transid was rejected as the user failed the security check on the transaction.
  • CASST0009W Error, shutdown transaction transid is defined as remote
    An attempt to shutdown a region externally via a transid was rejected as the transaction is defined as remote.
  • CASST0010W Shutdown transaction transid not found
    An attempt to shutdown a region externally via a transid was rejected as the transaction was not found.
  • CASST0011W Error allocating shared memory for shutdown transaction
    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 WARNING - Forcing ES termination - data may be lost
    A forceable region abend was requested via the dfhgrtrm utility.
  • CASST0013W WARNING - Forcing region abend without memory access protection
    A forceable region abend was requested via the dfhgrtrm utility without the protection of locking shared memory.
  • CASST0014E Error attempting to shutdown region-name, could not submit shutdown request
    While attempting to shutdown a region an error occurred trying to submit the shutdown request.
  • CASST0015E Error attempting to shutdown region-name, could not submit shutdown request
    While attempting to shutdown a region an error occurred trying to submit the shutdown request.
  • CASST0016E Error attempting to shutdown region-name, could not submit shutdown request
    While attempting to shutdown a region an error occurred trying to submit the shutdown request.
  • CASST0017E Error attempting to shutdown region-name, option force could not be used when region security is on
    While attempting to shutdown a region with option force the request has been rejected because the region security is on.
  • CASST0018S Safmgr initialization failed, reason = reason-code
    The Casstop process failed to initialize safmgr.
  • CASST0019S ES shutdown started due to a Safmgr initialization failure
    The Safmgr failed to initialize and, therefore, Enterprise Server will be shutdown.
Parent topic: CASST - CICS Region Termination Error Messages


CASST0000I Server manager termination started

The region manager has started its termination phase.
System Action:
Shared memory and semaphores will be removed.
Module:
dfhgterm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0001I Server manager termination completed successfully

The region manager has completed its termination phase.
System Action:
All shared memory and semaphores were removed successfully.
Module:
dfhgterm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0002W Error attaching to ES region-name

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0003W Invalid attempt to shutdown ES region-name externally

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0004W External shutdown request for ES server-name by user user name was rejected, reason=reason

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.

Possible values for reason are:

     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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0005I Shutdown of ES region-name starting

The shutdown program is starting to shutdown the region.
System Action:
Start shutting down the region.
Resolution:
None.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0006I Closing region with TRANSID=transid

The shutdown program is starting to shutdown the region by scheduling the transaction specified.
System Action:
Schedule transaction.
Resolution:
None.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0007I Abending ES region-name

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0008W User not authorized to run shutdown transaction transid

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0009W Error, shutdown transaction transid is defined as remote

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0010W Shutdown transaction transid not found

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0011W Error allocating shared memory for shutdown transaction

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.
Module:
dfhgrtrm
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0012W WARNING - Forcing ES termination - data may be lost

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.
Module:
dfhgrtrm
Destination:
Console and stdout
Parent topic: CASST0000 - CASST0019


CASST0013W WARNING - Forcing region abend without memory access protection

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.
Module:
dfhgrtrm
Destination:
Console and stdout
Parent topic: CASST0000 - CASST0019


CASST0014E Error attempting to shutdown region-name, could not submit shutdown request

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.
Module:
casstop
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0015E Error attempting to shutdown region-name, could not submit shutdown request

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.
Module:
casstop
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0016E Error attempting to shutdown region-name, could not submit shutdown request

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.
Module:
casstop
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0017E Error attempting to shutdown region-name, option force could not be used when region security is on

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.
Module:
casstop
Destination:
Console
Parent topic: CASST0000 - CASST0019


CASST0018S Safmgr initialization failed, reason = reason-code

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.
Module:
casstop
Destination:
Console and stdout
Parent topic: CASST0000 - CASST0019


CASST0019S ES shutdown started due to a Safmgr initialization failure

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.
Module:
any ES process (cascpsfi)
Destination:
Console and stdout
Parent topic: CASST0000 - CASST0019


CASST0020 - CASST0039

  • CASST0020I ES region-name already shutting down.
    The shutdown is in progress, use force if the region did not stop in a timely fashion.
  • CASST0021W Server manager termination delayed waiting for ES communications to terminate
    The allotted wait time for mfcs/casgate communications processes to terminate was exceeded.
  • CASST0022W Server manager termination delayed waiting for ES service processes to terminate
    The allotted wait time for ES service processes to terminate was exceeded.
  • CASST0023W Server manager termination delayed waiting for ES core processes to terminate
    The allotted wait time for ES core processes to terminate was exceeded.
  • CASST0024E Safmgr initialization failed, SEP terminating reason = reason-code
    The process failed to initialize safmgr.
Parent topic: CASST - CICS Region Termination Error Messages


CASST0020I ES region-name already shutting down.

The shutdown is in progress, use force if the region did not stop in a timely fashion.
System Action:
None.
Resolution:
None.
Module:
casstop
Destination:
Console and stdout
Parent topic: CASST0020 - CASST0039


CASST0021W Server manager termination delayed waiting for ES communications to terminate

The allotted wait time for mfcs/casgate communications processes to terminate was exceeded.
System Action:
Termination continues.
Resolution:
None.
Module:
casstop
Destination:
Console and stdout
Parent topic: CASST0020 - CASST0039


CASST0022W Server manager termination delayed waiting for ES service processes to terminate

The allotted wait time for ES service processes to terminate was exceeded.
System Action:
Termination continues.
Resolution:
None.
Module:
casstop
Destination:
Console and stdout
Parent topic: CASST0020 - CASST0039


CASST0023W Server manager termination delayed waiting for ES core processes to terminate

The allotted wait time for ES core processes to terminate was exceeded.
System Action:
Termination continues.
Resolution:
None.
Module:
casstop
Destination:
Console and stdout
Parent topic: CASST0020 - CASST0039


CASST0024E Safmgr initialization failed, SEP terminating reason = reason-code

The process failed to initialize safmgr.

The reason code is reason-code.

System Action:
The process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
any ES process (cascpsfi)
Destination:
Console and stdout
Parent topic: CASST0020 - CASST0039


CASST4000 - CASST4019

  • CASST4000I SHUTDOWN Requested
    A request to shutdown the Micro Focus Transaction System has been entered using either the CQIT transaction or the PERFORM SHUTDOWN command.
  • CASST4001I Immediate SHUTDOWN Requested
    A request to shutdown the Micro Focus Transaction System IMMEDIATELY has been entered using the PERFORM SHUTDOWN command.
  • CASST4002E Shutdown Request Failure, Return Code = return-code
    The shutdown request was rejected because the system was already in shutdown or was never successfully started.
  • CASST4010I Shutdown Started, PLT List = pltsd-name
    Shutdown processing has begun using the indicated PLT.
  • CASST4011I Shutdown Started, No PLT List
    Shutdown processing has begun; no PLTSD was specified for PLT processing.
Parent topic: CASST - CICS Region Termination Error Messages


CASST4000I SHUTDOWN Requested

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.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4000 - CASST4019


CASST4001I Immediate SHUTDOWN Requested

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.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4000 - CASST4019


CASST4002E Shutdown Request Failure, Return Code = return-code

The shutdown request was rejected because the system was already in shutdown or was never successfully started.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4000 - CASST4019


CASST4010I Shutdown Started, PLT List = pltsd-name

Shutdown processing has begun using the indicated PLT.
System Action:
PLTSD Processing is started, shutdown proceeding normally.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4000 - CASST4019


CASST4011I Shutdown Started, No PLT List

Shutdown processing has begun; no PLTSD was specified for PLT processing.
System Action:
Shutdown proceeding normally without PLT processing.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4000 - CASST4019


CASST4020 - CASST4039

  • CASST4020I Shutdown PLT Processing completed
    The PLTSD Phase 1 processing has been completed.
  • CASST4021E Shutdown PLT Processing Failed
    The PLTSD processing encountered an error in processing program list or one of the programs in the list ABENDed.
  • CASST4022S Shutdown PLT Processing LINK Failed
    The PLT processing transaction program, dfhzplt, could not be found.
Parent topic: CASST - CICS Region Termination Error Messages


CASST4020I Shutdown PLT Processing completed

The PLTSD Phase 1 processing has been completed.
System Action:
Shutdown proceeding normally.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4020 - CASST4039


CASST4021E Shutdown PLT Processing Failed

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.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4020 - CASST4039


CASST4022S Shutdown PLT Processing LINK Failed

The PLT processing transaction program, dfhzplt, could not be found.
System Action:
Shutdown processing aborted.
Resolution:
Do a SHUTDOWN IMMMEDIATE to bypass PLTSD processing.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4020 - CASST4039


CASST4080 - CASST4099

  • CASST4090I Disconnect Requested
    The attached terminal is automatically disconnected when a shutdown request is processed.
Parent topic: CASST - CICS Region Termination Error Messages


CASST4090I Disconnect Requested

The attached terminal is automatically disconnected when a shutdown request is processed.
System Action:
Disconnect the terminal requesting shutdown.
Module:
dfhzcqit
Destination:
Terminal
Parent topic: CASST4080 - CASST4099


CASST4100 - CASST4119

  • CASST4100I SHUTDOWN Requested
    A request to shutdown the Micro Focus Transaction System has been entered using either the CQIT transaction or the PERFORM SHUTDOWN command.
  • CASST4101I Immediate SHUTDOWN Requested
    A request to shutdown the Micro Focus Transaction System IMMEDIATELY has been entered using the PERFORM SHUTDOWN command.
  • CASST4102E Shutdown Request Failure, Return Code = return-code
    The shutdown request was rejected because the system was already in shutdown or was never successfully started.
  • CASST4110I Shutdown Started, PLT List = pltsd-name
    Shutdown processing has begun using the indicated PLT.
  • CASST4111I Shutdown Started, No PLT List
    Shutdown processing has begun; no PLTSD was specified for PLT processing.
Parent topic: CASST - CICS Region Termination Error Messages


CASST4100I SHUTDOWN Requested

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.
Module:
casrdo11
Destination:
Console
Parent topic: CASST4100 - CASST4119


CASST4101I Immediate SHUTDOWN Requested

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.
Module:
casrdo11
Destination:
Console
Parent topic: CASST4100 - CASST4119


CASST4102E Shutdown Request Failure, Return Code = return-code

The shutdown request was rejected because the system was already in shutdown or was never successfully started.
Module:
dfhzcqit
Destination:
Console (and Terminal)
Parent topic: CASST4100 - CASST4119


CASST4110I Shutdown Started, PLT List = pltsd-name

Shutdown processing has begun using the indicated PLT.
System Action:
PLTSD Processing is started, shutdown proceeding normally.
Module:
casrdo11
Destination:
Console
Parent topic: CASST4100 - CASST4119


CASST4111I Shutdown Started, No PLT List

Shutdown processing has begun; no PLTSD was specified for PLT processing.
System Action:
Shutdown proceeding normally without PLT processing.
Module:
casrdo11
Destination:
Console
Parent topic: CASST4100 - CASST4119


CASST5000 - CASST5019

  • CASST5000I PLTSD List(plt-name) Processing Started
    Shutdown PLT processing has started using the plt-name list.
  • CASST5001I PLTSD - No PLT Specified
    Shutdown PLT processing was entered, but no list was specified.
  • CASST5002S PLTSD - PLT List Open Error
    The Resource Definition file could not be opened to read the PLTSD program list table.
  • CASST5003S PLTSD - PLT List Read Error
    The specified PLTSD program list table could not be found in the Resource Definition file.
  • CASST5004S PLTSD - PLT List not in PPT
    The specified PLTSD program list table was not present in the installed PPT.
  • CASST5005S PLTSD List(plt-name) Program=program abend
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTSD processing.
  • CASST5006S PLTSD List(plt-name) PLT program program not found
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASST5010I PLTSD List(plt-name) Processing Completed
    Shutdown PLT processing has completed successfully using the plt-name list.
Parent topic: CASST - CICS Region Termination Error Messages


CASST5000I PLTSD List(plt-name) Processing Started

Shutdown PLT processing has started using the plt-name list.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5001I PLTSD - No PLT Specified

Shutdown PLT processing was entered, but no list was specified.
System Action:
Shutdown proceeds normally.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5002S PLTSD - PLT List Open Error

The Resource Definition file could not be opened to read the PLTSD program list table.
System Action:
PLT Processing is bypassed, shutdown continues.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5003S PLTSD - PLT List Read Error

The specified PLTSD program list table could not be found in the Resource Definition file.
System Action:
PLT Processing is bypassed, shutdown continues.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5004S PLTSD - PLT List not in PPT

The specified PLTSD program list table was not present in the installed PPT.
System Action:
PLT Processing is bypassed, shutdown continues.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5005S PLTSD List(plt-name) Program=program abend

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.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5006S PLTSD List(plt-name) PLT program program not found

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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASST5000 - CASST5019


CASST5010I PLTSD List(plt-name) Processing Completed

Shutdown PLT processing has completed successfully using the plt-name list.
System Action:
Shutdown proceeds normally.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5000 - CASST5019


CASST5020 - CASST5039

  • CASST5020I PLTSD Phase 2 List(plt-name) Processing Started
    Shutdown Phase 2 PLT processing has started using the plt-name list.
  • CASST5021I PLTSD Phase 2 - No PLT Specified
    Shutdown Phase 2 PLT processing was entered, but no list was specified.
  • CASST5022S PLTSD Phase 2 - PLT List Open Error
    The Resource Definition file could not be opened to read the PLTSD program list table.
  • CASST5023S PLTSD Phase 2 - PLT List Read Error
    The specified PLTSD program list table could not be found in the Resource Definition file.
  • CASST5024S PLTSD Phase 2 - PLT List not in PPT
    The specified PLTSD program list table was not present in the installed PPT.
  • CASST5025S PLTSD Phase 2 List(plt-name) Program=program abend
    A transaction program abend occurred in the program program of the plt-name list during Phase 2 PLTSD processing.
  • CASST5026S PLTSD Phase 2 List(plt-name) PLT program program not found
    The named program specified could not be found and resulted in a PGMIDERR.
  • CASST5030I PLTSD Phase 2 List(plt-name) Processing Completed
    Shutdown Phase 2 PLT processing has completed successfully using the plt-name list.
Parent topic: CASST - CICS Region Termination Error Messages


CASST5020I PLTSD Phase 2 List(plt-name) Processing Started

Shutdown Phase 2 PLT processing has started using the plt-name list.
System Action:
PLT processing proceeds normally.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5021I PLTSD Phase 2 - No PLT Specified

Shutdown Phase 2 PLT processing was entered, but no list was specified.
System Action:
Shutdown proceeds normally.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5022S PLTSD Phase 2 - PLT List Open Error

The Resource Definition file could not be opened to read the PLTSD program list table.
System Action:
PLT Processing is bypassed, shutdown continues.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5023S PLTSD Phase 2 - PLT List Read Error

The specified PLTSD program list table could not be found in the Resource Definition file.
System Action:
PLT Processing is bypassed, shutdown continues.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5024S PLTSD Phase 2 - PLT List not in PPT

The specified PLTSD program list table was not present in the installed PPT.
System Action:
PLT Processing is bypassed, shutdown continues.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5025S PLTSD Phase 2 List(plt-name) Program=program abend

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.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5026S PLTSD Phase 2 List(plt-name) PLT program program not found

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.
Module:
dfhzplt
Destination:
Console
Parent topic: CASST5020 - CASST5039


CASST5030I PLTSD Phase 2 List(plt-name) Processing Completed

Shutdown Phase 2 PLT processing has completed successfully using the plt-name list.
System Action:
Shutdown proceeds normally.
Module:
dfhzplt
Destination:
Console (and Terminal)
Parent topic: CASST5020 - CASST5039


CASST5200 - CASST5219

  • CASST5201I Spool service shutdown complete
    The spool service has terminated normally.
Parent topic: CASST - CICS Region Termination Error Messages


CASST5201I Spool service shutdown complete

The spool service has terminated normally.
Module:
dfhgspol
Destination:
Console
Parent topic: CASST5200 - CASST5219


CASST5220 - CASST5239

  • CASST5230I Event Manager Process termination started
    The Event Process is terminating.
  • CASST5231I Event Manager Process termination complete
    The Event Manager Process has terminated.
Parent topic: CASST - CICS Region Termination Error Messages


CASST5230I Event Manager Process termination started

The Event Process is terminating.
Module:
casevmgr
Destination:
Console
Parent topic: CASST5220 - CASST5239


CASST5231I Event Manager Process termination complete

The Event Manager Process has terminated.
Module:
casevmgr
Destination:
Console
Parent topic: CASST5220 - CASST5239


CASST6000 - CASST6019

  • CASST6002I WebSphere MQ gateway (CKTI) shutdown complete
    The WebSphere MQ trigger monitor program (CKTI) has disconnected from the queue manager and is terminating.
Parent topic: CASST - CICS Region Termination Error Messages


CASST6002I WebSphere MQ gateway (CKTI) shutdown complete

The WebSphere MQ trigger monitor program (CKTI) has disconnected from the queue manager and is terminating.
Module:
dfhtmqgw
Destination:
Console
Parent topic: CASST6000 - CASST6019


CASTD - CICS Transient Data Error Messages

  • CASTD0000 - CASTD0019
Parent topic: Enterprise Server Error Messages


CASTD0000 - CASTD0019

  • CASTD0001E Failed to update PSOR version of DCT TD queue name. Check status of PSOR.
    An update to the local DCT was not reflected in the PSOR copy.
  • CASTD0002E Call to TS/TD SOR exit failed. Exit disabled.
    Call to the TS/TD SOR exit failed.
  • CASTD0003E Failed to close extra partition TD queue TD queue name. File status code: file-status-byte-1file-status-byte-2
    castsc failed to close an extra partition TD queue.
  • CASTD0004E Failed to open extra partition TD queue TD queue name. File status code: file-status-byte-1file-status-byte-2
    castsc failed to open an extra partition TD queue.
Parent topic: CASTD - CICS Transient Data Error Messages


CASTD0001E Failed to update PSOR version of DCT TD queue name. Check status of PSOR.

An update to the local DCT was not reflected in the PSOR copy.
Resolution:
Check PSOR is accessible.
Module:
dfheserv
Destination:
console, CSFL
Parent topic: CASTD0000 - CASTD0019


CASTD0002E Call to TS/TD SOR exit failed. Exit disabled.

Call to the TS/TD SOR exit failed.
System Action:
TS/TD SOR exit TSTDRSUE is disabled. SOR models will be used instead.
Resolution:
Ensure that TSTDRSUE has been compiled correctly and placed in the product.
Module:
dfheserv
Destination:
Console
Parent topic: CASTD0000 - CASTD0019


CASTD0003E Failed to close extra partition TD queue TD queue name. File status code: file-status-byte-1file-status-byte-2

castsc failed to close an extra partition TD queue.
System Action:
DCT entry will still be marked closed but an active handle may remain.
Resolution:
Investigate cause of failure to close.
Module:
castsc
Destination:
Console
Parent topic: CASTD0000 - CASTD0019


CASTD0004E Failed to open extra partition TD queue TD queue name. File status code: file-status-byte-1file-status-byte-2

castsc failed to open an extra partition TD queue.
System Action:
DCT status will not be changed.
Resolution:
Investigate cause of failure to close.
Module:
castsc
Destination:
Console
Parent topic: CASTD0000 - CASTD0019


CASTM - CICS System Termination Error Messages

  • CASTM0020 - CASTM0039
  • CASTM5000 - CASTM5019
  • CASTM5020 - CASTM5039
  • CASTM5040 - CASTM5059
  • CASTM5060 - CASTM5079
  • CASTM5080 - CASTM5099
  • CASTM5100 - CASTM5119
Parent topic: Enterprise Server Error Messages


CASTM0020 - CASTM0039

  • CASTM0032W IMS TM Service Process data store type error for block data-store-block, segment data-store-segment.
    The ES TSC process has detected an invalid segment type in data store block data-store-block, segment (data-store-segment).
  • CASTM0033W IMS TM Service Process data store structure error at block data-store-block, segment data-store-segment.
    The ES TSC process has detected a structrual error within the data store block data-store-block at segment (data-store-segment).
Parent topic: CASTM - CICS System Termination Error Messages


CASTM0032W IMS TM Service Process data store type error for block data-store-block, segment data-store-segment.

The ES TSC process has detected an invalid segment type in data store block data-store-block, segment (data-store-segment).
System Action:
This segment is marked as invalid. This message will not be issued for any additional errors of this type detected within this block. However, the associated corrective action will be performed for these errors.
Resolution:
Verify that important data has not been lost.
Module:
castmc
Destination:
Console
Parent topic: CASTM0020 - CASTM0039


CASTM0033W IMS TM Service Process data store structure error at block data-store-block, segment data-store-segment.

The ES TSC process has detected a structrual error within the data store block data-store-block at segment (data-store-segment).
System Action:
This segment is marked as invalid. This message will not be issued for any additional errors of this type detected within this block. However, the associated corrective action will be performed for these errors.
Resolution:
Verify that important data has not been lost.
Module:
castmc
Destination:
Console
Parent topic: CASTM0020 - CASTM0039


CASTM5000 - 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.
  • 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.
  • 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 queue initialization failed. Reason (reason-code)
    The IMS TM Control Process failed to initialize its message queues.
  • CASTM5013I IMS TM Control message queue file cold started
    The IMS TM Message Queue file has been cold started.
  • CASTM5014W IMS TM messages queues not properly closed previously
    The IMS TM Message Queues were not properly closed 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.
  • CASTM5017I IMS TM running with queue-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.
  • 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.
Parent topic: CASTM - CICS System Termination Error Messages


CASTM5001I IMS TM Control Process initialization started

The server IMS TM Control Process initialization has started.
Module:
castmc
Destination:
Console
Parent topic: CASTM5000 - 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: CASTM5000 - CASTM5019


CASTM5003I IMS TM Control Process initialization complete

The IMS TM Control Process has completed initialization.
Module:
castmc
Destination:
Console
Parent topic: CASTM5000 - 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: CASTM5000 - 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: CASTM5000 - 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: CASTM5000 - CASTM5019


CASTM5007I IMS TM Control Process termination started

The IMS TM Control Process is terminating.
Module:
castmc
Destination:
Console
Parent topic: CASTM5000 - CASTM5019


CASTM5008I IMS TM Control Process termination complete

The IMS TM Control Process has terminated.
Module:
castmc
Destination:
Console
Parent topic: CASTM5000 - 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: CASTM5000 - 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: CASTM5000 - 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: CASTM5000 - CASTM5019


CASTM5012S IMS TM Control message queue initialization 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: CASTM5000 - CASTM5019


CASTM5013I IMS TM Control message queue file cold started

The IMS TM Message Queue file has been cold started.

No old message data has been retained.

Module:
castmc
Destination:
Console
Parent topic: CASTM5000 - CASTM5019


CASTM5014W IMS TM messages queues not properly closed previously

The IMS TM Message Queues were not properly closed 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: CASTM5000 - 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: CASTM5000 - 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: CASTM5000 - CASTM5019


CASTM5017I IMS TM running with queue-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: CASTM5000 - 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: CASTM5000 - 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 Customer Support 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 Customer Support 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: CASTM5000 - CASTM5019


CASTM5020 - CASTM5039

  • CASTM5020S IMS TM Message Queue 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.
  • CASTM5021S IMS TM Message Queue upgrade or cold start is required. IMS TM version: version
    The message queue disk file is written in a format that is not supported by this version of IMS TM.
  • 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 security group security-group from logical unit logical-unit.
  • 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 security group security-group from logical unit logical-unit.
  • 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 security group security-group from logical unit logical-unit.
  • 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 security group security-group from logical unit logical-unit.
  • 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 security group security-group from logical unit logical-unit.
  • 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.
  • 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. Disk version appears to be version number.
    The message queue disk file format is not recognized or not supported by this version of IMS TM.
  • CASTM5037I IMS TM old Message Queue file: queue-file-name
    queue-file-name is the name of the old IMS Message Queues file that was saved 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 received a QC status.
  • CASTM5039I IMS TM system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced
    A system dump of the IMS DB process was generated with a DUMPCODE of dump-code.
Parent topic: CASTM - CICS System Termination Error Messages


CASTM5020S IMS TM Message Queue 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.

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 Queue upgrade or cold start is required. IMS TM version: version

The message queue disk file is written in a format that is not supported 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 security 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 security 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 security 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 personnel.
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 security 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 personnel.
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 security 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:
Assess 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:
Assess 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. Disk version appears to be version number.

The message queue disk file format is not recognized or not supported by this version of IMS TM.

The version on disk appears to be version number.

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 Message Queue file: queue-file-name

queue-file-name is the name of the old IMS Message Queues file that was saved 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 received a QC status.

This message is only issued once for a given start of the system. However, the "wait for input" behavior continues. system. However, the "wait.

System Action:
For GU message queue calls issued after receiving a QC, this transaction will wait until a new transaction is available.
Module:
castmc
Destination:
Console
Parent topic: CASTM5020 - CASTM5039


CASTM5039I IMS TM system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced

A system dump of the IMS DB process was generated with a DUMPCODE of dump-code.

The caller was dump-caller and it was written to DATASET dump-dataset in response to a /DUMP DB command.

System Action:
The ES mfcs/casgate process produces a system dump.
Module:
castmc
Destination:
System Console
Parent topic: CASTM5020 - CASTM5039


CASTM5040 - CASTM5059

  • CASTM5040I IMS TM Message Queue File flush requests disabled
    Flush operations for this file are bypassed.
  • CASTM5041I IMS TM Message Queue File flush requests aggregate time is aggregation-minimum milliseconds
    A flush aggregation span of aggregation-minimum millisecond is now effective.
  • CASTM5042I IMS TM Message Queue File flush requests aggregate disabled
    Flush 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: Number of programs loaded
    The named modules have been loaded and associated with their related exit points.
  • CASTM5045S IMS Message Formatting Services local memory allocation error error number.
    Message Formatting Services has terminated attempting to allocate local storage.
  • CASTM5046W IMS TM MFS segment exit program exit program could not be called
    The requested exit program 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 is 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.
  • CASTM5053I IMS TM XA recovery committed in-doubt output for transaction Transaction on process process id
    The message queue output for transaction Transaction previously running on process ID process id was committed.
  • CASTM5054I IMS TM control process (PID:process-id) recovery initiated
    The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASTM5055S IMS Message Formatting Services local memory allocation error error code.
    Message Formatting Services has terminated attempting to allocate local storage for DBCS data.
  • CASTM5056I IMS TM Message Queue dataset upgraded from version 1/02 to version 1/03
    The Message Queue dataset format has changed and this startup uses an old format Message Queue.
  • CASTM5057I IMS TM Original Message Queue saved as <message-queue-name>
    <message-queue-name> is the new name of the original TM Message Queue dataset retained prior to upgrade.
  • CASTM5058S IMS TM Save of original Message Queue data prior to upgrade failed, RC <rename-return-code>
    The system attempt to rename the old message queue dataset failed.
  • CASTM5059I IMS TM Message Queue dataset upgrade is complete
    The Message Queue dataset upgrade has completed successfully.
Parent topic: CASTM - CICS System Termination 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 - CASTM5059


CASTM5041I IMS TM Message Queue File flush requests aggregate time is 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 - CASTM5059


CASTM5042I IMS TM Message Queue File flush requests aggregate disabled

Flush aggregation has been dynamically disabled.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5043I IMS TM Message Queue File flush enabled

Flush operations for this file are now enabled.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5044I IMS TM exit programs loaded: Number of programs loaded

The named modules have been loaded and associated with their related exit points.
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5045S IMS Message Formatting Services local memory allocation error error number.

Message Formatting Services has terminated attempting to allocate local storage.
System Action:
The process terminates normally.
Resolution:
Make sure there is enough memory available to the system.
Module:
casmfs
Destination:
System Console and standard error.
Parent topic: CASTM5040 - CASTM5059


CASTM5046W IMS TM MFS segment exit program exit program could not be called

The requested exit program exit program could not be called because of a local memory allocation problem.
System Action:
The exit is not called.
Resolution:
Make sure there is enough memory available to the system.
Module:
casmfs
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


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


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


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


CASTM5050W IMS TM Message Queue file is 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 - CASTM5059


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


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 subsequent 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 - CASTM5059


CASTM5053I IMS TM XA recovery committed in-doubt output for transaction Transaction on process process id

The message queue output for transaction Transaction previously running on process ID process id was committed.
System Action:
The transaction output was sent to the appropriate destination(s).
Module:
castmc
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5054I IMS TM control process (PID:process-id) recovery initiated

The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
castmc
Destination:
Console and standard error.
Parent topic: CASTM5040 - CASTM5059


CASTM5055S IMS Message Formatting Services local memory allocation error error code.

Message Formatting Services has terminated attempting to allocate local storage for DBCS data.
System Action:
The process terminates normally.
Resolution:
Make sure there is enough memory available to the system.
Module:
casmfs
Destination:
System Console and standard error.
Parent topic: CASTM5040 - CASTM5059


CASTM5056I IMS TM Message Queue dataset upgraded from version 1/02 to version 1/03

The Message Queue dataset format has changed and this startup uses an old format Message Queue.

The data will be copied to a new Message Queue file and the old file will be saved.

System Action:
Upgrade the TM Message Queue.
Module:
casrdo04
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5057I IMS TM Original Message Queue saved as <message-queue-name>

<message-queue-name> is the new name of the original TM Message Queue dataset retained prior to upgrade.
System Action:
The original Message Queue has been saved.
Module:
casrdo04
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5058S IMS TM Save of original Message Queue data prior to upgrade failed, RC <rename-return-code>

The system attempt to rename the old message queue dataset failed.

The original dataset is not upgraded.

Module:
casrdo04
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5059I IMS TM Message Queue dataset upgrade is complete

The Message Queue dataset upgrade has completed successfully.
System Action:
TM Message Queue dataset upgrade complete.
Module:
casrdo04
Destination:
Console
Parent topic: CASTM5040 - CASTM5059


CASTM5060 - CASTM5079

  • CASTM5060I IMS TM Message Queue data store is upgraded from versionprevious data-store-version to versioncurrent data-store-version
    A data store upgrade was automatically performed during a warm start.
  • CASTM5061E ims-control-error-message
    The IMS TM Control Process issued an error message.
  • CASTM5065I IMS TM Message Queue DB created/opened started at data-store location
    The TM message queue is opened at location data-store location.
  • CASTM5066E IMS TM Message Queue DB create/open failed, RC:return-code-part-1return-code-part-2, at data-store location
    The TM message queue create/open failed for location data-store location.
  • CASTM5067E IMS TM Message Queue DB data store support load failed, RC:operation, return-code-part-1return-code-part-2, data-store-location
    The TM message queue DB support failed to load.
  • CASTM5068E IMS TM Message Queue DB data store unexpected error on operation, RC:return-code-part-1return-code-part-2
    There was an unexpected error for an operation operation on against the TM message queue while supported by relational database.
  • CASTM5069E IMS TM Message Queue DB data store unexpected error on action operation, message number message-number, RC:return-code-part-1return-code-part-2
    There was an unexpected error for an operation action for message number message-number against the TM message queue while supported by relational database.
  • CASTM5070I IMS TM Message Queue cold start is requested by casstart -s:c
    IMS TM has been signaled to cold start its Message Queue.
  • CASTM5071S IMS TM Message Queue relational database access failed, server is terminating
    The TM message queue requested relational database access has failed and this server is terminating.
  • CASTM5072I ims-tm-trace-output
    The IMS Process output message queue trace data.
  • CASTM5073E IMS TM Message Queue DB data store unexpected error on action operation, RC:return-code-part-1return-code-part-2
    There was an unexpected error for an operation action for the TM message queue while supported by relational database.
  • CASTM5074E IMS TM Destination DB data store unexpected error on operation, RC:return-code-part-1return-code-part-2
    There was an unexpected error for an operation operation on against the TM message queue while supported by relational database.
Parent topic: CASTM - CICS System Termination Error Messages


CASTM5060I IMS TM Message Queue data store is upgraded from versionprevious data-store-version to versioncurrent data-store-version

A data store upgrade was automatically performed during a warm start.

The data store is now not compatible with the earlier version of this product that produced it.

System Action:
The data store is upgraded to match this version of product.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5061E ims-control-error-message

The IMS TM Control Process issued an error message.

The text is ims-control-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5065I IMS TM Message Queue DB created/opened started at data-store location

The TM message queue is opened at location data-store location.
System Action:
The db data store is created or opened.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5066E IMS TM Message Queue DB create/open failed, RC:return-code-part-1return-code-part-2, at data-store location

The TM message queue create/open failed for location data-store location.

The MFDBFH return code is return-code-part-1.

System Action:
The db data store will not be used for this TM instance.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5067E IMS TM Message Queue DB data store support load failed, RC:operation, return-code-part-1return-code-part-2, data-store-location

The TM message queue DB support failed to load.
System Action:
The db data store will not be used for this TM instance.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5068E IMS TM Message Queue DB data store unexpected error on operation, RC:return-code-part-1return-code-part-2

There was an unexpected error for an operation operation on against the TM message queue while supported by relational database.

Its return code is return-code-part-1return-code-part-2.

System Action:
If the operation is "OPEN", the db data store will not be used for this TM instance. Otherwise the operation is terminated.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5069E IMS TM Message Queue DB data store unexpected error on action operation, message number message-number, RC:return-code-part-1return-code-part-2

There was an unexpected error for an operation action for message number message-number against the TM message queue while supported by relational database.

The operation return code is return-code-part-1return-code-part-2.

System Action:
The operation is terminated.
Module:
castmc, casmpr, casbat or dfheserv
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5070I IMS TM Message Queue cold start is requested by casstart -s:c

IMS TM has been signaled to cold start its Message Queue.
System Action:
The DB or legacy data store will be reinitialized.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5071S IMS TM Message Queue relational database access failed, server is terminating

The TM message queue requested relational database access has failed and this server is terminating.
System Action:
The server will terminate.
Resolution:
Correct the relational database access failure and restart this server.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5072I ims-tm-trace-output

The IMS Process output message queue trace data.

This is controled by the idb-to-console trace flag. The trace output is ims-tm-trace-output.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5073E IMS TM Message Queue DB data store unexpected error on action operation, RC:return-code-part-1return-code-part-2

There was an unexpected error for an operation action for the TM message queue while supported by relational database.

The operation return code is return-code-part-1return-code-part-2.

System Action:
The operation is terminated.
Module:
castmc, casmpr, casbat or dfheserv
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5074E IMS TM Destination DB data store unexpected error on operation, RC:return-code-part-1return-code-part-2

There was an unexpected error for an operation operation on against the TM message queue while supported by relational database.

Its return code is return-code-part-1return-code-part-2.

System Action:
If the operation is "OPEN", the db data store will not be used for this TM instance. Otherwise the operation is terminated.
Module:
castmc
Destination:
Console
Parent topic: CASTM5060 - CASTM5079


CASTM5080 - CASTM5099

  • CASTM5099I user-message
    This is a message generated from user MFS exit code.
Parent topic: CASTM - CICS System Termination Error Messages


CASTM5099I user-message

This is a message generated from user MFS exit code.
Module:
castmc
Destination:
Console
Parent topic: CASTM5080 - CASTM5099


CASTM5100 - CASTM5119

  • CASTM5100S IMS TM dispatch queue is damaged: class dispatch-class; priority dispatch-priority; block queue-file-block; segment x'segment-number'
    The IMS TM dispatch queue is damaged.
  • CASTM5101E IMS TM failed a search for destination ID destination-id during an XA PREPARE for transaction ID message-source, source message-source (reference 3b6679)
    A search for a destination failed.
Parent topic: CASTM - CICS System Termination Error Messages


CASTM5100S IMS TM dispatch queue is damaged: class dispatch-class; priority dispatch-priority; block queue-file-block; segment x'segment-number'

The IMS TM dispatch queue is damaged.
System Action:
System discards the bad message segment(s).
Resolution:
Assess system damage, stop and repair system if necessary.
Module:
castmc
Destination:
Console
Parent topic: CASTM5100 - CASTM5119


CASTM5101E IMS TM failed a search for destination ID destination-id during an XA PREPARE for transaction ID message-source, source message-source (reference 3b6679)

A search for a destination failed.

This is an illogical result and should not occur.

System Action:
The output message for destination ID destination-id is discarded.
Resolution:
This failure is illogical. Collect diagnostic information and open a support incident.
Module:
castmc
Destination:
Console
Parent topic: CASTM5100 - CASTM5119


CASTP - Transaction Paging Error Messages

  • CASTP4100 - CASTP4119
  • CASTP4120 - CASTP4139
  • CASTP4900 - CASTP4919
Parent topic: Enterprise Server Error Messages


CASTP4100 - CASTP4119

  • CASTP4101 Cannot reset from temporary paging to autopaging.
    A terminal requested that it be reset from temporary paging status to autopaging status.
  • CASTP4104 A paging request was received but there are no pages for display.
    The CICS paging command (CSPG) or a request for paging was entered from a terminal in transaction status, but there are no pages to be displayed at the terminal.
  • CASTP4108 Requested pagepage-number does not exist (it is less than 1 or more than the number of pages in the message).
    The page page-number, as indicated by the page retrieval command, is either less than one or is greater than the number of pages in the message.
  • CASTP4109 The requested command page-command was not recognized. Check that you have the correct value.
    Transaction CSPG was entered at the terminal, but what follows cannot be identified as a paging command.
  • CASTP4110 page-function is not valid. Page RETRIEVE function must be A, C, L, N, P, Q, or a number.
    The page retrieve function represented by page-function is not one of the following: A, C, L, N, P, Q, or a number that may be preceded by a + (plus) or a - (minus) sign.
  • CASTP4111 function is not valid. Page PURGE function must be A, B, C, H, or R.
    The page purge function represented by function is not A, B, C, H, or R.
  • CASTP4115 You must purge the message from your terminal to continue.
    A transaction is displaying pages at the terminal.
  • CASTP4116 Your message request cannot be done while another message is being displayed.
    While viewing a message, the operator entered a request for a specific message (for example, P/1,xxx) or requested the message identifiers of messages waiting to be displayed (P/Q).
Parent topic: CASTP - Transaction Paging Error Messages


CASTP4101 Cannot reset from temporary paging to autopaging.

A terminal requested that it be reset from temporary paging status to autopaging status.

However, the terminal is defined as a paging terminal, or the message is marked to state that the operator must purge it.

System Action:
Other processing continues.
Resolution:
If the terminal is defined as a purging terminal, use the master terminal program to change the status of the terminal. If the message is so marked, the operator must purge the message. The system then automatically resets the status to autopaging.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4104 A paging request was received but there are no pages for display.

The CICS paging command (CSPG) or a request for paging was entered from a terminal in transaction status, but there are no pages to be displayed at the terminal.
System Action:
Other processing continues.
Resolution:
The paging session can be continued with a.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4108 Requested pagepage-number does not exist (it is less than 1 or more than the number of pages in the message).

The page page-number, as indicated by the page retrieval command, is either less than one or is greater than the number of pages in the message.

This can be caused, for example, by requesting the previous page after the first page, or the next page after the last page.

System Action:
Other processing continues.
Resolution:
The paging session can be continued with a valid page value. The last valid page displayed is still the current page. For example, to recall the last valid page displayed, execute the page retrieval command used to get a current page.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4109 The requested command page-command was not recognized. Check that you have the correct value.

Transaction CSPG was entered at the terminal, but what follows cannot be identified as a paging command.

page-command represents the first four non blank characters after CSPG.

System Action:
Other processing continues.
Resolution:
None.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4110 page-function is not valid. Page RETRIEVE function must be A, C, L, N, P, Q, or a number.

The page retrieve function represented by page-function is not one of the following: A, C, L, N, P, Q, or a number that may be preceded by a + (plus) or a - (minus) sign.

Valid values for page-function are:

Function Meaning
  A      All logical messages destined for and being displayed
         on that terminal.
  C      The current (level) logical message.
  L      The last page.
  N      The next page.
  P      The previous page.
  Q      (Query) display the identifier of all logical messages
         destined for this terminal. If the message is security
         protected, its identifier is displayed only if the operator
         identifier and class for the signed-on operator match
         those in the message. The identifier consists of
         1-to-6-digit hexadecimal number, and optionally, a
         message title.
System Action:
Other processing continues.
Resolution:
Use a valid page retrieve function.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4111 function is not valid. Page PURGE function must be A, B, C, H, or R.

The page purge function represented by function is not A, B, C, H, or R.

The functions have the following meanings.

Function Meaning
  A      All logical messages destined for and being displayed
         on that terminal.
  B      The logical message being displayed on that terminal
         and all logical messages chained to it.
  C      The current (level) logical message.
  H      All logical messages chained to the base logical
         message being displayed on that terminal.
  R      All logical messages queued for immediate delivery
(routed) to the terminal.
System Action:
Other processing continues.
Resolution:
Use a valid page purge function.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4115 You must purge the message from your terminal to continue.

A transaction is displaying pages at the terminal.

Before the operator can continue with the transaction, the message must be purged.

System Action:
Other processing continues.
Resolution:
Purge the current message (T/C).
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4100 - CASTP4119


CASTP4116 Your message request cannot be done while another message is being displayed.

While viewing a message, the operator entered a request for a specific message (for example, P/1,xxx) or requested the message identifiers of messages waiting to be displayed (P/Q).

CICS cannot service this request while another message is being displayed. xxx is the message identifier of one of the messages waiting to be displayed.

System Action:
Other processing continues.
Resolution:
If desired, reenter the request when there are no messages being displayed at the terminal.
Module:
dfhzcspg
Destination:
Terminal End User
Parent topic: CASTP4100 - CASTP4119


CASTP4120 - CASTP4139

  • CASTP4122 Requested purge completed successfully.
    CICS has completed a page purge function requested from the terminal.
  • CASTP4128 pa-pf-key is undefined for page retrieval.
    After a page retrieval (PR) session had been started, the operator pressed a PA or PF key for which no PR command had been defined in the SIT.
Parent topic: CASTP - Transaction Paging Error Messages


CASTP4122 Requested purge completed successfully.

CICS has completed a page purge function requested from the terminal.
System Action:
Processing continues.
Resolution:
None.
Module:
dfhzcspg
Destination:
Terminal End User
Parent topic: CASTP4120 - CASTP4139


CASTP4128 pa-pf-key is undefined for page retrieval.

After a page retrieval (PR) session had been started, the operator pressed a PA or PF key for which no PR command had been defined in the SIT.
System Action:
The command is ignored. The display status bit is not altered.
Resolution:
Ensure that the PR command in question is defined in the SIT.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4120 - CASTP4139


CASTP4900 - CASTP4919

  • CASTP4901 PAGING pseudo-conversational internal state error
    An unexpected logic error occurred during the processing of a BMS Paging operation.
  • CASTP4902 PAGING unexpected error accessing page queue. EIBRESP = eibresp-value.
    An unexpected TS Queue error occurred during the processing of a BMS Paging operation.
  • CASTP4903 PAGE COPYING is not currently supported.
    This functionality is not currently supported in Enterprise Server.
  • CASTP4904 PAGE CHAINING is not currently supported.
    This functionality is not currently supported in Enterprise Server.
  • CASTP4905 PAGE ROUTING is not currently supported.
    This functionality is not currently supported in Enterprise Server.
Parent topic: CASTP - Transaction Paging Error Messages


CASTP4901 PAGING pseudo-conversational internal state error

An unexpected logic error occurred during the processing of a BMS Paging operation.

The EIBRESP value is eibresp-value.

System Action:
The paging operation is terminated.
Resolution:
Retry the operation. If the issue reoccurs, report the problem to Micro Focus.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4900 - CASTP4919


CASTP4902 PAGING unexpected error accessing page queue. EIBRESP = eibresp-value.

An unexpected TS Queue error occurred during the processing of a BMS Paging operation.

The EIBRESP value is eibresp-value.

System Action:
The paging operation is terminated.
Resolution:
Check CICS TS (Temporary Storage) facilities for proper operation. If the issue is not identified, report the problem to Micro Focus.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4900 - CASTP4919


CASTP4903 PAGE COPYING is not currently supported.

This functionality is not currently supported in Enterprise Server.
System Action:
The paging operation is terminated.
Resolution:
None.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4900 - CASTP4919


CASTP4904 PAGE CHAINING is not currently supported.

This functionality is not currently supported in Enterprise Server.
System Action:
The paging operation is terminated.
Resolution:
None.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4900 - CASTP4919


CASTP4905 PAGE ROUTING is not currently supported.

This functionality is not currently supported in Enterprise Server.
System Action:
The paging operation is terminated.
Resolution:
None.
Module:
dfhzcspg
Destination:
Terminal end user
Parent topic: CASTP4900 - CASTP4919


CASTR - TRC Service Process Error Messages

  • CASTR0000 - CASTR0019
Parent topic: Enterprise Server Error Messages


CASTR0000 - CASTR0019

  • CASTR0001W ES TRC HSF processing error. Unexpected SCB data for task Task ID that TRC was generating an HSF record for, when it detected the error.
    The ES TRC process detected an error in the SEP Collection Block when creating an HSF record.
  • CASTR0002W ES TRC HSF response time error for task task-id, PID process-id. System dump produced, CODE:dump-code.
    A dump of the ES TRC process was generated for task ID %1, PID process-id with DUMPCODE dump-code in response to an administrative interface request.
Parent topic: CASTR - TRC Service Process Error Messages


CASTR0001W ES TRC HSF processing error. Unexpected SCB data for task Task ID that TRC was generating an HSF record for, when it detected the error.

The ES TRC process detected an error in the SEP Collection Block when creating an HSF record.
System Action:
The ES TRC process produces an ES system dump.
Resolution:
Send the dump file, aux trace, console log and csv files to Micro Focus.
Module:
castrc
Destination:
Console
Parent topic: CASTR0000 - CASTR0019


CASTR0002W ES TRC HSF response time error for task task-id, PID process-id. System dump produced, CODE:dump-code.

A dump of the ES TRC process was generated for task ID %1, PID process-id with DUMPCODE dump-code in response to an administrative interface request.
System Action:
ES TRC HSF process produces a system dump.
Module:
castrc
Destination:
Console
Parent topic: CASTR0000 - CASTR0019


CASTS - TSC Service Process Error Messages

  • CASTS0000 - CASTS0019
  • CASTS0020 - CASTS0039
  • CASTS1000 - CASTS1019
  • CASTS1020 - CASTS1039
  • CASTS5000 - CASTS5019
  • CASTS5020 - CASTS5039
  • CASTS5040 - CASTS5059
  • CASTS5060 - CASTS5079
  • CASTS5100 - CASTS5119
  • CASTS5120 - CASTS5139
  • CASTS5140 - CASTS5159
  • CASTS5600 - CASTS5619
Parent topic: Enterprise Server Error Messages


CASTS0000 - CASTS0019

  • CASTS0001I ES TSC Service Process restart in progress
    The ES TSC Service process has been restarted and recovery operations are in progress.
  • CASTS0002I ES TSC Service Process initialization complete
    The ES TSC Service Process has completed initialization.
  • CASTS0003I ES TSC Service Process termination started
    The ES TSC Service Process is terminating.
  • CASTS0004S ES TSC Service Process registration failed, reason = reason-code
    The ES TSC Service Process failed registration.
  • CASTS0005I ES TSC Service Process termination complete
    The ES TSC Service Process has terminated.
  • CASTS0006I tsc-control-message
    The ES TSC Service Process issued a message.
  • CASTS0007I ES TSC Service Process initialization started
    The server ES TSC Service Process initialization has started.
  • 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.
  • CASTS0009W TS queue queue name inconsistent end at location location block; should be value that should have been.
    The ES TSC process has encountered a problem with temporary storage queue queue name.
  • CASTS0010W TS queue queue name invalid chain start at location location block.
    The ES TSC process has encountered a problem with temporary storage queue queue name.
  • CASTS0011W TS queue queue name invalid chain next reference next pointer from block location block.
    The ES TSC process has encountered a problem with temporary storage queue queue name.
  • CASTS0012E tsc-control-error-message
    The ES TSC Service Process issued an error message.
  • CASTS0018W TS queue queue name invalid segment referenced segment reference from block location block.
    The ES TSC process has encountered a problem with temporary storage queue queue name.
  • CASTS0019I ES support for CICS TRANCLASS and transaction priority is enabled
    CICS TRANCLASS and priority is enabled for Enterprise Server.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS0001I ES TSC Service Process restart in progress

The ES TSC Service process has been restarted and recovery operations are in progress.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0002I ES TSC Service Process initialization complete

The ES TSC Service Process has completed initialization.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0003I ES TSC Service Process termination started

The ES TSC Service Process is terminating.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0004S ES TSC Service Process registration failed, reason = reason-code

The ES TSC Service Process failed registration.

The reason code is reason-code.

System Action:
The ES TSC Service Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0005I ES TSC Service Process termination complete

The ES TSC Service Process has terminated.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0006I tsc-control-message

The ES TSC Service Process issued a message.

The text is tsc-control-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0007I ES TSC Service Process initialization started

The server ES TSC Service Process initialization has started.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


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.
System Action:
The ES TSC Service Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0009W TS queue queue name inconsistent end at location location block; should be value that should have been.

The ES TSC process has encountered a problem with temporary storage queue queue name.

The reported block is the expected end and it may be orphaned.

System Action:
The end of the TS queue is adjusted to match the current data chain.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0010W TS queue queue name invalid chain start at location location block.

The ES TSC process has encountered a problem with temporary storage queue queue name.

The reported block(location block) is not of the proper TS data type.

System Action:
The TS queue is removed.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0011W TS queue queue name invalid chain next reference next pointer from block location block.

The ES TSC process has encountered a problem with temporary storage queue queue name.

The reported block(location block) has a chain next pointer of next pointer which is out of range.

System Action:
The TS queue is removed up to the reference point.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0012E tsc-control-error-message

The ES TSC Service Process issued an error message.

The text is tsc-control-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0018W TS queue queue name invalid segment referenced segment reference from block location block.

The ES TSC process has encountered a problem with temporary storage queue queue name.

The reported block(location block) has a chain next pointer of segment reference which points to an invalid segment in the message queue file.

System Action:
The TS queue is removed up to the reference point.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0019I ES support for CICS TRANCLASS and transaction priority is enabled

CICS TRANCLASS and priority is enabled for Enterprise Server.
System Action:
ES behavior is modified to support TRANCLASS and priority.
Module:
castsc
Destination:
Console
Parent topic: CASTS0000 - CASTS0019


CASTS0020 - CASTS0039

  • CASTS0020I ES is configured to discard unsolicited CICS TN3270 input
    Enterprise Server CICS terminal control is configured to discard all unsolicited TN3270 messages. i.e. it will discard TN3270 messages that arrive while a transaction is active for the target terminal unless the transaction has issued an explicit CICS RECEIVE after the first CICS terminal control command.
  • CASTS0021W TS block block number invalid for queue names that hash to index index
    The ES TSC process has encountered a problem with an internal temporary storage control block that has a chain next pointer of block number which points to an invalid area in the TS/TD dataset file.
  • CASTS0022W TD block block number invalid for queue names that hash to index index
    The ES TSC process has encountered a problem with an internal intra-partition transient data control block that has a chain next pointer of block number which points to an invalid area in the TS/TD dataset file.
  • CASTS0023I ES TSC Fileshare configuration cold started
    The ES TSC process has found a stored Fileshare configuration from a previous ES run.
  • CASTS0024I ES TSC Fileshare configuration warm started
    The ES TSC process has found a stored Fileshare configuration from a previous ES run.
  • CASTS0025I ES TSC system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced
    A dump of the ES TSC process was generated with a DUMPCODE of dump-code.
  • CASTS0026W TD queue queue-name inconsistent end at location actual-end-location; corrected to reported-end-location
    The ES TSC process has encountered a problem with transient data queue queue-name.
  • CASTS0027W TD queue queue-name invalid chain start at location reported-start-location.
    The ES TSC process has encountered a problem with transient data queue queue-name.
  • CASTS0028W TD queue queue-name inconsistent item count of actual countwhich should be reported-count
    The ES TSC process has encountered a problem with transient data queue queue-name.
  • CASTS0029W TD queue queue-name referenced invalid hash block location block-referenced.
    The ES TSC process has encountered a problem with transient data queue queue-name.
  • CASTS0030W TD queue queue-name reports invalid first and last records at invalid-first-record-address and invalid-last-record-address.
    The ES TSC process has encountered a problem with transient data queue queue-name.
  • CASTS0031W TD queue queue-name hash block hash-block-address reports an invalid first record address at invalid-first-record-address.
    The ES TSC process has encountered a problem with transient data queue queue-name.
  • CASTS0032W ES TSC Service Process data store type error for block data-store-block, segment data-store-segment.
    The ES TSC process has detected an invalid segment type in data store block data-store-block, segment (data-store-segment).
  • CASTS0033W ES TSC Service Process data store structure error at block data-store-block, segment data-store-segment.
    The ES TSC process has detected a structrual error within the data store block data-store-block at segment (data-store-segment).
Parent topic: CASTS - TSC Service Process Error Messages


CASTS0020I ES is configured to discard unsolicited CICS TN3270 input

Enterprise Server CICS terminal control is configured to discard all unsolicited TN3270 messages. i.e. it will discard TN3270 messages that arrive while a transaction is active for the target terminal unless the transaction has issued an explicit CICS RECEIVE after the first CICS terminal control command.

For messages that arrive while the terminal is idle, ES will attempt to start a transaction for the message.

System Action:
ES behavior is modified to not queue unsolicited TN3270 messages until the target terminal is available.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0021W TS block block number invalid for queue names that hash to index index

The ES TSC process has encountered a problem with an internal temporary storage control block that has a chain next pointer of block number which points to an invalid area in the TS/TD dataset file.
System Action:
The TS control block is dropped; data is lost.
Resolution:
The reported block is the expected continuation of the chain and should have been reported as a TS Block. Recovery actions may be required.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0022W TD block block number invalid for queue names that hash to index index

The ES TSC process has encountered a problem with an internal intra-partition transient data control block that has a chain next pointer of block number which points to an invalid area in the TS/TD dataset file.
System Action:
The TS control block is dropped; data is lost.
Resolution:
The reported block is the expected continuation of the chain and should have been reported as a TS Block. Recovery actions may be required.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0023I ES TSC Fileshare configuration cold started

The ES TSC process has found a stored Fileshare configuration from a previous ES run.

ES is currently configured to discard this information and use the ES static configuration.

System Action:
The saved configuration data is discarded.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0024I ES TSC Fileshare configuration warm started

The ES TSC process has found a stored Fileshare configuration from a previous ES run.

ES will use this configuration data.

System Action:
The saved configuration data is used for this ES run.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0025I ES TSC system dump CODE:dump-code, CALLER:dump-caller and DATASET:dump-dataset was produced

A dump of the ES TSC process was generated with a DUMPCODE of dump-code.

The caller was dump-caller and it was written to DATASET dump-dataset.

System Action:
The ES TSC process produces an ES system dump.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0026W TD queue queue-name inconsistent end at location actual-end-location; corrected to reported-end-location

The ES TSC process has encountered a problem with transient data queue queue-name.

The reported block is the expected end and it may be orphaned.

System Action:
The end of the TD queue is adjusted to match the current data chain.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0027W TD queue queue-name invalid chain start at location reported-start-location.

The ES TSC process has encountered a problem with transient data queue queue-name.

The reported block(reported-start-location) is not of the proper TD data type.

System Action:
The TD queue is removed.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0028W TD queue queue-name inconsistent item count of actual countwhich should be reported-count

The ES TSC process has encountered a problem with transient data queue queue-name.

The reported queue item count reported-count does not match the actual actual count items in the queue.

System Action:
The TD queue count is adjusted to match the current data that was verified to be in the queue.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0029W TD queue queue-name referenced invalid hash block location block-referenced.

The ES TSC process has encountered a problem with transient data queue queue-name.

The reported block(block-referenced) is not of the proper TD storage type.

System Action:
The TD queue is removed.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0030W TD queue queue-name reports invalid first and last records at invalid-first-record-address and invalid-last-record-address.

The ES TSC process has encountered a problem with transient data queue queue-name.

The reported first and last records each have invalid addressee. The invalid first address is invalid-first-record-address and the invalid last address is invalid-last-record-address. These are not valid data store addresses.

System Action:
The TD queue is removed.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0031W TD queue queue-name hash block hash-block-address reports an invalid first record address at invalid-first-record-address.

The ES TSC process has encountered a problem with transient data queue queue-name.

The reported block(invalid-first-record-address) is not of the proper TD storage type.

System Action:
An attempt to restore the TD queue with with only the last record will be made.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0032W ES TSC Service Process data store type error for block data-store-block, segment data-store-segment.

The ES TSC process has detected an invalid segment type in data store block data-store-block, segment (data-store-segment).
System Action:
This segment is marked as invalid. This message will not be issued for any additional errors of this type detected within this block. However, the associated corrective action will be performed for these errors.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS0033W ES TSC Service Process data store structure error at block data-store-block, segment data-store-segment.

The ES TSC process has detected a structrual error within the data store block data-store-block at segment (data-store-segment).
System Action:
This segment is marked as invalid. This message will not be issued for any additional errors of this type detected within this block. However, the associated corrective action will be performed for these errors.
Resolution:
Verify that important data has not been lost.
Module:
castsc
Destination:
Console
Parent topic: CASTS0020 - CASTS0039


CASTS1000 - CASTS1019

  • CASTS1000I ES TRC service process (PID:process-id) recovery initiated
    The ES TRC server process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASTS1001I ES TRC Service Process restart in progress
    The ES TRC Service process has been restarted and recovery operations are in progress.
  • CASTS1002I ES TRC Service Process initialization complete
    The ES TRC Service Process has completed initialization.
  • CASTS1003I ES TRC Service Process termination started
    The ES TRC Service Process is terminating.
  • CASTS1004S ES TRC Service Process registration failed, reason = reason-code
    The ES TRC Service Process failed registration.
  • CASTS1005I ES TRC Service Process termination complete
    The ES TRC Service Process has terminated.
  • CASTS1006I trc-control-message
    The ES TRC Service Process issued a message.
  • CASTS1007I ES TRC Service Process initialization started
    The server ES TRC Service Process initialization has started.
  • CASTS1008S ES TRC Service Process is not running in multi-threaded mode
    The ES TRC Service Process has not started with the required underlying thread support.
  • CASTS1009W TS queue queue name inconsistent end at location location; should be value expected.
    The ES TRC process has encountered a problem with temporary storage queue queue name.
  • CASTS1010W TS queue queue name invalid chain start at location location.
    The ES TRC process has encountered a problem with temporary storage queue queue name.
  • CASTS1011W TS queue queue name invalid chain next reference next pointer from block block.
    The ES TRC process has encountered a problem with temporary storage queue queue name.
  • CASTS1012E trc-control-error-message
    The ES TRC Service Process issued an error message.
  • CASTS1013W ES TRC has temporarily switched HSF off due to max queued work limit (Number of trace tables that can be held) being reached
    The spill thread in TRC has reached the maximum number of queued trace tables.
  • CASTS1014I ES TRC has re-enabled HSF processing because the queued work has been processed
    The spill thread in TRC has processed all queued trace tables.
  • CASTS1018W TS queue queue name invalid segment referenced next pointer from block block.
    The ES TRC process has encountered a problem with temporary storage queue queue name.
  • CASTS1019I ES support for CICS TRANCLASS and transaction priority is enabled
    CICS TRANCLASS and priority is enabled for Enterprise Server.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS1000I ES TRC service process (PID:process-id) recovery initiated

The ES TRC server process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
castrc
Destination:
Console and standard error.
Parent topic: CASTS1000 - CASTS1019


CASTS1001I ES TRC Service Process restart in progress

The ES TRC Service process has been restarted and recovery operations are in progress.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1002I ES TRC Service Process initialization complete

The ES TRC Service Process has completed initialization.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1003I ES TRC Service Process termination started

The ES TRC Service Process is terminating.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1004S ES TRC Service Process registration failed, reason = reason-code

The ES TRC Service Process failed registration.

The reason code is reason-code.

System Action:
The ES TRC Service Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1005I ES TRC Service Process termination complete

The ES TRC Service Process has terminated.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1006I trc-control-message

The ES TRC Service Process issued a message.

The text is trc-control-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1007I ES TRC Service Process initialization started

The server ES TRC Service Process initialization has started.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1008S ES TRC Service Process is not running in multi-threaded mode

The ES TRC Service Process has not started with the required underlying thread support.
System Action:
The ES TRC Service Process is terminated.
Resolution:
Report failure to Micro Focus.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1009W TS queue queue name inconsistent end at location location; should be value expected.

The ES TRC process has encountered a problem with temporary storage queue queue name.

The reported block is the expected end and it may be orphaned.

System Action:
The end of the TS queue is adjusted to match the current data chain.
Resolution:
Verify that important data has not been lost.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1010W TS queue queue name invalid chain start at location location.

The ES TRC process has encountered a problem with temporary storage queue queue name.

The reported block(location) is not of the proper TS data type.

System Action:
The TS queue is removed.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1011W TS queue queue name invalid chain next reference next pointer from block block.

The ES TRC process has encountered a problem with temporary storage queue queue name.

The reported block(block) has a chain next pointer of next pointer which is out of range.

System Action:
The TS queue is removed up to the reference point.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1012E trc-control-error-message

The ES TRC Service Process issued an error message.

The text is trc-control-error-message.

System Action:
Dependant on the message.
Resolution:
Action the message.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1013W ES TRC has temporarily switched HSF off due to max queued work limit (Number of trace tables that can be held) being reached

The spill thread in TRC has reached the maximum number of queued trace tables.

This limit is to prevent TRC from running out of memory. The max limit can be modified by setting ES_HSF_WORK_LIMIT. Default is 10000.

System Action:
HSF switched off until the backlog of work has been processed.
Resolution:
Report failure to Micro Focus.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1014I ES TRC has re-enabled HSF processing because the queued work has been processed

The spill thread in TRC has processed all queued trace tables.
System Action:
HSF re-enabled.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1018W TS queue queue name invalid segment referenced next pointer from block block.

The ES TRC process has encountered a problem with temporary storage queue queue name.

The reported block(block) has a chain next pointer of next pointer which points to an invalid segment in the message queue file.

System Action:
The TS queue is removed up to the reference point.
Resolution:
The reported block is the expected first in the chain. Verify that important data has not been lost.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1019I ES support for CICS TRANCLASS and transaction priority is enabled

CICS TRANCLASS and priority is enabled for Enterprise Server.
System Action:
ES behavior is modified to support TRANCLASS and priority.
Module:
castrc
Destination:
Console
Parent topic: CASTS1000 - CASTS1019


CASTS1020 - CASTS1039

  • CASTS1020I ES is configured to discard unsolicited CICS TN3270 input
    Enterprise Server CICS terminal control is configured to discard all unsolicited discard all unsolicited TN3270 messages. i.e. it will discard TN3270 messages that arrive while a transaction is active for the target terminal unless the transaction has issued an explicit CICS RECEIVE after the first CICS terminal control command.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS1020I ES is configured to discard unsolicited CICS TN3270 input

Enterprise Server CICS terminal control is configured to discard all unsolicited discard all unsolicited TN3270 messages. i.e. it will discard TN3270 messages that arrive while a transaction is active for the target terminal unless the transaction has issued an explicit CICS RECEIVE after the first CICS terminal control command.

For messages that arrive while the terminal is idle, ES will attempt to start a transaction for the message.

System Action:
ES behavior is modified to not queue unsolicited TN3270 messages until the target terminal is available.
Module:
castrc
Destination:
Console
Parent topic: CASTS1020 - CASTS1039


CASTS5000 - CASTS5019

  • CASTS5012S ES TSC Log and Intra-Partition TS/TD initialization failed. Reason (reason-code)
    The ES TSC Control Process failed to initialize its log facility.
  • CASTS5013I ES TSC Log and Intra-Partition TS/TD facility cold started
    The ES Log and TS/TD facility has been cold started.
  • 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.
  • CASTS5015I ES TSC Log and Intra-Partition TS/TD: queue-file-name
    queue-file-name is the name of the TS/TD Queues file that will be used during this execution of ES.
  • CASTS5016I ES TSC Log and Intra-Partition TS/TD File size: queue-block-count blocks (queue-file-size bytes)
    The allocated block count for the TS/TD queues is queue-block-count.
  • CASTS5017I ES TSC Log and Intra-Partition TS/TD running with log-buffer-count buffers of buffer-size bytes each
    log-buffer-count buffers are allocated for the TS/TD queues' use during this execution of ES.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5012S ES TSC Log and Intra-Partition TS/TD initialization failed. Reason (reason-code)

The ES TSC Control Process failed to initialize its log facility.

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 mismatch
 A = Queue file record block number mismatchror

These codes may be followed by a ":" and RTS file IO error code.

System Action:
The ES TSC Control Process is terminated and ES termination is initiated.
Resolution:
Correct the ES TSC configuration and restart the Enterprise Server.
Module:
castsc
Destination:
Console
Parent topic: CASTS5000 - CASTS5019


CASTS5013I ES TSC Log and Intra-Partition TS/TD facility cold started

The ES Log and TS/TD facility has been cold started.

No old data has been retained.

Module:
castsc
Destination:
Console
Parent topic: CASTS5000 - CASTS5019


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.
System Action:
ES will attempt to insure data integrity. Additional messages will report any problems with this process.
Module:
castsc
Destination:
Console
Parent topic: CASTS5000 - CASTS5019


CASTS5015I ES TSC Log and Intra-Partition TS/TD: queue-file-name

queue-file-name is the name of the TS/TD Queues file that will be used during this execution of ES.
Module:
castsc
Destination:
Console
Parent topic: CASTS5000 - CASTS5019


CASTS5016I ES TSC Log and Intra-Partition TS/TD File size: queue-block-count blocks (queue-file-size bytes)

The allocated block count for the TS/TD 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:
castsc
Destination:
Console
Parent topic: CASTS5000 - CASTS5019


CASTS5017I ES TSC Log and Intra-Partition TS/TD running with log-buffer-count buffers of buffer-size bytes each

log-buffer-count buffers are allocated for the TS/TD queues' use during this execution of ES.

Each buffer is buffer-size bytes in length.

Module:
castsc
Destination:
Console
Parent topic: CASTS5000 - CASTS5019


CASTS5020 - CASTS5039

  • CASTS5020S ES TSC Log and Intra-Partition TS/TD version mismatch. Disk version is version
    The ES TSC log and TS/TD disk file is written in a format that is not supported by this version of ES TSC.
  • CASTS5021S ES TSC Log and Intra-Partition TS/TD upgrade or cold start is required. ES TSC version: version
    The ES TSC Log and TS/TD file is written in a format that is not supported by this version of ES.
  • CASTS5033S ES TSC Log and Intra-Partition TS/TD corruption detected: block queue-file-block
    The ES TS/TD repository is corrupted.
  • CASTS5034S ES TSC Log and Intra-Partition TS/TD segment error: block queue-file-block; segment segment-number
    The ES TSC Log and TS/TD repository disk storage is corrupted.
  • CASTS5036S ES TSC Log and Intra-Partition TS/TD structure problem encountered. Disk version appears to be version number.
    The log and TS/TD disk file format is not recognized or not supported by this version of ES TSC.
  • CASTS5037I ES TSC old log and TS/TD file: Log and TS/TD repository name
    Log and TS/TD repository name is the name of the old ES Log and TS/TD repository that was saved as a part of cold starting the repository.
  • CASTS5038I Cannot open HSF file because the file is locked. File: Filename
    Filename cannot be opened because the file is locked.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5020S ES TSC Log and Intra-Partition TS/TD version mismatch. Disk version is version

The ES TSC log and TS/TD disk file is written in a format that is not supported by this version of ES TSC.

The version on disk appears to be version.

System Action:
ES TSC log support is disabled.
Resolution:
Upgrade the Log and TS/TD file if a utility is available or cold start ES.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5021S ES TSC Log and Intra-Partition TS/TD upgrade or cold start is required. ES TSC version: version

The ES TSC Log and TS/TD file is written in a format that is not supported by this version of ES.

The current ES TSC software version is version.

System Action:
The ES TSC Log and TS/TD repository is cold started. A .bak copy of the problem repository is retained in the defined location.
Resolution:
Upgrade the repository if a utility is available or continue with the current cold start.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5033S ES TSC Log and Intra-Partition TS/TD corruption detected: block queue-file-block

The ES TS/TD repository is corrupted.
System Action:
System attempts to correct error.
Resolution:
Assess system damage, stop and repair system if necessary.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5034S ES TSC Log and Intra-Partition TS/TD segment error: block queue-file-block; segment segment-number

The ES TSC Log and TS/TD repository disk storage is corrupted.
System Action:
System attempts to correct error.
Resolution:
Assess system damage, stop and repair system if necessary.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5036S ES TSC Log and Intra-Partition TS/TD structure problem encountered. Disk version appears to be version number.

The log and TS/TD disk file format is not recognized or not supported by this version of ES TSC.

The version on disk appears to be version number.

System Action:
ES TSC log and TS/TD support is cold started.
Resolution:
Recover log and TS/TD file if possible or continue the cold start.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5037I ES TSC old log and TS/TD file: Log and TS/TD repository name

Log and TS/TD repository name is the name of the old ES Log and TS/TD repository that was saved as a part of cold starting the repository.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5038I Cannot open HSF file because the file is locked. File: Filename

Filename cannot be opened because the file is locked.
Resolution:
Close any programs that have a lock on Filename.
Module:
castsc
Destination:
Console
Parent topic: CASTS5020 - CASTS5039


CASTS5040 - CASTS5059

  • CASTS5040I ES TSC Log and Intra-Partition TS/TD flush operations disabled
    Flush operations for this file are bypassed.
  • CASTS5041I ES TSC Log and Intra-Partition TS/TD flush requests aggregate time is aggregation-minimum milliseconds
    A flush aggregation span of aggregation-minimum millisecond is now effective.
  • CASTS5042I ES TSC Log and Intra-Partition TS/TD flush requests aggregate disabled
    Flush aggregation has been dynamically disabled.
  • CASTS5043I ES TSC Log and Intra-Partition TS/TD flush requests enabled
    Flush operations for this file are now enabled.
  • CASTS5050W ES TSC Log and Intra-Partition TS/TD facility file is nearly full
    The file is approaching an out-of-space condition.
  • CASTS5051E ES TSC Log and Intra-Partition TS/TD facility file out of space
    The file has reached its space limitations.
  • CASTS5052I ES TSC service process (PID:process-id) recovery initiated
    The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
  • CASTS5056I ES TSC data store dataset upgrade in progress
    The data store dataset format has changed and this startup uses an old format data store.
  • CASTS5057I ES TSC Original data store saved as <data-store-name>
    <data-store-name> is the new name of the original TSC data store dataset retained prior to upgrade.
  • CASTS5058S ES TSC Save of original data store data prior to upgrade failed, RC <rename-return-code>
    The system attempt to rename the old message queue dataset failed.
  • CASTS5059I ES TSC data store dataset upgraded from version 1/02 to version 1/03
    The data store dataset upgrade has completed successfully.
Parent topic: CASTS - TSC Service Process Error Messages


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.

Module:
castsc
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5041I ES TSC Log and Intra-Partition TS/TD flush requests aggregate time is 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:
castsc
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5042I ES TSC Log and Intra-Partition TS/TD flush requests aggregate disabled

Flush aggregation has been dynamically disabled.
Module:
castsc
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5043I ES TSC Log and Intra-Partition TS/TD flush requests enabled

Flush operations for this file are now enabled.
Module:
castmc
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5050W ES TSC Log and Intra-Partition TS/TD facility file is nearly full

The file is approaching an out-of-space condition.
Resolution:
Contact Product Support.
Module:
castsc
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5051E ES TSC Log and Intra-Partition TS/TD facility file out of space

The file has reached its space limitations.
Resolution:
Contact Product Support.
Module:
castsc
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5052I ES TSC service process (PID:process-id) recovery initiated

The IMS TM control process has been restarted after a failure and the new process is recovering pending requests to the previous server process (PID:process-id).
Module:
castsc
Destination:
Console and standard error.
Parent topic: CASTS5040 - CASTS5059


CASTS5056I ES TSC data store dataset upgrade in progress

The data store dataset format has changed and this startup uses an old format data store.

The data will be copied to a new data store file and the old file will be saved.

System Action:
Upgrade the TSC data store.
Module:
casrdo05
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5057I ES TSC Original data store saved as <data-store-name>

<data-store-name> is the new name of the original TSC data store dataset retained prior to upgrade.
System Action:
The original data store has been saved.
Module:
casrdo05
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5058S ES TSC Save of original data store data prior to upgrade failed, RC <rename-return-code>

The system attempt to rename the old message queue dataset failed.

The original dataset is not upgraded.

Module:
casrdo05
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5059I ES TSC data store dataset upgraded from version 1/02 to version 1/03

The data store dataset upgrade has completed successfully.
System Action:
TSC data store dataset upgrade complete.
Module:
casrdo05
Destination:
Console
Parent topic: CASTS5040 - CASTS5059


CASTS5060 - CASTS5079

  • CASTS5060I ES TSC Log and Intra-Partition TS/TD data store is upgraded from versionprevious data-store-version to versioncurrent data-store-version
    A data store upgrade was automatically performed during a warm start.
  • CASTS5061I ES TSC Log data store is upgraded from versionprevious data-store-version to versioncurrent data-store-version
    A data store upgrade was automatically performed during a warm start.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5060I ES TSC Log and Intra-Partition TS/TD data store is upgraded from versionprevious data-store-version to versioncurrent data-store-version

A data store upgrade was automatically performed during a warm start.

The data store is now not compatible with the earlier version of this product that produced it.

System Action:
The data store is upgraded to match this version of product.
Module:
castsc
Destination:
Console
Parent topic: CASTS5060 - CASTS5079


CASTS5061I ES TSC Log data store is upgraded from versionprevious data-store-version to versioncurrent data-store-version

A data store upgrade was automatically performed during a warm start.

The data store is now not compatible with the earlier version of this product that produced it.

System Action:
The data store is upgraded to match this version of product.
Module:
castsc
Destination:
Console
Parent topic: CASTS5060 - CASTS5079


CASTS5100 - CASTS5119

  • CASTS5112S ES TSC Log facility initialization failed. Reason (reason-code)
    The ES TSC Control Process failed to initialize its log facility.
  • CASTS5113I ES TSC Log facility cold started
    The ES TSC Log facility has been cold started.
  • CASTS5114W ES TSC Log facility file not properly closed previously
    The ES TSC Log facility file was not properly closed the last time it was accessed.
  • CASTS5115I ES TSC Log facility file: file-name
    file-name is the name of the file that supports XA logging during this execution of ES.
  • CASTS5116I ES TSC Log facility file size: file-block-count blocks (file-size bytes)
    The allocated block count is file-block-count.
  • CASTS5117I ES TSC Log facility is running with log-buffer-count buffers of buffer-size bytes each
    log-buffer-count buffers are allocated for the log's use during this execution of ES.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5112S ES TSC Log facility initialization failed. Reason (reason-code)

The ES TSC Control Process failed to initialize its log facility.

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 mismatch
 A = Queue file record block number mismatchror

These codes may be followed by a ":" and RTS file IO error code.

System Action:
The ES TSC Control Process is terminated and ES termination is initiated.
Resolution:
Correct the ES TSC configuration and restart the Enterprise Server.
Module:
castsc
Destination:
Console
Parent topic: CASTS5100 - CASTS5119


CASTS5113I ES TSC Log facility cold started

The ES TSC Log facility has been cold started.

No old data has been retained.

Module:
castsc
Destination:
Console
Parent topic: CASTS5100 - CASTS5119


CASTS5114W ES TSC Log facility file not properly closed previously

The ES TSC Log facility file was not properly closed the last time it was accessed.
System Action:
ES will attempt to insure data integrity. Additional messages will report any problems with this process.
Module:
castsc
Destination:
Console
Parent topic: CASTS5100 - CASTS5119


CASTS5115I ES TSC Log facility file: file-name

file-name is the name of the file that supports XA logging during this execution of ES.
Module:
castsc
Destination:
Console
Parent topic: CASTS5100 - CASTS5119


CASTS5116I ES TSC Log facility file size: file-block-count blocks (file-size bytes)

The allocated block count is file-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 file-size bytes.

Module:
castsc
Destination:
Console
Parent topic: CASTS5100 - CASTS5119


CASTS5117I ES TSC Log facility is running with log-buffer-count buffers of buffer-size bytes each

log-buffer-count buffers are allocated for the log's use during this execution of ES.

Each buffer is buffer-size bytes in length.

Module:
castsc
Destination:
Console
Parent topic: CASTS5100 - CASTS5119


CASTS5120 - CASTS5139

  • CASTS5120S ES TSC Log facility version mismatch. Disk version is version
    The ES TSC log facility file is written in a format that is not supported by this version of ES TSC.
  • CASTS5121S ES TSC Log facility upgrade or cold start is required. ES TSC version: version
    The ES TSC Log file is written in a format that is not supported by this version of ES.
  • CASTS5133S ES TSC Log facility corruption detected: block data-file-block
    The ES TSC Log facility is corrupted.
  • CASTS5134S ES TSC Log facility segment error: block queue-file-block; segment segment-number
    The ES TSC Log facility disk storage is corrupted.
  • CASTS5136S ES TSC Log facility structure problem encountered. Disk version appears to be facility-file-version.
    The log facility file format is not recognized or not supported by this version of ES TSC.
  • CASTS5137I ES TSC old log facility file: facility-file-name
    facility-file-name is the name of the old ES TSC Log repository that was saved as a part of cold starting the repository.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5120S ES TSC Log facility version mismatch. Disk version is version

The ES TSC log facility file is written in a format that is not supported by this version of ES TSC.

The version on disk appears to be version.

System Action:
ES TSC log support is disabled.
Resolution:
Upgrade the Log if a utility is available or cold start ES.
Module:
castsc
Destination:
Console
Parent topic: CASTS5120 - CASTS5139


CASTS5121S ES TSC Log facility upgrade or cold start is required. ES TSC version: version

The ES TSC Log file is written in a format that is not supported by this version of ES.

The current ES TSC software version is version.

System Action:
The ES TSC Log repository is cold started. A .bak copy of the problem repository is retained in the defined location.
Resolution:
Upgrade the facility file if a utility is available or continue with the current cold start.
Module:
castsc
Destination:
Console
Parent topic: CASTS5120 - CASTS5139


CASTS5133S ES TSC Log facility corruption detected: block data-file-block

The ES TSC Log facility is corrupted.
System Action:
System attempts to correct error.
Resolution:
Assess system damage, stop and repair system if necessary.
Module:
castsc
Destination:
Console
Parent topic: CASTS5120 - CASTS5139


CASTS5134S ES TSC Log facility segment error: block queue-file-block; segment segment-number

The ES TSC Log facility disk storage is corrupted.
System Action:
System attempts to correct error.
Resolution:
Assess system damage, stop and repair system if necessary.
Module:
castsc
Destination:
Console
Parent topic: CASTS5120 - CASTS5139


CASTS5136S ES TSC Log facility structure problem encountered. Disk version appears to be facility-file-version.

The log facility file format is not recognized or not supported by this version of ES TSC.

The version on disk appears to be facility-file-version.

System Action:
ES TSC log support is cold started.
Resolution:
Recover log file if possible or continue the cold start.
Module:
castsc
Destination:
Console
Parent topic: CASTS5120 - CASTS5139


CASTS5137I ES TSC old log facility file: facility-file-name

facility-file-name is the name of the old ES TSC Log repository that was saved as a part of cold starting the repository.
Module:
castsc
Destination:
Console
Parent topic: CASTS5120 - CASTS5139


CASTS5140 - CASTS5159

  • CASTS5140I ES TSC Log facility flush operations disabled
    Flush operations for this file are bypassed.
  • CASTS5141I ES TSC Log facility flush requests aggregate time is aggregation-minimum milliseconds
    A flush aggregation span of aggregation-minimum millisecond is now effective.
  • CASTS5150W ES TSC Log facility file is nearly full
    The file is approaching an out-of-space condition.
  • CASTS5151E ES TSC Log facility file out of space
    The file has reached its space limitations.
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5140I ES TSC Log facility 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.

Module:
castsc
Destination:
Console
Parent topic: CASTS5140 - CASTS5159


CASTS5141I ES TSC Log facility flush requests aggregate time is 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:
castsc
Destination:
Console
Parent topic: CASTS5140 - CASTS5159


CASTS5150W ES TSC Log facility file is nearly full

The file is approaching an out-of-space condition.
Resolution:
Contact Product Support.
Module:
castsc
Destination:
Console
Parent topic: CASTS5140 - CASTS5159


CASTS5151E ES TSC Log facility file out of space

The file has reached its space limitations.
Resolution:
Contact Product Support.
Module:
castsc
Destination:
Console
Parent topic: CASTS5140 - CASTS5159


CASTS5600 - CASTS5619

  • CASTS5600I Temporary storage queue cleanup task started.
    CTSC has started because a TS queue with an expiry has been written (by matching a TSMODEL).
  • CASTS5601I Temporary storage queue cleanup task exited.
    CTSC has exited because there are no more temporary storage queues with an expiry.
  • CASTS5605I Scan of temporary storage queues completed. Number of temporary storage queues scanned. temporary storage queues were scanned and Number of temporary storage queues that were deleted due to expiry interval elapsing. was|were (depending on whether one or many queues deleted) deleted.
    casztscl has completed a scan of TS queues to remove those queues that are eligible for deletion.
  • CASTS5606W The TS queue clean up task found expired queue Name of expired queue that could not be deleted., but deletion failed with EIBRESP EIBRESP from DELETEQ TS command..
Parent topic: CASTS - TSC Service Process Error Messages


CASTS5600I Temporary storage queue cleanup task started.

CTSC has started because a TS queue with an expiry has been written (by matching a TSMODEL).
Module:
casztscl
Destination:
Console
Parent topic: CASTS5600 - CASTS5619


CASTS5601I Temporary storage queue cleanup task exited.

CTSC has exited because there are no more temporary storage queues with an expiry.
Module:
casztscl
Destination:
Console
Parent topic: CASTS5600 - CASTS5619


CASTS5605I Scan of temporary storage queues completed. Number of temporary storage queues scanned. temporary storage queues were scanned and Number of temporary storage queues that were deleted due to expiry interval elapsing. was|were (depending on whether one or many queues deleted) deleted.

casztscl has completed a scan of TS queues to remove those queues that are eligible for deletion.
Module:
casztscl
Destination:
Console when 1 or more queues deleted, CSSL when no queues deleted.
Parent topic: CASTS5600 - CASTS5619


CASTS5606W The TS queue clean up task found expired queue Name of expired queue that could not be deleted., but deletion failed with EIBRESP EIBRESP from DELETEQ TS command..

Module:
casztscl
Destination:
Console
Parent topic: CASTS5600 - CASTS5619


CASXB - CICS BMS Macro Processor Error Messages

  • CASXB0000 - CASXB0019
  • CASXB0020 - CASXB0039
  • CASXB0040 - CASXB0059
  • CASXB0060 - CASXB0079
Parent topic: Enterprise Server Error Messages


CASXB0000 - 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.
  • CASXB0003E Unrecognized verb "<verb>" - remainder of macro discarded
    An unknown verb was found in the BMS source deck.
  • 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.
  • CASXB0006E POS=<position> is outside defined map size
    The DFHMDF POS= value places the field outside of the defined map boundaries.
  • 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 Hexadecimal value in error 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.
  • 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 - CICS BMS Macro Processor 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - CASXB0019


CASXB0009W Hexadecimal value in error 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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: CASXB0000 - 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.
  • CASXB0024E Too many fields in group - group closed
    SDF-type group definitions are currently limited to 50 member fields for each group instance.
  • 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.
  • 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.
  • 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.
  • 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.
  • CASXB0033W Host compatibility: Blank card found
    A blank input card was found.
  • 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.
  • CASXB0035W Warning: MCO forces TIOAPFX=YES on MOD/CPY generation
    TIOAPFX=NO was either specified or implied for the current map.
  • CASXB0036S Error: Unable to open .trl file, status=<file-status>
    <file-status> was returned from the open request for the translator listing (.trl) file.
  • 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 - CICS BMS Macro Processor 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.
  • CASXB0041W No comma after last parm, continuation cards are comments
    This card is continued, but the last parameter was not followed by a comma.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
Parent topic: CASXB - CICS BMS Macro Processor 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 Micro Focus Customer 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 Micro Focus Customer 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 <product> 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 - CASXB0079

  • 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.
  • 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.
  • 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.
  • 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.
  • CASXB0066W Name "<label>" exceeds 30 characters - truncated
    Names (labels) for fields (and compound fields) cannot exceed 30 characters.
  • 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.
  • CASXB0072E PICOUT is illegal at character <pic-pos>
    The PICOUT value is not a valid output picture clause for the selected language.
  • CASXB0073E PICIN/PICOUT string cannot exceed 32 characters
    Picture strings greater than 32 token-characters cannot be properly edited.
  • 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 - CICS BMS Macro Processor 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 - CASXB0079


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


CASXO - CICS Transaction Manager Error Messages

  • CASXO0000 - CASXO0019
  • CASXO0020 - CASXO0039
  • CASXO0040 - CASXO0059
Parent topic: Enterprise Server Error Messages


CASXO0000 - CASXO0019

  • CASXO0001S XA Resource Manager initialization error. Resource XAT resource name open failed, reason return-code
    The Resource manager for the XAT resource returned a non-zero value to the xa_open call.
  • CASXO0002S Switch Load Module for resource XAT resource name failed to load
    The Switch Load Module for the XAT resource failed to load.
  • CASXO0003S Resource Manager for resource XAT resource name Transaction start failed: reason return-code
    The Resource manager for the XAT resource returned a non-zero value to the xa_start call.
  • CASXO0004S Resource Manager for resource XAT resource name Transaction end failed: reason return-code, XID: XID
    The Resource manager for the XAT resource returned a non-zero value to the xa_end call.
  • CASXO0005S Resource Manager for resource XAT resource name Prepare failed: reason return-code, XID: XID
    The Resource manager for the XAT resource returned a non-zero value to the xa_prepare call.
  • CASXO0006S Resource Manager for resource XAT resource name May have heuristically completed due to a failure
    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 Resource Manager for resource XAT resource name Has heuristically committed the transaction
    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 Resource Manager for resource XAT resource name Has heuristically rolled back the transaction
    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 Resource Manager for resource XAT resource name Has heuristically partially committed and partially rolled back the transaction
    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 Resource Manager for resource XAT resource name Commit failed: reason return-code XID: XID
    The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.
  • CASXO0011S Resource Manager for resource XAT resource name Rollback failed: reason return-code, XID: XID
    The Resource manager for the XAT resource returned a non-zero value to the xa_rollback call.
  • CASXO0012S Resource Manager for resource XAT resource name Close failed: reason return-code
    The Resource manager for the XAT resource returned a non-zero value to the xa_close call.
  • CASXO0013S Resource Manager for resource XAT resource name Rolled back transaction: reason return-code
    The Resource manager for the XAT resource indicated it had rolled back the transaction.
  • CASXO0014S Resource Manager for resource XAT resource name Forget failed: reason return-code
    The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.
  • CASXO0015I XAT resource name XA interface initialized successfully
    The XA resource manager's switch module was loaded successfully and the xa-open processing called.
  • CASXO0016S XAT resource name XA interface initialization failure
    The XA resource manager's switch module had been previously loaded successfully by another server but failed to initialize on this process.
  • CASXO0017S Unrecoverable error in XAT resource name XA interface, RM interface disabled
    An unrecoverable error occurred interfacing with the XA Resource Manager.
  • CASXO0018S Resource Manager for resource XAT resource name Transaction end failed: reason return-code, XID: XID
    The Resource manager for the XAT resource returned a non-zero value to the xa_end call.
  • CASXO0019S Switch Load Module for resource XAT resource name failed to load RM XA resources, returned pointer was null
    The Switch Load Module for the XAT resource failed to load the necessary DLLs or .so programs.
Parent topic: CASXO - CICS Transaction Manager Error Messages


CASXO0001S XA Resource Manager initialization error. Resource XAT resource name open failed, reason return-code

The Resource manager for the XAT resource returned a non-zero value to the xa_open call.

Where the return code means :

       -1  An error occurred 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 XA resource entry has been disabled.
Resolution:
Check that the Database Manager has been started, if necessary.
Module:
dfhexa
Destination:
Console and standard error.
Parent topic: CASXO0000 - CASXO0019


CASXO0002S Switch Load Module for resource XAT resource name failed to load

The Switch Load Module for the XAT resource failed to load.
System Action:
he XA resource entry has been disabled.
Resolution:
Check that the Switch Load Module is on the libpath or in $TXDIR\lib.
Module:
dfhexa
Destination:
Console and standard error.
Parent topic: CASXO0000 - CASXO0019


CASXO0003S Resource Manager for resource XAT resource name Transaction start failed: reason return-code

The Resource manager for the XAT resource returned a non-zero value to the xa_start call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0004S Resource Manager for resource XAT resource name Transaction end failed: reason return-code, XID: XID

The Resource manager for the XAT resource returned a non-zero value to the xa_end call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0005S Resource Manager for resource XAT resource name Prepare failed: reason return-code, XID: XID

The Resource manager for the XAT resource returned a non-zero value to the xa_prepare call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0006S Resource Manager for resource XAT resource name May have heuristically completed due to a failure

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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0007S Resource Manager for resource XAT resource name Has heuristically committed the transaction

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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0008S Resource Manager for resource XAT resource name Has heuristically rolled back the transaction

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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0009S Resource Manager for resource XAT resource name Has heuristically partially committed and partially rolled back the transaction

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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0010S Resource Manager for resource XAT resource name Commit failed: reason return-code XID: XID

The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0011S Resource Manager for resource XAT resource name Rollback failed: reason return-code, XID: XID

The Resource manager for the XAT resource returned a non-zero value to the xa_rollback call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0012S Resource Manager for resource XAT resource name Close failed: reason return-code

The Resource manager for the XAT resource returned a non-zero value to the xa_close call.

Where the return code means :

       -2  Asynchronous operation already outstanding
       -3  A resource manager error occurred
       -5  Invalid arguments were given
       -6  Routine invoked in an improper context
Resolution:
Contact your system administrator for the resource.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0013S Resource Manager for resource XAT resource name Rolled back transaction: reason return-code

The Resource manager for the XAT resource indicated it had rolled back the transaction.

Where the return code means :

      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
Resolution:
Contact your system administrator for the resource.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0014S Resource Manager for resource XAT resource name Forget failed: reason return-code

The Resource manager for the XAT resource returned a non-zero value to the xa_commit call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0015I XAT resource name XA interface initialized successfully

The XA resource manager's switch module was loaded successfully and the xa-open processing called.
System Action:
None.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0000 - CASXO0019


CASXO0016S XAT resource name XA interface initialization failure

The XA resource manager's switch module had been previously loaded successfully by another server but failed to initialize on this process.
System Action:
None.
Resolution:
Determine the cause of the failure and restart the system.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0000 - CASXO0019


CASXO0017S Unrecoverable error in XAT resource name XA interface, RM interface disabled

An unrecoverable error occurred interfacing with the XA Resource 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.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0000 - CASXO0019


CASXO0018S Resource Manager for resource XAT resource name Transaction end failed: reason return-code, XID: XID

The Resource manager for the XAT resource returned a non-zero value to the xa_end call.

Where the return code means :

       -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.
Module:
dfhexa
Destination:
Terminal.
Parent topic: CASXO0000 - CASXO0019


CASXO0019S Switch Load Module for resource XAT resource name failed to load RM XA resources, returned pointer was null

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 $TXDIR\lib.
Module:
dfhexa
Destination:
Console and standard error.
Parent topic: CASXO0000 - CASXO0019


CASXO0020 - CASXO0039

  • CASXO0020I XA resource name XA interface loaded. Name(XA name), Registration Mode(XA registration mode)
    The XA resource manager's switch module was loaded successfully.
  • CASXO0021I XA resource name XA interface local transaction support enabled
    The XA resource manager's switch module contained appropriate support for local transactions.
  • CASXO0022W XA resource name XA interface local transaction support disabled
    The XA resource manager's switch module did not contain support for local transaction commit/rollback functions.
  • CASXO0023S Severe error detected in XAT resource name XA interface, RM interface disabled
    A severe error occurred interfacing with the XA Resource Manager.
  • CASXO0024I XA Switch XAT resource name, RM interface disabled on demand
    A user disabled the XA Resource Manager.
  • CASXO0025I XA Switch XAT resource name, RM interface enabled on demand
    A user enabled the XA Resource Manager.
  • CASXO0026I XA Switch XAT resource name, is installed to support one phase commit only
    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 XA log reported in-doubt transaction XID transaction number branch XID transaction branch number
    Enterprise Server recovery has rolled back in-doubt transaction XID transaction number branch XID transaction branch number.
  • CASXO0030S XA Automated recovery disabled for XA Switch Resource manager ID. The xa_recovery call returned rc XA return code.
    This XA switch module does not support xa_recovery calls.
  • CASXO0031S ES lost connection to the RM XA RM Name, attempting to reconnect.
    ES lost connection to an RM and attempts reconnection.
  • CASXO0032I ES has regained connection to XA RM Name.
    An RM has been reconnected to the region.
  • CASXO0033W XA Switch Resource Manager ID does not contain an xa_ping entry point, monitoring disabled
    xa_ping not found in specified switch module, monitoring is disabled for this RM.
  • CASXO0034I XA Switch Resource Manager ID excluded from xa reconnect processing on request.
    ES_XA_%RMNAME%_OPTIONS is set to EX.
  • CASXO0035I Request to add XA resource XA RM Name received.
    A request to add a new XA resource has been received.
  • CASXO0036I Request to update XA resource XA RM Name received.
    A request to update an existing XA resource has been received.
  • CASXO0037I Request to delete XA resource XA RM Name received.
    A request to delete an existing XA resource has been received.
  • CASXO0038I XA resource XA RM Name has now been enabled|disabled|added|deleted.
    A request that was received to enable|disable|add|delete an XA resource has now been executed.
  • CASXO0039E Request to enable|disable|add|delete XA resource XA RM Name failed RC: return code.
    A request that was received to enable|disable|add|delete an XA resource has failed.
Parent topic: CASXO - CICS Transaction Manager Error Messages


CASXO0020I XA resource name XA interface loaded. Name(XA name), Registration Mode(XA registration mode)

The XA resource manager's switch module was loaded successfully.
System Action:
None.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0021I XA resource name XA interface local transaction support enabled

The XA resource manager's switch module contained appropriate support for local transactions.
System Action:
None.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0022W XA resource name XA interface local transaction support disabled

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.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0023S Severe error detected in XAT resource name XA interface, RM interface disabled

A severe error occurred interfacing with the XA Resource 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.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0024I XA Switch XAT resource name, RM interface disabled on demand

A user disabled the XA Resource Manager.
System Action:
The XA Resource Manager will not be called for future transactions.
Resolution:
None.
Module:
casrdo81
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0025I XA Switch XAT resource name, RM interface enabled on demand

A user enabled the XA Resource Manager.
System Action:
The XA Resource Manager will be called for future transactions.
Resolution:
None.
Module:
casrdo81
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0026I XA Switch XAT resource name, is installed to support one phase commit only

A user requested support for one phase commit only.
System Action:
The XA Resource Manager will be called for future transactions.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


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: CASXO0020 - CASXO0039


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: CASXO0020 - CASXO0039


CASXO0029I XA log reported in-doubt transaction XID transaction number branch XID transaction branch number

Enterprise Server recovery 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.
Resolution:
None.
Module:
castsc
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0030S XA Automated recovery disabled for XA Switch Resource manager ID. The xa_recovery call returned rc XA return code.

This XA switch module does not support xa_recovery calls.
System Action:
The xa recovery system will not invoke this switch for indoubt transactions resolution.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0031S ES lost connection to the RM XA RM Name, attempting to reconnect.

ES lost connection to an RM and attempts reconnection.
System Action:
Verify why the RM disconnected.
Resolution:
None.
Module:
dfheserv
Destination:
Console and standard error.
Parent topic: CASXO0020 - CASXO0039


CASXO0032I ES has regained connection to XA RM Name.

An RM has been reconnected to the region.
System Action:
None.
Resolution:
None.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0033W XA Switch Resource Manager ID does not contain an xa_ping entry point, monitoring disabled

xa_ping not found in specified switch module, monitoring is disabled for this RM.
System Action:
None.
Resolution:
None.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0034I XA Switch Resource Manager ID excluded from xa reconnect processing on request.

ES_XA_%RMNAME%_OPTIONS is set to EX.
System Action:
None.
Resolution:
None.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0035I Request to add XA resource XA RM Name received.

A request to add a new XA resource has been received.
System Action:
The XA resource will be added to the system at the start of the next UOW.
Resolution:
None.
Module:
casasys
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0036I Request to update XA resource XA RM Name received.

A request to update an existing XA resource has been received.
System Action:
The XA resource will be updated at the start of the next UOW.
Resolution:
None.
Module:
casasys
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0037I Request to delete XA resource XA RM Name received.

A request to delete an existing XA resource has been received.
System Action:
The XA resource will be deleted from the system at the start of the next UOW.
Resolution:
None.
Module:
casasys
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0038I XA resource XA RM Name has now been enabled|disabled|added|deleted.

A request that was received to enable|disable|add|delete an XA resource has now been executed.
System Action:
None.
Resolution:
None.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0039E Request to enable|disable|add|delete XA resource XA RM Name failed RC: return code.

A request that was received to enable|disable|add|delete an XA resource has failed.
System Action:
None.
Resolution:
Contact Micro Focus Customer Support.
Module:
casasys
Destination:
Console.
Parent topic: CASXO0020 - CASXO0039


CASXO0040 - CASXO0059

  • CASXO0040W XA recovery detected unlogged in-doubt transaction XID: XID on RM: Resource manager
    Enterprise Server recovery has detected an in-doubt transaction XID: for resource manager Resource manager.
  • CASXO0048W MQSeries entry XAT resource name, using MQseries Server install is not supported for xa reconnect.
    MQSeries Server installation does not allow for xa reconnect.
  • CASXO0049S Severe xa error on entry XAT resource name, Oracle does not always recover, SEP about to be recycled.
    A severe error occurred processing an Oracle installation.
  • CASXO0050S XA reconnection to XAT resource name failed after multiple attempts, RM disabled. Use Dynamic XA to reenable
    The XA reconnection failed.
  • CASXO0051I XA reconnect processing active.
    -.
  • CASXO0052S ES has lost connection to the RM XA RM Name no retry requested. RM not disabled.
    An RM has lost connection, xa reconnect does not retry.
  • CASXO0053W Severe error detected in XAT resource name XA interface, switched to MIQM XAT resource name
    A severe error occurred interfacing with the XA Resource Manager.
  • CASXO0054W XA recovery error RC=4 on commit in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID
    Enterprise Server recovery will retry to commit in-doubt transaction XA Resource manager branch XA Return code for resource manager XID.
  • CASXO0055S XA MAX recovery attempts, manually commit in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID
    in-doubt transaction must now be manually committed XA Resource manager branch XA Return code for resource manager XID.
  • CASXO0056W XA recovery error RC=4 on rollback in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID
    Enterprise Server recovery will retry to rollback in-doubt transaction XA Resource manager branch XA Return code for resource manager XID.
  • CASXO0057S XA MAX recovery attempts, manually rollback in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID
    in-doubt transaction must now be manually rolled back XA Resource manager branch XA Return code for resource manager XID.
Parent topic: CASXO - CICS Transaction Manager Error Messages


CASXO0040W XA recovery detected unlogged in-doubt transaction XID: XID on RM: Resource manager

Enterprise Server recovery has detected an in-doubt transaction XID: for resource manager Resource manager.
System Action:
No action has been taken. The transaction remains in doubt.
Resolution:
Take appropriate remedial action.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0048W MQSeries entry XAT resource name, using MQseries Server install is not supported for xa reconnect.

MQSeries Server installation does not allow for xa reconnect.
System Action:
The xa reconnect feature does not support MQ Server installation.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0049S Severe xa error on entry XAT resource name, Oracle does not always recover, SEP about to be recycled.

A severe error occurred processing an Oracle installation.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0050S XA reconnection to XAT resource name failed after multiple attempts, RM disabled. Use Dynamic XA to reenable

The XA reconnection failed.
System Action:
Fix RM error and reenable the named xa resource using dynamic XA.
Resolution:
None.
Module:
dfheserv
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0051I XA reconnect processing active.

-.
Resolution:
None.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0052S ES has lost connection to the RM XA RM Name no retry requested. RM not disabled.

An RM has lost connection, xa reconnect does not retry.
System Action:
Verify why the RM disconnected.
Resolution:
None.
Module:
dfheserv
Destination:
Console and standard error.
Parent topic: CASXO0040 - CASXO0059


CASXO0053W Severe error detected in XAT resource name XA interface, switched to MIQM XAT resource name

A severe error occurred interfacing with the XA Resource Manager.
System Action:
As MIQM is enabled, ES will try to connect to the stand by server.
Resolution:
Determine the cause of the failure and re-enable it.
Module:
dfhexa
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0054W XA recovery error RC=4 on commit in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID

Enterprise Server recovery will retry to commit in-doubt transaction XA Resource manager branch XA Return code for resource manager XID.
System Action:
The transaction has not yet been committed on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0055S XA MAX recovery attempts, manually commit in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID

in-doubt transaction must now be manually committed XA Resource manager branch XA Return code for resource manager XID.
System Action:
The transaction has not been committed on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0056W XA recovery error RC=4 on rollback in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID

Enterprise Server recovery will retry to rollback in-doubt transaction XA Resource manager branch XA Return code for resource manager XID.
System Action:
The transaction has not yet been rolled back on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


CASXO0057S XA MAX recovery attempts, manually rollback in-doubt transaction RM: XA Resource manager RC: XA Return code XID: XID

in-doubt transaction must now be manually rolled back XA Resource manager branch XA Return code for resource manager XID.
System Action:
The transaction has not been rolled back on this resource manager.
Resolution:
None.
Module:
dfhexarc
Destination:
Console.
Parent topic: CASXO0040 - CASXO0059


COBEC - CICS API Preprocessor Error Messages

  • COBEC0000 - COBEC0019
  • COBEC0020 - COBEC0039
  • COBEC0040 - COBEC0059
  • COBEC1100 - COBEC1119
  • COBEC1120 - COBEC1139
  • COBEC1200 - COBEC1219
  • COBEC1220 - COBEC1239
  • COBEC1240 - COBEC1259
  • COBEC1300 - COBEC1319
  • COBEC1320 - COBEC1339
  • COBEC1340 - COBEC1359
  • COBEC1400 - COBEC1419
  • COBEC1500 - COBEC1519
  • COBEC6000 - COBEC6019
  • COBEC6020 - COBEC6039
  • COBEC9000 - COBEC9019
  • COBEC9020 - COBEC9039
Parent topic: Enterprise Server Error Messages


COBEC0000 - COBEC0019

  • COBEC0000I Micro Focus CICS Option <language> Preprocessor (CICS) - Version <version>
    Standard preprocessor identification.
  • COBEC0001S COPY Book File not found
    The preprocessor could not find the source file for the preceding COPY statement.
  • COBEC0002S COPY Book File OPEN failed
    The preprocessor could not open the file specified in the COPY statement.
  • COBEC0003I COPY name field is not Mainframe format
    The source code will compile correctly on the PC, but not on a mainframe.
  • COBEC0004S COPY name field is missing - syntax error
    No file name was found following the COPY verb.
  • COBEC0005S Invalid syntax for DFHRESP(condition)
    The DFHRESP string was not followed by a parenthesized name identifying the condition whose EIBRESP value should replace the DFHRESP construct.
  • COBEC0006E <x> is not a valid condition for DFHRESP
    The condition name specified in parentheses after DFHRESP is not a valid CICS condition name.
  • COBEC0007F Missing PROCEDURE DIVISION
    The preprocessor did not find a PROCEDURE DIVISION statement before end-of-file.
  • COBEC0008F Preprocessor Logic Error
    An internal processing error has occurred.
  • COBEC0009S Missing END-EXEC
    A period or COBOL verb was encountered in an EXEC statement instead of (or before) the END-EXEC to terminate the EXEC statement.
  • COBEC0010S Missing EXEC Type
    The EXEC was immediately terminated by an END-EXEC.
  • COBEC0011S <x> is not a valid EXEC Type
    The word <x> which immediately followed the EXEC word is not recognized as a valid EXEC type.
  • COBEC0012S EXEC <x> Preprocessor is not active
    Your source code contains EXEC DLI or EXEC SQL statements, but the appropriate preprocessor is not begin used according to the options specified to the TX preprocessor.
  • COBEC0013S Unmatched parentheses for EXEC CICS Argument
    An opening "(" or closing ")" parentheses occurred in an EXEC CICS statement without its partner.
  • COBEC0014S Too many Options in EXEC CICS statement
    The EXEC CICS statement has more than 100 options specified between the 'command' and the END-EXEC.
  • COBEC0015S EXEC CICS Option Argument exceeds 1024 char
    The source text for a single options argument exceeded 1024 characters (all blanks compressed to minimum required) without encountering the close parenthesis, ")", marking the end of the option value (argument).
  • COBEC0016W <cmd> command not supported or validated
    The CICS command <cmd> is recognized by the preprocessor as a valid command, but its syntax is not validated and it is not supported in the emulation.
  • COBEC0017W <cmd> command validated, but not supported
    The syntax of the CICS command <cmd> is validated by the preprocessor, but is not supported in the emulation.
  • COBEC0018E <cmd> is not a valid EXEC CICS command
    The command <cmd> is not recognized as a valid EXEC CICS command by the preprocessor.
  • COBEC0019I <opt> option is ignored for <cmd>
    The option <opt> is ignored on the EXEC CICS <cmd> command.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC0000I Micro Focus CICS Option <language> Preprocessor (CICS) - Version <version>

Standard preprocessor identification.
System Action:
Displayed at start of Preprocessor Execution.
Module:
cicsprep (dfhxinit)
Destination:
STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0001S COPY Book File not found

The preprocessor could not find the source file for the preceding COPY statement.
System Action:
COPY statement is ignored.
Resolution:
Verify that the COBCPY environment variable is set to the correct search paths for the application. Verify that the name in COPY statement exists as a file with no extension or with .CPY, .cpy, .CBL, or .cbl as the extension. The search is case-sensitive.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0002S COPY Book File OPEN failed

The preprocessor could not open the file specified in the COPY statement.
System Action:
COPY statement is ignored.
Resolution:
Check permissions for the file. Also verify that no other user has locked the file.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0003I COPY name field is not Mainframe format

The source code will compile correctly on the PC, but not on a mainframe.

This error is caused by using a path or extension with the COPY-file filename.

System Action:
COPY statement is processed as written.
Resolution:
If the application is to be portable to the mainframe, the name specified in the COPY statement should be written without any drive, path, or extension.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0004S COPY name field is missing - syntax error

No file name was found following the COPY verb.
System Action:
COPY statement is ignored.
Resolution:
Correct the COPY statement to include the name before the terminating period - i.e. conform to COBOL COPY syntax.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0005S Invalid syntax for DFHRESP(condition)

The DFHRESP string was not followed by a parenthesized name identifying the condition whose EIBRESP value should replace the DFHRESP construct.
System Action:
The DFHRESP is passed to the checker unchanged. This will, most likely, result in a Checker error message.
Resolution:
Correct the source.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0006E <x> is not a valid condition for DFHRESP

The condition name specified in parentheses after DFHRESP is not a valid CICS condition name.
System Action:
The preprocessor will generate a value of 9999 for the DFHRESP.
Resolution:
Specify a valid CICS condition name in the parentheses following DFHRESP.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0007F Missing PROCEDURE DIVISION

The preprocessor did not find a PROCEDURE DIVISION statement before end-of-file.
System Action:
The preprocess/check is aborted.
Resolution:
Correct the source.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0008F Preprocessor Logic Error

An internal processing error has occurred.
System Action:
The preprocess/check is aborted.
Resolution:
Contact Micro Focus support. Source will be needed to reconstruct the problem.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0009S Missing END-EXEC

A period or COBOL verb was encountered in an EXEC statement instead of (or before) the END-EXEC to terminate the EXEC statement.
System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the COBOL verb or the word following the period.
Resolution:
Correct the EXEC statement so that it conforms to the defined syntax for EXEC statements.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0010S Missing EXEC Type

The EXEC was immediately terminated by an END-EXEC.
System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the EXEC statement so that it conforms to the defined syntax for EXEC statements.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0011S <x> is not a valid EXEC Type

The word <x> which immediately followed the EXEC word is not recognized as a valid EXEC type.

The preprocessor will recognize CICS, DLI, and SQL as valid types.

System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the source. If this EXEC type should be handled by another preprocessor, make that preprocessor run before (closer to the source) than the TX preprocessor.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0012S EXEC <x> Preprocessor is not active

Your source code contains EXEC DLI or EXEC SQL statements, but the appropriate preprocessor is not begin used according to the options specified to the TX preprocessor.

See the chapter on Working with Databases.

System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Either omit the EXEC statement from the source or use the appropriate preprocessor with the TX preprocessor and indicate its use in the options.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0013S Unmatched parentheses for EXEC CICS Argument

An opening "(" or closing ")" parentheses occurred in an EXEC CICS statement without its partner.

Normally this is only detected when the END-EXEC is encountered.

System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the EXEC statement ensuring that all parentheses around option values have their corresponding partner and that any parentheses for subscripts, etc. are properly paired.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0014S Too many Options in EXEC CICS statement

The EXEC CICS statement has more than 100 options specified between the 'command' and the END-EXEC.

Note that this is about 16 larger than the largest number of distinct options possible in any valid EXEC CICS statement.

System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the EXEC CICS statement.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0015S EXEC CICS Option Argument exceeds 1024 char

The source text for a single options argument exceeded 1024 characters (all blanks compressed to minimum required) without encountering the close parenthesis, ")", marking the end of the option value (argument).
System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the statement; this may require redoing some table references by moving subscripted subscripts to a work area before using them in the EXEC CICS statement.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0016W <cmd> command not supported or validated

The CICS command <cmd> is recognized by the preprocessor as a valid command, but its syntax is not validated and it is not supported in the emulation.
System Action:
The preprocessor will generate either an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported commands when compiling this transaction. The EXEC CICS statement can remain in the source for compatibility with other environments; the module will be executable.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0017W <cmd> command validated, but not supported

The syntax of the CICS command <cmd> is validated by the preprocessor, but is not supported in the emulation.
System Action:
The preprocessor will generate either an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported commands when compiling this transaction. The EXEC CICS statement can remain in the source for compatibility with other environments; the module will be executable.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0018E <cmd> is not a valid EXEC CICS command

The command <cmd> is not recognized as a valid EXEC CICS command by the preprocessor.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to specify a valid command.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0019I <opt> option is ignored for <cmd>

The option <opt> is ignored on the EXEC CICS <cmd> command.

This normally applies to options which have no effect on the API behavior, but are specified for efficiency considerations in the mainframe implementation of the CICS API.

System Action:
The option <opt> is treated as comments.
Resolution:
None.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0000 - COBEC0019


COBEC0020 - COBEC0039

  • COBEC0020W <opt> option not supported for <cmd>
    The option <opt> is not supported for the EXEC CICS <cmd> command in the emulation.
  • COBEC0021E <opt> is not a valid option for <cmd>
    The option <opt> is not valid on the EXEC CICS <cmd> command.
  • COBEC0022E <opt-1> option conflicts with <opt-2> option
    The options <opt-1> and <opt-2> are mutually exclusive in the context of the current EXEC CICS command.
  • COBEC0023W Duplicate <opt> option
    The option <opt> is specified more than once on the current EXEC CICS statement.
  • COBEC0024E Required <opt> option missing from <cmd>
    The <opt> option is required on an EXEC CICS <cmd> command and has been omitted.
  • COBEC0025E <opt> option requires an argument
    The <opt> option is expected to have an argument in parentheses following the option.
  • COBEC0026E <opt> argument must be (data-area)
    The argument for the <opt> option must be a data-area; a literal or equivalent construct was found instead of a data-name.
  • COBEC0027W <opt> option should not have an argument
    An argument was specified for the <opt> option which should not have an argument.
  • COBEC0028E <opt> argument must be alphanumeric value/area
    The argument for the <opt> option must be either a data-area or an alphanumeric literal.
  • COBEC0029E <opt> argument must be numeric value/area
    The argument for the <opt> option must be either a numeric literal or a data-area.
  • COBEC0030E <opt> argument must be (ptr-ref) or ADDRESS OF ...
    The argument for the <opt> option must be an address.
  • COBEC0031W <opt> specifies length for an option not present
    The option <opt> is a length specification that gives the size of area for some other option which has been omitted.
  • COBEC0032E <opt> required in OSVS for Length specification
    The <opt> option is required in OSVS COBOL programs to provide a length specification.
  • COBEC0033E <opt-1> invalid without <opt-2>
    The <opt-1> option is valid only if the <opt-2> option is also specified for this EXEC CICS command.
  • COBEC0034E <opt-1> required with <opt-2>
    The <opt-1> option is required if the <opt-2> option has been specified for this EXEC CICS command.
  • COBEC0035I <cmd> command is a NO-OP if no options specified
    No options for the <cmd> command are required, however, if none are specified the command acts like a null operation.
  • COBEC0036W <opt> duplicate specification overrides previous
    The same option, <opt>, has been specified more than once in the same EXEC CICS statement and its later specification(s) will effectively override prior ones.
  • COBEC0037E <opt> argument must be a procedure label name
    The argument to the <opt> option must be a paragraph (or section) name in the procedure division.
  • COBEC0038E MAP(literal) or FROM or MAPONLY is required
    On a SEND MAP command, a data area is required for the user data to be mapped when MAPONLY is not specified.
  • COBEC0039S Invalid syntax for DFHVALUE(condition)
    The DFHVALUE string was not followed by a parenthesized name identifying the CVDA whose value should replace the DFHVALUE construct.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC0020W <opt> option not supported for <cmd>

The option <opt> is not supported for the EXEC CICS <cmd> command in the emulation.
System Action:
The preprocessor will either treat the option as a comment or it will generate an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported options when compiling this transaction. The option can remain in the EXEC CICS statement for compatibility with other environments; the module will be executable.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0021E <opt> is not a valid option for <cmd>

The option <opt> is not valid on the EXEC CICS <cmd> command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the option <opt> on the EXEC CICS statement.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0022E <opt-1> option conflicts with <opt-2> option

The options <opt-1> and <opt-2> are mutually exclusive in the context of the current EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement so that only one of the mutually exclusive options is specified.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0023W Duplicate <opt> option

The option <opt> is specified more than once on the current EXEC CICS statement.
System Action:
The second and subsequent specifications are ignored and a WARNING message is issued.
Resolution:
Correct the EXEC CICS statement so that the option only appears once.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0024E Required <opt> option missing from <cmd>

The <opt> option is required on an EXEC CICS <cmd> command and has been omitted.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to include all required options for the command.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0025E <opt> option requires an argument

The <opt> option is expected to have an argument in parentheses following the option.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by specifying the appropriate argument value or data-area following the <opt> option.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0026E <opt> argument must be (data-area)

The argument for the <opt> option must be a data-area; a literal or equivalent construct was found instead of a data-name.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify the name of a data-area.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0027W <opt> option should not have an argument

An argument was specified for the <opt> option which should not have an argument.
System Action:
The argument for the <opt> option is ignored by the preprocessor.
Resolution:
Correct the EXEC CICS statement to remove the argument from the <opt> option. N.B., this may indicate that the option that the argument should have belonged to has been omitted.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0028E <opt> argument must be alphanumeric value/area

The argument for the <opt> option must be either a data-area or an alphanumeric literal.

A numeric literal or equivalent construct was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify an alphanumeric literal or the name of a data-area.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0029E <opt> argument must be numeric value/area

The argument for the <opt> option must be either a numeric literal or a data-area.

An alphanumeric literal was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify a numeric literal or the name of a data-area.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0030E <opt> argument must be (ptr-ref) or ADDRESS OF ...

The argument for the <opt> option must be an address.

I.e., either the data-name of a pointer item or an ADDRESS OF data-name construct.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify an address as the name of a data-area or using an ADDRESS OF data-name construct.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0031W <opt> specifies length for an option not present

The option <opt> is a length specification that gives the size of area for some other option which has been omitted.
System Action:
The <opt> option is treated as comments and a WARNING message issued.
Resolution:
Correct the EXEC CICS statement by either removing the option or by specifying the option for which it is providing a length specification.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0032E <opt> required in OSVS for Length specification

The <opt> option is required in OSVS COBOL programs to provide a length specification.

Note that it is optional in VS COBOL II programs since it can be defaulted to the LENGTH OF construct.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by adding the required option and specifying an appropriate argument for the length.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0033E <opt-1> invalid without <opt-2>

The <opt-1> option is valid only if the <opt-2> option is also specified for this EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing the <opt-1> option or by specifying the <opt-2> option.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0034E <opt-1> required with <opt-2>

The <opt-1> option is required if the <opt-2> option has been specified for this EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by specifying the <opt-1> option, or by removing the <opt-2> option that makes it required.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0035I <cmd> command is a NO-OP if no options specified

No options for the <cmd> command are required, however, if none are specified the command acts like a null operation.

An example is HANDLE CONDITION, where no specific option is required, but the command does nothing unless one is present.

System Action:
The EXEC CICS statement is generated normally and will (effectively) do nothing at execution.
Resolution:
None required, however, the command has no function as coded.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0036W <opt> duplicate specification overrides previous

The same option, <opt>, has been specified more than once in the same EXEC CICS statement and its later specification(s) will effectively override prior ones.

The applies primarily to the HANDLE CONDITION and HANDLE AID commands where the second instance may specify a different destination than the first instance of the option.

System Action:
The options and EXEC CICS command are processed normally and a WARNING message is issued.
Resolution:
Correct the EXEC CICS statement so that it does not contain duplicate specifications of the <opt> option.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0037E <opt> argument must be a procedure label name

The argument to the <opt> option must be a paragraph (or section) name in the procedure division.

A literal or some other construct was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument for the <opt> option in the EXEC CICS statement.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0038E MAP(literal) or FROM or MAPONLY is required

On a SEND MAP command, a data area is required for the user data to be mapped when MAPONLY is not specified.

This can be explicitly specified using the FROM option or it can be implied if the argument for the MAP option is an alphanumeric literal.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS SEND MAP statement by specifying MAPONLY, or by specifying a FROM option, or by specifying an alphanumeric literal as the argument for the MAP option.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0039S Invalid syntax for DFHVALUE(condition)

The DFHVALUE string was not followed by a parenthesized name identifying the CVDA whose value should replace the DFHVALUE construct.
System Action:
The DFHVALUE is passed to the checker unchanged. This will, most likely, result in a Checker error message.
Resolution:
Correct the source.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0020 - COBEC0039


COBEC0040 - COBEC0059

  • COBEC0040E <x> is not a valid cvda-name for DFHVALUE
    The CVDA name specified in parentheses after DFHVALUE is not a valid CVDA name for CICS.
  • COBEC0041E <opt-1> invalid with <opt-2>
    The option <opt-1> is invalid when the <opt-2> option is present.
  • COBEC0042E Max. of <n> options for <cmd> exceeded
    The EXEC CICS <cmd> command allows a maximum of <n> options to be specified in a single instance of the command.
  • COBEC0043E <opt> option argument value missing
    The <opt> option was followed by an open parenthesis and a close parenthesis with no argument specification between them.
  • COBEC0044W CSA option returns NULL - Non-portable usage
    The EXEC CICS ADDRESS CSA option will always return a null pointer/address value in the emulation.
  • COBEC0045I <opt> argument should be (area), accepted (value)
    The argument for the <opt> option should be a data-area, but a value (literal or equivalent construct) was specified.
  • COBEC0046S EXEC CICS statement must be in PROCEDURE DIVISION
    Your source code contains an EXEC CICS statement before the PROCEDURE DIVISION header was found.
  • COBEC0047W CALL statement not supported in (NOT) EXCEPTION clause
    Your source code contains a CALL statement in an OVERFLOW, EXCEPTION, or NOT EXCEPTION clause within another CALL statement.
  • COBEC0048S EXEC CICS statement must be in PROCEDURE DIVISION
    Your source code contains an EXEC CICS statement in an OVERFLOW, EXCEPTION, or NOT EXCEPTION clause within a CALL statement.
  • COBEC0049W Nested CALL statement stack overflow
    The preprocessor stack for nested CALL statements has overflowed.
  • COBEC0050I <opt> is not valid in CALL on mainframe
    The <opt> keyword in the CALL statement is a Micro Focus extension which will be invalid on the mainframe.
  • COBEC0051S Command Option expected, found <opt>
    An argument (i.e. text enclosed in parentheses) or an alphanumeric literal was found where an option identifier is required in the EXEC CICS statement.
  • COBEC0052W 'quotation mark' or 'apostrophe' used as string delimiter with 'APOST' or 'QUOTE' directive - accepted
    The specified character was used as a character string delimiter when the alternative delimiter was in effect according to the specified directive.
  • COBEC0053S SYSTEM requires RESP/NOHANDLE
    Each EXEC CICS statement in a system program requires the use of the RESP or NOHANDLE option.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC0040E <x> is not a valid cvda-name for DFHVALUE

The CVDA name specified in parentheses after DFHVALUE is not a valid CVDA name for CICS.
System Action:
The preprocessor will generate a value of 9999 for the DFHVALUE construct.
Resolution:
Specify a valid CVDA name in the parentheses following DFHVALUE.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0041E <opt-1> invalid with <opt-2>

The option <opt-1> is invalid when the <opt-2> option is present.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing either the <opt-1> option or the <opt-2> option.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0042E Max. of <n> options for <cmd> exceeded

The EXEC CICS <cmd> command allows a maximum of <n> options to be specified in a single instance of the command.

The current instance of the command has more options than this maximum allowable number.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing some of the options or by splitting it into two (or more) separate instances of the command.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0043E <opt> option argument value missing

The <opt> option was followed by an open parenthesis and a close parenthesis with no argument specification between them.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by coding an appropriate argument specification between the parentheses or, possibly, by removing the parentheses.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0044W CSA option returns NULL - Non-portable usage

The EXEC CICS ADDRESS CSA option will always return a null pointer/address value in the emulation.

This option is a non-portable usage due to its dependence on the specific format of internal CICS control blocks.

System Action:
The command and option are processed normally and a WARNING message is issued. The emulation will return a null pointer (or address) value in the argument specified for the CSA option; any reference to data areas using this address may cause unpredictable results.
Resolution:
It is recommended that the CSA option be removed. Access to standard CICS system information should be acquired using the EXEC CICS ASSIGN command or using the CICS System Programming API commands.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0045I <opt> argument should be (area), accepted (value)

The argument for the <opt> option should be a data-area, but a value (literal or equivalent construct) was specified.

This occurs when an option is used both to specify a limit that the application will accept and to return the actual size that CICS returned to the application. The literal was accepted as the limit and no returned value will be made available to the application.

System Action:
The command is processed and generated normally. The value specified for the option will be passed to the emulation, but no area is provided for returning a value to the user application.
Resolution:
The application source should be updated to use a data-area as the argument for this option at some time so that the CICS returned value will be available to the application.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0046S EXEC CICS statement must be in PROCEDURE DIVISION

Your source code contains an EXEC CICS statement before the PROCEDURE DIVISION header was found.
System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the placement of the EXEC CICS statement within the source program.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0047W CALL statement not supported in (NOT) EXCEPTION clause

Your source code contains a CALL statement in an OVERFLOW, EXCEPTION, or NOT EXCEPTION clause within another CALL statement.
System Action:
The CALL statement is passed through to the Checker without any preprocessor action.
Resolution:
If the target program is not a CICS (translated) program, the CALL statement will operate correctly. If the target is a CICS program, then the CALL must not appear in one of the clauses of another CALL statement. One method of correcting this is to move the CALL to a separate paragraph which is performed from the clause within the other CALL statement.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0048S EXEC CICS statement must be in PROCEDURE DIVISION

Your source code contains an EXEC CICS statement in an OVERFLOW, EXCEPTION, or NOT EXCEPTION clause within a CALL statement.
System Action:
The EXEC CICS statement is passed through to the Checker without being translated by the preprocessor.
Resolution:
Correct the placement of the EXEC CICS statement within the source program. One method is to move the CALL to a separate paragraph which is performed from the clause within the CALL statement.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0049W Nested CALL statement stack overflow

The preprocessor stack for nested CALL statements has overflowed.

Nesting means further CALLs within OVERFLOW, EXCEPTION, and NOT EXCEPTION clause. The preprocessor stack contains state information for all CALL statements that have not terminated (by END-CALL or period). The stacking limit is 32 unterminated CALL statements.

System Action:
Processing continues normally, except that some CALL statements may not get the appropriate test code inserted to do the exit processing and check for CICS errors after returning from a called program.
Resolution:
If none of the programs invoked by the nested CALL statements is a CICS program and none of the invoke CICS programs (however indirectly), then the program will function correctly. If there are CICS programs invoked in the nested CALL statements, then they should be recoded in some other form to avoid the preprocessor limitation on nesting. This will guarantee that exit processing and error checking will be done at the return from called programs.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0050I <opt> is not valid in CALL on mainframe

The <opt> keyword in the CALL statement is a Micro Focus extension which will be invalid on the mainframe.

It is accepted and supported in the MCOv3 system.

System Action:
The CALL statement is processed and generated normally.
Resolution:
If mainframe compatibility is desired, the CALL statement source should be modified to avoid Micro Focus extensions.
Module:
cicsprep (dfhxc2pc)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0051S Command Option expected, found <opt>

An argument (i.e. text enclosed in parentheses) or an alphanumeric literal was found where an option identifier is required in the EXEC CICS statement.
System Action:
The erroneous text is ignored in the generated code for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing the parentheses (or quotes) or by specifying the appropriate option identifier before the argument text.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0052W 'quotation mark' or 'apostrophe' used as string delimiter with 'APOST' or 'QUOTE' directive - accepted

The specified character was used as a character string delimiter when the alternative delimiter was in effect according to the specified directive.
System Action:
The incorrect delimiter is accepted as though it was the correct delimiter.
Resolution:
Correct the EXEC CICS statement by changing the string delimiter to the correct character for the directive being used.
Module:
cicsprep (dfhxppin)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC0053S SYSTEM requires RESP/NOHANDLE

Each EXEC CICS statement in a system program requires the use of the RESP or NOHANDLE option.
System Action:
The EXEC statement is treated as comments, a SEVERE error is raised, and processing continues with the word following the END-EXEC.
Resolution:
Correct the EXEC CICS statement with RESP or NOHANDLE.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC0040 - COBEC0059


COBEC1100 - COBEC1119

  • COBEC1100S END-EXEC missing from command
    The EXEC CICS command did not have a terminating END-EXEC.
  • COBEC1101S Unexpected text after END-EXEC
    Text was found after the END-EXEC that was treated as part of the EXEC CICS statement.
  • COBEC1102E <left-paren> without preceding <option> - ignored
    A left parenthesis (signaling the start of an argument value) was found where an option string was expected.
  • COBEC1103E <left-paren> invalid after literal - ignored
    A left parenthesis was found immediately following a numeric or alphanumeric literal (where it cannot start a subscript, a reference modification, or a new argument).
  • COBEC1104E Repeated <left-paren> invalid - ignored
    A left parenthesis was found immediately following another left parenthesis in an argument where it is invalid.
  • COBEC1105E <left-paren> invalid here - skipping to matching <right-paren>
    A left parenthesis was found where it a parenthesized expression is invalid.
  • COBEC1106E Unmatched <right-paren> - ignored
    An unmatched right parenthesis was found in the statement.
  • COBEC1107E Null subscript list or reference mod is invalid
    An empty pair of parentheses was found in an argument where a subscript list or reference modification would be valid.
  • COBEC1108E Unexpected/invalid text <user text> - ignored
    The given user text was found in the EXEC CICS statement in a position where it should not occur.
  • COBEC1109E 'ADDRESS' or 'LENGTH' must be followed by OF - ignored
    The given COBOL special-register must be followed by the word 'OF' to be valid.
  • COBEC1110E 'ADDRESS OF' or 'LENGTH OF' must be followed by <data-name>
    The given COBOL special-register must be followed by a <data-name> in the argument for an option.
  • COBEC1111E 'DFHRESP' or 'DFHVALUE' must be followed by <left-paren>
    The given CICS symbolic reference must be followed by a parenthesized expression identifying the symbolic value to be translated to a numeric value.
  • COBEC1112E 'DFHRESP' or 'DFHVALUE' requires <'condition' or 'cvda' name> after <left-paren>
    The given CICS symbolic reference must be followed by a parenthesized expression containing the symbolic name to be translated to a numeric value.
  • COBEC1113E 'DFHRESP' or 'DFHVALUE' missing closing <right-paren>
    The given CICS symbolic reference requires a closing right parenthesis after the symbolic name.
  • COBEC1114E <user text> is not a valid <'condition' or 'cvda' name>
    The symbolic name given in the DFHRESP or DFHVALUE construct is not a valid symbolic name for that construct.
  • COBEC1115E 'DFHRESP' or 'DFHVALUE' cannot be an option on EXEC command
    The given CICS symbolic reference appeared in an EXEC CICS statement where an 'option' name is expected.
  • COBEC1116E 'IN' or 'OF' requires preceding <data-name>
    The given word signals qualification and must be preceded by a data-name.
  • COBEC1117E 'IN' or 'OF' cannot follow a <literal>
    The given word signals qualification and may not follow a character or numeric literal.
  • COBEC1118E 'IN' or 'OF' must be followed by <data-name>
    The given word signals qualification and must be followed by a data-name.
  • COBEC1119E <data-name> is invalid here
    A data-name is invalid in the context of the statement at this point.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1100S END-EXEC missing from command

The EXEC CICS command did not have a terminating END-EXEC.
System Action:
The command is processed as if the END-EXEC had been found.
Resolution:
Correct the EXEC CICS statement to include an END-EXEC.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1101S Unexpected text after END-EXEC

Text was found after the END-EXEC that was treated as part of the EXEC CICS statement.
System Action:
The command is processed as though the excess text was not present.
Resolution:
Correct the EXEC CICS statement by removing text following the END-EXEC.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1102E <left-paren> without preceding <option> - ignored

A left parenthesis (signaling the start of an argument value) was found where an option string was expected.
System Action:
The left parenthesis is ignored and processing of the EXEC CICS statement continues with the next non-blank character.
Resolution:
Correct the EXEC CICS statement by removing the left parenthesis or by inserting the appropriate option before it.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1103E <left-paren> invalid after literal - ignored

A left parenthesis was found immediately following a numeric or alphanumeric literal (where it cannot start a subscript, a reference modification, or a new argument).
System Action:
The left parenthesis is ignored and processing of the EXEC CICS statement continues with the next non-blank character.
Resolution:
Correct the EXEC CICS statement by removing the left parenthesis or by inserting the appropriate text before it.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1104E Repeated <left-paren> invalid - ignored

A left parenthesis was found immediately following another left parenthesis in an argument where it is invalid.
System Action:
The left parenthesis is ignored and processing of the EXEC CICS statement continues with the next non-blank character.
Resolution:
Correct the EXEC CICS statement by removing the left parenthesis or by inserting the appropriate text before it.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1105E <left-paren> invalid here - skipping to matching <right-paren>

A left parenthesis was found where it a parenthesized expression is invalid.
System Action:
The left parenthesis and all text to the matching right parenthesis is ignored and processing of the EXEC CICS statement continues with the next non-blank character after that right parenthesis.
Resolution:
Correct the EXEC CICS statement so that the parenthesized expression is used correctly.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1106E Unmatched <right-paren> - ignored

An unmatched right parenthesis was found in the statement.
System Action:
The left parenthesis is ignored and processing of the EXEC CICS statement continues with the next non-blank character.
Resolution:
Correct the EXEC CICS statement x.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1107E Null subscript list or reference mod is invalid

An empty pair of parentheses was found in an argument where a subscript list or reference modification would be valid.
System Action:
The empty pair of parentheses is ignored. Note that this may lead to further errors from the compiler.
Resolution:
Correct the EXEC CICS statement by removing the empty pair of parentheses or supplying the appropriate name(s) or value(s) between them.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1108E Unexpected/invalid text <user text> - ignored

The given user text was found in the EXEC CICS statement in a position where it should not occur.
System Action:
The invalid text is ignored.
Resolution:
Correct the EXEC CICS statement by removing the invalid text or supplying the appropriate additional text to make it valid.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1109E 'ADDRESS' or 'LENGTH' must be followed by OF - ignored

The given COBOL special-register must be followed by the word 'OF' to be valid.
System Action:
The given text is ignored.
Resolution:
Correct the EXEC CICS statement by supplying the word 'OF' or removing the given text.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1110E 'ADDRESS OF' or 'LENGTH OF' must be followed by <data-name>

The given COBOL special-register must be followed by a <data-name> in the argument for an option.
System Action:
The given text is ignored.
Resolution:
Correct the EXEC CICS statement by supplying the <data-name> or otherwise correcting the argument description.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1111E 'DFHRESP' or 'DFHVALUE' must be followed by <left-paren>

The given CICS symbolic reference must be followed by a parenthesized expression identifying the symbolic value to be translated to a numeric value.
System Action:
The DFHRESP or DFHVALUE construct is ignored and processing continues with the next text item.
Resolution:
Correct CICS symbolic reference in the EXEC CICS statement by following it with the parenthesized symbolic name.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1112E 'DFHRESP' or 'DFHVALUE' requires <'condition' or 'cvda' name> after <left-paren>

The given CICS symbolic reference must be followed by a parenthesized expression containing the symbolic name to be translated to a numeric value.
System Action:
The DFHRESP or DFHVALUE construct is ignored and processing continues with the next text item.
Resolution:
Correct CICS symbolic reference in the EXEC CICS statement by following it with the parenthesized symbolic name.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1113E 'DFHRESP' or 'DFHVALUE' missing closing <right-paren>

The given CICS symbolic reference requires a closing right parenthesis after the symbolic name.
System Action:
The DFHRESP or DFHVALUE construct is ignored and processing continues with the next text item.
Resolution:
Correct CICS symbolic reference in the EXEC CICS statement by supplying the closing right parenthesis.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1114E <user text> is not a valid <'condition' or 'cvda' name>

The symbolic name given in the DFHRESP or DFHVALUE construct is not a valid symbolic name for that construct.
System Action:
The DFHRESP or DFHVALUE construct is ignored and processing continues with the next text item.
Resolution:
Correct CICS symbolic reference in the EXEC CICS statement by supplying a valid symbolic name.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1115E 'DFHRESP' or 'DFHVALUE' cannot be an option on EXEC command

The given CICS symbolic reference appeared in an EXEC CICS statement where an 'option' name is expected.
System Action:
The DFHRESP or DFHVALUE construct is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement so that the DFHRESP or DFHVALUE construct appears as an argument to an option or remove the construct.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1116E 'IN' or 'OF' requires preceding <data-name>

The given word signals qualification and must be preceded by a data-name.

Note that 'OF' preceded by 'LENGTH' or 'ADDRESS' is treated as a special case.

System Action:
The given word is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement so that the use of 'IN' or 'OF' conforms to COBOL qualification formats or to the special register cases.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1117E 'IN' or 'OF' cannot follow a <literal>

The given word signals qualification and may not follow a character or numeric literal.
System Action:
The given word is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement so that the use of 'IN' or 'OF' conforms to COBOL qualification formats or to the special register cases.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1118E 'IN' or 'OF' must be followed by <data-name>

The given word signals qualification and must be followed by a data-name.
System Action:
The given word is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement so that the use of 'IN' or 'OF' conforms to COBOL qualification formats or to the special register cases.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1119E <data-name> is invalid here

A data-name is invalid in the context of the statement at this point.

This is most likely because of a missing 'IN' or 'OF' for qualification or after 'LENGTH' or 'ADDRESS'.

System Action:
The data-name is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement by inserting the appropriate required word or punctuation or by removing the inappropriate text.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1100 - COBEC1119


COBEC1120 - COBEC1139

  • COBEC1120E <literal> is invalid here
    A numeric or character literal was encountered following another literal or data-name in a context (i.e. not a subscript list) where it is invalid.
  • COBEC1121E <colon> is invalid here
    A colon was encountered where it is invalid (i.e. not in a reference modification).
  • COBEC1122E Closing quote missing from alphanumeric literal
    No closing apostrophe (or quote) was found for a character string literal.
  • COBEC1123W 'quotation mark' or 'apostrophe' used as string delimiter with 'APOST' or 'QUOTE' directive - accepted
    The specified character was used as a character string delimiter when the alternative delimiter was in effect according to the specified directive.
  • COBEC1124S Operand <data-name> is not declared
    The specified data-name was not declared in the data division.
  • COBEC1125S Operand <data-name> is not unique
    The specified data-name was not unique.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1120E <literal> is invalid here

A numeric or character literal was encountered following another literal or data-name in a context (i.e. not a subscript list) where it is invalid.
System Action:
The literal is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement by inserting appropriate punctuation or removing the improper use of a literal.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1120 - COBEC1139


COBEC1121E <colon> is invalid here

A colon was encountered where it is invalid (i.e. not in a reference modification).
System Action:
The colon is ignored and processing continues with the next text item.
Resolution:
Correct the EXEC CICS statement by removing the improper use of a colon.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1120 - COBEC1139


COBEC1122E Closing quote missing from alphanumeric literal

No closing apostrophe (or quote) was found for a character string literal.
System Action:
The entire literal is ignored, including any text that was treated as part of the literal.
Resolution:
Correct the EXEC CICS statement so that the closing apostrophe (or quote) is present in the correct place.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1120 - COBEC1139


COBEC1123W 'quotation mark' or 'apostrophe' used as string delimiter with 'APOST' or 'QUOTE' directive - accepted

The specified character was used as a character string delimiter when the alternative delimiter was in effect according to the specified directive.
System Action:
The incorrect delimiter is accepted as though it was the correct delimiter.
Resolution:
Correct the EXEC CICS statement by changing the string delimiter to the correct character for the directive being used.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1120 - COBEC1139


COBEC1124S Operand <data-name> is not declared

The specified data-name was not declared in the data division.
System Action:
The EXEC CICS statement is rejected.
Resolution:
Correct the EXEC CICS statement by changing the data-name to one defined in the data division or add a new data-name.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1120 - COBEC1139


COBEC1125S Operand <data-name> is not unique

The specified data-name was not unique.
System Action:
The EXEC CICS statement is rejected.
Resolution:
Correct the EXEC CICS statement by ensuring the data-name is unique.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1120 - COBEC1139


COBEC1200 - COBEC1219

  • COBEC1200E <cmd> is not a valid EXEC CICS command
    The command <cmd> is not recognized as a valid EXEC CICS command by the preprocessor.
  • COBEC1201E <cmd> command not supported or validated
    The CICS command <cmd> is recognized by the preprocessor as a valid command, but its syntax is not validated and it is not supported in the emulation.
  • COBEC1202E <cmd> command validated, but not supported
    The syntax of the CICS command <cmd> is validated by the preprocessor, but is not supported in the emulation.
  • COBEC1203I <cmd> command is a NO-OP if no options specified
    No options for the <cmd> command are required, however, if none are specified the command acts like a null operation.
  • COBEC1204E Max. of <n> options for <cmd> exceeded
    The EXEC CICS <cmd> command allows a maximum of <n> options to be specified in a single instance of the command.
  • COBEC1210E <opt> is not a valid option for <cmd>
    The option <opt> is not valid on the EXEC CICS <cmd> command.
  • COBEC1211E <opt-1> invalid without <opt-2>
    The <opt-1> option is valid only if the <opt-2> option is also specified for this EXEC CICS command.
  • COBEC1212E <opt-1> invalid with <opt-2>
    The option <opt-1> is invalid when the <opt-2> option is present.
  • COBEC1213E <opt> option not supported for <cmd>
    The option <opt> is not supported for the EXEC CICS <cmd> command in the emulation.
  • COBEC1214I <opt> option is ignored for <cmd>
    The option <opt> is ignored on the EXEC CICS <cmd> command.
  • COBEC1215W <opt> option is only partially supported for <cmd>
    The option <opt> is partially supported on the EXEC CICS <cmd> command.
  • COBEC1216E <opt> option is only partially supported for <cmd>
    The option <opt> is partially supported on the EXEC CICS <cmd> command.
  • COBEC1217S <opt> option is only partially supported for <cmd>
    The option <opt> is partially supported on the EXEC CICS <cmd> command.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1200E <cmd> is not a valid EXEC CICS command

The command <cmd> is not recognized as a valid EXEC CICS command by the preprocessor.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to specify a valid command.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1201E <cmd> command not supported or validated

The CICS command <cmd> is recognized by the preprocessor as a valid command, but its syntax is not validated and it is not supported in the emulation.
System Action:
The preprocessor will generate either an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported commands when compiling this transaction. The EXEC CICS statement can remain in the source for compatibility with other environments; the module will be executable.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1202E <cmd> command validated, but not supported

The syntax of the CICS command <cmd> is validated by the preprocessor, but is not supported in the emulation.
System Action:
The preprocessor will generate either an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported commands when compiling this transaction. The EXEC CICS statement can remain in the source for compatibility with other environments; the module will be executable.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1203I <cmd> command is a NO-OP if no options specified

No options for the <cmd> command are required, however, if none are specified the command acts like a null operation.

An example is HANDLE CONDITION, where no specific option is required, but the command does nothing unless one is present.

System Action:
The EXEC CICS statement is generated normally and will (effectively) do nothing at execution.
Resolution:
None required, however, the command has no function as coded.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1204E Max. of <n> options for <cmd> exceeded

The EXEC CICS <cmd> command allows a maximum of <n> options to be specified in a single instance of the command.

The current instance of the command has more options than this maximum allowable number.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing some of the options or by splitting it into two (or more) separate instances of the command.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1210E <opt> is not a valid option for <cmd>

The option <opt> is not valid on the EXEC CICS <cmd> command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the option <opt> on the EXEC CICS statement.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1211E <opt-1> invalid without <opt-2>

The <opt-1> option is valid only if the <opt-2> option is also specified for this EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing the <opt-1> option or by specifying the <opt-2> option.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1212E <opt-1> invalid with <opt-2>

The option <opt-1> is invalid when the <opt-2> option is present.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing either the <opt-1> option or the <opt-2> option.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1213E <opt> option not supported for <cmd>

The option <opt> is not supported for the EXEC CICS <cmd> command in the emulation.
System Action:
The preprocessor will either treat the option as a comment or it will generate an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported options when compiling this transaction. The option can remain in the EXEC CICS statement for compatibility with other environments; the module will be executable.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1214I <opt> option is ignored for <cmd>

The option <opt> is ignored on the EXEC CICS <cmd> command.

This normally applies to options which have no effect on the API behavior, but are specified for efficiency considerations in the mainframe implementation of the CICS API.

System Action:
The option <opt> is treated as comments.
Resolution:
None.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1215W <opt> option is only partially supported for <cmd>

The option <opt> is partially supported on the EXEC CICS <cmd> command.

The full range of values is not supported in this implementation.

System Action:
The option <opt> is flagged as a warning.
Resolution:
See the documentation for a list of the supported values.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1216E <opt> option is only partially supported for <cmd>

The option <opt> is partially supported on the EXEC CICS <cmd> command.

The full range of values is not supported in this implementation.

System Action:
The option <opt> is flagged as an error.
Resolution:
See the documentation for a list of the supported values.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1217S <opt> option is only partially supported for <cmd>

The option <opt> is partially supported on the EXEC CICS <cmd> command.

The full range of values is not supported in this implementation.

System Action:
The option <opt> is flagged as severe.
Resolution:
See the documentation for a list of the supported values.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1200 - COBEC1219


COBEC1220 - COBEC1239

  • COBEC1220E Required <opt> option missing from <cmd>
    The <opt> option is required on an EXEC CICS <cmd> command and has been omitted.
  • COBEC1221E <opt-1> required with <opt-2>
    The <opt-1> option is required if the <opt-2> option has been specified for this EXEC CICS command.
  • COBEC1222E <opt-1> option conflicts with <opt-2> option
    The options <opt-1> and <opt-2> are mutually exclusive in the context of the current EXEC CICS command.
  • COBEC1230W Duplicate <opt> option
    The option <opt> is specified more than once on the current EXEC CICS statement.
  • COBEC1231W <opt> duplicate specification overrides previous
    The same option, <opt>, has been specified more than once in the same EXEC CICS statement and its later specification(s) will effectively override prior ones.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1220E Required <opt> option missing from <cmd>

The <opt> option is required on an EXEC CICS <cmd> command and has been omitted.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to include all required options for the command.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1220 - COBEC1239


COBEC1221E <opt-1> required with <opt-2>

The <opt-1> option is required if the <opt-2> option has been specified for this EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by specifying the <opt-1> option, or by removing the <opt-2> option that makes it required.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1220 - COBEC1239


COBEC1222E <opt-1> option conflicts with <opt-2> option

The options <opt-1> and <opt-2> are mutually exclusive in the context of the current EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement so that only one of the mutually exclusive options is specified.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1220 - COBEC1239


COBEC1230W Duplicate <opt> option

The option <opt> is specified more than once on the current EXEC CICS statement.
System Action:
The second and subsequent specifications are ignored and a WARNING message is issued.
Resolution:
Correct the EXEC CICS statement so that the option only appears once.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1220 - COBEC1239


COBEC1231W <opt> duplicate specification overrides previous

The same option, <opt>, has been specified more than once in the same EXEC CICS statement and its later specification(s) will effectively override prior ones.

The applies primarily to the HANDLE CONDITION and HANDLE AID commands where the second instance may specify a different destination than the first instance of the option.

System Action:
The options and EXEC CICS command are processed normally and a WARNING message is issued.
Resolution:
Correct the EXEC CICS statement so that it does not contain duplicate specifications of the <opt> option.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1220 - COBEC1239


COBEC1240 - COBEC1259

  • COBEC1240E <opt> required in OSVS for Length specification
    The <opt> option is required in OSVS COBOL programs to provide a length specification.
  • COBEC1241W <opt> specifies length for an option not present
    The option <opt> is a length specification that gives the size of area for some other option which has been omitted.
  • COBEC1242E MAP(literal) or FROM or MAPONLY is required
    On a SEND MAP command, a data area is required for the user data to be mapped when MAPONLY is not specified.
  • COBEC1243W CSA option returns NULL - Non-portable usage
    The EXEC CICS ADDRESS CSA option will always return a null pointer/address value in the emulation.
  • COBEC1244S use of SOAPFAULT API requires ECM SPFAULT directive to be set
    The EXEC CICS SOAPFAULT CREATE/ADD API requires the ECM SPFAULT directive to be set.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1240E <opt> required in OSVS for Length specification

The <opt> option is required in OSVS COBOL programs to provide a length specification.

Note that it is optional in VS COBOL II programs since it can be defaulted to the LENGTH OF construct.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by adding the required option and specifying an appropriate argument for the length.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1240 - COBEC1259


COBEC1241W <opt> specifies length for an option not present

The option <opt> is a length specification that gives the size of area for some other option which has been omitted.
System Action:
The <opt> option is treated as comments and a WARNING message issued.
Resolution:
Correct the EXEC CICS statement by either removing the option or by specifying the option for which it is providing a length specification.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1240 - COBEC1259


COBEC1242E MAP(literal) or FROM or MAPONLY is required

On a SEND MAP command, a data area is required for the user data to be mapped when MAPONLY is not specified.

This can be explicitly specified using the FROM option or it can be implied if the argument for the MAP option is an alphanumeric literal.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS SEND MAP statement by specifying MAPONLY, or by specifying a FROM option, or by specifying an alphanumeric literal as the argument for the MAP option.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1240 - COBEC1259


COBEC1243W CSA option returns NULL - Non-portable usage

The EXEC CICS ADDRESS CSA option will always return a null pointer/address value in the emulation.

This option is a non-portable usage due to its dependence on the specific format of internal CICS control blocks.

System Action:
The command and option are processed normally and a WARNING message is issued. The emulation will return a null pointer (or address) value in the argument specified for the CSA option; any reference to data areas using this address may cause unpredictable results.
Resolution:
It is recommended that the CSA option be removed. Access to standard CICS system information should be acquired using the EXEC CICS ASSIGN command or using the CICS System Programming API commands.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1240 - COBEC1259


COBEC1244S use of SOAPFAULT API requires ECM SPFAULT directive to be set

The EXEC CICS SOAPFAULT CREATE/ADD API requires the ECM SPFAULT directive to be set.

If not, the parameters will be truncated.

System Action:
The compilation is stopped and an ERROR message is issued.
Resolution:
It is advised that the user compiles their program using CICSECM(SPFAULT=YES) directive.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1240 - COBEC1259


COBEC1300 - COBEC1319

  • COBEC1300W <opt> option should not have an argument
    An argument was specified for the <opt> option which should not have an argument.
  • COBEC1310E <opt> option requires an argument
    The <opt> option is expected to have an argument in parentheses following the option.
  • COBEC1311I <opt> option argument value missing
    The <opt> option was followed by an open parenthesis and a close parenthesis with no argument specification between them and the <opt> option allows an argument but does not require an argument.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1300W <opt> option should not have an argument

An argument was specified for the <opt> option which should not have an argument.
System Action:
The argument for the <opt> option is ignored by the preprocessor.
Resolution:
Correct the EXEC CICS statement to remove the argument from the <opt> option. N.B., this may indicate that the option that the argument should have belonged to has been omitted.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1300 - COBEC1319


COBEC1310E <opt> option requires an argument

The <opt> option is expected to have an argument in parentheses following the option.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by specifying the appropriate argument value or data-area following the <opt> option.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1300 - COBEC1319


COBEC1311I <opt> option argument value missing

The <opt> option was followed by an open parenthesis and a close parenthesis with no argument specification between them and the <opt> option allows an argument but does not require an argument.
System Action:
The option is treated as if no argument was specified (i.e., that the parentheses were not present).
Resolution:
Verify that the argument was not inadvertently omitted from the option. Correct if necessary.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1300 - COBEC1319


COBEC1320 - COBEC1339

  • COBEC1320E <opt> argument must be (data-area)
    The argument for the <opt> option must be a data-area; a literal or equivalent construct was found instead of a data-name.
  • COBEC1321I <opt> argument should be (area), accepted (value)
    The argument for the <opt> option should be a data-area, but a value (literal or equivalent construct) was specified.
  • COBEC1330E <opt> argument must be alphanumeric value/area
    The argument for the <opt> option must be either a data-area or an alphanumeric literal.
  • COBEC1331E <opt> argument must be numeric value/area
    The argument for the <opt> option must be either a numeric literal or a data-area.
  • COBEC1332E <opt> argument must be (ptr-ref) or ADDRESS OF ...
    The argument for the <opt> option must be an address.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1320E <opt> argument must be (data-area)

The argument for the <opt> option must be a data-area; a literal or equivalent construct was found instead of a data-name.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify the name of a data-area.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1320 - COBEC1339


COBEC1321I <opt> argument should be (area), accepted (value)

The argument for the <opt> option should be a data-area, but a value (literal or equivalent construct) was specified.

This occurs when an option is used both to specify a limit that the application will accept and to return the actual size that CICS returned to the application. The literal was accepted as the limit and no returned value will be made available to the application.

System Action:
The command is processed and generated normally. The value specified for the option will be passed to the emulation, but no area is provided for returning a value to the user application.
Resolution:
The application source should be updated to use a data-area as the argument for this option at some time so that the CICS returned value will be available to the application.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1320 - COBEC1339


COBEC1330E <opt> argument must be alphanumeric value/area

The argument for the <opt> option must be either a data-area or an alphanumeric literal.

A numeric literal or equivalent construct was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify an alphanumeric literal or the name of a data-area.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1320 - COBEC1339


COBEC1331E <opt> argument must be numeric value/area

The argument for the <opt> option must be either a numeric literal or a data-area.

An alphanumeric literal was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify a numeric literal or the name of a data-area.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1320 - COBEC1339


COBEC1332E <opt> argument must be (ptr-ref) or ADDRESS OF ...

The argument for the <opt> option must be an address.

I.e., either the data-name of a pointer item or an ADDRESS OF data-name construct.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify an address as the name of a data-area or using an ADDRESS OF data-name construct.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1320 - COBEC1339


COBEC1340 - COBEC1359

  • COBEC1340E <opt> argument must be a procedure label name
    The argument to the <opt> option must be a paragraph (or section) name in the procedure division.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1340E <opt> argument must be a procedure label name

The argument to the <opt> option must be a paragraph (or section) name in the procedure division.

A literal or some other construct was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument for the <opt> option in the EXEC CICS statement.
Module:
cicsecm (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC1340 - COBEC1359


COBEC1400 - COBEC1419

  • COBEC1400W Excess HANDLE label qualifier <text> - ignored
    A label can only be qualified by a section-name (i.e. paragraph of section) and further qualification is not possible.
  • COBEC1401S Undefined HANDLE label <paragraph name><' OF '><section name> - used at line <line number>, col <column number>
    The named paragraph (optionally with qualification) does not exist in the program.
  • COBEC1402S HANDLE label <paragraph name><' OF '><section name> - not unique, used at line <line number>, col <column number>
    If a qualified name is given, then the paragraph name appears more than once in the given section.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1400W Excess HANDLE label qualifier <text> - ignored

A label can only be qualified by a section-name (i.e. paragraph of section) and further qualification is not possible.

A label in a HANDLE function was specified with more than 2 names. The 3rd name (2nd level of qualification) and all subsequent names are ignored.

System Action:
The warning is produced and the label reference is done using only the first two names specified.
Resolution:
Correct the paragraph name.
Module:
cicsecm (dfhxecmg)
Destination:
Source Listing
Parent topic: COBEC1400 - COBEC1419


COBEC1401S Undefined HANDLE label <paragraph name><' OF '><section name> - used at line <line number>, col <column number>

The named paragraph (optionally with qualification) does not exist in the program.

It was used in the EXEC statement at the given line and column of the source.

System Action:
The severe error message is produced and the name reference is replaced with a 'dummy' in the CICS branch table for handles that will exit the program.
Resolution:
Correct the paragraph name or add it to the program.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1400 - COBEC1419


COBEC1402S HANDLE label <paragraph name><' OF '><section name> - not unique, used at line <line number>, col <column number>

If a qualified name is given, then the paragraph name appears more than once in the given section.

If a single name is given, then the named paragraph exists more than once in the program, but not in the implied local section where it was used. It was used in the EXEC statement at the given line and column of the source.

System Action:
The severe error message is produced and the name reference is replaced with a 'dummy' in the CICS branch table for handles that will exit the program.
Resolution:
Correct the paragraph name or explicitly qualify it or add it to the section of the program where it was used.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1400 - COBEC1419


COBEC1500 - COBEC1519

  • COBEC1501S Unexpected PL/I nesting level encountered - contact Micro Focus Customer Support
    The maximum nesting level of 30 has been exceeded.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC1501S Unexpected PL/I nesting level encountered - contact Micro Focus Customer Support

The maximum nesting level of 30 has been exceeded.
System Action:
The current EXEC CICS command is aborted.
Resolution:
Contact Micro Focus.
Module:
cicsecm (cicsecm)
Destination:
Source Listing
Parent topic: COBEC1500 - COBEC1519


COBEC6000 - COBEC6019

  • COBEC6001S Unrecognizable text <text> ignored
    x.
  • COBEC6002E Invalid command <cmd>
    The command <cmd> is not recognized as a valid EXEC CICS command by the translator.
  • COBEC6003W Unsupported command |<cmd> null string or "(syntax validated)"| ignored
    The CICS command <cmd> is recognized by the preprocessor as a valid command, but it is not supported in the emulation.
  • COBEC6004E Command <cmd> requires at least 1 keyword
    Although none of the options for the <cmd> command are required, at least one of them must be specified.
  • COBEC6005S Too many keywords for command |<cmd> (Max = Max keywords)|
    Case 1: The EXEC CICS Max keywords command allows a maximum of number of options to be specified in a single instance of the command and that number was exceeded.
  • COBEC6006E Invalid keyword <opt> specified
    The option <opt> is not valid on the EXEC CICS command.
  • COBEC6007I Keyword <opt> is ignored
    The option <opt> is ignored on the EXEC CICS command.
  • COBEC6008W Unsupported keyword <opt> specified
    The option <opt> is not supported for the EXEC CICS command in the emulation.
  • COBEC6009E Required keyword <opt> missing
    The <opt> option is required on the EXEC CICS command and has been omitted.
  • COBEC6010W Duplicate keyword <opt> specified
    The option <opt> is specified more than once on the current EXEC CICS statement.
  • COBEC6011E Mutually exclusive keywords specified |<keyword list>, <keyword list>|
    Either the options in the <keyword list> are mutually exclusive in the context of the current EXEC CICS command or the first options in the list is invalid when the second option is present.
  • COBEC6012E Keyword <opt-1> invalid without keyword <opt-2>
    The <opt-1> option is valid only if the <opt-2> option is also specified for this EXEC CICS command.
  • COBEC6013E Keyword <opt-1> required with keyword <opt-2>
    The <opt-1> option is required if the <opt-2> option has been specified for this EXEC CICS command.
  • COBEC6014W Keyword <opt> does not take an argument
    An argument was specified for the <opt> option which should not have an argument.
  • COBEC6015E Keyword <opt> requires an argument
    The <opt> option is expected to have an argument in parentheses following the option.
  • COBEC6016E Keyword <opt> argument value missing
    The <opt> option was followed by an open parenthesis and a close parenthesis with no argument specification between them.
  • COBEC6017E Illegal value <argument-value> for keyword "DFHRESP" or "DFHVALUE" specified
    For keyword DFHRESP, the condition name specified in parentheses is not a valid CICS condition name.
  • COBEC6018E MAP(literal) or FROM or MAPONLY required
    On a SEND MAP command, a data area is required for the user data to be mapped when MAPONLY is not specified.
  • COBEC6019W CSA non-portable
    The EXEC CICS ADDRESS CSA option will always return a null pointer/address value in the emulation.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC6001S Unrecognizable text <text> ignored

x.
System Action:
x.
Resolution:
x.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6002E Invalid command <cmd>

The command <cmd> is not recognized as a valid EXEC CICS command by the translator.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to specify a valid command.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6003W Unsupported command |<cmd> null string or "(syntax validated)"| ignored

The CICS command <cmd> is recognized by the preprocessor as a valid command, but it is not supported in the emulation.

The syntax is validated if the "(syntax validated)" string appears in the message, otherwise it is not validated.

System Action:
The preprocessor will generate either an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported commands when compiling this transaction. The EXEC CICS statement can remain in the source for compatibility with other environments; the module will be executable.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6004E Command <cmd> requires at least 1 keyword

Although none of the options for the <cmd> command are required, at least one of them must be specified.

An example is HANDLE AID, where no specific option is required, but the command is invalid without at least one of them.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS <cmd> command by specifying at least one valid option.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6005S Too many keywords for command |<cmd> (Max = Max keywords)|

Case 1: The EXEC CICS Max keywords command allows a maximum of number of options to be specified in a single instance of the command and that number was exceeded.

Case 2: The EXEC CICS statement has more than 100 options specified between the 'command' and the END-EXEC (which is about 16 more than the largest number of unique options possible in any EXEC CICS command).

System Action:
Case 1: An Unsupported Function abend is generated for the EXEC CICS statement and a SEVERE error is raised.
Resolution:
Correct the EXEC CICS statement by removing some of the options or by splitting it into two (or more) separate instances of the command.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6006E Invalid keyword <opt> specified

The option <opt> is not valid on the EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the option <opt> on the EXEC CICS statement.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6007I Keyword <opt> is ignored

The option <opt> is ignored on the EXEC CICS command.

This normally applies to options which have no effect on the API behavior, but are specified for efficiency considerations in the mainframe implementation of the CICS API.

System Action:
The option <opt> is treated as comments.
Resolution:
None.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6008W Unsupported keyword <opt> specified

The option <opt> is not supported for the EXEC CICS command in the emulation.
System Action:
The preprocessor will either treat the option as a comment or it will generate an Unsupported Function abend call or a 'no-op' call, depending on the options specified by the user.
Resolution:
Choose the appropriate generation option for unsupported options when compiling this transaction. The option can remain in the EXEC CICS statement for compatibility with other environments; the module will be executable.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6009E Required keyword <opt> missing

The <opt> option is required on the EXEC CICS command and has been omitted.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to include all required options for the command.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6010W Duplicate keyword <opt> specified

The option <opt> is specified more than once on the current EXEC CICS statement.

On some commands, primarily to the HANDLE CONDITION and HANDLE AID commands, the later specification(s) will effectively override prior ones. For all other commands, the later specification(s) will be ignored.

System Action:
The second and subsequent specifications are ignored (or used to override previous specifications) and a WARNING message is issued.
Resolution:
Correct the EXEC CICS statement so that it does not contain duplicate specifications of the <opt> option.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6011E Mutually exclusive keywords specified |<keyword list>, <keyword list>|

Either the options in the <keyword list> are mutually exclusive in the context of the current EXEC CICS command or the first options in the list is invalid when the second option is present.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement so that only one of the mutually exclusive options is specified.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6012E Keyword <opt-1> invalid without keyword <opt-2>

The <opt-1> option is valid only if the <opt-2> option is also specified for this EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by removing the <opt-1> option or by specifying the <opt-2> option.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6013E Keyword <opt-1> required with keyword <opt-2>

The <opt-1> option is required if the <opt-2> option has been specified for this EXEC CICS command.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by specifying the <opt-1> option, or by removing the <opt-2> option that makes it required.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6014W Keyword <opt> does not take an argument

An argument was specified for the <opt> option which should not have an argument.
System Action:
The argument for the <opt> option is ignored by the preprocessor.
Resolution:
Correct the EXEC CICS statement to remove the argument from the <opt> option. N.B., this may indicate that the option that the argument should have belonged to has been omitted.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6015E Keyword <opt> requires an argument

The <opt> option is expected to have an argument in parentheses following the option.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by specifying the appropriate argument value or data-area following the <opt> option.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6016E Keyword <opt> argument value missing

The <opt> option was followed by an open parenthesis and a close parenthesis with no argument specification between them.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement by coding an appropriate argument specification between the parentheses or, possibly, by removing the parentheses.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6017E Illegal value <argument-value> for keyword "DFHRESP" or "DFHVALUE" specified

For keyword DFHRESP, the condition name specified in parentheses is not a valid CICS condition name.

For keyword DFHVALUE, the CVDA name specified in parentheses is not a valid CVDA name.

System Action:
The preprocessor will generate a value of 9999 for the invalid DFHRESP or DFHVALUE construct.
Resolution:
Specify a valid CICS condition name in the parentheses following DFHRESP, or specify a valid CVDA name in the parentheses following DFHVALUE.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6018E MAP(literal) or FROM or MAPONLY required

On a SEND MAP command, a data area is required for the user data to be mapped when MAPONLY is not specified.

This can be explicitly specified using the FROM option or it can be implied if the argument for the MAP option is an alphanumeric literal.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS SEND MAP statement by specifying MAPONLY, or by specifying a FROM option, or by specifying an alphanumeric literal as the argument for the MAP option.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6019W CSA non-portable

The EXEC CICS ADDRESS CSA option will always return a null pointer/address value in the emulation.

This option is a non-portable usage due to its dependence on the specific format of internal CICS control blocks.

System Action:
The command and option are processed normally and a WARNING message is issued. The emulation will return a null pointer (or address) value in the argument specified for the CSA option; any reference to data areas using this address may cause unpredictable results.
Resolution:
It is recommended that the CSA option be removed. Access to standard CICS system information should be acquired using the EXEC CICS ASSIGN command or using the CICS System Programming API commands.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6000 - COBEC6019


COBEC6020 - COBEC6039

  • COBEC6020I Argument for keyword <opt> should be area-accepted value
    The argument for the <opt> option should be a data-area, but a value (literal or equivalent construct) was specified.
  • COBEC6021E Argument for keyword <opt> must be data area
    The argument for the <opt> option must be a data-area; a literal or equivalent construct was found instead of a data-name.
  • COBEC6022E Argument for keyword <opt> must be pointer reference
    The argument for the <opt> option must be an address.
  • COBEC6023E Argument for keyword <opt> must be statement label
    The argument to the <opt> option must be a valid PL/I label name.
  • COBEC6024E Argument for keyword <opt> has wrong data type
    The argument for the <opt> option is an inappropriate type for the EXEC CICS command.
  • COBEC6025U CICS BE detected internal error <description> Please contact software-provider for service
    An internal error in the translator caused it to terminate.
  • COBEC6026E Keyword <opt> context is invalid
    The option was invalid in the context of the other keywords and could not be processed.
  • COBEC6027I Argument for keyword <opt> must be a string literal
    The argument to the <opt> option must be a valid string literal.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC6020I Argument for keyword <opt> should be area-accepted value

The argument for the <opt> option should be a data-area, but a value (literal or equivalent construct) was specified.

This occurs when an option is used both to specify a limit that the application will accept and to return the actual size that CICS returned to the application. The literal was accepted as the limit and no returned value will be made available to the application.

System Action:
The command is processed and generated normally. The value specified for the option will be passed to the emulation, but no area is provided for returning a value to the user application.
Resolution:
The application source should be updated to use a data-area as the argument for this option at some time so that the CICS returned value will be available to the application.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6021E Argument for keyword <opt> must be data area

The argument for the <opt> option must be a data-area; a literal or equivalent construct was found instead of a data-name.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify the name of a data-area.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6022E Argument for keyword <opt> must be pointer reference

The argument for the <opt> option must be an address.

I.e., either the data-name of a pointer item or an ADDRESS OF data-name construct.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify an address as the name of a data-area or using an ADDR(data-name) construct.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6023E Argument for keyword <opt> must be statement label

The argument to the <opt> option must be a valid PL/I label name.

A literal or some other construct was found.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument for the <opt> option in the EXEC CICS statement.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6024E Argument for keyword <opt> has wrong data type

The argument for the <opt> option is an inappropriate type for the EXEC CICS command.

This normally applies to literals and special language constructs.

System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument of the <opt> option in the EXEC CICS statement to specify an argument of the appropriate type.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6025U CICS BE detected internal error <description> Please contact software-provider for service

An internal error in the translator caused it to terminate.
System Action:
The translation is terminated.
Resolution:
Contact the translator provider for support.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6026E Keyword <opt> context is invalid

The option was invalid in the context of the other keywords and could not be processed.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the EXEC CICS statement to conform to the syntax rules given in the CICS APRM.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC6027I Argument for keyword <opt> must be a string literal

The argument to the <opt> option must be a valid string literal.
System Action:
An Unsupported Function abend is generated for the EXEC CICS statement and an ERROR is raised.
Resolution:
Correct the argument for the <opt> option in the EXEC CICS statement.
Module:
dfhxcics (dfhxvldt)
Destination:
Source Listing
Parent topic: COBEC6020 - COBEC6039


COBEC9000 - COBEC9019

  • COBEC9000F CICS Preprocess/Check Aborted
    The user has done a control-break to terminate the check process, or a FATAL error has occurred, or some system failure has caused the preprocess/check to be terminated prematurely.
  • COBEC9001F Invalid Preprocess Directive = <string>
    The PREPROCESS directive following the options for the TX preprocessor is incomplete or improperly specified.
  • COBEC9002F Unrecognized Directives = <string>
    The only directive which can follow the TX preprocessor options is an explicit PREPROCESS directive.
  • COBEC9003F COBOL Dialect = <dialect directive> is not supported
    The COBOL directive, <dialect directive>, specifies a dialect which is not supported by the Micro Focus CICS Option.
  • COBEC9005F Error loading CICS preprocessor module preprocessor-module
    The CICS preprocessor module could not be loaded as part of the initialization.
  • COBEC9010F Preprocessor Option Flags missing
    There was not a string following the PREPROCESS(cicsprep) directive to specify the TX preprocessor options.
  • COBEC9011F Invalid COBOL Dialect option = <l>
    The first flag in the TX preprocessor options specifies the language dialect.
  • COBEC9012F Invalid VSC2 Uppercase/Lowercase Source option = <c>
    The second flag in the TX preprocessor options specifies whether lowercase syntax (literals can always be lowercase) is allowed.
  • COBEC9013F Invalid Preprocessor Error Pause option = <e>
    The third flag in the TX preprocessor options specifies whether the preprocessor should pause and query the user when an error is encountered.
  • COBEC9014F Invalid Preprocessor Debug Output option = <b>
    The fourth flag in the TX preprocessor options specifies what debug files are to be produced.
  • COBEC9015F Invalid DL/I Support option = <d>
    The fifth flag in the TX preprocessor options specifies whether EXEC DLI support is present.
  • COBEC9016F Invalid SQL Support option = <s>
    The sixth flag in the TX preprocessor options specifies whether EXEC SQL support is present.
  • COBEC9017F Invalid Reusable Code Manager Support option = <r>
    The seventh flag in the TX preprocessor options specifies whether Reusable Code Manager support is needed.
  • COBEC9018F Invalid Unsupported Function Action code = <f>
    The eighth flag in the TX preprocessor options specifies the default action to be taken for an unsupported CICS API command.
  • COBEC9019F Invalid Unsupported Option Action code = <o>
    The ninth flag in the TX preprocessor options specifies the default action to be taken for an unsupported option on a CICS API command.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC9000F CICS Preprocess/Check Aborted

The user has done a control-break to terminate the check process, or a FATAL error has occurred, or some system failure has caused the preprocess/check to be terminated prematurely.
System Action:
Terminating the preprocess/check.
Resolution:
Correct any errors and redo the preprocess/check.
Module:
cicsprep
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9001F Invalid Preprocess Directive = <string>

The PREPROCESS directive following the options for the TX preprocessor is incomplete or improperly specified.
System Action:
Terminate the preprocess/check.
Resolution:
Correct the PREPROCESS directive and restart the preprocess/check.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9002F Unrecognized Directives = <string>

The only directive which can follow the TX preprocessor options is an explicit PREPROCESS directive.

The <string> string is not recognized by the TX preprocessor as valid text.

System Action:
Terminate the preprocess/check.
Resolution:
Either omit or correct the string following the TX preprocessor options.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9003F COBOL Dialect = <dialect directive> is not supported

The COBOL directive, <dialect directive>, specifies a dialect which is not supported by the Micro Focus CICS Option.
System Action:
Terminate the preprocess/check.
Resolution:
Remove the <dialect directive> directive from the COBOL directives file or or use a directives file for a supported dialect.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9005F Error loading CICS preprocessor module preprocessor-module

The CICS preprocessor module could not be loaded as part of the initialization.

This module is required for the preprocessor to execute.

System Action:
Abort the Preprocess/Check.
Resolution:
Check that $TXDIR is set correctly and the named module exists in $TXDIR/lib.
Module:
cicsprep
Destination:
Standard error
Parent topic: COBEC9000 - COBEC9019


COBEC9010F Preprocessor Option Flags missing

There was not a string following the PREPROCESS(cicsprep) directive to specify the TX preprocessor options.

This string is required.

System Action:
Terminate the preprocess/check.
Resolution:
Specify an TX preprocessor option string following the PREPROCESS(cicsprep) directive.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9011F Invalid COBOL Dialect option = <l>

The first flag in the TX preprocessor options specifies the language dialect.

It must be one of the following characters (not case-sensitive):

   O - OSVS COBOL dialect
   V - VS COBOL II dialect, default level
   1 - VS COBOL II dialect, level 1
   2 - VS COBOL II dialect, level 2
   3 - VS COBOL II dialect, level 3
   4 - VS COBOL II dialect, level 4
   D - DOSVS COBOL dialect
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid COBOL dialect options in the first position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9012F Invalid VSC2 Uppercase/Lowercase Source option = <c>

The second flag in the TX preprocessor options specifies whether lowercase syntax (literals can always be lowercase) is allowed.

It must be one of the following characters (not case-sensitive):

   U - All syntax (COBOL verbs, etc.) must be uppercase
   L - Lowercase syntax should be recognized
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid options for the case of COBOL syntax in the second position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9013F Invalid Preprocessor Error Pause option = <e>

The third flag in the TX preprocessor options specifies whether the preprocessor should pause and query the user when an error is encountered.

It must be one of the following characters (not case-sensitive):

   Q - pause at errors and query user
   Z - take default actions for all errors
   0 - not specified

Note that this option is similar to the Checker ERRQ directive but it is completely independent of that directive.

System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid Error Pause options in the third position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9014F Invalid Preprocessor Debug Output option = <b>

The fourth flag in the TX preprocessor options specifies what debug files are to be produced.

It must be one of the following characters (not case-sensitive):

   N - no Debug files are produced
   C - the .MCC file is produced.  This file is translated
       source suitable for separate compilation.
   D - the .MCD file is produced.  This file is useful in
       debugging preprocessor behavior.
   B - both the .MCC and .MCD files are produced.
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid Debug Output options in the fourth position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9015F Invalid DL/I Support option = <d>

The fifth flag in the TX preprocessor options specifies whether EXEC DLI support is present.

It must be one of the following characters (not case-sensitive):

   N - no EXEC DLI support is present
   Y - the user has provided for EXEC DLI support by an
       explicit PREPROCESS directive.
   I - the IMSVS86 EXEC DLI preprocessor is to be invoked
       by the TX preprocessor
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid DL/I Support options in the fifth position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9016F Invalid SQL Support option = <s>

The sixth flag in the TX preprocessor options specifies whether EXEC SQL support is present.

It must be one of the following characters (not case-sensitive):

   N - no EXEC SQL support is present
   Y - the user has provided for EXEC SQL support by an
       explicit PREPROCESS directive or the SQL directive.
   X - the XDB EXEC SQL preprocessor is to be invoked by
       the TX preprocessor
   G - the GUPTA EXEC SQL preprocessor is to be invoked by
       the TX preprocessor
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid SQL Support options in the sixth position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9017F Invalid Reusable Code Manager Support option = <r>

The seventh flag in the TX preprocessor options specifies whether Reusable Code Manager support is needed.

It must be one of the following characters (not case-sensitive):

   N - no RCM support is needed
   Y - the user has provided for RCM support by an
       explicit PREPROCESS directive.
   X - the RCM preprocessor is to be invoked by the TX
       preprocessor
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid RCM Support options in the seventh position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9018F Invalid Unsupported Function Action code = <f>

The eighth flag in the TX preprocessor options specifies the default action to be taken for an unsupported CICS API command.

It must be one of the following characters (not case-sensitive):

   A - Generate it to cause an Unsupported Function abend
       when the command is executed.
   N - Generate it as a "No-Op" API command.
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid Unsupported Function Action options in the eighth position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9019F Invalid Unsupported Option Action code = <o>

The ninth flag in the TX preprocessor options specifies the default action to be taken for an unsupported option on a CICS API command.

It must be one of the following characters (not case-sensitive):

   A - Generate the CICS API command to cause an
       Unsupported Function abend when the command is
       executed.
   N - Generate the CICS API command as a "No-Op" API
       command.
   I - Ignore the unsupported option (treat as comments)
       and generated the CICS API normally.
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid Unsupported Option Action options in the ninth position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9000 - COBEC9019


COBEC9020 - COBEC9039

  • COBEC9020F Invalid Codeset (ASCII/EBCDIC) option = <a>
    The tenth flag in the TX preprocessor options specifies the character set (codeset) to be used for the program.
  • COBEC9021F Invalid CONVERTPTR (Yes/No) option = <p>
    The eleventh flag in the TX preprocessor options specifies whether the CONVERTPTR compiler option is being used for the program.
  • COBEC9030W MCO <flag-name> option conflicts with COBOL <directive-name> directive
    The MCO Preprocessor option flag specifies a value which does not logically match the specified COBOL directives that are being used for the preprocess/check of the source program.
  • COBEC9031W Warning - "CPY" extension not specified in COPYEXT directive
    The copybook preprocessor, CP, uses the extensions specified by the COPYEXT directive to locate source copybooks.
  • COBEC9032W Warning - CP not available - copybook source not processed
    The copybook preprocessor, CP, could not be found.
  • COBEC9033W <preprocessor-name> request ignored - duplicates explicit PREPROCESS directive
    The <d>, <s>, or <r> flag in the TX preprocessor options requested the generated invocation of the named preprocessor, but an explicit PREPROCESS directive already specified a preprocessor of the same type (DLI, SQL, or RCM).
  • COBEC9034W CALL-RECOVERY illegal with MCO CICS - forced to NOCALL-RECOVERY
    The CALL-RECOVERY Checker directive may not be used with the MCO CICS preprocessor.
  • COBEC9035S CICSECM initialization error error-code
    An unexpected initialization error occurred.
  • COBEC9036S CICSECM licensing error error-code
    An unexpected licensing error occurred.
  • COBEC9037S No MSS license found
    You do not have a valid CICS license to perform this task.
Parent topic: COBEC - CICS API Preprocessor Error Messages


COBEC9020F Invalid Codeset (ASCII/EBCDIC) option = <a>

The tenth flag in the TX preprocessor options specifies the character set (codeset) to be used for the program.

It must be one of the following characters (not case-sensitive):

   A - ASCII character set (codeset)
   E - EBCDIC character set (codeset)
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid Character Set options in the tenth position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9021F Invalid CONVERTPTR (Yes/No) option = <p>

The eleventh flag in the TX preprocessor options specifies whether the CONVERTPTR compiler option is being used for the program.

It must be one of the following characters (not case-sensitive):

   Y - CONVERTPTR is specified in the compiler options
   N - CONVERTPTR is not specified
   0 - not specified
System Action:
Terminate the preprocess/check.
Resolution:
Correct the TX preprocessor options to specify one of the valid CONVERTPTR options in the eleventh position.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9030W MCO <flag-name> option conflicts with COBOL <directive-name> directive

The MCO Preprocessor option flag specifies a value which does not logically match the specified COBOL directives that are being used for the preprocess/check of the source program.
System Action:
The preprocess/check continues normally using the option/value specified by the COBOL directive instead of the option/value specified by the MCO preprocessor option flag.
Resolution:
Ensure that the correct COBOL directives and MCO preprocessor options are used and that they specify the same logical values.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9031W Warning - "CPY" extension not specified in COPYEXT directive

The copybook preprocessor, CP, uses the extensions specified by the COPYEXT directive to locate source copybooks.

Earlier releases of MCO used different defaults which can be equated to COPYEXT"CPY,cpy,CBL,cbl,". The default setting of COPYEXT on UNIX does not include the uppercase extensions which are required by MCO.

System Action:
The preprocess/check continues normally but may produce compilation errors if copybooks could not be located.
Resolution:
Ensure that the COPYEXT directive specifies all of the copybook extensions required by your programs. Refer to the MCO documentation for more information about preprocessor changes in this release which may affect the compilation/execution of your CICS programs.
Module:
cicsprep (dfhxc2pp)
Destination:
Source Listing, .TRL file, STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9032W Warning - CP not available - copybook source not processed

The copybook preprocessor, CP, could not be found.

The MCO preprocessor relies on CP to find and expand all copybook source so that any EXEC CICS statements, DFHRESP(...) and DFHVALUE(...) references, etc. can be processed by the MCO preprocessor. If no copybook contains any source that the MCO preprocessor needs to modify, then this message may be safely ignored.

System Action:
The preprocess/check continues normally but may produce compilation or execution errors if any copybook source contains lines that need to be processed by the MCO preprocessor.
Resolution:
Verify that your COBOL system meets minimum version requirements for this version of MCO. Verify that the COBDIR environment variable is set correctly. The CP preprocessor (CP.GNT) should be in CHECK.LBR in one of the directories specified by COBDIR.
Module:
cicsprep (dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9033W <preprocessor-name> request ignored - duplicates explicit PREPROCESS directive

The <d>, <s>, or <r> flag in the TX preprocessor options requested the generated invocation of the named preprocessor, but an explicit PREPROCESS directive already specified a preprocessor of the same type (DLI, SQL, or RCM).
System Action:
The preprocess/check continues normally but without generating the requested invocation.
Resolution:
Correct the TX preprocessor options or the string of PREPROCESS directives so that only one preprocessor of the given type is selected.
Module:
cicsprep(dfhxinit)
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9034W CALL-RECOVERY illegal with MCO CICS - forced to NOCALL-RECOVERY

The CALL-RECOVERY Checker directive may not be used with the MCO CICS preprocessor.

MCO CICS provides the necessary ability to force EXIT PROGRAM appropriately for CICS programs.

System Action:
The preprocess/check continues normally but with NOCALL-RECOVERY set.
Resolution:
Correct the directives to omit CALL-RECOVERY for MCO (CICS) preprocessed programs.
Module:
cicsprep(dfhxc2pp)
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9035S CICSECM initialization error error-code

An unexpected initialization error occurred.

Common error codes:

     1   -   DFHXECM0.DAT not found
     2   -   error opening DFHXECM0.DAT
     3   -   error reading DFHXECM0.DAT
System Action:
No CICS commands will be translated and the compiled program will be unusable.
Resolution:
Try to resolve the problem as indicated by the error-code and retry.
Module:
cicsecm
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9036S CICSECM licensing error error-code

An unexpected licensing error occurred.

Common error codes:

     1     -   Unable to open database
     2     -   Database corrupted
     3     -   License checksum failure
     4     -   License limit exceeded
     5     -   License limit exceeded
     6     -   Product not licensed
     7     -   Unknown license failure
     8     -   License DB too large
     9     -   Heap error
     10    -   Cannot contact License manager
     11    -   Message send failure
     12    -   Message receive failure
     13    -   Returned checksum failure
     14    -   Integrity check failure
     15    -   License limit exceeded - no overdraft
     16    -   License limit exceeded
     17    -   License limit exceeded
     98    -   User tampering with license system
     100   -   User tampering with license system
System Action:
No CICS commands will be translated and the compiled program will be unusable.
Resolution:
Try to resolve the problem as indicated by the error-code and retry.
Module:
cicsecm
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


COBEC9037S No MSS license found

You do not have a valid CICS license to perform this task.
System Action:
No CICS commands will be translated and the compiled program will be unusable.
Resolution:
Contact Micro Focus or your sales representative.
Module:
cicsecm
Destination:
STDOUT
Parent topic: COBEC9020 - COBEC9039


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
  • Exit When a Trace Switch Occurs in an Enterprise Server Region
    The BKAUXTRC exit will be called when a trace switch occurs in the enterprise server region.
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


Exit When a Trace Switch Occurs in an Enterprise Server Region

The BKAUXTRC exit will be called when a trace switch occurs in the enterprise server region.
The current aux trace will be closed and renamed to .bkp and the BKAUXTRC exit is then called to archive the file so that traces are not lost in a busy system. The exit will be passed the full name of the file that has been closed ready to archive on the command line.
Note: You must enable the switch by adding it to the path.

Syntax:

BKAUXTRC

On Entry:

The exit is started with a command line that contains the name of the backup file with its location.

On Exit:

Nothing.

Return codes:

No return codes.

Example

The following sample program shows the COBOL code used with the BKAUXTRC exit:

        01 ws-command-line.
          03 ws-command-line-size pic x(2) comp-x.
          03 ws-command-line-data pic x(256).
        01 ws-reply pic x.
        procedure division.
          accept ws-command-line-data from command-line
          *> do what you need to do to archive the file
          goback.
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


Enterprise Server Security

Contains information and procedures for all aspects of securing an Enterprise Server installation.
  • Default Enterprise Server Security Configuration
    An introduction to how Enterprise Server is secured upon installation
  • Securing an Enterprise Server Installation
  • Enterprise Server Auditing
  • Securing Communications
    The topics in this section describe the process of using SSL and PKI certificates to secure Enterprise Server communications.
  • Multi-Factor Authentication
  • Vault Facility
    Describes the vault facility, which enables the Micro Focus Directory Server (MFDS) to keep certain sensitive information in a form of storage defined as a vault.
Parent topic: Enterprise Server
Related concepts
User Impersonation for CICS and JCL
Related information
Security Considerations (Known Issues)


Default Enterprise Server Security Configuration

Beginning with release 10.0, a basic security configuration is included with Enterprise Developer and Enterprise Server and enabled as part of product installation. This configuration requires users authenticate to Enterprise Server, including Enterprise Server Common Web Administration (ESCWA), and be authorized to perform various actions.

The default security configuration is comprised of the following elements:

  • The VSAM ESM Module, which implements an External Security Manager (ESM) using a set of COBOL indexed files. The VSAM ESM Module was introduced in release 9.0 as an Early Adopter Program (EAP) feature. It is now a regular feature of the Visual COBOL, Enterprise Developer, and Enterprise Server products.
  • A set of security definitions (users, groups, and resource access rules) for the VSAM ESM Module, based on the sample security configuration for LDAP which is also supplied with Enterprise Server. These definitions are supplied with the product as a YAML file, and during installation are used to create a set of security-data files for the VSAM ESM Module in a standard location.
  • An External Security Facility (ESF) Security Manager definition in ESCWA which uses the VSAM ESM Module and the supplied default security data. On installation, ESCWA is configured to use this Security Manager.
  • A similar ESF Security Manager definition in MFDS. The MFDS Default ES Security is set to use this definition, and MFDS itself is set to use Default ES Security as its security configuration.
  • Credentials for the administration user account SYSAD and a limited-access account readonly in the default Micro Focus Secrets Vault. Passwords for these two accounts are created at installation, so they are different for each product installation. See Getting Started with Default Enterprise Server Security for instructions on retrieving these credentials.
  • Utilities for disabling and recreating the default security configuration.

For product reinstallations or upgrades, if security data already exists, default security will not be enabled. Your existing security definitions will be preserved.

Note: Micro Focus recommends backing up security and other configuration data before reinstalling or upgrading.
  • Getting Started with Default Enterprise Server Security
  • Why does Enterprise Server have a default security configuration?
    Explains the motivation for the default security configuration
  • To Disable the Default Enterprise Server Security Configuration
    Follow these instructions to disable the default Enterprise Server Security Configuration. This can be done at any time after product installation, if the default security configuration is in effect.
  • To Recreate the Default Enterprise Server Security Configuration
    Follow these instructions to recreate the Enterprise Server Default Security Configuration, if you have disabled it and wish to restore it, or to reset security to the default.
  • User accounts in the Default Enterprise Server Security Configuration
    Users that are defined in the default security configuration
Parent topic: Enterprise Server Security
Related concepts
To Recreate the Default Enterprise Server Security Configuration
Related reference
Enterprise Server Security Considerations


Getting Started with Default Enterprise Server Security

After installing Enterprise Developer or Enterprise Server, you should retrieve the administration credentials that were generated at installation time from the vault. You will need these for most Enterprise Server activities.

Note: Micro Focus recommends you make a note of the administration username and password, and then delete them from the vault and/or change the password, as described below.

To retrieve the administration credentials:

  1. You will need an interactive session (Windows command prompt, UNIX/Linux shell) on the target system. Remember that the installer creates a unique password for each product installation.
  2. Set your session up with the product environment. Open an Enterprise Server command prompt on Windows, or source the cobsetenv script on UNIX. On UNIX, you may need to be running as either the Enterprise Server account (as specified when installing the product) or root, in order to have read access to the vault.
  3. Run mfsecretsadmin read microfocus/temp/admin. You should receive output similar to:
    {"mfUser":"SYSAD", "mfPassword":"abcd1234"}

    The username will always be SYSAD. Note down the generated password.

  4. Connect a browser to ESCWA using http://hostname:10086, where hostname is localhost if you are running on the same system as ESCWA, or the remote system's hostname otherwise. You will be prompted to sign on. Enter the username and password from step 3 to confirm they work.

    You change the password using the following options:

    • Before you log on to ESCWA, on the splash screen, click Change Password and complete the login details, confirm the new password and click Submit.
    • In ESCWA, click Security from the menu bar. In the navigation panel, expand ESCWA Configuration and then expand your security manager, then click Users. In the SYSAD row, click the Edit icon. This opens the Properties dialog box. Type a new password and then click Save.
  5. Optional: Delete the admin credentials from the vault using this command:
    mfsecretsadmin write -overwrite microfocus/temp/admin
    Note: If you delete the SYSAD user or change the password generated for it by the installer in the default VSAM Security Manager, you need to provide new sufficiently authorized credentials for the Server Explorer connection.
  6. Optional: Disable, delete, or change the password of the test user accounts SAFU, mf_mdsa, and SAFUIMS. These accounts exist for backward compatibility and are used by some tutorials, but have a known password and so entail a certain amount of risk. You can modify or remove the accounts using ESCWA's Security page, by selecting the security manager under ESCWA Security Configuration in the navigation pane.
  7. Optional: Disable, delete, or change the passwords of the system accounts mf_cs and mf_dep. See User accounts in the Default Enterprise Server Security Configuration for more information.

Alternatively, you can disable the Default Enterprise Server Security configuration. You can do this at any time. See To Disable the Default Enterprise Server Security Configuration for more information.

Parent topic: Default Enterprise Server Security Configuration
Related concepts
Enterprise Server Security Considerations
Default Generated Password for SYSAD
User accounts in the Default Enterprise Server Security Configuration
Related reference
User accounts in the Default Enterprise Server Security Configuration


Why does Enterprise Server have a default security configuration?

Prior to release 10.0, the Visual COBOL and Enterprise Server products supported application security, but did not enable most security features by default. In particular, users were not required to authenticate to Enterprise Server components such as ESCWA, or to be authorized to use various product features.

A growing consensus in the information-technology industry sector is that software security should be enabled by default. It is increasingly proving to be dangerous to deploy software systems without adequate security mechanisms. Government regulators and industry standards bodies are imposing more security requirements for both developing and deploying software.

Security is a particularly pressing concern for a software system like ESCWA which exists to enable creating and executing custom programs, often remotely. A compromised enterprise server instance can often be used to do anything permitted by the operating system. Enterprise Server also has many features, which means it has a large attack surface.

Some people might believe that as long as production systems are secured, it is less important to secure developer systems. Unfortunately, developer systems are a highly desirable target for attackers. Since developers are creating software that will be used either internally or by customers of the organization, an attacker might use a compromised developer system to spread malware within the company and/or to its customers. Developer systems have tools which are useful for advanced attacks such as living off the land, in which no malware files need to be installed by the attacker, which makes detection more difficult and creating backdoors in other systems for persistent access to organizational systems. Developers often work with elevated permissions, giving attackers more leverage, and have access to other prized targets such as CI/CD systems.

For all these reasons, Micro Focus has elected to enable a basic security configuration for Enterprise Server upon product installation, so it is secured as soon as it is installed. This security configuration can be removed or replaced, of course, but Micro Focus strongly recommends that you use the product security features in both development and production environments.

Parent topic: Default Enterprise Server Security Configuration


To Disable the Default Enterprise Server Security Configuration

This procedure requires an interactive session on the system where you can disable the default Enterprise Server security configuration, set up with the Enterprise Server environment. On Windows, you will need permission to stop and start services. On UNIX, you will need permission to alter files such as commonwebadmin.json in the product configuration area.
Beginning with release 10.0, Enterprise Developer and Enterprise Server are installed with security enabled, using a basic default security configuration. If you want to use a different security configuration, or want to disable security entirely, follow this procedure to disable the default security configuration.
Note: Micro Focus does not recommend running Enterprise Developer without security enabled. See Why does Enterprise Server have a default security configuration? for more information.
  1. Run the command DisableESDefaultSecurity.cmd. You will see a series of messages as the script disables default security.
  2. Restart any running enterprise server region to have them pick up the configuration changes. Regions will no longer require credentials for starting/stopping and other actions.
c:\>DisableESDefaultSecurity.cmd
Micro Focus DisableESDefaultSecurity utility: Version 1.0.0

MFDS is using ES Default Security, attempting to disable.
MFDS mfdsacfg.xml backup file created C:\ProgramData\Micro Focus\Enterprise Developer\20240307164321_mfdsacfg.xml
MFDS esm.dat backup file created C:\ProgramData\Micro Focus\Enterprise Developer\MFDS\20240307164321_des_esm.dat
MFDS is no longer using ES Default Security.
ESCWA is using ES Default Security, attempting to disable.
ESCWA commonwedadmin.json backup file created C:\ProgramData\Micro Focus\Enterprise Developer\ESCWA\20240307164321_commonwebadmin.json
ESCWA is no longer using ES Default Security.
Backed up secret "microfocus\temp\admin" to "microfocus\temp\admin.disabled"
Backed up secret "microfocus\common\readonly" to "microfocus\common\readonly.disabled"
Parent topic: Default Enterprise Server Security Configuration
Related concepts
Samples and Tutorials


To Recreate the Default Enterprise Server Security Configuration

This procedure requires an interactive session on the system where you require to re-enable the default Enterprise Server security configuration, set up with the Enterprise Server environment. On UNIX or Linux, you need to be running under the Enterprise Server system user account you specified during product installation, so that file ownership and permissions will be correct. If you have security enabled for ESCWA or MFDS, you will need credentials for administrative access to those systems:
  1. Run the command mfsecconv reset. This command performs the following actions:
    • The security data for the VSAM ESM Module in the default location is initialized using es_default_security.yaml, which is supplied with the product. Any existing VSAM ESM Module security data in the default location is overwritten.
    • A new password is generated for the default administrator user account, SYSAD. A verifier (secure hash) for the password is written to the user record in the VSAM ESM Module security data, and the username and password are written to the default Micro Focus Vault Facility under microfocus/temp/admin. See Getting Started with Default Enterprise Server Security for more information about credentials in the vault.
    • A new password is generated for the limited-access user account, readonly. A verifier for it is written to the VSAM ESM Module user record, and the username and password are written to the vault under microfocus/common/readonly.

    mfsecconv reset takes various options. Run mfsecconv reset -help or consult the reference information for mfsecconv in the product Help for more information.

    Note: If you are already using the VSAM ESM Module with the default security data location for ESCWA or MFDS security, running this command will invalidate your existing administrator access. You will have to get the new password for SYSAD from the vault before continuing.
  2. Run the command mfsecretsadmin read microfocus/temp/admin and record the password for the SYSAD user that is displayed. You will have the password you need for administrative access to Enterprise Server as you re-enable security.
  3. Connect a browser to ESCWA, typically using http://localhost:10086.
  4. Select Security in the ESCWA menu bar. The ESCWA security page is displayed.
  5. Select Security Managers in the navigation panel. If a manager named OoB using the vsam_esm module is listed, skip the next step and proceed to step 7. ("OoB" stands for "Out-of-Box", an earlier name for the Default ES Security feature.)
  6. Click + Add to create a new Security Manager. Set the Name to OoB (or another name of your choice) and the Module to vsam_esm. The other fields may be left with their default values. Click Save to save the security manager. Your new security manager is displayed in the list of managers.
  7. Select ESCWA Configuration in the navigation pane. The ESCWA security configuration is displayed.
  8. If any security managers are listed at the bottom of the configuration, use the – icon next to each one to remove it.
  9. Click + Add and select the OoB security manager (or the one you created in step 6, if you gave it a different name). Click Select to save your choice. The Default Enterprise Security security manager is added to ESCWA's security configuration.
  10. Click the checkbox for the Use All Groups option. This option is enabled in the default security configuration to make it easier to use and operate in the way most users expect. Ensure the check boxes for Allow unknown resources and Allow unknown users are not checked.
  11. Click Apply to save the changes to the ESCWA security configuration. You will be prompted to sign in. Use the username SYSAD and the password you retrieved in step 2. ESCWA is now secured using the default security configuration.
  12. Click Native in the ESCWA menu bar. Under Directory Servers in the navigation pane, select your local MFDS instance. This is usually the only directory server listed; if not, it will probably be named local or something similar. The enterprise server region and server list for the directory server is displayed.
  13. Click Security > Security Managers from the directory server menu bar (below the ESCWA top menu bar). If a security manager named VSAM ESM is displayed, skip the next step and proceed with step 15. The list of security managers defined in the directory server is displayed.
  14. Click + Add to create a new security manager. Set the Name to VSAM ESM (or another name of your choice) and the Module to vsam_esm. The other fields may be left with their default values. Click Save to save the security manager. Your new security manager is displayed in the list.
  15. Click Security > Default ES Configuration from the directory server menu bar. The default ES security configuration for the directory server is displayed.
  16. If any security managers are listed at the bottom of the configuration, use the – icon next to each one to remove it.
  17. Click + Add and select the VSAM ESM security manager (or the one you created in step 14, if you gave it a different name). Click Select to save your choice. The security manager is added to the Default ES security configuration.
  18. Check Use All Groups.
  19. Click Apply to save the changes to the Default ES security configuration. Enterprise server instances will now use the default security configuration, once they have been restarted.
  20. Click Security > Directory Server Configuration from the directory server menu bar. The directory server security configuration is displayed.
  21. Check Use ES Default Security Managers and click Apply. If you are prompted to sign into the directory server using credentials for the old security configuration, use the username SYSAD and the password SYSAD
  22. Check Restrict Directory Server Access and click Apply. You will be prompted to sign into the directory server using credentials for the new security configuration. Use SYSAD and the password from step 2. The directory server is now secured using the default security configuration.
Enterprise server instances will only start using the new security settings when they are restarted. You will need to use the administrator credentials (SYSAD user and the password you noted in step 2) for actions such as starting and stopping regions. You can use ESCWA to add more users, change passwords, and perform other security administration tasks.
Parent topic: Default Enterprise Server Security Configuration
Related concepts
Samples and Tutorials
Related reference
Default Enterprise Server Security Configuration


User accounts in the Default Enterprise Server Security Configuration

A number of user accounts are included in the default Enterprise Server security configuration. Some are intended for interactive use; others are special-purpose accounts used by the system. This topic lists the predefined user accounts and explains how they are used.

Note: The default security configuration enables all-groups mode for ESCWA, MFDS, and enterprise server instance, by selecting the Use All Groups option in each security configuration definition. In all-groups mode, users have the permissions of all the groups they belong to, and the optional sign-on group field on the various sign-on screens is ignored. All-groups mode simplifies security definitions and user actions, and is similar to how group security works on Windows and UNIX.
The predefined users are:
SYSAD
This is the default administrator. During product installation, a random 8-character password is generated for SYSAD which is written to the default Micro Focus Secrets Vault. You can run mfsecretsadmin read microfocus/temp/admin to retrieve this password. See Getting Started with Default Enterprise Server Security for more information.

If you run mfsecconv init or mfsecconv reset manually to restore the default security definitions, you can specify different or additional administrator user accounts, and optionally specify passwords for them. See The mfsecconv Command for more information.

readonly
This is a user account which has limited access. During product installation, a random 8-character password is generated for it and written to the vault. You can run mfsecretsadmin read microfocus/common/reaodnly to retrieve it.

This account can be used interactively. For example, to give someone permission to check the status of system components but not to make changes. It is also used by default by some Enterprise Server components to retrieve information about a running enterprise server instance so they can communicate with it. The Micro Focus Common Client and the Host Access for the Cloud included with Enterprise Developer will both use this account by default.

CICSUSER
This is the system default user account for Enterprise Server MSS CICS. It is not possible to explicitly sign on interactively as this user (in the default security configuration).
JESUSER
This is the system default user account for Enterprise Server MSS JES. It is not possible to sign on interactively as this user.
IMSUSER
This is the system default user account for Enterprise Server MSS IMS. It is not possible to sign on interactively as this user.
mfuser
This is the system default user account for the ESMAC (Enterprise Server Monitor and Control) Web API. It is not possible to sign on interactively as this user.
PLTPISUR
This is the system user account used for processing enterprise server region startup tasks. It is not possible to sign on interactively as this user.
SAFU
This is a test user account. For historical reasons, this account can be used interactively and has some permission to use various resources, and initially has the password test.
Note: Micro Focus recommends disabling the SAFU user account or changing its password. You can do this in ESCWA.
SAFUIMS
This is a test user account for IMS. Like the SAFU account, it has a known password of test.
Note: Micro Focus recommends disabling the SAFUIMS user account or changing its password.
mf_cs
This is a system account which is used by MFCS to bind to MFDS if MFCS is started without specifying other credentials. Typically this is because an enterprise server instance was started without specifying credentials. If an enterprise server instance is started with credentials, those will be passed to all MFCS communications processes running under that instance.
Note: Micro Focus recommends disabling this account or changing its password to improve security. If the account is disabled, MFCS will not be able to start without credentials (but with security enabled, enterprise server instance need credentials to start anyway). If the password is changed, MFCS will not be able to start without credentials unless the new password is provided in the mf-server.dat file.
mf_dep
This is a system account which is used by default by the COBOL Web service and EJB installation program, mfdepinst.
Note: Micro Focus recommends disabling or deleting this account. If COBOL Web services and EJBs are being used, a different account should be created for service installation. See Security Considerations for Service Interface Deployment.
mf_mdsa
This is a system account which is used by casstart to bind to MFDS if no credentials have been specified.
Note: Micro Focus recommends disabling this account or changing its password to improve security. If the account is disabled or the password changed, casstart will not be able to start without credentials. However, with security enabled, an enterprise server instance require credentials to start.
Parent topic: Default Enterprise Server Security Configuration
Related concepts
Getting Started with Default Enterprise Server Security
Related reference
Getting Started with Default Enterprise Server Security
The mfsecconv Command
Security Considerations for Service Interface Deployment


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
  • VSAM ESM Module
  • JES Security
  • 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
  • To Secure Access to Enterprise Server Logs
    Use these security settings to restrict access to the Enterprise Server console and communications logs through the web administration interfaces.
  • Security Considerations for Service Interface Deployment
    Describes Enterprise Server security issues introduced by service interface deployment, provides procedures for configuring deployment security in Enterprise Server, and provides deployment access recommendations.
  • DCAS Security
  • Security Reference Information
  • Using External Security Facility (ESF) Features
  • Glossary
  • PAM ESM Module
    The PAM ESM Module lets you use the Pluggable Authentication Modules (PAM) mechanism as an External Security Manager (ESM) for Enterprise Server.
Parent topic: Enterprise Server Security
Related information
The Directories Page


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

Communication flow among components involved in securing an installation

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.

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 referred 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.
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.
pam_esm
On Linux, this security manager provides access to the Pluggable Authentication Modules (PAM) framework. You can use it to authenticate Linux users.
vsam_esm
This security manager provides authentication and authorization using security data stored in COBOL indexed files. It is a simpler alternative to mldap_esm if you do not need a central repository of security data or some of the advanced features of mldap_esm. As of the 10.0 release, it is used to implement default security when the product is installed fresh, not upgraded from a previous release. See The Default Enterprise Server Security Configuration for more information.
MFDS Internal Security
Directory Server security can be implemented through 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 enables you to specify users and groups, and restrict access to Enterprise Server administration functions.
Note: MFDS Internal Security is now deprecated.Micro Focus recommends you use a security manager with vsam_esm instead.
CASESM
The CAS ESM Module (casesm) uses the Enterprise Server legacy security definitions which are stored in the CICS resource tables. This is the model used in Net Express or Server Express 5.0 and earlier.

This enables you to use any security configurations from Net Express or Server Express prior to release 5, which uses the current architecture.

Note: casesm can only be used within CAS and the CAS command-line utilities, and is ignored by MFDS, MFCS, and any non-CAS utilities such as esfadmin.

casesm is now deprecated.Micro Focus recommends you use a security manager with vsam_esm instead.

In addition to the above, security managers can be anything that processes the API security queries that the ESF generates, and that 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
Related reference
PAM ESM Module


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 behavior 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 from the list
  • To Edit a Security Manager's Properties
Parent topic: Configuring Enterprise Server Security


To Add or Remove a Security Manager from the list

To add or remove a security manager from the list in ESCWA perform the following steps:

  1. In the menu bar, click Security. This displays the Defined External Security Managers page.
  2. Click + Add. This opens the External Security Manager Configuration dialog box.
  3. Specify the details of the External Security Manager (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.
    Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
  4. Click Save.

    The ESM is added to the list and is available for use in your configurations.

To remove an ESM from the list, click Remove at the end of the row.
Parent topic: Adding a Security Manager to the Pool


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 Test Server\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.

    Most ESM Modules ignore this parameter. It is supported by the MLDAP 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.

    Most ESM Modules ignore this parameter. It is supported by the MLDAP 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


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.

  • Security Configuration Custom Configuration Information
Parent topic: Customizing the Security Settings for an Enterprise Server Instance


Security Configuration Custom Configuration Information

Each security configuration for MFDS, ES Default Security, or a particular enterprise server instance support additional configuration that can be set by modifying the text in the Configuration Information field. Text in this field is organized into sections which begin with a tag label in square brackets, followed by lines containing name-value pairs.

You can add these settings in the Configuration Information field for the security configuration, and not a Security Manager. Security Managers also have a custom configuration setting, with parameters defined by the External Security Manager module they use. See the documentation for the specific ESM module for more information.

The following are the configuration sections, and the options that can be set in each section:

[Admin] section

allow-list=yes | no
If this is set to yes, then Admin LIST requests, for example, list users, groups, and resource access rules are allowed for all users, with no additional access check.

[Audit] section

category 3 events=yes | no
Setting this option disables audit category 6 events for SAF Auth and XAuth calls, and enables category 3 events for Verify, Auth, and XAuth calls. This option is provided for backwards compatibility.

The default value is no.

password change success = yes | no
Setting this option enables an extra audit event for every successful password change.
Note: Password change rejections and related errors are always audited. See Audit event 6 2 in Audit Event Codes for more information.

The default value is no.

selective=yes | no
This setting enables the optional selective-auditing feature. It has no effect if auditing is not enabled.

When selective auditing is enabled, auditing for normal ESF requests is suppressed unless the AUDIT flag is set in the request, or an ESM Module determines that the particular request should be audited. The flag can be set by the caller. Currently, only the MLDAP ESM Module performs selective auditing. If a user, group, or resource access rule object contains the optional LDAP Boolean attribute microfocus-MFDS-Audit, and the value of the attribute is TRUE, then requests pertaining to that object will be audited. For example, if a user is defined in LDAP with microfocus-MFDS-Audit set to TRUE, and selective auditing is enabled, then any request pertaining to that user - a Verify request signing the user on or an Auth request for resource access on that user's behalf - will be audited.

The default value is no.

[Cache] section

flush on change=yes | no
Set to yes to tell the cache to discard any cached Verify result if it receives 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.
ignore=list of request fields
When the ESF cache checks to see whether the request it is currently processing matches a cached request, it will ignore the fields listed in this configuration entry when comparing them. That means the cached result will be used even if the current request and the cached request differ in one of more of the listed fields. This is useful if the fields in question do not change security decisions in your environment.

The list can be zero or more field names, separated with whitespace and/or commas.

Currently the fields that can be included are:

subsystem
The Enterprise Server subsystem, such as CICS or IMS.
subsys
An alias for "subsystem".
facility
The facility, which is usually a terminal name or other input source.
transaction
The transaction name, for subsystems where this is relevant.
trans
An alias for "transaction".

Currently no ESM Modules make use of any of these fields when making security determinations, so it is safe to ignore any or all of them.

The default values are subsystem, facility. Transaction is not ignored by default because it is one of the most likely to be encountered in custom ESM Modules.

report interval=seconds
You can configure how often 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.
requests=list of request types
This setting specifies what type of ESF requests can be cached. It is set to a list of tokens, separated by commas or spaces. See Requests for a full list of possible tokens.
tracing=integer
Controls trace messages from the ESF cache. If this is set to 0, tracing is disabled. Positive values enable progressively verbose trace information; currently values 1-5 are supported.

The default value is 0.

See the chapter ESF Caching for more information.

[Operation] section

failover retry interval=seconds | never
This option changes the behavior of redundant mode. It is ignored if redundant mode is not enabled. See the redundant setting below for more information. By default, when redundant mode is enabled, failing Security Managers are retried on every request when they would normally be invoked. This might cause performance issues if a failed manager takes a long time to respond.

If this option is set to a positive number, a failed Security Manager only retries when at least that many seconds have elapsed since it failed.

If this option is set to 0 or never, a failed Security Manager is disabled until ESF is reinitialized or the process is restarted.

federate=yes | no | compatible
Control the federation of group information among Security Managers. See Security Federation for more information. This only has an effect if more than one Security Manager is configured.

The default value is compatible for product versions through to 8.0, and yes for 9.0 and later. Micro Focus recommends setting it to yes if multiple Security Managers are used.

password case=upper | lower | preserve
Fold passwords to upper or lower case when processing Verify requests, or leave them as supplied. The default value is preserve.
protect sensitive data=yes | no
If enabled, sensitive data such as passwords are obfuscated in memory to help prevent its disclosure.

The default value is yes. This should only be disabled if an issue is suspected with sensitive data protection.

redundant=yes | no
If this option is set to yes, you can configure multiple equivalent Security Managers and let processing continue as long as at least one Security Manager is available. By default, if any Security Manager returns an error during initialization or security request processing, the request fails. If redundant mode is enabled, initialization and request processing only need one successful Security Manager.

The default value is no.

trim whitespace=yes | no
If enabled, leading and trailing whitespace in any of the character-string fields of an ESF request will be removed. This is useful if requests are likely to contain extraneous whitespace.

The default value is yes. This should only be disabled if an issue is suspected with whitespace trimming.

update interval=seconds
If this is set to a positive number, ESF waits at least that many seconds between checks for administrative update notifications. Update notifications are used to tell ESF that security information has changed and it should discard cached data and update information it has stored about users and groups. This check might affect performance under heavy loads, in which case setting an update interval can improve performance, at the cost of ESF taking more time to recognize that security information has been changed.
user exit=module-name
Configure a user exit module. See ESF User Exit for more information.
userid case=upper | lower | preserve
Fold (force) userids, also known as usernames, to upper or lower case when processing Verify requests, or leave them as supplied. The default value is preserve (do not alter userids).
username case=upper | lower | preserve
A synonym for userid case. If both are set, the userid case setting takes precedence.
verify throttle threshold=integer | none
Set this to specify at what point verify throttling is activated, or to disable verify throttling. If the value is a positive integer, it represents the maximum number of Verify requests that will be accepted within one second before the process starts throttling (imposing a delay) on them. This makes it more difficult to guess valid credentials by brute force.
Note: In an enterprise server instance Verify requests are typically processed by SEPs, so the effective threshold is actually this value times the number of regular SEPs available.

If the value is negative or zero, or the word none, then throttling is disabled.

The default value is 100.

[Passtoken] section

allow=none | generate | signon | both | yes
Specifying none disables pastokens, generate enables passtoken generation but not their use, signon enables passtoken use for signon but not generation, both enables both generation and signon, and yes which is a synonym for both.

See Passtoken Options for ESF Manager for more information.

[Trace] section

name mapping=yes | no
If enabled, trace messages are logged during name-mapping operations.

The default value is no.

[Verify] section

map short names=yes | no
If enabled, when a request to Verify (authenticate) a user is submitted with a username that is no more than 8 characters long, ESF will first attempt to map this to a "long name" (ESM username). If that is successful, the long name will be used in place of the name provided in the request. This option is useful when name mapping is enabled, because some Enterprise Server facilities do not permit entering long names, and have to use Enterprise Server mainframe-style 8-character userids ("short names") instead. These include the CICS CESN and CESL transactions and the USER parameter on the JCL job card.

The default value is no. Micro Focus recommends you enable this feature if you use name mapping.

Parent topic: To Set Security Configuration Options for an Enterprise Server
Related reference
Using Flush on Change
Requests
ESF Caching
ESF User Exit
Passtoken Options for ESF Manager


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 (ESM) 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 Common Web Administration (ESCWA) 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

The following lists the available options, actions, and their description:

Option | Action | Description
-a action The update action to perform can be one of the following:
  • add
  • delete
  • modify
  • other
The default value is modify.
-u | user | The username or secret location for binding to Directory Server.
-p | password | The password or secret location for binding to Directory Server.
-m | host[:port] | The location of Directory Server. The default location 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 exits.
-h | Displays syntax information and exits.
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.

If the update-type is user, and you are using name mapping, you can supply the short name (Enterprise Server userid) of the user to be updated. With the MLDAP ESM Module version 2.5.27 (for Enterprise Server 5.0), 2.7.9 (for Enterprise Server 7.0), or 2.8.0 or later, you can also use the long name (ESM username).

Comments

If user and password are not supplied, esfupdate attempts to bind to Directory Server anonymously.

If user is supplied but not the 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 Server 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
The following example uses the Micro Focus Vault Facility to obtain a secret:
esfupdate -u mfsecret:admin/username -p mfsecret:admin/password all
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 Test 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.
  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.
Note: esfadmin is a generic utility which accepts a wide range of options and values, not all would be available to all security managers. This can result in requests failing, depending on the configuration of the security manager that is being used.
  • 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 ESM Module. This is a text file, in the same format as the Configuration Information field 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 is being used to sign on to the ESF. The default value is SYSAD.

Usage:

esfadmin -uSYSAD
-pESF password.
The associated password. The default value 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 prompts for the ESM username. For LIST commands, esfadmin lets the ESM module use its default credentials.

Note: You must supply this username, either with -U or when prompted, even if the security manager does not require it. For VSAM ESM Module you can use any username and password.
-PESM password
The associated password.

If this is not supplied, then for commands other than the LIST commands, esfadmin prompts for a password.

-Sserver URL
Specifies the connection path for the ESM module. For MLDAP ESM Module, this is the URL of the LDAP server. For VSAM ESM Module it is the path to the data file directory.

Usage:

esfadmin -S ldap://adhost
Note: You can specify a value up to 256 characters in length.
-ooptions file
Specifies the relative or absolute path and file name that contains the options to be used with the esfadmin command. Values containing spaces must be quoted. Options must be delimited with spaces and/or newlines.

The options file can contain any esfadmin options and positional parameters, except -o. An options file can be combined with command-line options. Parameters from the options file and the command line will be combined in the order they appear on the command line.

The options file is typically used to contain sensitive data such as the ESM password, or to simplify scripting a set of commands.

Note: The options file path and file name is limited to 256 bytes.
-Mmodule
Specifies the ESM module. The default is mldap_esm. Use -Mvsam_esm to specify the VSAM ESM Module.

The sub commands are:

  • ADDACE, ALTACE, DELACE
  • ADDUSER, ALTUSER, DELUSER, LISTUSER
  • ADDGROUP, ALTGROUP, DELGROUP, LISTGROUP
  • ADDCLASS, ALTCLASS, DELCLASS, LISTCLASS
  • ADDMEMBER, DELMEMBER
  • ADDRESOURCE, ALTRESOURCE, DELRESOURCE, LISTRESOURCE
  • LISTREFERENCES
  • 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 must be entered without spaces between the keyword, the equal sign, and the value. Values that contain spaces or other special characters must 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 reference
Long Usernames and Passwords
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, ADDMEMBER, or DELMEMBER 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.

  • Currently, only one ESM Module (specified with the -M option) can be used by esfadmin. It cannot use a "stacked" security configuration.
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
Long Usernames and Passwords


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-A2 argon2 verifiers). 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.
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.
CNSSTNT=NO
This parameter name is an abbreviation of the word "consistent". It disables locking the ESF group list while computing group membership. This introduces a small chance of returning inconsistent results for the user's group list, but it improves performance and enables multiple LISTUSER commands to run in parallel. This option has no effect if the parameter COMPUTED=NO is specified, this is because the group membership is omitted.

Inconsistent results will only occur if LISTUSER overlaps with the initial Verify operation for the same user, with an ESF Update operation which changes the user's group membership, or with an ESF Admin ALTGROUP, DELGROUP, or ALTUSER operation which happens to affect the group entry LISTUSER is currently examining. The most likely result is the appearance of an empty group name in the returned results.

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-A2 argon2 verifiers).
Parent topic: esfadmin Sub-commands


Using the MFDS Internal Security Module

Note: Micro Focus strongly recommends that you do not use MFDS Internal Security in a production environment. An External Security Manager such as the MLDAP ESM should be used instead. The MFDS Internal Security feature will be deprecated in a future release of this product.

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 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. 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
  • MLDAP ESM Module Caching
  • Using All Groups to Which a User Belongs
  • Federation in the MLDAP ESM Module
  • Understanding passwords with LDAP-based security
  • Changing passwords with the MLDAP ESM Module
  • MLDAP ESM Module Bind Rejection Heuristics
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.

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 the following 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.
.** | Depending on configuration, this may be treated as a wildcard matching the empty string or any string starting with "."; or it may be treated as "**" if it appears at the end of a name. See MLDAP ESM Module Custom Configuration Information for more information on setting the dss-wildcard option in the module configuration.
% | 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 percent-wildcard option. See MLDAP ESM Module Custom Configuration Information for more information on setting the percent-wildcard option in the module configuration.

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 exists. See Match Rank for more information.
  • 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 exists in that ACL. See Match Rank for more information.
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, USER.${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.
  • The token ${user_long} will be replaced with the user's long name. See Long Usernames and Passwords.

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 USER.${user}.** will take precedence over one named USER.*.** 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 substitutions=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 USER.**, while denying other users access to them:

dn: CN=USER.${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: USER.${user}.**
description: Allow full access to user's own area

dn: CN=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:*:none
microfocus-MFDS-UID: USER.**
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
Related reference
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, 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 determine the users access.

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 data sets) applies to all resources of that class. See Wildcards for Resource, User, and Group Names for more information.

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 determines the result of a particular request. A more specific rule that matches the request should take precedence. 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 determine 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.) You might want to use the new algorithm for its improved behavior and performance, and possibly for new features that require it. However, if you use complex, ambiguous resource access control rules you might, in rare cases, notice different results for some authorization queries when 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 data set 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 data sets under the DEV top-level qualifier, and update access to all data sets with ALICE as the final qualifier. What happens if Alice tries to update the data set DEV.PROJ1.ALICE.NOTES?

Of the two rules, the second (**.ALICE.*) matches that data set name more completely, because it matches more literal characters. Under the version 1 algorithm the module applies the first rule, because it returns it first when searching for applicable rules. That means Alice does not have update access to the data set. Using the version 2 algorithm, the module returns 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 is applied, and Alice is granted update access.

You can specify configuration options that can modify the exact behavior of the version 2 algorithm. See the Operation section of MLDAP ESM Module Custom Configuration Information for more information.

  • 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 typical default 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 (DN). 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
The size of the LDAP search-result cache, in kilobytes. If this is set to 0, LDAP search-result caching is disabled.
Cache TTL
The Time To Live (TTL) or lifetime of entries in the LDAP search-result cache, in seconds. If this is set to 0, LDAP search-result caching is disabled.
  • MLDAP ESM Module Custom Configuration Information
Parent topic: Module Configuration
Related concepts
ESM Module Configuration


MLDAP ESM Module Custom Configuration Information

The MLDAP ESM Module 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.

The following list the various configuration sections, and the options that can be set in each section:

[Auth] section

audit rule=yes | no
When this setting is enabled, and the Security Manager is able to satisfy an Auth or XAuth (resource access permission) request, it generates an audit event describing the effective rule - the security rule which was used to make the decision.

The audit event has category code 100 and event code 1. It includes:

  • The Security Manager index and name.
  • The module name ("mldap_esm").
  • The Username.
  • The Subsystem.
  • The type of request ("AUTH" or "XAUTH").
  • The name of the resource.
  • The access decision ("allowed", "denied", or "answered").
  • The name of the rule.

The rule name is the LDAP CN (Common Name) of the microfocus-MFDS-Resource object which was matched to the request and had an ACL (Access Control List) which applied to the request.

Note: This has no effect if ESF Auditing is not enabled.

[LDAP] section

provider=module
The name of the dynamically-loadable module containing the LDAP client functions. It should be a DLL (Windows), 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 (for example, "_t.so.2") is 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 to search for the LDAP client library as it is typically installed for this platform.
For example:
[LDAP]
 provider=libldap.a
This instructs 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 value is 3. Typically, 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 is appended to the value to create the full DN of the user container. See base above for more information. The default value 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: If this option is set to a non-default value, the sample LDAP schema and data files have to be edited in order to create compatible data in the LDAP repository.
Attribute names are case-insensitive. The default value is CN.
group class=LDAP class name
Set the name of the LDAP object class used to hold group information. The default value 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.
group member attribute=name
Set the name of the LDAP attribute that holds the list of Enterprise Server users who are members of each group object. Attribute names are case-insensitive. The default is microfocus-MFDS-Group-member, unless the group type is set to AD, in which case it is member.
group short name attribute=name
Set the name of the optional LDAP attribute for group objects which is to be used as the Enterprise Server name of the group, if it has a value. Enterprise Server user-group names are restricted to 8 characters. By default, the first 8 characters of the group's CN (LDAP Common Name) is used as the group name. This configuration option can be used to tell the MLDAP ESM Module to use the value of a different attribute for the group's name. If the attribute is not defined for the group class, or it is not set for a given group, then the CN is used.

If this option is used, the group's "short name" (the value of this attribute) should be used when:

  • Specifying the group in a resource ACL.
  • Specifying a signon group for the ESF Verify operations.
  • Specifying a nested group (one group as a member of another group).

You can use an existing string attribute, such as displayName or microfocus-MFDS-UID, for the group short name, or add a new attribute to the LDAP schema.

group type=MF | custom | AD | both
Configures the processing of user-group information. This setting enables the use of Active Directory user groups and group members specified by its LDAP distinguished name. See Using Non-Micro Focus Group Objects with LDAP-based Security for more information.
resource class=LDAP class name
Set the name of the LDAP object class used to hold resource access rule information. The default value 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 value is CN=Enterprise Server Resources.
bind=simple | negotiate | es-user
Set the method for binding to the LDAP server:
simple
This 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 must be an LDAP distinguished name.
negotiate
This 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 must be a Windows username, optionally prefixed with a domain name followed by a backslash (domain\user).
es-user
This 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 value is simple.

search scope=child | tree
Set the scope for LDAP searches. child searches only the first level within the specified user, group, and resource containers. tree searches 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 value 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 might cause servers to reject certain queries. For example, Active Directory rejects subtree queries if referrals are enabled. See search scope above for more information.

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 value 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 value is no.

timeout=seconds
Set the timeout for lengthy LDAP operations. This affects LDAP searches; depending on the LDAP provider, it might 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 either succeeds or fails quickly (the server either accepts or rejects 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: The ESF initialization, the thread invoking ESF, and any processing that depends on security in any other threads are 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 takes 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).
retry bind=yes | no
If this option is set to yes, and the retry attempts option is set to a value greater than 1, then LDAP bind operations that fail with various potentially transient errors, such as LDAP_BUSY and LDAP_OTHER, will be retried, even if a previous ldap_connect operation succeeded.

If it is set to no, then LDAP bind operations are only retried if the server does not support ldap_connect. If the server does support ldap_connect, then that can be retried if it fails; but if it succeeds, the bind is only tried once.

The default value is no, which corresponds to the behavior in earlier versions of the product, this corresponds to versions earlier than 3.0 PU24, 4.0 PU18, and 5.0 PU7.

always retry bind=yes | no
If this option is set to yes, and the retry attempts option is set to yes, then LDAP bind operations will be retried regardless of the error returned from the LDAP bind operation even if it is considered an non-retryable error. If it is set to no, then LDAP bind operations are only retried for errors that are retryable.
keepalive idle time=seconds
Linux only, and only when using the OpenLDAP client library. Set the time in seconds before starting keepalive probes on the conversation. The default is determined by the operating system configuration. See the tcp(7) Linux man page for more information.
keepalive interval=seconds
Linux only, and only when using the OpenLDAP client library. Set the time in seconds between keepalive probes. The default is determined by the operating system configuration. See the tcp(7) Linux man page for more information.
keepalive probes=integer
Linux only, and only when using the OpenLDAP client library. Set the number of keepalive probes that can go unacknowledged by the remote side until the conversation is terminated. The default is determined by the operating system configuration. See the tcp(7) Linux man page for more information.

[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 value is 64; the maximum value is 9999. Increasing this value consumes more shared memory and increase processing time for authorization requests, Micro Focus recommends 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 are issued 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 value 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 value 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 attempts to keep track of login attempts by updating this attribute. It is 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 attempts 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 Compatibility Rule Matching algorithm is used. See Compatibility Rule Matching for more information. The default value is no.
rule substitutions=yes | no
Set this to yes to enable the use of the ${user} and ${user_long} tokens, which are 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.
check TLQ first=yes | no
If this option is set to yes, it modifies the behavior used to determine if a user is authorized to use a resource. If no exactly matching rule is found, the next query returns all rules that match the TLQ followed by a wildcard, for example, DEV.JCL.TEMP searches for DEV.*. This option might alter the rule finally used for authorization. This option can improve performance when there are large numbers of resources in a class.

The default value is no.

maximum qualifiers for initial check=number
This option is the generalized form of the check TLQ first option. Where number can be 0 or a positive integer. If number is set to 0, then the behavior is equivalent to check TLQ first=no. If number is set to 1, then the behavior is equivalent to check TLQ first=yes. If number is greater than 1, then when the system searches for rules for a resource name with qualifiers, up to number of the initial qualifiers are used. If the resource name has fewer than number qualifiers, only the available qualifiers will be used in the search. For example, if maximum qualifiers for initial check is set to 2, and a request for a resource named DEV.JCL.TEMP is made. The following LDAP searches are performed in order:
  1. A search for the exact name DEV.JCL.TEMP.
  2. If the previous search returns no rules, or the request cannot be satisfied using those rules, a search for DEV.JCL.*. That is, a search for rules beginning with the literal string DEV.JCL.
  3. If that search returns no rules, or the request cannot be satisfied using those rules, a search for all rules containing wildcards is made.
As with check TLQ first, this option might alter which rule is used for authorization, this can lead to unexpected results. This option can improve performance if there are a large number of resource rules in the DATASET class.

Setting this option implies check TLQ first=yes.

The default value is 0 if check TLQ first is not set or is set to no, and 1 if check TLQ first is set to yes.

percent-wildcard=yes | no
If this is set to yes, the percent (%) 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. At most, only one of the plus-wildcard and percent-wildcard options can be enabled. The percent wildcard is provided for closer emulation of IBM RACF rule names; the plus wildcard is provided for closer emulation of CA Top Secret rule names.

The default value is no.

dss-wildcard=compatible | loose | strict
This option controls how the sequence ".**", also known as "dot-star-star", is treated in rule names.

If it is set to compatible, then when ".**" appears in a rule name it is treated as a literal dot (.) character followed by the "**" wildcard, unless it appears at the end of a name, in which case the dot is ignored and it is treated like the "**" wildcard. For example, in this mode, a rule named "A.B.**" matches "A.B", "A.B.C", and "A.BC.D". This is the behavior in Enterprise Server prior to release 6.0.

If it is set to loose, the ".**" sequence is a special wildcard which matches either the empty string or any string beginning with a dot character. For example, in this mode, "A.B.**" would not match "A.BC.D", because "C.D" does not begin with a dot. However, "A.B.**.C.D" would match both "A.B.C.D" (the wildcard matches the empty string) and "A.B.X.C.D" (it matches a string beginning with a dot). This behavior is closer to that of RACF on the mainframe. It is the default beginning with Enterprise Server 6.0.

Note: Exact emulation of RACF is not guaranteed.

If it is set to strict, the ".**" sequence is always interpreted as a literal dot character followed by the "**" wildcard. With this setting "A.B.**" would not match "A.B" or "A.BC", but would match "A.B.C" and "A.B.C.D".

The default value is compatible for Enterprise Server 5.0 and earlier, and loose for Enterprise Server 6.0 and later.

check constraints for already-verified users=yes | no
When this setting is enabled, when the Security Manager is processing a Verify (authentication) request where a previous Security Manager has already allowed the Verify, the Security Manager will still check certain constraints and disallow the verify if those checks fail. The constraints are whether signon is allowed (microfocus-MFDS-User-AllowLogin); whether the account is expired (microfocus-MFDS-User-ExpirationDate); and whether the user is a member of the signon group, if one was specified. The default value is no.
group membership uses short name=yes | no
When this setting is enabled, when the Security Manager searches groups to determine which ones a user belongs to, it uses the user's "short name" (ES userid) rather than its "long name" (LDAP CN). This only applies to Micro Focus group objects (of class microfocus-MFDS-Group) and to custom group types which use the simple username to identify members. It does not apply when configured to use AD groups, or custom groups which use the LDAP distinguished name to identify members. This is useful when name mapping is enabled and a Security Manager knows the user only by the ES userid. The default value is no.
search users by short name=yes | no
When this setting is enabled, the Security Manager will use the user's "short name" (ES userid) rather than its "long name" (LDAP CN) to search for an LDAP record for the user. This is useful when name mapping is enabled and a Security Manager identifies the user only by the ES userid. The default value is no.

[Passwords] section

expiration=number
Set the default password expiration interval, in days. It only applies if MF-hash verify mode (that is, a Micro Focus password hash) 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 is changed to this many days in the future. The default value 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 date 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.

For example:

esfadmin -uADMIN -pADMIN -U"cn=..." -Pxxx altuser user=SYSAD passexp=20091231

this sets the password expiration date for the user SYSAD to the last day of 2009.

bind failure analysis=setting
Enables a set of heuristics that attempt to determine the most probable reason a user bind was rejected by the LDAP server, which might include invalid credentials, expired password, locked account, and so on. If this is set to 1 or a string beginning with y, and bind-mode verification is enabled, then when a user's bind request is rejected, the module checks a series of optional user attributes for evidence of why the bind might have failed. See [Verify] section for more information. Based on these heuristics it returns what it determines is the most appropriate error code. See MLDAP ESM Module Bind Rejection Heuristics for more information.
bind failure analysis=setting
Enables a set of heuristics that attempt to determine the most probable reason a user bind was rejected by the LDAP server, which might include invalid credentials, expired password, locked account, and so on. If this is set to 1 or a string beginning with y, and bind-mode verification is enabled, then when a user's bind request is rejected, the module checks a series of optional user attributes for evidence of why the bind might have failed. See [Verify] section for more information. Based on these heuristics it returns what it determines is the most appropriate error code. See MLDAP ESM Module Bind Rejection Heuristics for more information.
expiration-check
A historical alias for bind failure analysis.
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 value is 0, that is, no password history is kept.
minimum length=number
Require that new passwords be at least number characters long. If you are using a password type other than "MF", you might also be able to configure this and other password requirements in your LDAP server or OS security policy.
Note: While ESF itself supports long passwords, some MSS programs and APIs are currently limited to a maximum of 8 characters, so use caution when setting this value.
maximum length=number
Require that new passwords be no more than number characters long. If you are using a password type other than "MF", you might also be able to configure this and other password requirements in your LDAP server or OS security policy.
Note: While ESF itself supports long passwords, some MSS programs and APIs are currently limited to a maximum of 8 characters, so use caution when setting this value.
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.

For example:

[Passwords]
required=alphabetic, numeric

this results in password changes failing 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, 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, and so on. 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.

The various password restriction options can be used in combination, for example:

[Passwords]
 minimum length=6
 required=mixed-case
 complexity=2

this 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. Typically, 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 allow the creation and use of self-only passtokens.
secret=string
Set the secret data which 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: Any setting here is not secret to 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 region) that 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 is valid for this length of time after it is generated; after that, it is rejected. The default value is 60 seconds.
table size=size
Sets the size of the table used to store passtokens. If passtokens are being used for multi-factor authentication, then this table must be larger than the peak number of users concurrently logging on. The default size value is 64.
Note: Increasing the size degrades performance by increasing memory requirements.
short passtoken reuse=yes | no
Sets whether or not short passtokens, which are used for multi-factor authentication, can be used once or multiple times and until they expire based on the duration option. The default value is no.

[Prefix Search] section

Enabled=setting
Enable the Prefix Search wildcard optimization for limiting the scope of wildcard resource entities checked (under a resource class) if an exact resource entity match is not found when checking authorization requests. If this is set to a string beginning with "y" or to "1", the ESM Module will use this feature for any class rules specified in this section.
classname=number
Where the classname specifies a resource class name and the number is the prefix length.

This means that if there is not an exact match for a resource entity, which will be under a resource class, in the LDAP directory, instead of defaulting to a wildcard check for all resource entities which at least contain a *, the entities' name will be taken and will use the prefix length to establish what the LDAP search will be for.

For example, if MYCLASS=3 is specified, then if an authorization request for entity MYENTITY in class MYCLASS, then the prefix search would be for MYE*. MYE* would be used to try to find a relevant entity that can fulfil the authorization request. This occurs before falling back to check other wildcard entities in the class.

Note: Avoid using rules for classes like DATASET or PHYSFILE which contain "." characters. You can enable check TLQ first for classes like DATASET which use data set names.

[Trace] section

Config=yes | no
Setting this to yes triggers the module to emit a message for each valid configuration setting specified in the Configuration Information field of your Security Manager. This can be used for auditing and debug purposes. By default, this option is set to no.
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 makes 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 makes 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 makes a log entry for every search that returns an error other than "not found". During Auth requests, there is typically many searches that return "not found"; the fail setting avoids logging these normal unsuccessful searches. If it is set to found, the module logs all searches that succeed or return an error other than "not found". If it is set to all, y, or yes, it logs 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 makes a log entry if one of these silent modify operations fails. If it is set to all, y, or yes, it logs 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 makes a log entry when it binds to the LDAP server. This might 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 makes a log entry when it tries to acquire, acquires, or releases a lock. OpenText Support for Micro Focus Products might 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 are logged. If it is set to changes, additional messages are logged when an update request causes the module to change internal state, such as the MSS attributes (operator class, and so on) 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 following 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 can be used.
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 (for example "TCICSTRN"); wildcards can be used.
    entity
    Is a resource entity name (for example "CINQ"); wildcards can be used.
result
Is allow, deny, unknown, fail, any, or debug

The request is traced if all of the conditions of the rule are met. Tracing means one or more informational messages about the request is written to the log. A result setting of debug is logged based on any result (like any), but logs additional information during processing a request that matches the function, actor, and parameters.

For example:

  • verify:SYSAD:deny traces Verify (signon) requests where the SYSAD user is denied.
  • auth:SYSADM group:TCICSTRN:C*:allow traces 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, 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 data set 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 data set.

Cache=setting
Log messages regarding the operation of the LDAP search-result cache. See MLDAP ESM Module Caching for more information. If this is set to a string beginning with y or to 1, the ESM Module logs messages regarding cache searches, additions, removals, and other activity.

[Update] section

rename active users=no | individual | all

Use this setting to enable the ACEE rename feature. When it is set to no, ESF Update processing will not attempt to rename ACEEs. See Renaming ACEEs and Implementing Security Manager Changes for more information.

When set to individual, ESF Update User requests will cause the MLDAP ESM Module to check whether the named user has been renamed. If so, the module will find all ACEEs for the user and attempt to rename them.

When set to all, ESF Update User requests will trigger rename processing for the specified user as described above. In addition, ESF Update Users and Update All requests will cause the MLDAP ESM Module to search all ACEEs to determine if their associated user has been renamed, then process all of those changes.
CAUTION:
This can take a significant amount of time, depending on how many users have signed on to the enterprise server instance, and will block most other work from being processed.

The default value is no.

[Verify] section

attempt password change=after | before | both
When bind-mode authentication is enabled, specify whether password changes should be attempted before or after trying to authenticate the user's credentials by binding. If this is set to after, the password change will be attempted only after a successful bind, and will use the session bound to the user's account. If it is set to before, the password change will be tried before binding, using the security manager's LDAP session. If it is set to both, it will be attempted before binding, and if that fails, it will also be attempted after binding.

This setting is normally only useful for the Active Directory (AD) password type, and requires additional configuration in Active Directory or AD LDS. See Changing passwords with the MLDAP ESM Module for more information. It has no effect when the verify mode is not bind.

Micro Focus strongly recommends against changing this setting when using any password-type setting other than AD.

The default value is after.

migrate passwords=setting
Enable automatic migration of passwords using a different verifier type to the specified type. Currently only migrating from MF-MD5 to MF-A2 is supported. If this is set to a string beginning with y or to 1, then when a user successfully signs in with their current password, if their current password verifier is of a different type than the value of the password type setting, the MLDAP ESM Module will attempt to replace the verifier with one of the new type. This can be used to gradually migrate users to a more secure type of verifier.
mode=MF-hash | bind
Determine how user credentials (username and password) are verified:
MF-hash
This 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.
bind
This 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 is the same as for the LDAP server, which is the same as for logging into the OS itself, if the OS is using LDAP authentication.
Note: This method might be slower and consume more resources.

The default value is MF-hash.

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.
password change failure=allow | deny
This configuration setting determines what happens when a user requests a password change, and the password change fails, for example, because the new password is too short but the user would have been successfully signed on without the password change.

If it is set to allow, the verify request will succeed and the user will be signed on, but the user's password will not be changed. If it is set to deny, a password-change failure causes the verify request to be denied.

In older versions of the product, the behavior in this case was inconsistent among various configurations. It is now consistent and can be controlled with this setting.

The default value is deny.

password type=MF | MF-A2 | MF-Argon2 | MF-MD5 | AD | MD5 | plain | compatible | SSHA512
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. Currently this is a salted MD5 hash of the password, the same as the MF-MD5 setting. Starting with Enterprise Server 4.0, it will use a salted Argon2 hash, the same as MF-A2.
MF-A2|MF-Argon2
These create a secure verifier using a salted Argon2 hash. This is supported starting in Enterprise Server Patch Update 2. It is more secure - harder to find a matching password - than the previous MF-MD5 scheme, particularly for short passwords.
MF-MD5
Creates a secure verifier using a salted MD5 hash, as used in older versions of Enterprise Server. You can use this if you need to use the same LDAP directory with older and newer versions of Enterprise Server. This is less secure than the new Argon2-based verifier (MF-A2).
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 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 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: 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.
compatible
This setting first tries to set unicodePwd using the Microsoft syntax, then tries to set userPassword using the MD5 method. This will typically 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 will not be a unicodePwd attribute so the more common userPassword attribute will be set instead.
SSHA512
Specifies a salted 512-bit SHA-2 hash of the password, using RFC 2307 syntax. This password type is supported by OpenLDAP with the optional pw-sha2 module, and by some other LDAP servers.
Note: SSHA512 is significantly more secure than the MD5 type.
MF
This is the default value, unless the password verification mode is set to bind, in which case the default is compatible.
Note: 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.
Parent topic: MLDAP ESM Module Configuration Fields
Related concepts
Federation in the MLDAP ESM Module
"Use all groups" Mode
MLDAP ESM Module Caching
Understanding passwords with LDAP-based security
Changing passwords with the MLDAP ESM Module
Username Substitution
Configuring LDAP User Group Mode


MLDAP ESM Module Caching

Beginning with Enterprise Server 7.0, the MLDAP ESM Module implements LDAP search-result caching. When this is enabled, the results of most successful LDAP searches (those that return a result, even an empty one, rather than an error) are stored for a period of time. If a subsequent request needs those results, they are returned from the cache, saving the network and processing latency of a query to the LDAP server.

Caching can significantly improve system performance, at the cost of some additional overhead and some delay in recalling changes to the external security information in the LDAP repository.

  • Understanding LDAP Caching
  • Enabling and Configuring MLDAP ESM Module Caching
Parent topic: MLDAP ESM Module
Related reference
MLDAP ESM Module Custom Configuration Information


Understanding LDAP Caching

The MLDAP ESM Module's LDAP search-result caching feature is enabled by setting positive values for the Cache Limit and Cache TTL configuration parameters in the Security Manager definition.

Note: The Micro Focus sample security manager definitions, and those created new using the administration user interfaces, typically have positive settings for the cache parameters. This means caching will be enabled in many existing configurations, and will be enabled by default in new ones. Set the cache limit and/or cache TTL to 0 to disable caching.

Each MLDAP ESM Module cache is private to that Security Manager and process. Caches are only shared between threads running in a single process.

How the cache is used

The MLDAP ESM Module makes use of the LDAP cache while processing two types of ESF requests: Verify (authenticate a user) and Auth (authorize access to a resource). Other requests, such as ESF Admin, bypass the cache. Also, certain special search operations do not use the cache; these include the ones used to query the LDAP schema, check whether an optional resource class is defined, or check whether a session with the LDAP server is still valid.

LDAP search results which may be cached include information about user, group, and resource access control rule objects.

Search results are stored in cache entries along with related metadata such as the time the entry was created, when it was last used, and how often it has been used. Each entry has a key which includes all of the relevant data for the LDAP search, to ensure that a cached result is returned only for an identical search request.

Cache eviction

It is useful to understand when and why entries are evicted (removed) from the cache. There are four causes of eviction:

  • Expiration: An entry reaches the end of its lifetime. This is the period specified by the Cache TTL (Time To Live) in the Security Manager configuration.
  • Early eviction: When the MLDAP ESM Module has a new search result to cache, if there is not enough room remaining in the cache (after evicting expired entries), it may remove the least-recently used entry to make more room. (This is also known as LRU eviction.) The least-recently used entry is the one which has gone the longest time without being returned from the cache. The principle behind LRU eviction is that an entry which is used infrequently is not very valuable.
  • Staleness: Sometimes the MLDAP ESM Module modifies an object in the LDAP repository. The module knows that modification means any cached information about that object is now out of date, or "stale". For example, when a Verify request includes a (successful) password change, then the search result for that user becomes stale. In such a case the module marks the corresponding cache entry as stale. Stale entries are not returned from the cache and are evicted when they are no longer in use.
  • Flushing: The ESF Update feature is used to notify ESF that security data has been updated. When an Update request is processed by the MLDAP ESM Module, it will flush the cache, evicting all the entries in it.

Cache information

When a process terminates ESF (usually while shutting down), the MLDAP ESM Module will log message 1095 with information about the performance of the cache.

There is also an optional cache tracing configuration setting. This will produce extensive information about cache activity, so it should be used with care. See MLDAP ESM Module Custom Configuration Information.

Parent topic: MLDAP ESM Module Caching


Enabling and Configuring MLDAP ESM Module Caching

There are two main parameters for enabling caching. They can be found on the configuration page for each Security Manger. Only Security Managers using the MLDAP ESM Module currently make use of these values. The two parameters are:

Cache TTL
This determines how long, in seconds, a cache entry will be kept. When a cache entry is stored longer than this time, it is ignored and removed from the cache when space is required for a new entry. This setting can be used to ensure that any expired 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. Because LDAP search results vary widely in size, based on the search parameters and number of results which, for many searches depends on your organization's security configuration. It is not possible to predict how many entries will fit into the cache at any time. Instead, the cache limit should strike a balance between large enough to be useful, but not so large that it strains process or system resources or causes high overhead in searching or updating the cache.

The best values for these parameters depend on your particular application mix. If your applications use many different Mainframe Subsystem Support (MSS) resources, or you have many users, user groups, or resource access rules, they may benefit from a larger cache, but larger caches also take longer to search.

The Cache TTL should be set relatively high if you want caching to be effective for processes that run relatively infrequently, such as less-active SEPs. Balanced with your tolerance for the duration an Enterprise Server can be allowed to use out-of-date security information.

Note: In some cases, cache entries are automatically discarded. See Understanding LDAP Caching for more information.

A 16 KB cache limit and 300-second TTL are typically a good starting point.

Parent topic: MLDAP ESM Module Caching


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


Understanding passwords with LDAP-based security

Enterprise Server integrates with LDAP servers to provide security using the MLDAP ESM Module, one of the available External Security Manager (ESM) modules for the External Security Feature (ESF). There are a number of ways that password-based authentication can be implemented using LDAP.

When the MLDAP ESM Module provides user authentication for Enterprise Server, it must verify the userid and password (sometimes referred to as credentials) supplied to ESF by an Enterprise Server component, and ultimately by the user. The module supports a variety of authentication processes, depending on its configuration.

Mode

Authentication in the MLDAP ESM Module is performed in one of two main ways:

  • By checking the password against a verifier within the module itself.

Or:

  • By binding to the LDAP server using the supplied credentials.

The setting "mode" in the "[Verify]" section specified in the Configuration Information field determines which method is used. With the setting mode=MF-hash (the default), the module will retrieve the verifier from the LDAP repository and check it against the password, while the setting mode=bind instructs it to use the binding method.

Note: A security manager can only operate in one of the two modes. If the ESF configuration includes multiple security managers using the MLDAP ESM Module, they can use different modes.

In the MF-hash mode, each user object in the LDAP repository holds a password verifier string for that user. Typically, this is a salted cryptographic hash of the user's password. The module retrieves the verifier for the named user from the repository, computes a hash of the same type from the supplied password and the same salt as used in the verifier, and compares the result with the verifier. If they match, the password is correct.

Bind mode, on the other hand, asks the LDAP server to validate the user's credentials. An LDAP bind operation is equivalent to signing on to the LDAP server. The module makes a bind request using the supplied userid and password, and its success indicates the credentials were accepted by the LDAP server.

LDAP servers can delegate authentication to other systems. This is transparent to the MLDAP ESM Module.

Bind-mode verification is often useful where LDAP-server authentication is integrated into identity systems, or where the LDAP server is already used to authenticate users, and you would like to use existing user accounts and credentials as Enterprise Server users. However, this has certain disadvantages. As more processing is involved, Enterprise Server signons might be slower with bind-mode verification. Diagnostics are limited; the MLDAP ESM Module will often not be able to distinguish among different types of authentication failures (incorrect password, account locked out, and so on). And changing passwords is more complex and more likely to fail. See Changing passwords with the MLDAP ESM Module for more information.

Password-verifier types

The MLDAP ESM Module supports various types of password verifiers. Some of these are generated and processed by the module itself, in MF-hash mode. Others are created by or for the LDAP server when performing a password change in bind mode, and are processed (for authentication) by the LDAP server or some authentication system it uses.

It is not an error to configure a password-setting mode which does not correspond to the authentication mode, such as password type "AD" with MF-hash mode or password type "MF-A2" with bind mode. Nor is it an error to configure a password type which is not normally supported by the LDAP server, such as AD type with an OpenLDAP server. But such combinations generally are not useful. The administrator should ensure that the combination of authentication mode and password type are prudent.

Note: The password type only applies when a user requests a password change. When authenticating user credentials, the type of the existing password verifier is determined automatically.

Internal verifier types (MF-hash mode)

The verifiers supported by the module in MF-hash mode are prefixed with a scheme name and a colon, followed by data, which can include parameters (such as salt) in addition to the verifier data proper.

The supported schemes include:

literal:
This scheme's data is the verbatim password. It is typically used for testing and should be avoided in production systems, since anyone with read access to the user object in the LDAP repository can trivially recover the password.
MF-MD5:
A salted MD5 hash. This was the default verifier type in older product versions. It is now deprecated, due to the ease of brute-forcing MD5 hashes of short passwords.
MF-A2:
A salted Argon2 hash. Argon2 is a strong (storage-expensive) password-hash algorithm which resists brute-force attacks. This is the default verifier type for more recent product versions.
MF-MD5A2:
An Argon2 hash of a MF-MD5 verifier. This type exists to ease migration from MF-MD5 verifiers to Argon2 verifiers.

In MF-hash mode the password verifier is held in the microfocus-MFDS-User-Pwd attribute. Because each verifier specifies its type, different users can have verifiers of different types.

External verifier types (bind mode)

In bind mode, the actual verifier used by the LDAP server (or external identity system) is outside the scope of the MLDAP ESM Module. However, LDAP servers offer various mechanisms for setting passwords, and these are also treated as "password types" by the module. In some cases this "password type" can determine what type of verifier is stored by the LDAP server.

The supported mechanisms for setting passwords in LDAP servers are:

AD:
This uses Microsoft's password-change mechanism for Active Directory and AD LDS. It involves sending a special LDAP message which causes AD to validate the request and perform a Windows local or domain password change, as appropriate, if the account represents a Windows user, or update the user object's password if it does not. See Changing passwords with the MLDAP ESM Module for more information.
MD5:
This mechanism follows the format defined in RFC 2307 to set a password verifier as an MD5 hash. Micro Focus recommends that you do not use this type of verifier for production environments.
SSHA512:
This is another RFC 2307 password-change type which uses a salted SHA-512 hash.
Plain:
The RFC 2307 password attribute is updated with the verbatim new password. Normally this would be insecure, but some servers can be configured to process this update specially by generating a strong hash with the supplied data.

Password constraints

The MLDAP ESM Module can be configured to apply various constraints on new passwords when a password change is requested. These include minimum and maximum length, character sets (alphabetic, numeric, and so forth) and complexity, and password history. The password-history constraint relies on the module being able to save hashes of old passwords in the user object in LDAP, which is not always possible, depending on the LDAP server and security manager configurations.

These constraints are applied before attempting to change the password and apply to both authentication modes (MF-hash and bind) and all password types.

When an external password type is configured, the LDAP server can apply its own constraints. For example, with the AD password type, Active Directory will enforce all password constraints configured for the domain, such as complexity and password history.

LDAP servers or other security systems can impose other constraints beyond those configured by the administrator. For example, Active Directory usually only allows one password change every 24 hours for a given account.

Configuration options

There are various configuration options for the MLDAP ESM Module which affect password validation and password changes.

[Passwords] section

Password-related options in the [Passwords] section include:

expiration
Sets the expiration interval for new passwords. Only applies in MF-hash mode.
bind failure analysis
Attempts to determine the most probable reason why a bind was rejected, and sets the return codes accordingly so applications can take the required action.
Note: This only applies in bind mode.
expiration-check
A historical alias for bind failure analysis.
history
Enables password history and sets the number of password hashes to store. A new password which matches a stored password is rejected.
minimum length and maximum length
Constraints on the length of a new password.
required and complexity
Constraints on the complexity of a password.

[Verify] section

Password-related options in the [Verify] section include:

mode
Sets the authentication mode (MF-hash or bind).
password type
Sets the mechanism to use when changing passwords, and in some cases the type of verifier generated.
attempt password change
Affects the order of password-change processing in bind mode. See Changing passwords with the MLDAP ESM Module for more information.
password change failure
If a password change is requested but fails, this controls whether the sign-on request can still succeed or will be denied.
password attribute
Overrides the default attribute used for the password verifier.
migrate passwords
An optional feature when attempting to migrate from MF-MD5 to MF-A2 verifiers as users sign on to Enterprise Server. Only applies in MF-hash mode.

See MLDAP ESM Module Custom Configuration Information for more information.

Parent topic: MLDAP ESM Module
Related concepts
Changing passwords with the MLDAP ESM Module
Related reference
MLDAP ESM Module Custom Configuration Information


Changing passwords with the MLDAP ESM Module

Overview of password changes

A password change is attempted when a normal ESF Verify request includes a new password. A "normal" request is one for a normal sign-on operation which includes the existing password (not a no-password Verify).

If the user is successfully authenticated, the MLDAP ESM Module can proceed with attempting the password change. If there are multiple security managers in the security configuration, a password change will only be attempted if no security manager has already successfully changed the user's password for this request.

Additional configuration of the MLDAP ESM Module, security manager, or LDAP server might be required to permit password changes. Changing passwords is not a primary LDAP function so it is not always possible to do it using LDAP. When a password change fails, only limited diagnostic information is available, and an LDAP or system administrator might have to consult other sources to diagnose the information.

How passwords are changed

Password changes in the MLDAP ESM Module all involve the LDAP "modify" operation, but the specific attributes being modified and their content depends on the password type. See Understanding passwords with LDAP-based security for more information.

Changing internal-verifier passwords

The password types which use "internal verifiers", such as MF-A2, are changed by modifying the value of the attribute microfocus-MFDS-User-Pwd (or a different attribute specified in the security manager configuration) in the LDAP object that represents the target user.

The new value of the attribute will be a cryptographic hash which can be used to verify the new password in future sign-on attempts.

The MLDAP ESM Module will only attempt to change the value of this attribute after successfully authenticating the user's credentials, including applying all sign-on constraints (such as account lockout), and checking the new password against whatever password constraints might be configured.

The following is a special case: When a new password is specified, the sign-on constraints "password expired" (controlled by the microfocus-MFDS-User-Pwd-ExpirationDate attribute) and "password must be changed" (the microfocus-MFDS-User-Pwd-MustChange attribute) are ignored. The presence of a new password indicates the user is addressing these restrictions.

In order for the LDAP modify to succeed, the account configured for the LDAP connection in the security manager definition (specified in the "Authorized User" field) must have write access to the attribute.

Changing external-verifier passwords

The other password types, such as AD and SSHA512, refer to password verifiers which are managed by the LDAP server, or some other authentication system that the LDAP server is associated with. Changing these passwords involves making an LDAP modify request, but in many cases that request is intercepted by the LDAP server for special processing.

For the AD (Microsoft Active Directory and AD LDS) password type, the MLDAP ESM Module uses a special LDAP request documented by Microsoft for this purpose. It involves a combined "delete value" request with the old (existing) password, and an "add value" request with the new password, against the write-only attribute unicodePwd. This tells AD to perform a Windows password change for the user. With AD LDS, the target user does not need to be a Windows user account, just an object of the user class. The operation only succeeds if the old password is correct and the new password meets the requirements set on the local computer and/or domain.

For the other external password types, the MLDAP ESM Module uses the mechanism described by RFC 2307, updating the attribute userPassword (unless set otherwise in the configuration) with a new value formed from the password using the hash specified by the password type. Some servers simply set the value of the attribute; others will transform it or perform some other operation, possibly against an external authentication service.

As an example of the server transforming the value being set for userPassword, the OpenLDAP server's olcPasswordHash configuration option can be set to instruct the server to hash the value of userPassword when an application attempts to modify it. In this type of environment, an Enterprise Server administrator could configure the MLDAP ESM Module to use the literal password type so that the new password is sent to the server verbatim. In this configuration, Micro Focus strongly recommends using TLS with LDAP, so passwords are not exposed on the network.

Typically, external password changes are performed after authenticating the user. Because external password types are used with bind-mode verification, when the password change is attempted, the MLDAP ESM Module has an LDAP session bound to the identity of the target user. It will use that session to attempt the password change, so with external verifiers users in effect change their own passwords with the LDAP server, as opposed to having the password change be attempted using the account configured for the security manager. This is more likely to succeed, because LDAP servers are typically configured so users have permission to modify their own passwords, but the account used by the security manager generally does not have permission to modify the passwords of arbitrary users.

External password types and the change-required problem

Attempting the password change only after verifying the user presents a problem for bind-mode authentication. If, for example, the user account requires a password change because the password is expired then the bind operation will typically be rejected. This leaves users with no way to change expired (or must-change) passwords when bind-mode authentication is configured.

Unfortunately, there is no straightforward solution to this issue when RFC 2307 password types are used.

Password changes with Active Directory and AD LDS

There is a potential solution to this for Active Directory and AD LDS. As noted above, the mechanism for the AD password type involves a request which includes both the old and new passwords. In effect, the user is authenticated as part of the password-change operation. That means the password change can be attempted before trying to bind as the user without compromising security.

In order for this to work, a second security mechanism needs to be relaxed. An AD-type password change also requires that the LDAP session being used for the request be bound to an account that has the "Change Password" special permission for the user object being updated. Typically, this permission is granted only to NT_AUTHORITY\SELF, to let users change their own passwords.

It is possible to grant Change Permission to the account configured for the security manager, for user objects in AD or AD LDS. This lets that account change the passwords of those users. As noted above, the change will only succeed if the correct existing password is supplied, so this is safe.

Granting the permission involves updating the Access Control List (ACL) for a user object, or for a container of user objects (in which case it must be made inheritable). For example, using Microsoft's dsacls command with a local AD LDS installation and the sample LDAP configuration supplied with Enterprise Server might look like:

dsacls "\\localhost\CN=SYSAD,CN=Enterprise Server Users,CN=Micro Focus,CN=Program Data,DC=local" /G "CN=MFReader,CN=ADAM Users,CN=Micro Focus,CN=Program Data,DC=local:CA;Change Password"

Usually it is more efficient to set inherited ACLs on containers than on individual user objects. ACL changes can also be scripted using PowerShell.

Once this has been implemented, you can use the attempt password change configuration setting with the before or both value to try the password change before attempting to bind as the user. See MLDAP ESM Module Custom Configuration Information for more information.

An alternative to setting this ACL is to configure the security manager to use an account that has administrative privilege. Some installations historically have used this approach, particularly with AD LDS, to enable AD password changes. AD LDS comes with the predefined roles Reader, which does not have any update rights, and Administrator, which can update any attribute of any object in the AD LDS instance; for convenience, AD LDS administrators might configure an AD LDS account in the Administrator role for use by Enterprise Server. However, Micro Focus recommends against using the Administrator role for the account used by Enterprise Server security managers, as a security vulnerability or credential breach could give an attacker high-value access to the AD LDS repository.

It is unsafe to configure before-binding password-change attempts with other external password types.

Protecting passwords on the network

To avoid exposing passwords or password verifiers on the network, it is safer to configure the security manager to connect to the LDAP server using SSL/TLS. This is also known as LDAP-over-SSL or LDAPS. There is less risk with using MF-mode authentication because the existing password is not sent to the server and when using a hashed password type such as MF-A2 or SSHA512 because only a hash of the new password is sent.

Some servers might require SSL/TLS connections to perform password changes. That is the default for Active Directory and AD LDS.

To use SSL/TLS, both the server and the provider (client library) must be configured to support it. See your LDAP software documentation for more information. Then the connection string in the security manager definition should be changed to begin with ldaps://.

Parent topic: MLDAP ESM Module
Related concepts
Understanding passwords with LDAP-based security
Related reference
MLDAP ESM Module Custom Configuration Information


MLDAP ESM Module Bind Rejection Heuristics

When the MLDAP ESM Module is configured to authenticate users by trying to bind to the LDAP server with their credentials (configuration option mode=bind), the only information that the module gets from the server is success or failure. Applications are typically required to report more information to the user in the event of a failure, for example, invalid credentials, account is disabled, or password is expired and needs to be changed.

The MLDAP ESM Module can apply various heuristics to try to determine the most likely cause of bind failure, and set the ESF return codes, and if enabled, log tracing messages, accordingly. These heuristics involve checking for a number of optional LDAP user attributes which a server might use for additional information about the state of a user account.

This feature can be enabled using the following configuration setting in the Security Manager Configuration Information field:

[Passwords]
bind failure analysis=yes

or the older equivalent:

[Passwords]
expiration-check=yes

When the feature and bind-based verification is enabled, the module will look for some or all of the following attributes in the user's LDAP record and examine their values to determine the most probable reason the user's bind was rejected:

  • Attributes used primarily by Microsoft Active Directory:
    • msDS-UserAccountDisabled
    • badPwdCount
    • msDS-UserDontExpirePassword
    • pwdLastSet
    • userAccountControl
    • msDS-User-Account-Control-Computed
  • Attributes used primarily by Micro Focus eDirectory:
    • loginDisabled
    • passwordExpirationTime
  • Attributes used primarily by OpenLDAP and other servers based on it:
    • pwdChangedTime
    • pwdAccountLockedTime
    • pwdMustChange and pwdReset (these work in combination)
    • pwdLockout, pwdFailureCountInterval, pwdFailureTime, and pwdMaxFailure (these work in combination)

For pwdLastSet and pwdChangedTime to be useful, a password expiration interval must be configured, so the module can determine whether the password is old enough to have expired. For Active Directory (and AD LDS), however, typically msDS-User-Account-Control-Computed will indicate an expired password, so this is not a concern; and if your server uses passwordExpirationTime, that is also sufficient to detect an expired password.

Note: Due to limitations of the ESF API, and the IBM mainframe SAF API on which it's based, the return codes do not distinguish some conditions. In particular, the password-expired condition and the password-must-be-changed condition are both reported as "password expired", and the account-disabled and account-locked (due to too many failed login attempts) condition are both reported as "userid revoked".

You can get more specific information about why a user bind failed by enabling bind tracing with this configuration setting:

[Trace]
bind=yes

Enabling the bind failure analysis feature will typically improve the user experience, therefore Micro Focus recommends using it for customers using LDAP security and binding to verify user credentials.

Parent topic: MLDAP ESM Module


VSAM ESM Module

The VSAM ESM Module provides an External Security Manager (ESM) for Enterprise Server which uses a collection of COBOL VSAM (.dat) files to store security configuration information.

The VSAM ESM Module does not currently provide all of the features of the MLDAP ESM Module, it does offer basic authentication and authorization support. It is simpler to set up and use than the MLDAP ESM Module. It does not require any third-party software and does not rely on network connectivity, assuming its files are on the local system, and does not require system-administrator privileges to set up and configure.

The VSAM ESM Module can also be used in conjunction with other ESM Modules by "stacking" multiple security managers in a security configuration. You might find that this is a useful configuration if, for example, most of your security data is in LDAP, but sometimes you need to make small additions without changing the LDAP repository data. It is also possible to stack multiple security managers which use the VSAM ESM Module, for example, to test the effect of new security rules.

The VSAM ESM file directory can be created and administered using the command-line utility, mfsecconv, which supports importing security data defined using a YAML file, and exporting existing security data as well.

The VSAM external security manager consists of two shared libraries:

  • vsam_esm
  • vsam_esm_io

When configuring a Security Manager to use the VSAM ESM Module, specify vsam_esm as the module name.

  • VSAM ESM Module Configuration Fields
  • Administering Security Data
  • Data File Attributes
  • Limitations
  • The mfsecconv Command
    Describes the mfsecconv security utility
Parent topic: Securing an Enterprise Server Installation


VSAM ESM Module Configuration Fields

The VSAM ESM Module can be configured from the External Security Managers Configuration dialog box on the Define External Security Managers page in ESCWA:

Enabled
If this is unchecked, then the ESF Manager will not load, initialize, or pass requests to this Security Manager.
Name
Specify the name used to identify the VSAM ESM Module.
Module
Specify vsam_esm as the module.
Connection Path
This is the fully qualified file system path to the VSAM ESM file directory, for example, C:\esm_file_dir\. The default path is %PROGRAMDATA%\Micro Focus\Enterprise Developer\vsam_esm. Some previous early-access versions of the VSAM ESM Module used es_esm_file_directory as the default directory name.
Note: Ensure the directories and files containing the ESM file directory have the appropriate filesystem permissions. Operating system accounts used to run Enterprise Server components, such as ESCWA and enterprise server instance, that are configured to use the security manager will need at least read access to the files. Accounts used to create and update the files, for example, by running mfsecconv, will require write access.

On Windows platforms, both forward slashes and backslashes can be used in the connection path.

Authorized ID
Not used by this module.
Password
Not used by this module.
Description
Optional, specify a description of the security manager.
Configuration Information
See VSAM ESM Module Custom Configuration Information for the additional configuration that can be specified.
Cache Limit
Not used by this module.
Cache TTL
Not used by this module.
  • VSAM ESM Module Custom Configuration Information
Parent topic: VSAM ESM Module


VSAM ESM Module Custom Configuration Information

The VSAM ESM Module supports some additional configuration that can be set by editing the Config field. 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 pairs. The following are the various configuration sections, and corresponding options that can be set in each section:

[Operation] section

signon attempts=integer
Set the maximum number of consecutive failed sign in (Verify) attempts before a user account is automatically disabled. If integer is set to a value greater than 0, then after that many attempts to sign in a user using an incorrect passwords, the account is disabled. Successfully signing a user in with the correct password will reset the count. The default value is 0, which disables this feature.

[Password] section

expiration=integer
Set the default password expiration interval, in days. If a user changes their password and their account is configured with a password expiration date (the user-password-expire-date attribute), and that date is in the past or less than the specified days in the future, then it is changed to this many days in the future. The default value is 90 days.
history=integer
Stores an integer number of previous password hashes for each user. When users try to change their passwords, if the new password matches one of the stored hashes, then the request is rejected. The default value is 0, that is, no password history is stored.
minimum length=integer
Requires that new passwords be at least an integer number of characters long.
CAUTION:
While ESF itself supports long passwords, some Mainframe Subsystem Support (MSS) programs and APIs are limited to a maximum of 8 characters.
maximum length=integer
Requires that new passwords be no more than integer number of characters long.
CAUTION:
While ESF itself supports long passwords, some Mainframe Subsystem Support (MSS) programs and APIs are limited to a maximum of 8 characters.
required=alphabetic|mixed-case|numeric|punctuation,...
Requires a 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 with whitespace and/or commas.

For example:

[Passwords]
required=alphabetic, numeric

this results in the password change failing if the new password does not include at least one letter and one digit.

complexity=1-5
Requires a new passwords to include at least one character from number + 1 character classes. Uppercase and lowercase are counted separately, for example, complexity=1 would be satisfied by a mixed-case password, or a password with lowercase letters and digits, or digits and punctuation characters, and so on. Characters that are not (ASCII) letters, digits, or punctuation are counted as another character class, so there are five classes in total, uppercase, lowercase, digit, punctuation, and other.

The various password restriction options can be used in combination, for example:

[Passwords]
minimum length=6
required=mixed-case
complexity=2

this would enforce passwords that had a minimum of 6 characters, with both uppercase and lowercase letters and at least one non-letter character.

[Trace] section

Config=yes|no
Traces configuration settings. Setting this to yes generates a message for each valid configuration setting specified in the Config field of your External Security Manager Configuration dialog box. This can be used for auditing and debug purposes.

The default value is no.

Groups=string
Logs various messages regarding the processing of user groups. If this is set to a string beginning with "y" or to "1", the ESM Module makes 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.
Modify=fail|all|y|yes
Enables the logging of some modify operations which are normally not logged. If this is set to fail, the ESM Module makes a log entry if one of these "silent modify" operations fails. If it is set to all, y, or yes, it logs all of these modify operations, including ones that succeed. Affected operations include setting the last-login-time user attribute, and possibly others.
Update=y|yes|changes|all
Logs update requests, which are ESF control requests, made using ESCWA 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 are logged. If it is set to changes, additional messages are logged when an update request causes the module to change internal state, such as the MSS attributes (operator class, and so on) 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.
Vsam=yes
Logs file-handler status codes for VSAM I/O operations on the ESM file directory. If this is set to yes, the status codes from the file handler are logged.

[VSAM timeout] section

retry count=integer
Set the maximum number of retries to open a file in the VSAM ESM file directory. The time between each retry attempt is specified by wait length.

The maximum value is a signed 32-bit integer and the default retry count when retry count and max wait are not specified is 30.

wait length=integer
Set the time in milliseconds to wait between retries when opening a file in the VSAM ESM file directory.

The maximum value is a signed 32-bit integer and the default value when not specified is 1000, which is one second.

max wait=integer
Set the maximum time to wait to open a file in the VSAM ESM file directory.

The maximum value is a signed 32-bit integer and the default value when not specified is 0, which disables the maximum wait.

Parent topic: VSAM ESM Module Configuration Fields


Administering Security Data

The security data used by the VSAM ESM Module is kept in a set of COBOL VSAM (.dat) files, referred to as the VSAM ESM file directory. These files can be created and updated using the mfsecconv utility, which can convert between data specified in a YAML file and the VSAM ESM file directory. YAML is a data serialization language typically used for configuration files which can be created and maintained using a text editor.

The COBOL VSAM files in the VSAM ESM file directory can also be edited using the Data File Editor. See Data File Editor for more information.

An example YAML file is provided with the product, es_default_security.yaml, which is located at %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc.

Note: Importing the es_default_security.yaml file into an existing security configuration with the --update option will overwrite all changes that have been made to objects in the security configuration which have a definition in the YAML file. This includes the password generated for the SYSAD user during product installation. Micro Focus recommends creating a YAML file with only the changes you require. You can use es_default_security.yaml as a template, but remove all entries you do not require.

The YAML syntax used with mfsecconv is as follows:

Users:
  - User:
    UserId: ""  #Attribute type: String
    AltId: "" #Attribute type: String
    AllowLogon: True #Attribute type: Boolean
    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String
    DefaultGroup: "" #Attribute type: String
    CreateToken: "" #Attribute type: String
    UseToken: "" #Attribute type: String
    LastLoginTime: "" #Attribute type: String, format ISO8601
    ExpirationDate: "" #Attribute type: String, format ISO8601
    LoginAttempts: 0 #Attribute type: Integer
    Audit: True #Attribute type: Boolean
    MTOs:
      Priority: 0 #Attribute type: Integer
      Timeout: 0 #Attribute type: Integer
      OperatorClass: 0 #Attribute type: Integer
      OperatorID: "" #Attribute type: String
      GroupPrefix: "" #Attribute type: String
    Password:
      - Verifier: "" #Attribute type: String in the format "<verifier type>:<verifier>" e.g. "literal:a_strong_password"
      - MustChange: True #Attribute type: Boolean
      - ExpirationDate: "" #Attribute type: String, format ISO8601
      - History: # A sequence of Attribute type: String
        # conforming to the following format "<ISO8601 date/time>:<verifier type>:<verifier> e.g.:"
        - "20220811T164639Z:literal:an_old_password"

UserGroups:
  - UserGroup:
    GroupId: "" #Attribute type: String
    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String
    Member: # A sequence of Attribute type: String, where each entity is a member of this user group
      - "SYSAD" #Meaning the SYSAD user is a member of this user group
      - "#DSAdmin Group" #The " group" suffix indicates "#DSAdmin" is a user group, whose members are also members of this group.
    Audit: True #Attribute type: Boolean

ResourceClass:
  - ResourceClass:
    ResourceClassId: "" #Attribute type: String
    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String

ResourceRules:
  - ResourceRule:
    RuleID : "" #Attribute type: String
    ResourceClassId: "" #Attribute type: String
    ACEs: #A sequence of Attribute type: String representing this rule's Access Control Entries
    # in the format: "<access type>:<actor>:<permission level>" e.g.
      - "allow:ALLUSER group:read" # the " group" suffix indicates ALLUSER is a group and allows all it's members to read.
      - "deny:SYSAD:execute"  #Denies the user SYSAD from executing.
      - "deny:*:write" # denies all actors(both users and groups) from writing.

    Description: "" #Attribute type: String
    CustomText: "" #Attribute type: String
    Audit: True #Attribute type: Boolean

Use the mfsecconv command to import or export security data. See The mfsecconv Command for more information.

Parent topic: VSAM ESM Module


Data File Attributes

The following are the field and record definitions for the data files used in the VSAM ESM file directory, and their corresponding YAML configuration names.

Users.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
user-name | UserId | 8 | N/A |
long-name | AltId | 100 | N/A |
user-allowed-logon | AllowLogon | 1 | N/A | Single character Y or N boolean flag.
user-description | Description | 100 | N/A |
user-custom-text | CustomText | 100 | N/A |
user-expire-date | ExpirationDate | 17 | N/A | ISO8601 date-time string
user-default-group | DefaultGroup | 8 | N/A |
user-password | Verifier | 108 | N/A |
user-password-expire-date | ExpirationDate | 17 | N/A | ISO8601 date-time string
user-password-change | MustChange | 1 | N/A | Single character Y or N boolean flag.
user-create-token | CreateToken | 4 | N/A |
user-use-token | UseToken | 4 | N/A |
user-last-logon-time | LastLoginTime | 17 | N/A | ISO8601 date-time string
user-logon-attempts | LoginAttempts | N/A | 4 |
user-audit | Audit | 1 | N/A | Single character Y or N boolean flag.
user-mto-priority | Priority | N/A | 4 |
user-mto-timeout | Timeout | N/A | 4 |
user-mto-operator-class | OperatorClass | N/A | 4 |
user-mto-operator-id | OperatorID | 3 | N/A |
user-mto-group-prefix | GroupPrefix | 8 | N/A |

PasswordHistories.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
user-id | UserId | 8 | N/A |
password-history-value | An element in the History sequence | 126 | N/A |

Groups.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
group-name | GroupId | 8 | N/A |
group-description | Description | 100 | N/A |
group-custom-text | CustomText | 100 | N/A |
group-audit | Audit | 1 | N/A | Single character Y or N boolean flag.

Memberships.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
membership-group-id | GroupId | 8 | N/A |
membership-member-id | An element in the Member sequence | 8 | N/A |
membership-group-ind | CustomText | 1 | N/A | Single character Y if the member id corresponds to a group, OR N if the member id corresponds to a user.

Classes.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
class-name | ClassID | 44 | N/A |
class-description | Description | 100 | N/A |
class-custom-text | CustomText | 100 | N/A |

Rules.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
resource-name | RuleID | 1000 | N/A |
resource-description | Description | 100 | N/A |
resource-custom-text | CustomText | 100 | N/A |
resource-audit | Audit | 1 | N/A | Single character Y or N boolean flag.

ACEs.dat

Data File Attribute Name | YAML Configuration Equivalent | Character Limit | Integer Digit Limit | Notes
ace-id | N/A | N/A | 8 | Not end user defined.
resource-id | RuleID | 8 | N/A |
actor-name | substring of an entry in ACEs sequence | 8 | N/A | Single character Y or N boolean flag.
ace-group-ind | substring of an entry in ACEs sequence | 1 | N/A | Single character Y or N boolean flag.
ace-type | substring of an entry in ACEs sequence | 5 | N/A | Either ALLOW or DENY .
ace-perm | substring of an entry in ACEs sequence | 80 | N/A |
Security Data files can be edited with Micro Focus Data File Tools. See the file definitions below:
Note: The level-88 items specify valid values for some fields.
fd users.
01 user-rec. *>502
  05 user-name pic x(8).
  05 long-name pic x(100).
  05 user-allowed-logon pic x.
    88 is-allowed-logon value "Y" false "N".
  05 user-description pic x(100).
  05 user-custom-text pic x(100).
  05 user-expire-date pic x(17).
  05 user-default-group pic x(8).
  05 user-password pic x(108).
  05 user-password-expire-date pic x(17).
  05 user-password-change pic x.
    88 is-password-change-required value "Y" false "N".
  05 user-last-password-change-time pic x(17).
  05 user-create-token pic x(4).
  05 user-use-token pic x(4).
  05 user-last-logon-time pic x(17).
  05 user-logon-attempts pic x(4) comp-x.
  05 user-audit pic x.
    88 is-audit value "Y" false "N".
  05 user-mto-priority          pic x(4) comp-x.
  05 user-mto-timeout           pic x(4) comp-x.
  05 user-mto-operator-class    pic x(4) comp-x.
  05 user-mto-operator-id pic x(3).
  05 user-mto-group-prefix pic x(8).

fd password-historys.
01 password-history-rec.
  05 password-history-key.
    10 password-history-value pic x(126).
    10 user-id pic x(8).
fd groups.
01 group-rec.
  05 group-name pic x(8).
  05 group-description pic x(100).
  05 group-custom-text pic x(100).
  05 group-audit pic x.
    88 is-audit value "Y" false "N".

fd memberships.
01 membership-rec.
  05 membership-key.
    10 membership-group-id pic x(8).
    10 membership-member-id pic x(8).
    10 membership-group-ind pic x.
      88 is-group value "Y".
fd classes.
01 class-rec.
  05 class-name pic x(44).
  05 class-description pic x(100).
  05 class-custom-text pic x(100).

fd resources.
01 resource-rec.
  05 resource-name pic x(1000).
  05 resource-description pic x(100).
  05 resource-custom-text pic x(100).
  05 resource-audit pic x.
    88 is-audit value "Y" false "N".

fd aces.
01 ace-rec.
  05 ace-id pic x(8) comp-x.
  05 resource-id pic x(1000).
  05 ace-actor.
    10 actor-name pic x(8).
    10 ace-group-ind pic x.
      88 is-group value "Y" false "N".
  05 ace-type pic x(5).
    88 is-allow value "ALLOW" false "DENY ".
  05 ace-perm pic x(80).
Parent topic: VSAM ESM Module


Limitations

The VSAM ESM Module has the following limitation:

Attribute Length
See Data File Attributes for more information on compatible inputs and restrictions on attribute length and data types when modifying data files.
Parent topic: VSAM ESM Module


The mfsecconv Command

The mfsecconv command is used to import, export, and convert security data for the VSAM ESM Module. It is also used to initialize security data for the Default ES Security Configuration. It provides these functions:

Importing
Creating and updating the security data in the VSAM (COBOL indexed) files used by the VSAM ESM Module, from security definitions specified in a YAML or LDIF file. YAML is a convenient structured-text format for editing or manipulating with scripting languages. LDIF is a text format used for importing to and exporting from LDAP servers.
Exporting
Creating a YAML file of security definitions from a set of VSAM ESM Module VSAM files.
Converting
Converting ESF security information in an LDIF file into YAML, which might be useful for customers migrating from LDAP-based security (using the MLDAP ESM Module) to file-based security (using the VSAM ESM Module).
Initializing
Creating a set of VSAM files for the VSAM ESM Module and performing other tasks associated with the Default Enterprise Server Security Configuration. See Default Enterprise Server Security Configuration.
  • mfsecconv Command Reference
    Sub-commands and options for the mfsecconv command
Parent topic: VSAM ESM Module
Related concepts
User accounts in the Default Enterprise Server Security Configuration


mfsecconv Command Reference

mfsecconv sub-command parameters [options]

Administer security definitions for the VSAM ESM Module.

Sub-commands

init
Initialize the default Enterprise Server security configuration. This sub-command will only make changes to the system if there is currently no VSAM ESM Module security data in the default location, which is %ProgramData%\Micro Focus\product-name\vsam_esm.
reset
Equivalent to the init sub-command, except that it will overwrite any existing security configuration in the default location. It will also overwrite any entries in the default Micro Focus Secrets Vault used by the default Enterprise Server security configuration, microfocus/temp/admin and microfocus/common/readonly (possibly affected by options specified on the command).
import
  • Import security definitions from a YAML or LDIF file into a set of VSAM (COBOL indexed) data files for the VSAM ESM Module. Options specify whether existing definitions will be replaced, updated, or left unchanged, and whether new definitions will be added.
  • Convert security definitions in an LDIF file into YAML format.
export
Create a YAML file containing the security definitions from a set of VSAM ESM Module data files.

init and reset

Syntax:
  • mfsecconv init [options]
or:
  • mfsecconv reset [options]

These sub-commands create the security definitions for the default Enterprise Server security configuration, and (by default) put user account credentials in the vault. The only difference between init and reset is that init will not overwrite existing security data, and reset will. mfsecconv init is run by the product installer to create the default Enterprise Server security configuration when the product is installed.

Note: These commands only update the VSAM ESM Module security data (in the default location) and information in the vault. They do not change the security definitions in ESCWA or MFDS. See To Recreate the Default Enterprise Server Security Configuration if you need to restore the full default configuration.
CAUTION:
Micro Focus recommends that you back up your existing security data prior to running the mfsecconv reset command.

Options for init and reset

-h|-H|--help
Displays the command help.
-s|-S|--user username
Add username as an administrator to the security definitions. This can be used multiple times. If at least one instance of this option is used, the SYSAD default administrator will not be installed, unless it is also specified with this option, that is --user SYSAD is specified. Unless a password is also supplied with the --pass option or one of its aliases, a random password will be generated for the user and stored in the list of credentials in the vault under microfocus/temp/admin.
-p|-P|--pass password
Set the password for the previous user account, specified with --user. If no password is supplied for a user, a random one will be generated, as described for --user.
-d|-D|--displaypass
Rather than writing generated credentials to the vault, write them to standard output.
-i|-I|--interactive
Rather than generating passwords, read them from standard input.
-x|-X|--exit-codes
Typically, mfsecconv exits with an exit code of 0 if no error messages were logged, that is, nothing more severe than a warning. If the --exit-codes option is specified, it exits with a return code of 3 if there was a fatal (critical) error, 2 if there were any non-fatal errors, 1 if there were any warnings, or 0 if there were no warnings or errors. This might be useful when invoking mfsecconv from a script.

For example:

mfsecconv reset --user MYADMIN --pass Secret_1

import

Syntax:

mfsecconv import source-file destination [options]
source-file
This is a YAML or LDIF file. It must have one of the following extensions .yaml, .yml, .ldif, or .ldf and is case insensitive.
destination
This is either a directory where VSAM files will be created, or a YAML file, which must have an extension of .yaml or .yml.

This sub-command either generates VSAM ESM Module security data from a YAML or LDIF file, or converts an LDIF file containing security data (using the Micro Focus LDAP schema) to YAML. It can be used to generate the VSAM security data for first use, for example to install a stock security configuration on a new system or initialize security for an enterprise server instance running in a container, to update existing security data with new or modified definitions, to migrate from LDAP-based security to VSAM-based, and so on.

When importing to VSAM, there are three options which control how the new data interacts with any existing security data: --truncate, --update, and --append. Either one or two of these needs to be specified for the command to have an effect. The options and their affect are as follows:

--truncate
Any existing security data is deleted. The target directory is created if necessary.
--append
New records are added to the existing security data, where the imported information does not conflict with the existing data. Information in the source which matches an existing record is ignored.
--update
Existing data is updated where the imported information refers to an existing record. Information in the source which does not correspond to an existing record is ignored.
--truncate --append
Any existing data is deleted, the directory is created if necessary, and the source information is used to create the security data.
--append --update
No existing data is deleted. Information in the source that matches an existing record updates the existing record; new records are created for new information in the source.
Note: When using the --update option, ensure the file you are importing does not contain definitions for any objects in the existing security configuration that you do not wish to change. Specifically, avoid using --update with es_default_security.yaml, as you will overwrite any changes that have been made to your security configuration, including the password generated for the SYSAD user during product installation.

Options for import:

-h|-H|--help
Displays the command help.
-a|-A|--append
Imported information which does not match an existing record will be added.
-t|-T|--truncate
Delete existing security data.
-u|-U|--update
Imported information which matches an existing record will update that record.
-l|-L|--loglevel value
Set the logging verbosity. value is an integer 0-4, with higher numbers suppressing more messages. Level 1 suppresses debug messages, level 2 also suppresses informational messages, level 3 also suppresses warning messages, and level 4 also suppresses non-fatal error messages, only critical errors are displayed.
For example:
mfsecconv import security_defs.yaml $COBDIR/etc/vsam_esm --append --update

The VSAM ESM file directory structure will be similar to the following:

$COBDIR/etc/vsam_esm
|---Users.dat
|---PasswordHistories.dat
|---Groups.dat
|---Memberships.dat
|---Classes.dat
|---ACICSPCT # A resource class name
|---|---ACEs.dat
|---|---Rules.dat
|---CCICSCMD # Another resource class name
|---|---ACEs.dat
|---|---Rules.dat

export

Syntax:

mfsecconv export source destination-file [options]
source
This is a directory containing VSAM ESM Module security data files.
destination
This is a YAML file, which must have an extension of .yaml or .yml, and is case insensitive.

This subcommand creates a YAML file representing the VSAM ESM security data in the source directory. This can be used to back up or replicate the security configuration, or create a text version which can be edited and then imported back into the security data files.

Options for export:

-h|-H|--help
Displays the command help.
-l|-L|--loglevel value
This sets the logging verbosity. value is an integer 0-4, with higher numbers suppressing more messages. Level 1 suppresses debug messages, level 2 also suppresses informational messages, level 3 also suppresses warning messages, and level 4 also suppresses non-fatal error messages, only critical errors are displayed.
For example:
mfsecconv export "c:\ProgramData\Micro Focus\Enterprise Developer\vsam_esm" c:\secdefs.yaml
Parent topic: The mfsecconv Command


JES Security

If JES is enabled in an enterprise server instance, it is important to secure it so it cannot easily be used by an unauthorized user to execute arbitrary programs. This section discusses a number of security measures you can take. These require that your Enterprise Server has External Security configured with a suitable External Security Manager. See Configuring Enterprise Server Security.

  • Overview of JES Security
  • JCL Enhanced Security Checks
Parent topic: Securing an Enterprise Server Installation


Overview of JES Security

User and resource security for JES

You must define administrators for the system. Create one or more administrator accounts, and add them to the SYSADM and ALLUSER groups. Depending on your security configuration, you may need to add them to other groups or grant them additional permissions.

User accounts defined in the default security configuration should be disabled or removed so that well-known user accounts cannot be used to gain access. Remove all permissions of the default JES user, JESUSER, so that no one can submit work anonymously. All users should be required to sign on.

The primary access check for running a JCL job is user authentication with a valid userid and password. This is checked when the user issues a JES command, from the command line or using ESCWA. Commands are also checked for authorization. For example, to submit a job the user must be authenticated and have access to the cassub resource in the OPERCMDS class. Access to ESCWA administration pages can be restricted using the Common Web Administration class.

When a job is submitted, a check is made against the PHYSFILE class that the JES engine can create its parsing files in the specified location by the user submitting the job. If the job requires read access to libraries, a check is made against the DATASET class.

When a job is run, DATASET checks are made for each dataset it accesses. If a new dataset is created, a PHYSFILE check is made against its location.

Having a well-defined naming convention and defining DATASET rules as to who can access which datasets, plus PHYSFILE rules governing access to filesystem locations for the datasets, will restrict dataset creation and access to authorized users. Separating jobs that create datasets from those that only use existing ones also helps limit what permissions users need to be granted.

Limit where programs are loaded from

This section applies to programs named in the PGM attribute of an EXEC card in a JCL job.

Currently, if a program can be found on the search path the search path set as the JES Program Path in Enterprise Server configuration then it will be run. So, any program could be run without limit on what it does. A job can set STEPLIB and JOBLIB libraries to specify private (user) program libraries, and we prepend those locations to the search path.

You can set additional restrictions on how the JES engine searches for programs, using SYS1.LNKLIB and the ES_JES_HIGHER_SECURITY_LEVEL environment variable. See JCL Enhanced Security Checks.

How SYS1.LINKLIB is constructed

SYS1.LINKLIB starts with the product's \bin or \bin64 folder (Windows) or the /lib directory (UNIX). This is the location that system-supplied utilities can be loaded from. SYS1.LINKLIB does not exist as a dataset in the catalog so users cannot change the PC-DSN.

On Windows:

SYS1.LNKLIB= $TXDIR\bin
or
SYS1.LNKLIB= $TXDIR\bin64

On UNIX:

SYS1.LNKLIB= $TXDIR/lib

A concatenation of libraries built from SYS1.PARMLIB are added to this location.

SYS1.PARMLIB(IEASYM00) is already used to hold system symbols. It could also hold SYSPARM entries. Alternatively, you could placed these in a new dataset, SYS1.PARMLIB(IEASYM01) such that SYS1.PARMLIB(IEASYM01) could be used to hold SYSPARM entries for the IEASYSnn members to load.

Note that LPARNAME equates to a region name, and SYSPARM gives indexes for IEASYSnnxx members, so different library indexes could be used for different regions. For example:

  SYSDEF  HWNAME(MVS3090) LPARNAME(JCLTEST)
          SYSPARM(01,L)

  SYSDEF  HWNAME(MVS3090) VMUSERID(VMSYSCB) LPARNAME(ESDEMO)
          SYSPARM(03,L)

  SYSDEF  HWNAME(SYSCC)
          SYSPARM(01,02,L)

The different library indexes (01, 02, 03 etc.) for the different systems indicate the index of the IEASYSnn library to load. For example, IEASYS01, IEASYS02 for all regions, IEASYS01, IEASYS02 for JCLTEST, IEASYS01, IEASYS02, and IEASYS03 for ESDEMO. The 'L' in the SYSPARM parameter indicates that the list should be shown on first access.

Each IEASYSnn member contains a list of LNKLST indexes to load:

LNK=(00,01,02,03)
In the format:
LNK={aa             }
    {(aa,bb,...[,L])}
    {(,L)           }

SYS1.PARMLIB(LNKLSTnn) members hold lists of datasets that hold programs that can be run:

LNKLST00:   SYS1.CMDLIB,SYS1.TSORTNS,SYS1.BTAMLIB,
LNKLST01:   SYS1.LINKLIB,DBLUE.U30LIB(U30PAK),SYS2.U30LIB
LNKLST02:   SYS1.AUXLIB,SYS1.JES3
LNKLST03:   SYS1.TEST

IEASYS00 is always read so it could contain the only LNK statement for the system. If multiple LNKLST members are to be read, then entries from IEASYM00 and IEASYM01 need to be read in and used to read IEASYSnn, which is used to read the LNKLSTnn.

So, the eventual list of public program libraries would be:

SYS1.LINKLIB, SYS1.CMDLIB,SYS1.TSORTNS,SYS1.BTAMLIB, SYS1.LINKLIB,DBLUE.U30LIB(U30PAK),SYS2.U30LIB, SYS1.AUXLIB,SYS1.JES3, SYS1.TEST

When a program is executed, the JES engine searches all of the libraries in the link list until it finds a program of that name which the user has the necessary access to. At the default security level (see Migrating to Increased Security Checks, and JCL Enhanced Security Checks), a message will be logged to the console if permission has not been granted to the program or the program is not found. When a program is successfully loaded, a message will be logged about which library it was loaded from.

Dynamic PDS

Dynamic PDS are extremely useful in that any file in a folder that is defined as a dynamic PDS immediately becomes a member of the PDS and can therefore be found and used. This is useful because a program just needs to be compiled and put into that folder. It is dangerous for the same reason in that a malicious user could do the same thing with a malicious program. To prevent this, at the BASIC security level dynamic PDS are excluded from program load locations. At the default security level (NONE), a warning is logged if the program is found in a dynamic PDS.

The ESF PROGRAM resource class

Further security checks can be implemented in ESF by creating the PROGRAM resource class, if it does not exist, and adding resource access rules there. A check would be made that a user has permission to READ or EXECUTE the program in the dataset. A PROGRAM resource access rule would be named program-name.library-name, possibly with wildcards (use ** as a wildcard in the library name to match multiple DSN qualifiers).

An example in LDIF, for use with LDAP-based security:

dn:CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=mftesting,DC=com
objectClass: top
objectClass: container
description: JES Class for controlling access to programs

dn:CN=*.**,CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=mftesting,DC=com
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PROGRAM
microfocus-MFDS-Resource-ACE: allow:*:read
microfocus-MFDS-UID: no
description: Allow everyone permission to run any program in any library

To specify a program in a library, construct an entry with a CN of program_name.library_name:

dn:CN= MYPROG.MFI01.JOBLIB1,CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=mftesting,DC=com
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PROGRAM
microfocus-MFDS-Resource-ACE: allow:AUTOUSER:read
microfocus-MFDS-Resource-ACE: allow:SYSAD:read
microfocus-MFDS-Resource-ACE: deny:*:read
microfocus-MFDS-UID: no
description: Allow AUTOUSER and SYSAD permission to run the MYPROG program in the MFI01.JOBLIB1 library

To use wildcards:

dn:CN= ABC*.MFI01**,CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=mftesting,DC=com
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PROGRAM
microfocus-MFDS-Resource-ACE: allow:AUTOUSER:read
microfocus-MFDS-Resource-ACE: allow:SYSAD:read
microfocus-MFDS-Resource-ACE: deny:*:read
microfocus-MFDS-UID: no
description: Allow AUTOUSER and SYSAD permission to run any program starting with ABC (including ABC) program in any library that starts with MFI01

Entries are required for both the program name identified in the JCL and also its alias if it has one - for example, IDCAMS and MFJAMS.

Program libraries should be POs with programs identified as members. Adding member entries to the PDS requires ALTER permission for the dataset. As mentioned above, dynamic PDS would not be permitted in the LNKLIB list. Programs in the library require OS execute permission for the user that the JES Initiator process is running as.

Migrating to increased security checks

Beginning with release 9.0, the JES engine supports additional security measures. These are not enabled by default because they could cause program loads that were working in earlier versions to fail. This section briefly discusses these additional security features. See JCL Enhanced Security Checks for more information. Micro Focus recommends enabling at least the BASIC security level for improved product security.

The new security features are enabled by setting the ES_JES_HIGHER_SECURITY_LEVEL environment variable.

Parent topic: JES Security
Related reference
ES_JES_HIGHER_SECURITY_LEVEL
Related information
ES_JES_HIGHER_SECURITY_LEVEL


JCL Enhanced Security Checks

Note: The following applies to native COBOL applications only.

In release 9.0, the JCL engine has been enhanced to provide increased security when running programs. In the past, built programs were placed in a location identified as the JES Program Path or in a location that was identified in the catalog as a Dynamic PDS and used as the STEPLIB or JOBLIB in a job. You can still use these locations and they will work without any changes to your existing configuration settings.

However, it is now possible to increase the security by limiting the locations that any main utility and user programs may be loaded from to a set of identified datasets. You can also restrict who has access to change those datasets. These changes make it difficult for a malicious program to be picked up and used just because it is in a location that is on the JES Program Path or in a Dynamic PDS.

If you continue to use the previous configuration, you will receive some warning messages indicating that programs may not be loaded from certain locations if the enhanced security is enabled. These give you a guide to what you may need to change when moving to a higher level of security to protect your system.

Starting with 9.0, there are two new levels of security available:

  • The first, as mentioned earlier, is to ensure that programs are only loaded from predefined locations.
  • The second is to restrict access to a program in a library. To do this, you need to use the PROGRAM resource security class, which is similar to the RACF 'PROGRAM' class. You can switch to the higher levels of security by setting the environment variable ES_JES_HIGHER_SECURITY_LEVEL to values of 2, 3 or 4, where the default is 1 (none).

    If ES_JES_HIGHER_SECURITY_LEVEL=2 (or BASIC), user programs can only be loaded from defined, catalogued program libraries. These libraries should be standard partitioned datasets (PO) rather than dynamic partitioned datasets.

    You can create a set of general locations to hold programs that can be run by anyone. This list of locations is known as SYS1.LNKLIB. It is a concatenation of datasets which is created by defining them in SYS1.PARMLIB(LNKLSTNN) members. SYS1.LNKLIB does not exist as a catalogued dataset but the concatenation can be viewed using IDCAMS to LISTCAT ENTRIES(SYS1.LNKLIB)

The search for the program to load and the checks for access to that program use the alias of the program (if one is set). This ensures that if the alias of, for example, IDCAMS is changed from MFJAMS to MYPROG the search and checks are made for MYPROG. The JES Program Path for programs other than the main program called from the JCL job may still be used and programs will still be loaded from there. The loading and check is against the program identified in the JCL job. As such, each program should appear as a separate entry in a PO. The PC-DSN of the entry should point to the actual program to load. If that program makes calls to other programs, those programs may be in the STEPLIB, JOBLIB, SYS1.LNKLIB or the JES Program Path.

Important: Only approved users (Administrators) should be granted ALTER access (for the DATASET resource class) to the POs that hold programs to be loaded. This ensures that the contents might not be changed by a malicious user.

Also, the JOBLIB and STEPLIB (the private libraries) can add locations for loading programs, but when they are used, EXECUTE access are checked on the datasets. Take care when granting EXECUTE access to users on broad matching DATASET rules.

The PDS that hold programs must be disk-based, even when running with data hosted in a database. The system cannot load programs from a database location.

Example

The jcl-symbols example is available in the Mainframe\JCL\Classic subfolder (Windows) in your product samples' location, and in $COBDIR/demo (UNIX). The INITSYS.JCL, INITSYS2.JCL, and MOVEPGMS.JCL files in the sample can be used to set up the libraries for holding system programs, and to move any built modules into those libraries. Check the sample's readme file for more details.

This is how you can run the example:

  1. In ESCWA, create a JCL-enabled region.
  2. Compile the programs, and add them into the JES Program Path location.

    The MOVEPGMS.JCL looks for the programs in /home/sysadmin/libs/ (UNIX) but any location identified on the JES Program Path will work.

  3. Start the region.

    When you start it for the first time, a warning message will be written to the console log that indicates that there are no SYS1.LNKLIB entries:

    JES000067W JES Validation - 0 SYS1.LNKLIB entries.
  4. Execute INITSYS.JCL.

    This creates the symbols and a number of SYS1.PARMLIB members that describe the program datasets to load at system startup.

  5. Execute INITSYS2.JCL to create those datasets.

    A listing of SYS1.LNKLIB now shows four datasets - SYS1.PROGLIB, SYS2.LNKLIB, MFI01.MFITEST.LIB and SYS2.U30LIB.

    Note that SYS1.MFTEST.LIB(TEST1) which is specified in SYS1.PARMLIB(LNKLST02) does not appear because the member(TEST1) has not yet been created. Similarly, other datasets that might be listed in the SYS1.LNKLIB concatenation do not appear if they do not also exist in the catalog. You can create them, and populate them with load modules later on.

  6. Execute the SYMBOL6.JCL sample job. Look at the JESYSMSG for the job.

    You can see messages that state where each utility program was loaded from, including a message that the program CALLMFJZ could not be found in the private libraries and SYS1.LNKLIB. There is also a message listing the libraries:

    JCLCM0305W Failed to find program CALLMFJZ in private libraries and SYS1.LNKLIB.
JCLCM0306I Number of SYS1.LNKLIB entries:         3.
JCLCM0307I SYS1.LNKLIB : SYS1.PROGLIB,SYS2.LNKLIB,MFI01.MFITEST.LIB.

    However, because the higher security level has not been set the system goes on to look on the JES Program Path for the program, and finds it:

    JCLCM0303I Program CALLMFJZ loaded from library SYS2.LOADLIB
JCLCM0199I Program CALLMFJZ  is COBOL ANS85 ASCII  Big-Endian    NOAMODE.

    You can use MOVEPGMS.JCL to copy programs from the build location into the PO datasets.

    In the example job, the DEF1 dataset is defined as a dynamic PDS that has all *.dll files (Windows) or *.so programs (UNIX) in the /home/sysadmin/libs/ folder as its members. STEP10 uses the MFPOADD utility to copy some members of the Dynamic PDS into the standard PO, SYS1.PROGLIB, which has been identified as a system program library. MFPOADD is a variant of IEBCOPY (MFJCOPY) and will accept IEBCOPY control statements as given in the example steps in MOVEPGMS.JCL.

  7. Execute MOVEPGMS.JCL to move the programs into the locations defined in INITSY2.JCL, after first altering the location of the DEF1 temporary dynamic PDS to the location in which you have put your built program.
  8. Make sure your programs are now in the SYS1.PROGLIB dataset. They should be visible in the catalog listing.

    If running on UNIX, you might need to set the program permissions to be executable as these may have been lost in the copy from the original location.

  9. If you run SYMBOL6.JCL again, you should now see that CALLMFJZ is now loaded from SYS1.PROGLIB.
  10. Stop the region, and add the following entry to the ES Configuration section in the region definition:
    [ES-Environment]
ES_JES_HIGHER_SECURITY_LEVEL=2
  11. Start the region, and look at the console.log.

    You should see the following messages:

    ES000067I JES Validation -         5 SYS1.LNKLIB entries.
JES000068I SYS1.LNKLST: SYS1.PROGLIB,SYS2.LNKLIB,MFI01.MFITEST.LIB,SYS1.MFTEST.LIB(TEST1),SYS2.U30LIB

    These show that there are five entries in the SYS1.LNKLIB concatenation. Note that not all of these entries exist in the catalog as can be seen by doing an IDCAMS LISTCAT ENTRIES(SYS1.LNKLIB).

  12. Execute SYMBOL6.JCL again.

    The following messages appear:

    Program IEBGENER (MFJGENER) loaded from library SYS1.LOADLIB
Program CALLMFJZ loaded from library SYS1.PROGLIB
  13. From the catalog view, delete the CALLMFJZ member from the SYS1.PROGLIB PO, and run SYMBOL6.JCL again.

    You should receive the following message:

    Failed to find program CALLMFJZ in private libraries and SYS1.LNKLIB

    Even though the program might still be on the JES Program Path, it will not be used unless it is in one of the defined system libraries or a private JOBLIB or STEPLIB library.

    In the program load messages above, the symbolic name SYS1.LOADLIB indicates that the program has been loaded from the product. SYS2.LOADLIB would indicate the JES Program Path.

Parent topic: JES Security
Related reference
ES_JES_HIGHER_SECURITY_LEVEL


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 does not 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. 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
default=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).
[Trace] section
verify=yes

Enables trace messages for the osesm Verify operation. Trace messages are written to the same location as error messages, for example the console log. Tracing is useful in diagnosing issues, but might reveal sensitive data to an attacker who can obtain copies of log files. Disable tracing when it is not needed.

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. The Micro Focus YouTube channel contains videos on how to configure an AD LDS instance, and then define an external security manager that utilizes it in Enterprise Server,

  • 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 OpenText Support for Micro Focus Products 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


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


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


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

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.

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.

Note: If you want to use the Microsoft user object class for your Enterprise Server 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 (deprecated)
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 (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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
Related information
ES_USR_DFLT_ESMAC


Configure ES Security

To use the ES security information in LDAP, you will need to configure ES security in ESCWA:

  1. In the menu bar, click Security.

    This opens the Defined External Security Managers page.

  2. Click + Add.

    This opens the External Security Manager Configuration dialog box.

  3. In the Name field, type a descriptive name.
  4. In the Module field, type mldap_esm.
  5. In the Connection Path field, type the connection path and port number to your LDAP server.
    Note: ldap://servername or ldaps://servername to use an SSL-secured connection, if your LDAP client and server support SSL.
  6. In the Authorized ID and Password fields, type the credentials that the MLDAP ESM module requires to connect.

    The user should have read, write, and modify access to the Enterprise Server user, group, and resource objects in the LDAP repository.

    Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
  7. In the Description field, type a description.
  8. In the Configuration Information field, you can add a number of directives to alter the default behavior. Configure this for your particular LDAP repository requirements. A typical configuration might 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
  9. In the Cache limit field, sets the size of the LDAP search-result cache.
  10. In the Cache TTL field, parameter sets the lifetime of entries in the LDAP search-result cache.
  11. Click Save.
  12. 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.

Parent topic: Preparing Active Directory for Enterprise Server Security


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

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.
    Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
  • 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


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 with ESF
  • 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


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 with ESF

When you configure ESF to use Windows users, you can optionally make use of Windows groups to assign resource access permissions.

The OS ESM Module does not set user-group information in Enterprise Server, but it is possible to use Windows groups through the MLDAP ESM Module, even if you are using the OS ESM Module to validate user credentials.

By default, the MLDAP ESM Module uses Micro Focus group objects in the LDAP repository (object class microfocus-MFDS-Group) to assign users to groups. You can configure it to use Windows groups defined in Active Directory (AD) instead with the group type configuration option in the Security Manager's Configuration Information field. For example:

[LDAP]
group type=AD

You might also need to set options such as group container and search scope so the Security Manager can find the groups in your Active Directory tree.

With this setting, the module will apply group membership based on Active Directory groups that the user belongs to.

There are some restrictions:

  • As with Micro Focus groups, settings such as the maximum number of groups, the use-all-groups option, and the group federation setting still apply.
  • Group names in Enterprise Server are limited to 8 characters, so all Active Directory group names will be truncated at 8 characters. Groups with names which are not unique in the first 8 characters will be treated as a single group. Resource access rules must use these shorter names.

It is also possible to configure a different attribute of the group object to be used as the group name with the group short name attribute configuration option.

See MLDAP ESM Module Custom Configuration Information for more information.

  • Group logon restrictions
Parent topic: Restrictions


Group logon restrictions

When using Active Directory users with Enterprise Server, normal Windows security mechanisms apply. This also means that any security restrictions that apply to a user's groups, such as allowed logon times, will be enforced, even if Enterprise Server is not configured to use Windows groups.

Parent topic: Windows Groups with ESF


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


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


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 behavior. 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.
Note: If MFDS is set to Restrict administration access and the MFDS Anonymous access option is off (the default), then valid authorized credentials will be required to access information stored in the Directory Server either via the legacy UI, ESCWA, or utilities such as mdump.
Parent topic: Verify the Security Configuration
Related reference
Long Usernames and Passwords


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 Enterprise Server Environment
  • Configuring the OpenLDAP server
  • Configuring mldap_esm Security Manager for an LDAP Server
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 Enterprise Server 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). Enterprise Server 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 OpenText Support for Micro Focus Products website's Examples and Utilities page.

  • Follow this link to the Examples and Utilities page:

    Micro Focus Customer Support 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


Configuring the OpenLDAP server

The following assumptions must be true before you start the configuration of the OpenLDAP server:

  • You have appropriate authority to administer the system.
  • Are working in a writeable working directory.
  • The Enterprise Server product is installed in the default location.
  • Root access will be required for most actions.
Note: Different UNIX versions might require variations of the listed commands.

The subsequent use of secldap is an example container name; customize this as required.

Perform the following steps to configure your OpenLDAP server:

  1. The following step is optional and only required if you want to start from a known initial state if you already have OpenLDAP installed and in use. If OpenLDAP has not already been installed skip to step 2.
    Important: Checked with your LDAP administrator before you remove slapd configuration from your system, especially if you already have applications relying on OpenLDAP or the schema in use has previously been extended. Micro Focus recommends that you backup any existing files in case you might need to restore them, for example:
    tar czf /etc/openldap/slapd-backup.tgz slapd.conf -C /var/lib ldap

    To stop and clear slapd, execute the following on the command line:

    systemctl stop slapd
systemctl disable slapd
rm -rf
/etc/openldap/slapd.d
rm -f /var/lib/ldap/*
yum -y remove openldap-servers
yum -y remove openldap-clients
  2. To install OpenLDAP, execute the following on the command line:
    yum -y install openldap-servers
    yum -y install openldap-clients
  3. Modify the slapd.d/cn=config/olcDatabase={0}config.ldif file:
    sed -i '/CRC.*/d' /etc/openldap/slapd.d/cn=config/olcDatabase={0}config.ldif

sed -i '/olcAccess:.*/c\olcAccess: {0}to * by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage by * break' /etc/openldap/slapd.d/cn=config/olcDatabase={0}config.ldif

sed -i '/ al,cn=auth.*/d' /etc/openldap/slapd.d/cn=config/olcDatabase={0}config.ldif
  4. Start the slapd process:
    systemctl start slapd
  5. Create a chrootpwd.ldif file in the current directory with the following contents:
    dn: olcDatabase={0}config,cn=config
changetype: modify
add: olcRootPW
olcRootPW: {SSHA}xxxxxxxxxxxxxxxxxxxxxxxx
  6. Modify chrootpwd.ldif and add a Root DN password. In the command below replace [password] with a password of your choice:
    secret=$(slappasswd -s [password])

sed -i "/olcRootPW:.*/c\olcRootPW: $secret" chrootpwd.ldif
  7. Extend the LDAP schema using ldapadd commands:
    ldapadd -Y EXTERNAL -H ldapi:/// -f chrootpwd.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/core.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/corba.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/cosine.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/duaconf.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/dyngroup.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/inetorgperson.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/java.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/misc.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/nis.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/openldap.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/collective.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/ppolicy.ldif
  8. Create a backend.ldif file in the current directory with the following contents:
    dn: cn=module,cn=config
objectClass: olcModuleList
cn: module
olcModulepath: /usr/lib/openldap
olcModuleload: back_hdb

dn: olcDatabase=hdb,cn=config
objectClass: olcDatabaseConfig
objectClass: olcHdbConfig
olcDatabase: {1}hdb
olcDbDirectory: /var/lib/ldap
olcDbIndex: objectClass eq,pres
olcDbIndex: ou,cn,mail,surname,givenname eq,pres,sub
olcSuffix: dc=secldap,dc=com
olcRootDN: cn=Manager,dc=secldap,dc=com
olcRootPW: {SSHA}xxxxxxxxxxxxxxxxxxxxxxxx
olcAccess: {0}to attrs=userPassword,shadowLastChange by dn="cn=Manager,dc=secldap,dc=com" write by anonymous auth by self write by * none
olcAccess: {1}to dn.base="" by * read
olcAccess: {2}to * by dn="cn=Manager,dc=secldap,dc=com" write by * read
  9. Create a password for the Enterprise Server connection, replace [connection password] with a password of your choice:
    secret=$(slappasswd -s [connection password])

sed -i "/olcRootPW:.*/c\olcRootPW: $secret" backend.ldif

ldapadd -Y EXTERNAL -H ldapi:/// -f backend.ldif
  10. Stop the slapd daemon:
    systemctl stop slapd
  11. Create a schema_convert.conf file with following contents:
    include corba.schema
include core.schema
include cosine.schema
include duaconf.schema
include dyngroup.schema
include inetorgperson.schema
include java.schema
include misc.schema
include nis.schema
include openldap.schema
include ppolicy.schema
include collective.schema
include container.schema
include mfds.schema
  12. Create Enterprise Server schema extensions using MFDS:
    cp -r /etc/openldap/schema .

mfds -l "dc=secldap,dc=com" 2 schema/mfds.schema

rm -rf schema/cn=config

cd schema

slaptest -f ../schema_convert.conf -F .

cd ..

cp schema/cn=config/cn=schema/cn={12}container.ldif /etc/openldap/slapd.d/cn=config/cn=schema

cp schema/cn=config/cn=schema/cn={13}mfds.ldif /etc/openldap/slapd.d/cn=config/cn=schema

chown -R ldap /etc/openldap/slapd.d

chmod -R 700 /etc/openldap/slapd.d
  13. Restart the slapd standalone LDAP daemon:
    systemctl start slapd
  14. Enable the slapd service:
    systemctl enable slapd
  15. Create a log folder:
    rm -rf schema/log

mkdir schema/log
  16. Create an additional schema extension file top.ldif in the schema directory:
    dn: dc=secldap,dc=com
objectClass: dcObject
objectClass: organization
dc: secldap
description: secldap domain
o: MFSECLDAP
  17. Create an additional schema extension file mf-containers.ldif in schema directory:
    dn: cn=Micro Focus,dc=secldap,dc=com
cn: Micro Focus
objectClass: container

dn: cn=Enterprise Server Resources,cn=Micro Focus,dc=secldap,dc=com
cn: Enterprise Server Resources
objectClass: container

dn: cn=Enterprise Server Users,cn=Micro Focus,dc=secldap,dc=com
cn: Enterprise Server Users
objectClass: container

dn: cn=Enterprise Server User Groups,cn=Micro Focus,dc=secldap,dc=com
cn: Enterprise Server User Groups
objectClass: container
  18. Install the remaining schema extensions:
    ldapadd -v -D "cn=Manager,dc=secldap,dc=com" -w [connection_password] -f schema/top.ldif -h localhost:389 > schema/log/top.log

ldapadd -v -D "cn=Manager,dc=secldap,dc=com" -w [connection_password] -f schema/mf-containers.ldif -h localhost:389 > schema/log/containers.log

rm -f schema/mfds-users.ldif

mfds -e "cn=Micro Focus,dc=secldap,dc=com" "cn=Enterprise Server Users" "cn=Enterprise Server User Groups" "cn=Enterprise Server Resources" 2 "schema/mfds-users.ldif"

ldapadd -v -D "cn=Manager,dc=secldap,dc=com" -w [connection_password] -f schema/mfds-users.ldif -h localhost:389 -c > schema/log/mfds-users.log

sed 's/DC=X/CN=Micro Focus,dc=secldap,dc=com/' /opt/microfocus/EnterpriseDeveloper/etc/es_default_ldap_openldap.ldf > schema/es_default_ldap_openldap.ldif

ldapadd -v -D "cn=Manager,dc=secldap,dc=com" -w [connection_password] -f schema/es_default_ldap_openldap.ldif -h localhost:389 -c > schema/log/es_default_ldap_openldap.log
  19. Confirm the schema extensions have been installed using the following command:
    ldapsearch -h localhost:389 -x -b "cn=subschema" -s base + > schema.txt
    Check the contents of the resulting file, schema.txt, to verify that there are attributes and objectClass entries that begin with microfocus-. You can also attempt to connect to the "dc=secldap,dc=com" or your customized variation, Base DN using an LDAP browser or other LDAP access tool via port 389 using the "cn=Manager,dc=secldap,dc=com" simple id and [connection password] password and browse the "cn=Micro Focus" container tree.
Parent topic: Configuring Security Using OpenLDAP


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, you are defining a User.
description: User Description | User description, used for documentation purposes.
microfocus-MFDS-UID: no | Unique Identifier (UID), this can be any string; it does not have to be unique. It is not used by Enterprise Server.
microfocus-MFDS-CustomText | Optional, this can be any text. Not used by Enterprise Server.
microfocus-MFDS-User-AllowLogon: TRUE | TRUE if the user can login to a terminal or ESMAC.
microfocus-MFDS-User-CreateToken: self | User can create a passtoken for themselves. Used for single sign-on (SSO), the user can sign into MFDS and credentials will be passed to ESMAC.
microfocus-MFDS-User-DefaultGroup: PAYROLL | Default group, a user has a default group, but can be part of several groups. The default group is used if the user does not specify a group when logging in.
microfocus-MFDS-User-LastLoginTime | Optional, usually set by Enterprise Server, if enabled. Date and time of the user's most recent login.
microfocus-MFDS-User-LoginAttempts | Optional, usually set by Enterprise Server, if enabled. Number of unsuccessful login attempts since user last logged in.
microfocus-MFDS-User-MTO-Priority: 0 | User priority for mainframe emulation.
microfocus-MFDS-User-MTO-Timeout: 0 | User login timeout in minutes, for mainframe emulation. 0 means use the default timeout configured for the enterprise server region. Inactivity when signed on.
microfocus-MFDS-User-MTO-OperatorClass: 0 | Operator Class for mainframe emulation.
microfocus-MFDS-User-Pwd: literal:UserPassword | User password, this can be changed by using ESMAC or CESN.
microfocus-MFDS-User-Pwd-ExpirationDate | Optional, If set, the user's password expires on the given date and must be changed.
microfocus-MFDS-User-Pwd-History | Optional, usually set by Enterprise Server, if enabled. History of password hashes used to enforce non-reuse of passwords.
microfocus-MFDS-User-Pwd-MustChange | TRUE if the user must change his password at next login.
microfocus-MFDS-User-UseToken: self | The User can be signed on using a passtoken created for themselves. Used for single signon.
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
objectClass: microfocus-MFDS-Group | Object class, we are defining a Group
adminDisplayName: Payroll group | Display Name
description: People who can process Payroll | Description for the group
microfocus-MFDS-CustomText | Optional. Can be any text. Not used by Enterprise Server
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.
microfocus-MFDS-UID: no | UID (Unique Identifier). This can be any string; it does not have to be unique. It is not used by Enterprise Server
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 class OPERCMDS
changetype: add | Action set to add, will create the resource class
objectClass: top | This is a top-level object
objectClass: container | This is a container (it will contain resource entities)
description: Class for operator commands used by casstart/casstop/casout/casfile/cassub commands | Description. May be any text
 | 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 entity
microfocus-MFDS-CustomText | Optional. Can be any text. Not used by Enterprise Server
microfocus-MFDS-Resource-Class: OPERCMDS | Name of the resource class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSADM group:alter | Access Control Entry 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). This can be any string; it does not have to be unique. It is not used by Enterprise Server
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 resource class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSADM group:alter | Access Control Entry 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). This can be any string; it does not have to be unique. It is not used by Enterprise Server
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 class DATASET
changetype: add | Action set to add, will create the resource class
objectClass: top | This is a top-level object
objectClass: container | This is a container (it 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 resource class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSADM group:update | Access Control Entry 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 Access Control Entry definition can be added
microfocus-MFDS-UID: no | UID (Unique Identifier). This can be any string; it does not have to be unique. It is not used by Enterprise Server
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 class
changetype: add | Action set to add, will create the resource class
objectClass: top | This is a top-level object
objectClass: container | This is a container (it 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-CustomText | Optional. Can be any text. Not used by Enterprise Server
microfocus-MFDS-Resource-Class: SURROGAT | Name of the resource class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:SYSAD:read | Access Control Entry definition, we allow SYSAD to be a surrogat user of PLTPISUR
microfocus-MFDS-Resource-ACE: deny:*:execute | Access Control Entry definition, we deny everyone else
microfocus-MFDS-UID: no | UID (Unique Identifier). This can be any string; it does not have to be unique. It is not used by Enterprise Server
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 class
changetype: add | Action set to add, will create the resource class
objectClass: top | This is a top-level object
objectClass: container | This is a container (it 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 resource class that the entity belongs to
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:read | Access Control Entry definition, we grant anyone from group ALLUSER read access
microfocus-MFDS-Resource-ACE: deny:*:execute | Access Control Entry definition, we deny everyone else
microfocus-MFDS-UID: no | UID (Unique Identifier). This can be any string; it does not have to be unique. It is not used by Enterprise Server
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.
  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.
Note: The requirement to be signed into ESF can be disabled for LIST commands, using the allow-list configuration option:
[Admin]
allow-list=yes
This allows ESF Admin LIST requests by anonymous users, that is, without specifying credentials. It applies only to LIST requests.
  • About Managing an LDAP Server
  • Changing User Passwords Stored in an LDAP Server
  • 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 Server

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.

In addition, 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, 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.

Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
Parent topic: Managing LDAP Security Manager from the Enterprise Server UI


Changing User Passwords Stored in an LDAP Server

There are various ways for Enterprise Server users to change passwords stored in an LDAP server. 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 perform this in ESCWA:

  1. In the top menu bar, click Security.

    This opens the Defined External Security Managers page.

  2. Select the definition that you want to edit by clicking edit icon at the end of the row.

    This opens the External Security Manager Configuration dialog box.

  3. 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 (DN).

    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.

  4. In the Password field, type the password used to bind to the LDAP server.
    Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
  5. Click Save.
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, 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 is 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 and vsam_esm modules, you can use the Enterprise Server Common Web Administration (ESCWA) screens to define users, groups, resource classes, and resources, which are 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 enables you to write a single rule to apply to multiple resources.

With the mldap_esm and vsam_esm modules, 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. See Using all groups to which a user belongs for more information.

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.

  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

Attention: ESF LDAP security administration Web interface is no longer supplied with Enterprise Developer. Micro Focus recommends you adopt the Enterprise Server Common Web Administration (ESCWA) interface. ESCWA is a modern and feature-rich interface that combines functionality from Enterprise Server Administration, ESMAC, and the ESF LDAP Security Administration interfaces. See Enterprise Server Common Web Administration for more information.
Parent topic: Securing an Enterprise Server Installation


Migrating from Enterprise Server Early Versions

For Enterprise Server releases after Net Express or Server Express 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).

Note: casesm can only be used within CAS and the CAS command-line utilities, and is ignored by MFDS, MFCS, and any non-CAS utilities such as esfadmin.
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 Enterprise Developer applications, its schema must be extended to support the Enterprise Developer 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:

Parameter | Description
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

This is the default value.

2
OpenLDAP
3
Sun Directory
4
OpenLDAP (v2.4)
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 (for example, mfds_schema_1.05.09.ldf)

schema-version-1 Specifies the version of the schema extensions to be generated:
0
Current schema version.

This is the default value.

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 than 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 the following command:

mfds -L DC=mycom,DC=com 1 c:\mfds-schema.ldf

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 LDIFDE tool is used to extend the repository schema, the generated LDIF 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 exported 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 in ESCWA:

  1. Add a security manager to the security manager list as described by To Add or Remove a Security Manager from the List and specify the following details:
    • In the Name field, type the name that you will use to refer to the security manager when adding it to particular security manager lists, for example, you might call it MLDAP.
    • In the Modulefield, type mldap_esm.
    • In the Connection Path field, type the address for your LDAP server, for example, localhost:389.
    • The Authorized ID and Password fields 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.
      Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
      mfsecret:configuration-name:secret-path

      or:

      mfsecret::secret-path

      or:

      mfsecret:secret-path

    Make sure that you check Enabled. 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 Specifying an External Security Manager for more information.
Parent topic: AD LDS Migration Tasks


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


To Secure Access to Enterprise Server Logs

Enterprise Server external security using an LDAP security manager must be configured and enabled for the region.
  1. In the LDAP repository, in the resource container (default CN=Enterprise Server Resources), create the class container CN=Communications Server, if it does not already exist.
  2. In the class container CN=Communications Server, create the resource access control objects CN=Enterprise Server Console Log and CN=Communications Server Log, if they do not already exist. Use the LDAP class microfocus-MFDS-Resource, unless a different resource class is specified in your Security Manager configuration (this is rare). Access to the console and communications logs through the administration web interfaces (or by HTTP requests directly to the communications server) is now restricted by these objects. The logs cannot be viewed remotely unless Access Control Lists (ACLs) are set.
    Note: When security is enabled for an Enterprise Server log, Enterprise Server uses HTTP Basic Authentication to request a username and password. To avoid credentials being sent in plaintext over the network, configure SSL for the region's Communications Servers. The username and password are validated, and then the user's identity is checked against the Access Control List.
  3. Edit the CN=Enterprise Server Console Log and CN=Communications Server Log objects to specify access to the console and communications logs, respectively. Edit the value of the attribute microfocus-MFDS-Resource-ACE to add one or more Access Control Entries granting access to the log.
  4. Save your changes to the LDAP data and either restart the region or send it a Security Update notification. Your new settings will take effect.
For example, the access control entry allow:SYSAD:read will allow the SYSAD user to retrieve the log over HTTP and view it in the web administration interfaces.
Parent topic: Securing an Enterprise Server Installation


Security Considerations for Service Interface Deployment

The ability to deploy a service interface to Enterprise Server poses security risks. An attacker with network access to an enterprise server instance could use service interface deployment to upload and execute arbitrary programs under Enterprise Server, replace an existing service with a malicious implementation, or retrieve information about existing services. To mitigate these risks you can disable or restrict deployment to an enterprise server instance.

Disabling deployment

A deployed service interface running on an enterprise server instance uses a communications listener. This listener typically uses the Web conversation type, which is named Web by default. When a new enterprise server instance is created, a Web listener is created for it.

You can completely disable deployment by setting the New Status of the Web listener to Disabled.

Note: If a listener is currently disabled, you can enable it by changing the status to Stopped or to Started if the server is running.

Restricting deployment to local clients

As an alternative to completely disabling deployment to an enterprise server instance, you can restrict the Web listener to accept deployment from local connections only. A local connection, also called a loopback or localhost connection, originates from the same host. The local connection prevents the acceptance of deployment from any remote connection.

Important:
  • By default, all newly created enterprise server instances restrict deployment acceptance to local connections.
  • When using the Validate function, and when importing a server definition, ESCWA interface displays a warning if remote deployment is enabled.

To set the deployment acceptance behavior for a Web listener:

  1. From the Enterprise Server Administration Home page, click the Stop button in the Status column for the enterprise server region you are configuring.
  2. On the Stop Server Confirmation page, click OK.

    Wait for the server's status to change to stopped.

  3. In the Communications Process column, click Details.

    This takes you to the Listeners page.

  4. Click the Edit button that corresponds to Web listener.
  5. Edit the Web listener definition using one of the following options:
    • To restrict the listener to accept deployment from local systems only:
      1. In the Endpoint Address field, type localhost:*.
      2. Click OK.
    • To enable (or reinstate) remote deployment acceptance:
      1. In the Endpoint Address field, type *:*.
      2. Click OK.
  6. Click Home to return to the Enterprise Server Administration Home page.
  7. Click the Start button in the Status column for the enterprise server region you are configuring.

Requiring user authentication and authorization

Beginning with Enterprise Server 5.0, the Web service deployment listener can be configured to require user authentication, and optionally to restrict deployment to specific users. This feature requires an enterprise server instance with External Security enabled. See About Securing an Enterprise Server Installation for more information on Enterprise Server security.

User authentication prevents anonymous deployment of service interfaces. The deployment client must present user credentials identifying the user who is attempting to deploy the interface. There are three options for authenticating deployment users:

  • HTTP Basic Authentication: A username and password are supplied as part of the HTTP requests made by the deployment client. Users who deploy using the IDE can supply these credentials when they deploy. With the imtkmake command-line utility, they can be supplied using the username and password parameters. For the web-deploy.html deployment web page, the browser will prompt for credentials if the listener is configured to require them.
  • Certificate Authentication: If the deployment listener is configured to use SSL/TLS, and to require or allow client certificates, the deployment client can send a client certificate to the server. The server can be configured to associate this certificate with a specific user. For the IDE and imtkmake, the client certificate can be configured in mf-client.dat. When deploying with a browser and web-deploy.html, the client certificate will have to be configured using the browser's certificate management interface. Client certificates can be associated with users using the cascertreg utility or by automatic registration (see Deployment listeners).

Recommendations

Micro Focus recommends you consider the following:

  • Do not enable deployment through the Web listener if you are using Enterprise Server for mainframe emulation only.
  • If the Web listener is enabled, keep it restricted to local deployment if possible. This is sufficient for typical development use, where a developer builds and deploys on a local machine for testing.
  • When possible, avoid enabling remote deployment acceptance, particularly for production and staging systems used for Continuous Integration (CI) or QA testing. In cases where remote deployment acceptance is absolutely necessary, Micro Focus recommends that you consider taking any or all of these additional precautions:
    • Restrict access to the Web listener using a firewall.
    • Use the Enterprise Server conversation filtering feature. See Conversation Filtering for more information.
    • Enable TLS (SSL) with client certificate authentication.
  • For CI, QA testing, and production, copy CAR files to the target system using a mechanism such as file sharing or FTP, and install the interface by running the mfdepinst utility. See mfdepinst command for more information.
Parent topic: Securing an Enterprise Server Installation
Related concepts
User accounts in the Default Enterprise Server Security Configuration


DCAS Security

Enterprise Server provides a feature known as Digital Certificate Authentication Service (DCAS), that provides temporary credentials for users to sign on to an enterprise server region that is secured using the External Security Facility (ESF). The DCAS feature is most commonly used to provide single sign-on for TN3270 users using the Express Logon Facility (ELF), also known as Certificate Express Logon (CEL), or using an external single-sign-on provider such as Micro Focus Host Access for Cloud (formerly Host Access Management and Security Server) and its Automated Sign-On for Mainframe feature. The DCAS feature is not enabled by default.

In previous releases of Enterprise Server, enabling the DCAS feature created a security vulnerability, because access to the DCAS mechanism was not sufficiently restricted. A knowledgeable attacker could use DCAS to impersonate other Enterprise Server users. To correct this issue, a number of security features have been added to DCAS. This topic provides an overview of those features.

Internal and external DCAS

You can implement DCAS to work either internally with one or more TN3270 listeners and the Express Logon Facility, or externally to support advanced authentication systems such as Automated Sign-On for Mainframe. Here "internally" means the TN3270 listener calls DCAS directly, and it is not necessary to configure a DCAS listener. "Externally" means the DCAS listener connects to an external client such as Host Access for Cloud.

With internal DCAS, only TN3270 listeners can use DCAS. This makes it less vulnerable to attack. However, you can only use internal DCAS to implement Express Logon Facility, and not for any other purpose.

Internal DCAS is enabled in the configuration of each TN3270 listener that is to support Express Logon Facility. See the configuration options for the TN3270 conversation type for more information.

You can use external DCAS for Express Logon Facility and other DCAS applications. External DCAS is enabled by creating a custom listener with the DCAS conversation type. You might also need to configure your TN3270 listener to use external DCAS. See the topics Configuring a region for Express Logon Facility and Configuring a region for Automated Sign-On for Mainframe.

DCAS client authentication

A DCAS listener must use TLS (SSL). With TLS you can optionally require client authentication, which prevents clients from connecting to the listener unless they have a client certificate that is signed by a certificate authority (CA) known to the listener. Enabling client authentication is an additional security measure you can use to prevent abuse of the DCAS feature. See the topic SSL Options for more information.

When client authentication is enabled for the DCAS listener, by default, the listener also requires that the client certificate be associated with an Enterprise Server user, using the certificate registration information. This is also known as "certificate mapping". See the topic User Certificate Registration for CICS Web Interface Servers and DCAS. This requirement can be relaxed using the DCAS configuration setting allow unauthenticated clients=yes; refer to the list of configuration settings for the DCAS conversation type for more information.

When using client certificates with DCAS (or other listeners), the enterprise server region administrator might also need to add the following setting to the listener configuration:

[MF SSL]
match client hostname=no

This tells the listener that client certificates do not need to identify the client host machine, but may identify a user.

Restricting certificate mapping

There are two types of DCAS requests, referred to as "Format 1" and "Format 2" in the IBM and Micro Focus documentation. Format 1, usually used by Express Logon Facility, accepts a user's certificate and returns an Enterprise Server user ID and passticket. Format 2, typically used by external authentication systems such as Automated Sign-On for Mainframe, accepts a user ID and returns a passticket. You can configure which formats are accepted by a DCAS listener. See allowed formats under DCAS conversation type for more information.

For a Format 1 request, the DCAS listener must "map" the certificate to an Enterprise Server user, as it does for the client certificate when client authentication is enabled, as described in the previous section. It does this by consulting the collection of registered certificates. If the certificate is not found, the request is rejected.

Note: Do not confuse the client certificate, which is optionally sent by the client as part of establishing the TLS conversation, with the user's certificate that is contained in the Format 1 request. The client certificate identifies the client program; the user certificate identifies the user who is requesting a passticket to sign on to the enterprise server region. The two might be the same certificate, or not, but they are used for different purposes. Also, the client certificate is optional, but the user certificate must be supplied as part of the Format 1 request.

After the certificate is mapped, the DCAS listener checks to see if the mapping is allowed for DCAS. By default, registered certificate mappings can be used for both DCAS and CICS Web Interface (CWI). An administrator can mark a mapping as not allowed for DCAS by adding the line dcas=no to the certificate mapping file. This can also be done when a certificate is registered using the cascertreg utility. See the topics User Certificate Registration for CICS Web Interface Servers and DCAS and cascertreg for more information.

This additional control lets an administrator specify that a mapping can only be used for a specific purpose (currently DCAS or CWI), or disable a mapping for all purposes while retaining it for future reference.

Note: The mapping restrictions and other data in the certificate registration file is read the first time a user certificate is received by DCAS or CWI after region startup. Changing the settings in the file after that will not take effect until the region is restarted.

DCAS supports an option to do an implicit client mapping, for Format 1 requests only, from the Common Name (CN) component of the client certificate's Subject Distinguished Name. If this is enabled by setting userid source=cnv or userid source=cn fallback in the listener configuration, then a certificate registration is not required if the client certificate has a CN which is a valid Enterprise Server user ID, or can be mapped to an Enterprise Server user ID by the External Security Facility, if map CN=yes is also configured.

DCAS user authorization

The DCAS listener has two optional authorization checks that can also be enabled to restrict the users for whom DCAS generates passtickets. These checks are made using the external security (ESF) configuration of the enterprise server region.

By default, after identifying the user for whom a passticket is being requested, and validating that user ID, DCAS queries external security to see if that user has "update" access to a resource in the PTKTDATA class. The name of the resource is the APPLID supplied in the request. When DCAS is invoked for Express Login Facility, the APPLID is supplied by the TN3270 client, but could be modified by the TN3270 listener. See the configuration options for the TN3270 conversation type. For other DCAS uses, the APPLID is supplied by the DCAS client. By convention it is typically the enterprise server region name.

The purpose of the PTKTDATA resource class is similar to how it is used on the mainframe, but details of its use are different.

If the PTKTDATA resource class is not defined, this check passes for all requests. The check can also be disabled in the listener configuration using the check user authorization setting; this could be useful for both development and test enterprise server regions.

DCAS can also be configured to make an authorization check using the client certificate. This check is disabled by default and must be enabled using the check client authorization configuration setting. When it is enabled, if the client sends a certificate, DCAS extracts the subject (an X.509 distinguished name) and request access to a resource with that name in the DCASCCRT class. For a Format 1 request, "read" access to this resource is required; for a Format 2 request, "control" access is required.

Note: Clients can be forced to send a certificate by configuring the DCAS listener appropriately.

The certificate subject is a distinguished name with components ordered from least-specific to most-specific and separated by slashes, for example /C=US/ST=MD/L=Rockville/O=Micro Focus/OU=Development/CN=Some User. Depending on how you issue user certificates, you might use this to restrict DCAS passtickets to users in particular groups. For example, consider these security rules:

Resource name | Access control list
**/OU=Customer Agent/** | allow:*:control
**/OU=Administrators/** | allow:*:read
** | allow:*:none

With these rules:

  • User certificates for users in the "Customer Agent" organizational unit can be used for Automated Sign-On for Mainframe and for Express Login Facility.
  • User certificates for users in the "Administrators" organizational unit can be used for Express Login Facility, but not for DCAS Format 2 requests. This makes it more difficult for an attacker to impersonate an administrator, while still giving administrators a single sign-on mechanism for TN3270.
  • User certificates for users in other organizational units cannot use DCAS at all.

Other DCAS security controls

The following additional security measures can also be used to help prevent abuse of the DCAS feature. These are available even in older versions of Enterprise Server that lack the new features described above.

Restricting access to passtokens (LDAP-based security)
When an enterprise server region uses LDAP-based security, access to the passtoken feature can be restricted on a per-user basis using attributes of the LDAP user objects. This can be used to prevent certain high-risk users, such as system administrators, from being signed on to a centerprise server region using DCAS.
Listener binding
A DCAS listener can be configured to bind to only a particular network interface (specified as a hostname or IP address), rather than to "*", which means all interfaces. This is most commonly used with localhost to bind the DCAS listener only to the loopback interface, preventing connections to it from other systems on the network.
Listener conversation filtering
The Micro Focus Communications Server has a simple firewall mechanism known as conversation filtering. It can be used to restrict which systems can connect to a DCAS listener. See the topic Conversation Filtering for more information.
Parent topic: Securing an Enterprise Server Installation
Related concepts
Configuring a region for Express Logon Feature
Configuring a region for Automated Sign-On for Mainframe
User Certificate Registration for CICS Web Interface Servers and DCAS
Conversation Filtering
Multi-Factor Authentication
Related reference
cascertreg
check client authorization
check user authorization
allow unauthenticated clients
allowed formats


Security Reference Information

This section contains security-related reference information.

  • Environment Variables used in Enterprise Server Security
  • Resource Classes used by Enterprise Server
  • Resource Classes for Communications 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
Note: JCL job submission through ESCWA and the IDE will fallback to the ESMAC default user unless the ESCWA JES Default User Job Submission property has been set in the Advanced Region Properties page in ESCWA, in this case it will fallback to the JES default user.
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_JES_HIGHER_SECURITY_LEVEL
  • 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 behavior CESN transaction response for invalid user credentials. Default behavior 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
Note: Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
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.
Note: The environment variable ES_ESM_SECPRFX is only applied to CICS classes.
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_JES_HIGHER_SECURITY_LEVEL

Determines which programs are loaded based on checks made against the list of SYS1.LNKLIB entries.
Syntax
ES_JES_HIGHER_SECURITY_LEVEL={0|[1|NONE][2|BASIC][3|WARN][4|ENHANCED]}
Parameters
0
The behavior is unchanged with regard to JES enhanced security.
1|NONE
A value of 1 or NONE is the equivalent of not setting the value and maintains the behaviour of earlier versions of Enterprise Test Server. With a setting of 1 or no setting at all, warning messages about the number of SYS1.LNKLIB entries might be issued if none have been defined (JES000067W) and messages about programs not being loaded from certain locations (JES000069W) are also given. In addition, messages JCLCM0260W and JCLCM0308W might also be issued.
2|BASIC
A level of BASIC or 2 causes programs to be loaded from the list of SYS1.LNKLIB entries, STEPLIB, and JOBLIB locations. Programs in other locations are not loaded. The loading of programs from dynamic PDSs is also entirely disabled.
3|WARN
A level of WARN or 3 causes checks to be made against the PROGRAM and the PHYSFILE security classes. The PHYSFILE check is to make sure the PHYSFILE resource class is implemented. If these checks fail, a warning message (JCLCM0262W, JCLCM0263W or JCLCM0266W) is issued.
4|ENHANCED
A level of ENHANCED or 4 will cause the same PROGRAM and PHYSFILE checks to be made but if they fail then the job will abend with an S913 security error and a suitable message will be issued to indicate the failure.
Default
ES_JES_HIGHER_SECURITY_LEVEL=1
Parent topic: Variables for Configuring MSS Security Behavior
Related concepts
Overview of JES Security
JCL Enhanced Security Checks
Related information
Overview of JES Security


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.
Note: Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure this environment variable. See Advanced Region Properties for more information.
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 behavior 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 Communications Server
  • 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 behavior, use the ES_OLD_SEC_TSTD environment variable.

Parent topic: Resource Classes used by Enterprise Server


Resource Classes for Communications Server

The table below defines the name of each default resource class used in Enterprise Server Communications Server, the entities contained, and the permissions that a user requires:

Class name | Entities | Description | ACCESS LEVEL
Communications Server | Enterprise Server Console Log | Controls access to the Enterprise Server Console Log via the web interface. | Read
 | Communications Server Log | Controls access to the Communications Process Log via the web interface. | Read
 | Statistics | Controls access to the Communications Process Statistics view via the web interface. | Read
Parent topic: Resource Classes used by Enterprise Server
Parent topic: Security Reference Information


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
Controls use of a dataset; it verifies that a user has access to a dataset. | Files | None, Read, Update, Alter
Access to the list of datasets in ESMAC

See the DATASET usage notes section below.

nodename.userid
NONE
Allows no access.
READ
Allows user to view the datasets list.
UPDATE|CONTROL|ALTER
Allows user to view and delete and create datasets.
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
localnodeid.userid.jobname (for job cancellation authority)
SUBMIT
localnodeid.jobname.userid (for job submissions)
Where localnodeid 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 datasets 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, for exmple, 001
name
The dd name.

These rules are not typically used, but they do provide granularity of control for those environments with special requirements.

Note: In a PAC environment, the enterprise server name must be in parenthesis and prefixed by the PAC name. For example, the following rule trace below specifies EXACLUS as the PAC name and EXACLUS1 is the enterprise server name:
EXACLUS1 ESFEM1030I ESM1: MLDAP ESM:
SYSAD AUTH request for "EXACLUS(EXACLUS1).SYSAD" in
JESSPOOL denied by rule "EXACLUS(EXACLUS1).**"
NONE
Allows no access.
READ
Allows user to view the spool dataset, 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 dataset.
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 creation of a physical file.

See PHYSFILE usage notes section for more information.

Physical files None, Alter
PROGRAM
JES relation Entities ACCESS LEVEL
Controls access to JCL programs.

See PROGRAM usage notes section for more information.

Programs Execute, None
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.

When security is enabled, and a JCL job is submitted that uses a PROC or INCLUDE file that is part of a cataloged Partitioned Dataset (PO), READ access for the dataset is checked. If the user does not have permission to read the dataset, an error is reported.

When security is enabled, and a JCL job is submitted that includes either JOBLIB or STEPLIB entries, the system checks that the user has EXECUTE access to each of the Partition Datasets (PO). If the user does not have the required access, the job abends with a COND CODE of S913.

A user that submits jobs must have permission to READ the JCL job file that is being submitted. This is an important security check as it prevents a user from submitting files as JCL jobs when they do not have permission to read those files.

The rule that covers this will also need to cover the reading of a dataset created for the INTRDR submission. It may be that different rules are required as there is a difference between use of the cassub -j command, which will produce a temporary file, and cassub -x, which will pass the whole path and name of the file. The INTRDR cassub command uses the -x option and passes the whole path and name of the dataset.

If the rule that allows the user submitting the job to read the JCL file is based on group membership, the default group of the user submitting the JCL must be one of the groups that allows read access. A user who is a member of one of the groups but does not have a default group set in their security profile must specify the group they are using when they submit the JCL file. That group information cannot be passed through as a property of an INTRDR job generated from the submitted JCL. So the user must specify a default group in their profile which will be used when the check for read permission is made.

To view the catalog, it is necessary for the logged-on user to have access to the DATASET resource. You can achieve this with a nodename.userid resource format entry, for example, MSSDEMO.MyJESusr.

An example LDIF definition for DATASET can be found in the es_default_ldap.ldf file, which is available from the bin directory of your product installation directory.

PHYSFILE usage notes

The PHYSFILE security class controls creation of physical files, including spool files. It is checked when a file is created or renamed. It is not required that the PHYSFILE class is implemented, and if the PHYSFILE class does not exist, access is permitted. Note that in this case, an access check is still 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.

Micro Focus strongly recommends implementing PHYSFILE rules to restrict where datasets may be created, so that datasets are only created in locations that are within the system working set. This will prevent users from specifying an inappropriate location.

Relationship with DATASET

The DATASET class is used to verify that a user can access a dataset in a given way - read, write, create, or delete a dataset - and is checked each time the dataset is accessed. The PHYSFILE class is only checked at dataset creation, and is used to verify that the user can create a dataset in that location.

Relationship with JESSPOOL

Spool files are also datasets, and the PHYSFILE check will be made when these are created to verify that the user who is running the JCL job can create the spool files in the given location. The JESSPOOL security class is used to verify that a user can access the spool files that have been created by a job.

The user id used to submit and run the job must have authority to create the job log files. These are spool files that will be created in the spool files location, and so a PHYSFILE rule to allow access to this location would be required.

Below is an example LDIF definition for PHYSFILE.

Micro Focus suggests allowing all users access to defined areas, and restrict certain areas to certain users. Allocation override rules can be used in combination with PHYSFILE settings to mandate where datasets are created, based on catalog properties, and who has permission to create them.

Note: The PHYSFILE class is also used by the Remote File Access (RFA) feature. Under RFA, PHYSFILE rules are interpreted differently. Specifically, the default if the class does not exist is to deny access, the "*" and "**" wildcards operate differently, and there are more permission levels available. If you use Remote File Access, see RFA security for more information.

Example

In the following examples it is assumed that all datasets are to be created in an area on disk called C:\WORKAREA. The definition of rules that allows access to specific areas implicitly denies access to areas not covered by the rules:

#########################
# RACF Class = PHYSFILE #
#########################
dn:CN=PHYSFILE, CN=PHYSFILE,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: top
objectClass: container
description: JES Class for controlling access to physical files

###################################
# ALLOW ALL USERS PERMISSION TO   #
# CREATE FILES IN THE DATA AREA   #
###################################

dn:CN=C\3A\\WORKAREA\\DATA\\**,CN=PHYSFILE,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PHYSFILE
microfocus-MFDS-Resource-ACE: allow:*:alter
microfocus-MFDS-UID: no
description: Allow everyone permission to create a physical file in the DATA area

###################################
# IF SPOOL FILES ARE HELD IN A    #
# DIFFERENT LOCATION ALLOW ALL    #
# USERS PERMISSION TO CREATE      #
# FILES IN THE SPOOL AREA         #
###################################
dn:CN=C\3A\\WORKAREA\\SPOOL\\**,CN=PHYSFILE,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PHYSFILE
microfocus-MFDS-Resource-ACE: allow:*:alter
microfocus-MFDS-UID: no
description: Allow everyone permission to create job logs and spool fiels in the SPOOL area

####################################
# LIMIT ACCESS TO THE MFI01 FOLDER #
# TO AUTOUSER                         #
####################################
dn:CN=C\3A\\WORKAREA\\MFI01\\**,CN=PHYSFILE,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PHYSFILE
microfocus-MFDS-Resource-ACE: allow:AUTOUSER:alter
microfocus-MFDS-UID: no
description: Allow AUTOUSER permission to create datasets in the MFI01 folder

#####################################
# PHYSICAL FILES IN XYZ FOLDER      #
# THIS SHOWS RESTRICTING USE OF A   #
# FOLDER AND SUB-FOLDERS TO A GROUP #
#####################################
dn:CN=D\3A\\WORKAREA\\XYZ\\**,CN=PHYSFILE,CN=Enterprise Server Resources,CN=Micro Focus,CN=Program Data,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class:PHYSFILE
microfocus-MFDS-Resource-ACE: allow:ALLUSER group:alter
microfocus-MFDS-UID: mfuid

PROGRAM usage notes

The PROGRAM security class can be used to limit which user has permissions to run a particular program in a library. The entry takes the format of:

<PROGRAM NAME>.<LIBRARY NAME>

This enables you to grant a user execute access to a program in a particular library but not to a program of the same name in another library.

Program Security Class Example

The symbolic name SYS1.LOADLIB stands for all the utility programs shipped with the product. As such, it is likely that all users should be granted execute permission for programs in that library. In the example below, the PROGRAM class is defined and entries are made to give access to everyone to programs in SYS1.LOADLIB. This entry shows the use of a wildcard to indicate that any program in SYS1.LOADLIB can be used by any user.

The second entry shows a program called CBLMAIN in the library SYS2.LNKLIB. This program can be used by anyone except a user called SAFDSA. If you use the PROGRAM security class, it is more secure to specify each system user and the programs they can access rather than use wildcards to allow all users access to a program or programs in a library.

#########################
# RACF Class = PROGRAM  #
#########################
dn:CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=mftesting,DC=com
changetype: add
objectClass: top
objectClass: container
description: JES Class for controlling access to programs

###########################################
# PROGRAM SYS1.LOADLIB                                            #
# ALLOW ALL USERS ACCESS TO MAIN PROGRAMS  #
###########################################
dn:CN=*.SYS1.LOADLIB,CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=Program Data,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PROGRAM
microfocus-MFDS-Resource-ACE: allow:*:execute
microfocus-MFDS-UID: no
description: Allow everyone access to product programs

#########################################
# PROGRAM CBLMAIN.MFI01.MFITEST.LIB2          #
# ALLOW ALL USERS ACCESS TO CBLMAIN             #
#########################################
dn:CN=CBLMAIN.MFI01.MFITEST.LIB2,CN=PROGRAM,CN=Enterprise Server Resources,CN=Micro Focus,DC=Program Data,DC=local
changetype: add
objectClass: microfocus-MFDS-Resource
microfocus-MFDS-Resource-Class: PROGRAM
microfocus-MFDS-Resource-ACE: allow:*:execute
microfocus-MFDS-Resource-ACE: deny:SAFDSA:execute
microfocus-MFDS-UID: no
description: Prevent SAFDSA access to CBLMAIN.MFI01.MFITEST.LIB2 KLIB
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
Related information
ES_IMS_RCLASS


Resource Classes for ESMAC and Operator Command Security

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.
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.
DCBINFO
A class that controls who can access to the DCB information for cataloged datasets in ESMAC for a LDAP secured region.
Entity
dataset name
Access levels
If a user has an 'update' or 'alter' access to this resource, they can modify the dataset characteristics from the catalog page in ESMAC from the DCB link.

If a user has 'Read' access to this resource, they can view the DCB info page from ESMAC, but cannot make any changes to the file properties.

If a user has 'None' permission access to this resource, they cannot view the DCB info page from ESMAC.

OPERCMDS
Relation
Class for operator commands used by the casstart, casstop, casfile, cassub, cassub.content, casout, and the following ESMAC pages:
  • JES Control (casrdo44) which disables job submission and initiator/printer starts; requires any access.
  • JES Alias (casrdo49) which disables update and delete of alias'; requires update access.
Note: The cassub.content resource class controls authorization for remote JCL submission by content.

Job submission through the IDE follows the same security rules as ESCWA and ESMAC. Therefore the user submitting a job through the IDE must have update access specified in the cassub entry.

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

Enables you to control who can access the console, the traces, and any dumps in ESMAC for a LDAP-secured region.

If the user has 'read' or 'update' or 'alter' access to this resource, they are able to view the diagnostics, such as console.log, aux traces and dumps from ESMAC.

If the user has 'None' access to this resource, they cannot view the diagnostics from ESMAC.

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 list when the By Group selection is used. If the user has "Update" access to this resource, they will be able to access all the buttons that appear under the Resources list when the By Group selection is made.

The user also needs "Update" access, as well as the corresponding permission for a particular resource, in order to modify resources, including delete.

GRP controls just the Groups button in ESMAC under By Group. It also acts as a upper level control for the resources which are added into groups.

GRP also controls the By Type dropdown in ESMAC. If the user has no access to GRP resource, the user is not able to view any of the resources and the By Type does not display the list of resource types in the sidebar.

Note: To be able to modify any resource that is associated with a group, the user needs to have alter access to the corresponding resource class in addition to alter access to the GRP resource.
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.
BAT, DCT, DOC, FCT, ICE, JCT, MPR, PCT, PLT, PPT, RNL, SIT, SNT, SUP, SYS6, SYSC, TCP, TCT, TERM, TST, TTYPE, URI, XAT, XLT This controls the access a user has to the various resources (for example, DCT, PCT, FCT) when selected via the By Type or Active menus under the Resources list. "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*, they 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. For example, a page is primarily the DCT details for a DCT entry then attempting to access this page with no authority will result in you being directed to a "Sign-on" screen.

ENV

This controls whether a user has 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).

TCLS

This controls whether a user has access to view the transaction class settings of an enterprise server by enabling or disabling the TranClass button or using a direct URL.

To use this entity, create a new element (TCLS*) 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 TranClass button in ESMAC) or ACE=allow:SYSADM group:read (enables TranClass in ESMAC).

MQL

This controls whether a user has access to view MQ listener and writer settings of an enterprise server in ESMAC.

To use this entity, create a new element (MQL*) in the LDAP schema in the CN=MFESMAC group below CN=Enterprise Server Resources.

Use the microfocus-MFDS-Resource-ACE attribute to configure the group or the user access rights. For example:

  • ACE=deny:SYSADM group:read - denies access to any MQ listeners and writers in ESMAC
  • ACE=allow:SYSADM group:read - enables users to view the MQ listeners and writers in ESMAC
  • ACE=allow:SYSADM group:alter - enables users to alter MQ listeners and writers in ESMAC
BDL | This controls access to the ESMAC bundle button under the Resources drop down in ESMAC. Bundle is part of CICS WebServices. In order for Bundle to appear in ESMAC the correct CCSID tables need to be installed. See CCSID Conversion Tables for more information.
PIP | This enables full access to any ESMAC PIPELINE Screen.
WEB | This controls access to any ESMAC WEBSERVICE Screen.
THH | This controls access to any ESMAC THRESHOLD Screen.
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 Micro Focus 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
Accessing Directory Server information from an ESCWA instance, when the Directory Server enables authentication. | Read
Options | Changing of Directory Server options. | Update
Object Permissions Allocation of permissions on individual enterprise servers.

Controls the following options on a region's security tab:

  • Use default ES Security Manager configuration
  • Security Facility Configuration
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.

Controls the following options on a region's security tab:

  • Automated Execution Control Enterprise Server Credentials
  • Enable Security Manager Administration GUI
  • Security Manager List
Update, Add, Delete
Scripts | Controls the execution, and update permissions for an enterprise server region's start, stop, and not responding scripts. | Execute, Update
Note: To restrict read access to Enterprise Server security configuration, such as which Security Managers are defined for enterprise server region or the MF Directory Server and what their properties are, a new "Security Configuration" resource can be specified under the "Enterprise Server Administration" resource class. Only users and user groups that have read access for the resource will be able to query such a security configuration. This means that any user or user group with permission to start a secured region must also have "Security Configuration" read access, otherwise the region start will fail because its security configuration cannot be accessed by the region processes.
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
  • Enhanced security for HTTP and MFBINP
Parent topic: Security Reference Information


Service Deployment and Security

Enterprise Server provides a deployment feature to allow developers to 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 Enterprise Server, 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 Enterprise Server 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 allows mfdepinst to 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, allows MFDS to 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 Enterprise Server 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.

Additional considerations and advanced security for deployment

As organizations have become more conscious of potential security issues within corporate networks, additional considerations for Enterprise Server service deployment have been identified.

Newer releases of Enterprise Server have additional security features for deployment, as described in Deployment Listeners.

Parent topic: Solutions, Restrictions, and Changes in Behavior


Restrictions on usernames and passwords

MSS is limited by IBM mainframe compatibility to 8-character usernames. However, it is now possible to use usernames and passwords of up to 100 characters in Enterprise Server, with some restrictions and additional considerations. See Long Usernames and Passwords for more information.

Restrictions still apply to JES and JCL support. Any name referenced in JCL must be uppercase (for example, USER=XXX), as you cannot use a lower-case or mixed-case username in JCL. You can have a user with a lower- or mixed-case name, including names longer than eight characters, to submit jobs. The USER parameter of JCL job cards are still restricted to eight characters.

Parent topic: Solutions, Restrictions, and Changes in Behavior
Related information
Long Usernames and Passwords


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


Enhanced security for HTTP and MFBINP

Beginning with release 9.0, Enterprise Server offers options for enhanced security for HTTP and MFBINP conversations. These options are supported by the Web Services and J2EE conversation type, and some of the HTTP-related options apply to the Remote File Access (RFA) and Web conversation types.

Note: RFA has a number of security options specific to it.

Enhanced security works in conjunction with other Enterprise Server features, such as external security and conversation filtering (firewall), to improve the overall security posture of the enterprise server instance and provide defense in depth.

Enhanced security is configured in the listener Custom Configuration filed.

Enhanced security includes the following features, most of which can be used independently.

Authentication

Authentication verifies the identity of the client connecting to the enterprise server listener. Typically, it is the end user who is authenticated, but in some cases an organization might authenticate the client system using SSL/TLS and a client certificate.

With enhanced security, if authentication is enabled, it can be required — all clients must authenticate successfully or the conversation is terminated — or it can be optional. Optional authentication lets a client authenticate, in which case it may be granted additional access that is not available to an unauthenticated client.

Authentication requires that Enterprise Server External Security is configured for the enterprise server region.

Authentication options apply to RFA as well as Web Services and J2EE.

Authorization

Authorization restricts what requests a client is allowed to make. If authorization is enabled, then a security access check is performed using either the authenticated user, or a default user account if authentication is optional and the client is not authenticated.

The parameters of the access check depend on the protocol (HTTP or MFBINP), the type of request, and the resource, such as the HTTP URL, named in the request.

By default, access requests are made against the resource class "Communications Server Service Control". The name of the class can be changed in the listener configuration.

Authorization requirements for HTTP requests

For HTTP, the path portion of the URL in the request is the resource name used for the access request.

The HTTP method determines the required permission level:

  • HTTP GET, HEAD, and OPTIONS require read permission.
  • POST requires update permission.
  • PUT requires add permission.
  • DELETE requires delete permission.
  • Any other request method requires control permission.

For example, a web service client making a POST request to a Web service with the following URL:

https://eshost:9000/tempuri/account_update/credit?account=12345&amount=500.00
This would require update permission for the resource /tempurl/account_update/credit in the resource class "Communications Server Service Control".

Authorization requirements for MFBINP requests

MFBINP requests always ask for execution permission. The resource name for MFBINP access requests is the service name for normal service requests, and BINP control message for other types of MFBINP messages such as transaction control.

COBOL programs deployed to Enterprise Server as EJBs have their service names specified as part of interface mapping, and the service names will also be visible in the service objects configured in ESCWA for an enterprise server region. Built-in services used by functions such as casfile and casout include the following:

CASA_Sub_JCL
Submit JCL
CASA_File_Set
casfile operations (set CICS files)
CASA_Out_JCL
casout JCL spool / catalog functions
CASA_Out_Set
casout other functions

With COBOL Application Server (CAS) service names, you might need to experiment and consult the logs to see precisely which service is being allowed or denied for a given task.

Constraints

Constraints restrict which features of the Web Services and J2EE conversation type a given listener supports. They are useful to disable features you never use, in order to reduce the attack surface, or to create specific listeners for different purposes, which might be bound to different interfaces, use different firewall rules, or have different authentication and authorization settings.

With constraints you can disable any number of the following features:

HTTP requests
Disabling this will also disable ESMAC
MFBINP requests
Disabling this will also disable CAS services, dynamic debugging, and MFBINP file handler.
ESMAC
Including the ESMAC service used by ESCWA.
All CAS services
Such as, cassub and casfile.
Dynamic debugging
MFBINP file handler
Used for remote access by the Data File Editor.

Configuration

All of these security options are set in the [Security] section of the Custom Configuration filed for the listener.

Note: All setting names and values are case-insensitive.

Syntax

[Security]
authenticate=required|enabled|optional|ignore failure|disabled
default user=username
authorize=required|disabled
restricted=yes|http|mfbinp|no
authentication=types
realm=string
keep authentication when passive=yes|no
allow HTTP=yes|no
allow MFBINP=yes|no
allow ESMAC=yes|no
allow CAS services=yes|no
allow MFBINP FH=yes|no
allow dynamic debugging=yes|no
authenticate
The possible settings are:
required
All clients must authenticate.
enabled
Authentication is permitted; clients which do not authenticate will use the default user account.
optional
Synonym for enabled.
ignore failure
Like enabled, but if authentication is supplied by the client but fails, treat the request as if authentication was not attempted (use the default user).
disabled
Do not perform authentication.

The default value is disabled unless restricted (see below) is enabled for the protocol, in which case the default is enabled.

This setting applies to RFA and Web listeners as well.

Note: Do not confuse this setting with authentication, described below.
default user=string
Set string to the name of the default user account, used if authentication is optional and the client does not authenticate. The default value is MFCSUSER.
authorize
Controls whether authorization is performed for the request. Possible values are required and disabled.

The default is disabled.

restricted
For Web Services and J2EE listeners, this setting can be used to restrict authentication to only one of the two protocols (HTTP and MFBINP). For historical reasons, it can also be used with listeners using the Web conversation type, with some differences. Possible values are:
yes

The authenticate setting applies to all requests (HTTP and J2EE). This is the default if authenticate is set to anything other than disabled.

HTTP
The authenticate setting applies only to HTTP requests. (For RFA and Web, this means all requests, as they do not use MFBINP.)
MFBINP
The authenticate setting applies only to MFBINP requests.
no
This setting is only useful for the Web conversation type, where it means authentication is allowed but not required.
While this setting can be used with RFA, it does nothing useful for that conversation type, since if authentication is enabled the only useful value for restricted is yes (or HTTP, which has the same effect).
authentication=types
Set the types of authentication that are supported by this listener. This setting applies to RFA and Web listeners (HTTP authentication mechanisms only) as well.

The value of this setting is one or more of the following tokens, separated by spaces and/or commas:

HTTP
Allow HTTP Basic Authentication. This passes credentials in Base64 encoding, so if you are concerned about sensitive data on the network, you should enable SSL/TLS.
MFBINP
Allow authenticating using the MFBINP Security header. This passes credentials in the clear on the network (unless SSL/TLS is used).
MF
Support an older proprietary HTTP authentication mechanism, which was used by older product releases for COBOL service deployment. This passes credentials in the clear on the network (unless SSL/TLS is used).
certificate or cert
Allow clients to authenticate using client certificates. This requires an SSL/TLS listener and certificate registration. This uses the same certificate registry as the CICS Web Interface and DCAS features. See User Certificate Registration for CICS Web Interface Servers and DCAS for more information.
Note: The Web Services and J2EE conversation type supports this authentication mechanism for both HTTP and MFBINP.
register

Like certificate, but if the client sends an unrecognized certificate, try the other enabled authentication mechanisms (for example HTTP). If the client is authenticated using one of them, register the client's certificate under that identity for future use.

The default value is HTTP, MFBINP, MF.
Note: Do not confuse this setting with authenticate, discussed above.
realm=string
For HTTP Basic Authentication, this sets the realm string. Browsers display the realm when prompting for credentials for Basic Authentication, and use the realm to determine whether they can send cached credentials. This setting is also supported by RFA and Web.

The default value is "MF Communications Server for region region-name".

keep authentication when passive
Set this to yes to have MFBINP sessions retain their authentication status if they are passivated. Passivation allows an MFBINP session to be preserved across conversations, in the same MFCS instance. This feature is rarely used by MFBINP clients.

If this is not enabled, clients trying to reactivate an MFBINP session will have to re-authenticate. This is more secure if an attacker attempts to get the session ID of a passivated session. For example, because the client stored it in a file.

The default value is no.

allow feature
These constraint settings can be used to disable various features in a Web Services and J2EE listener. Set the value to yes to enable the feature or no to disable it.

The default value is yes for all features.

Parent topic: Solutions, Restrictions, and Changes in Behavior
Related reference
Web Services and J2EE conversation type
Remote File Access conversation type


Using External Security Facility (ESF) Features

ESF features that might be useful in your organization include:

  • 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
  • Long Usernames and Passwords
  • Verify Request Throttling
  • Using Non-Micro Focus Group Objects with LDAP-based Security
    Using Active Directory user groups, or other LDAP objects, to specify user groups for Enterprise Server security.
  • Selective Auditing
  • Renaming ACEEs
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 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).

[Trace] section

verify=yes
Enables trace messages for the osesm Verify operation. Trace messages are written to the same location as error messages, for example the console log. Tracing is useful in diagnosing issues, but might reveal sensitive data to an attacker who can obtain copies of log files. Disable tracing when it is not needed.
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. From Enterprise Developer 7.0, the MLDAP ESM Module can use this to cache the results of LDAP searches. See MLDAP ESM Module for more information.

  • What is Cached?
  • Enabling and Configuring ESF Caching
Parent topic: Using External Security Facility (ESF) Features
Related concepts
Security Configuration Custom Configuration Information


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 ESF 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
Security Configuration Custom Configuration Information
Flush on Change


Enabling and Configuring ESF 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
  • Ignore
  • 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 ESF 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 ESF Caching
Related concepts
Security Configuration Custom Configuration Information


Ignore

The ignore setting specifies what fields in ESF requests can be ignored when comparing them with cached ones. Ignoring fields makes cached results more widely applicable and improves the cache hit rate.

The ignore setting is set to a list of tokens, separated by commas or spaces. The possible tokens are:

facility
Ignore the facility field. This identifies the terminal for requests associated with a TN3270 connection, the conversation for a request associated with CICS Transaction Gateway processing, and so on.
subsystem
Ignore the subsystem field. This identifies which type of environment (such as CICS, JES, or COBOL web services) the request originated from.
subsys
A synonym for subsystem.
transaction
For CICS, this is usually the name of the transaction which triggered the request. Can be set by other callers to some arbitrary string.
trans
A synonym for transaction.

The default is ignore=facility subsystem.

To make all fields significant (no fields are ignored when comparing a request with those in the cache), set this configuration item with an empty value.

Parent topic: Enabling and Configuring ESF 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 ESF 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 ESF 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 ESF 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) signon 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 can be used for the following 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 sends 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 is 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.
  • Passtokens may be used for TN3270 automated sign-on using ELF or DCAS.

Not all ESM Modules support passtokens. If you are using a module that does not support passtokens to verify users, user identities are not automatically transferred across security domains, and users have to explicitly signon with their normal credentials in each domain.

Note: To use ESF passtokens between components with separate security configurations, such as the Enterprise Server Administration user interface hosted by Micro Focus Directory Server (MFDS) and the ES Monitor & Control interface hosted in the region, the security configurations for both components must be identical. Passtokens between components with differing configurations might work but are not supported.
  • Access to Passtokens
  • Using Passtokens
  • Passtoken API
Parent topic: Using External Security Facility (ESF) Features
Related concepts
Configuring a region for Express Logon Feature
Configuring a region for Express Logon Feature
Related reference
Multi-Factor Authentication


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
Related concepts
Security Configuration Custom Configuration Information


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, you can set values in the optional [Passtoken] section of the Configuration Information field to set some options for passtoken processing. See MLDAP ESM Module Configuration Fields for more information.

Parent topic: Passtoken Options for the MLDAP ESM Module
Related concepts
Module Configuration
MLDAP ESM Module Custom Configuration Information
Related reference
MLDAP ESM Module Configuration Fields


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 always have to sign on explicitly when entering security domains. Administrators have to log on to MFDS and ESMAC separately, and user identity is not automatically transferred over Inter-System Communication (ISC) links between enterprise server regions, for purposes such as CICS Transaction Routing.

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 Web interface. See Passtoken Options for ESF Manager for more information.

Passtokens for MFDS and ESMAC

Administrators might find it convenient to enable passtokens for the MFDS and ESMAC administrative interfaces, especially since these 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. See Access to Passtokens for more information.
Note: Micro Focus recommends that you do not use surrogate passtokens. Surrogate passtokens represent a possible security risk, any user who has permissions to create surrogate passtokens can impersonate any other user who is allowed to sign on using a surrogate passtoken.
To enable passtokens for MFDS and ESMAC, do not disable passtoken support in your ESF Manager configuration for the enterprise server region where you want passtoken support. The configuration is located in the Configuration Information field of the region's security tab.
Note: By default, passtoken support is enabled in the ESF Manager.

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, a passtoken is not 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 region 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 for MFDS or enterprise server region where you want ISC passtoken support. The configuration is located in the Configuration Information field of the region's security tab.
Note: By default, passtoken support is enabled in the ESF Manager.

Also, you may have to perform ESM-specific actions to enable:

  • Surrogate passtoken generation by any user account used to start a region that makes ISC requests to another enterprise server region.
  • Surrogate passtoken signon for any user account that run a transaction that 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 run CICS transactions that might 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.

Passtokens for multi-factor authentication

Customers who want to make use of the multi-factor authentication for logging on to the mainframe without providing a username and password need to enable passtokens.

Multi-factor authentication makes use of RACF-style passtokens for logins, also referred to here as short passtokens. These short passtokens are generated by the Digital Certificate Access Server (DCAS). They enable the user log on to CICS in the enterprise server region where the passtoken was generated.

To enable passtokens, do not disable passtoken support in your ESF Manager configuration for the enterprise server region where you want passtoken support.. This configuration is located in the Configuration Information field of the region's security tab.
Note: By default, passtoken support is enabled in the ESF Manager.

You might have to perform ESM-specific configuration to enable passtoken generation and sign-on for your users. With the MLDAP ESM Module, For each user who wants to use multi-factor Authentication, set the following attributes in the LDAP repository to:

  • microfocus-MFDS-User-CreateToken to "self"
  • microfocus-MFDS-User-UseToken to "self"
Parent topic: Access to Passtokens
Related concepts
Passtoken Options for ESF Manager


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
Configuring LDAP User Group Mode


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, instructs 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.

If federation is not configured, and two or more security managers which use the MLDAP ESM Module are used, the system will operate in "compatibility mode" for federation. This implements the historical behavior of old product versions prior to the introduction of full federation support. In this mode, ESM Modules do not fully federate but have some interaction, which can lead to unexpected results in some cases. Compatibility mode is currently deprecated. Micro Focus strongly recommends that you explicitly configure federation as either enabled or disabled, depending on your requirements.

If you are not sure what setting to use, try the following guidelines:

  • If your configuration only has one ESM, you do not need to configure federation.
  • If your configuration has multiple ESMs, but you are not using the MLDAP ESM Module, or you only have one instance of the MLDAP ESM Module, you do not need to configure federation. You might want to configure federation 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

The following messages in this class have been defined:

400I Initializing caching: cache size "size" KB ("entries" entries)
The ESF cache has been initialized for the given size, which can hold the given number of entries.
401I Cache "state": "queries" cache queries, "hits" hits (~"percentage"%), "entries" entries
This message is emitted periodically to note the state of the ESF cache. Valid states are:
  • initialization
  • termination
  • status
The information displayed includes the number of cache queries, the number of hits (successful queries), approximate hit percentage, and the number of entries currently in the cache.
402E Unable to create cache ("bytes" bytes)
ESF was unable to allocate the given number of bytes for the cache. Caching is disabled.
403I Caching disabled (cache size set to zero)
The ESF cache is disabled in the security configuration.
404W Unrecognized token in [cache] "type" configuration: "value"
An unrecognized token was encountered in processing some portion of the cache configuration information, which appears in the optional [cache] section of the configuration text area of the security configuration. The type may be "requests" or "ignore", and the given value is the unrecognized token.
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 OpenText Support for Micro Focus Products 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
Related concepts
Security Configuration Custom Configuration Information


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 OpenText Support for Micro Focus Products 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


Long Usernames and Passwords

Enterprise Server now supports long passwords and usernames. This chapter provides information on restrictions and considerations for their use.

  • Long Passwords
  • Long Usernames
  • Permitted Characters for Short Names
  • Name Mapping
Parent topic: Using External Security Facility (ESF) Features
Related concepts
Setting User Passwords with esfadmin
esfadmin Command Syntax
Verify MFDS Restricted Access
Using a Fileshare Password File
Setting Up an MSS-enabled Enterprise Server as a Fileshare Client
Related information
Restrictions on usernames and passwords


Long Passwords

Most user interfaces and public APIs in Enterprise Server that accept passwords have been extended to enable long passwords (sometimes referred to as passphrases) of up to 100 characters.

They include:

  • Administration Web interfaces in MFDS and ESMAC.
  • Command-line utilities that accept passwords with command-line options, such as casstart.
  • For CICS, the IBM-standard sign-on transaction CESL is now supplied. It accepts a long password or passphrase.
    Note: The CESN transaction is still limited to 8-character passwords. This is to preserve compatibility with applications that expect the CESN screen layout.
  • APIs such as EXEC CICS SIGNON, which now supports the IBM-standard PHRASE optional parameter.

Only single-byte characters are supported. There may be issues with EBCDIC translation of some characters. See Permitted Characters for Short Names for more information.

Parent topic: Long Usernames and Passwords


Long Usernames

Enterprise Server has provisions for supporting usernames that do not meet the mainframe convention of 1-8 characters from a restricted character set. These mainframe-style usernames are conventionally referred to as "short names". Usernames that are not mainframe-compatible are called "long names", even though they are not necessarily longer than eight characters. For example, since spaces are not allowed in short usernames, a six-character username containing a space would be considered a "long" name.

Since Enterprise Server's Mainframe Subsystem Support (MSS) features must remain mainframe-compatible when dealing with usernames, MSS and other Enterprise Server components use short names internally.

In effect, "long name" means "the username outside Enterprise Server", while "short name" means "the alias used in Enterprise Server". If you are not using the long-name feature, those two are the same.

If you make use of the long-name feature:

  • In most cases, when users enter their username, they use the long name. This includes user interfaces such as the MFDS Enterprise Server Administration tool and command-line utilities such as casstart. The main exceptions are the CICS signon transactions CESN and CESL; the underlying CICS APIs such as EXEC CICS SIGNON; and the USER parameter of JCL job cards. For mainframe compatibility those are still restricted to eight characters and so must use the short name.
  • If an application running in MSS queries the user's name, the short name is returned.
  • Under the External Security Facility (ESF):
    • External Security Manager (ESM) Modules verify the user by long name. For the MLDAP ESM Module, user-group membership is specified using the long name.
    • ESF resource access checks use the short name.

    That is, when establishing a user's identity, the long name is used. That includes discovering all the attributes of a user, such as group membership. When operating on a user's identity, the short name is used.

Parent topic: Long Usernames and Passwords


Permitted Characters for Short Names

Short names must conform to mainframe requirements and are further restricted to permit reliable translation between ASCII and EBCDIC. The following characters are allowed for short names:

  • ASCII alphanumerics.
  • The following 17 ASCII symbols: #$@<+|&!*-%_>?:=.
    Note: Including the period.

For security reasons, the Enterprise Server Administration user interface (MFDS) does not permit adding or editing usernames that include any of these characters: <+&%=>? This is because of their special meanings in HTML and HTTP. You can add and edit usernames with these characters using the esfadmin utility or by working directly with the ESM, for example, with an LDIF file for LDAP.

Long names and passwords can include spaces and most single-byte characters. The low-values or NUL character is not permitted, and some others may not be accepted by some user interfaces.

Parent topic: Long Usernames and Passwords


Name Mapping

If you use long names, ESF has to provide a mapping between long and short names. This is done by a "name mapper", or possibly by multiple name mappers. For simplicity, Micro Focus recommends using only one. A name mapper is a Security Manager that performs the name-mapping function. It can also provide other Security Manager functions such as Verify and Auth.

The MLDAP ESM Module now supports name-mapping, using a configurable LDAP attribute:

[LDAP]
map attribute=<LDAP attribute name>

The LDAP attribute name can be, for example, "name" or "displayName" or a custom attribute, depending on the user's objectClass definition in the LDAP schema.

Upon request, Micro Focus can provide a sample name-mapping ESM that uses a COBOL indexed file to store the mapping, and the SDK components needed to create custom name mappers.

There is a default name mapper built into ESF which is used if no other name mapper is configured. The default mapper truncates long names to eight characters, converts spaces to underscores, and converts other disallowed characters to periods.

As part of Verify processing, the long name is mapped to a short name. The long name and short name can be identical, if the long name meets the criteria for a short name.

The mapping can map any name to something else, which might be useful in some cases. For example, you might want to sign into CICS with the username you use in Windows or Linux which is different from your user ID in CICS. The name mapper enables you to do this.

  • Short-to-long Mapping
  • Short-to-long Mapping for Verify
Parent topic: Long Usernames and Passwords


Short-to-long Mapping

In some circumstances, the name mapper is asked to map a short name to the corresponding long name. The MLDAP ESM Module and the sample file-based mapping module can both do this, as long as the names they are configured to map are unique.

For short-to-long mapping, the default mapper simply returns the short name as the "long" name. This means that the default mapper does not reliably (one-to-one or isomorphically) map long names to short names and back again. For some system configurations this is not an issue; see Short-to-long Mapping for Verify for more information. If you wish to use long names for ordinary MSS users, as opposed to purely administrative use, you might want to use a name mapper other than the default one.

Parent topic: Name Mapping


Short-to-long Mapping for Verify

The ESF Verify operation, used to verify a user's credentials and sign the user into an Enterprise Server subsystem, operates on the long name.
Note: Some interfaces only accept short names. This includes the CICS sign-on transactions and APIs such as EXEC CICS SIGNON.

If you use long names and use CICS you may need to use another related feature, known as short-to-long mapping for the Verify operation. When this is enabled, the Verify operation does the following:

  1. If the name is longer than eight characters it proceeds normally, otherwise:
  2. It checks that the Enterprise Server MSS system already recognizes the short name is associated with a long name. This is the case if the user has already signed onto this region using their long name, which has been mapped to their short name. If this is the case it continues the Verify operation using the associated long name.
  3. It attempt to map the short name to a long name. If this succeeds, it continues the Verify process using the mapped long name.
  4. If none of the previous steps succeed it attempts the Verify operation using the short name as supplied by the caller.

There are some additional requirements for short-to-long mapping for Verify:

  • The security configuration must enable the "Use all groups" option, sometimes referred to as "all-groups mode". This is necessary for the ACEE search in step 2 to succeed. This is because at this point in the Verify operation the user's default group is not known.
  • The security configuration must use a name mapper that provides a one-to-one mapping between short and long names. This can be configured in the MLDAP ESM, the File Mapping ESM, or a custom ESM.
    Note: The built-in default name mapper cannot be used with short-to-long mapping for Verify operations because this can lead to one-to-many mappings.

You can enable short name mapping on a region's Security tab, or on the Default ES Security tab. In the Configuration Information field, type:

[Verify]
map short names=yes
Note: It cannot be enabled from a Security Manager definition.
Parent topic: Name Mapping


Verify Request Throttling

The External Security Facility (ESF) can be configured to throttle the handling of large volumes of incoming Verify (user authentication/signon) requests. This is intended to reduce the effectiveness of Denial-of-Service (DoS) type attacks, and of brute force attempts to login. By default, throttling starts when there are more than 100 requests received per second. The severity of the throttling (how long Verify requests are delayed) is based on the number of requests made per second.

You can configure the number of requests at which the throttling occurs in the Security Facility Configuration for the region. In the Configuration Information field, type:

[Operation]
verify throttle threshold=number

Where number is the number of requests above which requests are throttled. To disable throttling, set the number to 0.

When throttling occurs and auditing is configured, a message is logged with an event category of 2 and a type 6 (code 2 6).

Parent topic: Using External Security Facility (ESF) Features


Using Non-Micro Focus Group Objects with LDAP-based Security

LDAP-based security for Enterprise Server through the MLDAP ESM Module now supports additional options for configuring user groups. User groups are typically used to assign access permissions for resources controlled by Enterprise Server.

In earlier releases of Enterprise Server, user groups used the microfocus-MFDS-Group LDAP object class. Group members were specified using microfocus-MFDS-Group-Member, a multi-valued attribute, where each value is an enterprise server user ID.
Note: A user ID is typically the LDAP Common Name, or CN, of a user object, though a different attribute can be configured for the user ID.
Members could also be group names, specified as X group or group X, to indicate nested groups.

In Enterprise Server 3.0 Patch Update 9, Enterprise Server 4.0 Patch Update 1, and later, administrators can configure the MLDAP ESM Module to obtain group information from the LDAP server in one of four ways:

Micro Focus groups
This is the original mechanism described above, with microfocus-MFDS-Group objects specifying members as user IDs in the microfocus-MFDS-Group-Member attribute.
Active Directory groups
When this option is selected, group membership is determined by using objects of the LDAP group class and its member attribute. Members are specified as LDAP Distinguished Names (DNs) of user objects. This is how Microsoft represents Windows user groups in Active Directory, so this mode enables the use of Windows domain groups for enterprise server security.
Custom groups
In this mode, an arbitrary LDAP class name and membership attribute name can be configured. Group members can be any combination of user ID, group name with the "group" prefix or suffix, and user or group Distinguished Name (DN). This is similar to the Micro Focus groups mode, except the class and attribute name can be configured and members can be identified by its DN.
Note: Since DNs are unambiguous, DN group members (for nested groups) do not use the "group" prefix or suffix.
Combined mode
This tells the MLDAP ESM Module to look for both AD groups and custom groups. This enables you to use existing AD groups in conjunction with Windows users, while also adding some groups solely for Enterprise Server.
  • Configuring LDAP User Group Mode
    The configuration of your Security Manager determines how user groups for Enterprise Server security are configured in LDAP.
Parent topic: Using External Security Facility (ESF) Features


Configuring LDAP User Group Mode

The group mode and related settings are specified in the Configuration Information field of the Security Manager definition in the Enterprise Server Administration web interface:

[LDAP]
group type=MF|custom|AD|both
group class=group-class-name
group member attribute=member-attribute-name

group type

The group type configuration setting has four possible values:

MF
Is the default and enables Micro Focus group mode.
custom
Enables custom group mode.
AD
Enables Active Directory group mode.
both
Enables combined group mode.

The default group mode is MF. See Using Non-Micro Focus Group Objects with LDAP-based Security for more information on the group modes.

Note: For AD and combined modes it might be necessary to specify the base and container settings as well. See Other configuration settings section below.

group class and group member attribute

In custom mode, use these to set the name of the LDAP object class containing group information, and the name of the LDAP attribute listing group members.

In combined mode, these attributes apply only to non-AD groups.

The default for group class is microfocus-MFDS-Group and for group member attribute is microfocus-MFDS-Group-Member.

Other configuration settings

When using a group type other than MF, the group container is often in a different part of the LDAP repository hierarchy than the other Enterprise Server LDAP data. This might require the base, user container, group container, and resource container to be configured appropriately.

In some cases, it might be necessary (or simplest) to set base to an empty value, and then send each of the container settings to the full Distinguished Name (DN) of the associated container object.

With the combined groups mode (group type=both), Active Directory groups and custom groups can be in different container objects. To enable the MLDAP ESM Module to find groups in both containers, set group container to the common ancestor of the two group containers, and enable subtree searching with search scope=tree.

Note: If the base is specified, do not including this component when setting the group container.

If you are using more than one Security Manager, you might need to enable federation in the region's security configuration. See Security Federation for more information.

Parent topic: Using Non-Micro Focus Group Objects with LDAP-based Security
Related reference
MLDAP ESM Module Custom Configuration Information
Security Federation


Selective Auditing

Selective auditing is a mechanism to configure emitting audit events for only specific users, groups, resources, or transactions. This is currently only supported for the MLDAP ESM module.

When enabled, most audit events will cease to be emitted. Only if the affected entity/entities have the auditing attribute value set to TRUE will an event be emitted.

Note: Some system audit events, for example, startup and termination and some other miscellaneous events will always be emitted.

A new attribute is required to make use of the new selective auditing feature: - "microfocus-MFDS-Audit". This is an optional attribute for user, user group, and resource object classes. If there is already an existing LDAP repository with Micro Focus extensions installed. See Adding the auditing attribute to the LDAP schema for more information.

The following describes which entities are examined for requests. At this time, only Verify and Auth/XAuth requests are audited:

Affected entities - Verify

In Verify requests, the affected entities are the user and the signon group. The user is checked first, which means that the group might not need to be examined for the audit attribute value. This results in fewer MLDAP searches being required.

If All Groups mode is enabled, all groups that the user is a member of are checked for the auditing attribute value. This may result in performance degradation during user signon. If any group has the auditing property set, the Verify request will be audited.

Affected entities - Auth/XAuth

In Auth/XAuth requests, the affected entries are the user, the signon group or the user's group set (if All Groups mode is enabled), the resource being accessed, and the transaction. The users and groups auditing attribute value are not checked at this time; they are remembered from the Verify request in the ACEE. The resource is then checked, and if it does not have the auditing property set, the transaction is then checked.

Note: The transaction is only checked if the region uses the default transaction class TCICSTRN, and the calling subsystem has set the transaction name in the request.

Enabling/Disabling auditing in a running region

The esfupdate command line utility can be used to refresh ACEEs present in the system. Updating either users or groups will result in all related ACEEs updating their auditing status.

Note: esfupdate group updates cannot turn off auditing for a user, only turn it on. If a user no longer needs to be audited, ensure its auditing property is disabled, along with its signon group, and do a user update. This procedure only works for the user and signon group; the auditing flag cannot be reset for a given user while a region is running if All Groups mode is enabled and the user's auditing flag has been set by membership in an audited group.
  • Adding the auditing attribute to the LDAP schema
Parent topic: Using External Security Facility (ESF) Features


Adding the auditing attribute to the LDAP schema

The new auditing attribute required for ESFs selective auditing feature is an optional attribute for user, user group, and resource object classes. If the LDAP schema of your Directory Server has already been extended with Micro Focus attributes and object classes, but without the microfocus-MFDS-Audit attribute, the new attribute can be added in one of the following ways, depending on the type of LDAP server:

Microsoft Active Directory:

Save the following file as mf-selective-audit-attr.ldf:

dn: CN=microfocus-MFDS-Audit,DC=X
changetype: add
cn: microfocus-MFDS-Audit
lDAPDisplayName: microfocus-MFDS-Audit
adminDisplayName: microfocus-MFDS-Audit
oMSyntax: 1
attributeSyntax: 2.5.5.8
objectClass: attributeSchema
schemaIDGUID:: xmDwqgutS4ycMWycKH9dmc==
attributeID: 1.3.6.1.4.1.5043.1.1.0.400.10
isSingleValued: TRUE
adminDescription: MFDS SAF selective auditing attribute
description: MFDS SAF selective auditing attribute

Then run the command:

ldifde -i -f mf-selective-audit-attr.ldf -k -v -j . -c "DC=X" #schemaNamingContext

Additional command-line options, such as login credentials or port numbers may be required, depending on where the Active Directory instance is running and whether the current user has administration access.

To extend the required objectClasses to use the new attribute:

  • If you are using "microfocus-MFDS-User" objectClass to define Enterprise Server users:
    1. Save the following file as mf-selective-auditing-classes.ldf:
      dn: CN=microfocus-MFDS-User,DC=X
changetype: modify
add: mayContain
mayContain: microfocus-MFDS-Audit
-
dn: CN=microfocus-MFDS-Group,DC=X
changetype: modify
add: mayContain
mayContain: microfocus-MFDS-Audit
-
DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-
dn: CN=microfocus-MFDS-Resource,DC=X
changetype: modify
add: mayContain
mayContain: microfocus-MFDS-Audit
-
DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
    2. Then run the command:
      ldifde -i -f mf-selective-audit-classes.ldf -k -v -j . -c "DC=X" #schemaNamingContext
  • If you are using existing MS "user" objectClass to define Enterprise Server users:
    1. Save the following file as mf-selective-auditing-classes.ldf:
      dn: CN=user,DC=X
changetype: modify
add: mayContain
mayContain: microfocus-MFDS-Audit
-
DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-
dn: CN=microfocus-MFDS-Group,DC=X
changetype: modify
add: mayContain
mayContain: microfocus-MFDS-Audit
-
DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
-
dn: CN=microfocus-MFDS-Resource,DC=X
changetype: modify
add: mayContain
mayContain: microfocus-MFDS-Audit
-
DN:
changetype: modify
add: schemaUpdateNow
schemaUpdateNow: 1
    2. Then run the command:
      ldifde -i -f mf-selective-audit-classes.ldf -k -v -j . -c "DC=X" #schemaNamingContext

OpenLDAP

If you are using OpenLDAP, add the following text into the existing Micro Focus schema extensions file:

attributeType ( 1.3.6.1.4.1.5043.1.1.0.400.10 NAME 'microfocus-MFDS-Audit'
    DESC 'MFDS SAF selective auditing attribute'
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
    SINGLE-VALUE  )

To add the auditing attribute to existing user, user group, and resource objectClasses add the new attribute to the MAY sections of the 'microfocus-MFDS-User', 'microfocus-MFDS-Group' and 'microfocus-MFDS-Resource' objectclass definitions, for example:

objectclass ( 1.3.6.1.4.1.5043.1.2.1.1000 NAME 'microfocus-MFDS-User'
    DESC 'The user object class used to define entries representing Micro Focus user profiles'
    MUST ( 	cn $
                  microfocus-MFDS-UID $
                  microfocus-MFDS-User-MTO-Priority $
                  microfocus-MFDS-User-MTO-Timeout $
                  microfocus-MFDS-User-MTO-OperatorClass $
                  microfocus-MFDS-User-AllowLogon )
    MAY ( 	 microfocus-MFDS-CustomText $
                  microfocus-MFDS-User-MTO-OperatorID $
                  microfocus-MFDS-User-MTO-GroupPrefix $
                  microfocus-MFDS-User-Pwd $
                  microfocus-MFDS-User-ExpirationDate $
                  microfocus-MFDS-User-DefaultGroup $
                  microfocus-MFDS-User-Pwd-MustChange $
                  microfocus-MFDS-User-Pwd-ExpirationDate $
                  microfocus-MFDS-User-CreateToken $
                  microfocus-MFDS-User-UseToken $
                  microfocus-MFDS-User-LastLoginTime $
                  microfocus-MFDS-User-Pwd-History $
                  microfocus-MFDS-User-LoginAttempts $
                  microfocus-MFDS-Audit $
                  displayName $
                  description )
Parent topic: Selective Auditing


Renaming ACEEs

The External Security Facility (ESF) can be configured to permit changing userids of users who are already signed on to an Enterprise Server component (for example, enterprise server, MFDS, ESCWA, and so forth). When enabled, the userid or "short name" of one or more ACEE objects, which identify signed-on users, can be updated as part of processing an ESF Update request. The effect of the ESF Update is that the Enterprise Server identity of a user might be altered within a running enterprise server region, without having to restart it.

This feature, known as ACEE rename, requires the following ESF features:
Name Mapping
ACEE rename changes the "short name" (ES userid) associated with a "long name" (external username). If name mapping is not being used, this is not meaningful.
LDAP-based security
ACEE rename is implemented as part of the ESF Update processing performed by the MLDAP ESM Module. At least one Security Manager using the MLDAP ESM Module must be configured and enabled for the enterprise server region or other component to process ACEE renames.
Note: The name mapping does not need to be implemented using LDAP - it can be provided by any Security Manager.

ACEE rename is a change in behavior and is potentially expensive, since it must scan and modify the ACEEs in the system, which requires locking and will potentially block other processes. Consequently it is not enabled by default. Enable it using the rename active users setting in the [Update] section of the Configuration Information field for an LDAP-based Security Manager. See The MLDAP ESM Module for more information.

ACEE rename workflow

  1. An enterprise server region with suitable security configuration is running. Various users have signed on to the region, creating ACEEs.
  2. An administrator changes the security data in the External Security Manager (ESM) used for name mapping, so that one or more users now have "short names" that are different from the ones they had when they signed on to the enterprise server region. You want the enterprise server region to recognize these changes.
  3. You must submit an ESF Update request with the appropriate parameters, as specified below.
  4. The enterprise server instance identifies the affected ACEEs and changes the short names in them to reflect their new values.

ESF update and ACEE renaming

There are different types of ESF Update requests. See Implementing Security Manager Changes for more information.

When ACEE renaming is enabled, you can use the following types of ESF Update requests to process ACEE renames:

  • An Update User request will check for and process an ACEE rename for the specified user. For example, esfupdate ... user USERA will check for an ACEE rename for ACEEs that currently use the short name "USERA".
    Note: The old short name should be specified with such a request. See the note regarding user updates, short names, and long names below.
  • An Update Users or Update All request will check all ACEEs for renames, and process any that it finds.
    CAUTION:
    As with any Update Users or Update All operation, this is significantly more expensive than a single-user Update request, and might pause processes in the Enterprise Server for a significant span of time, depending on how many ACEEs exist in the system.

Effects of ACEE renaming

Renaming an ACEE changes the ES userid of the ACEE. This is how the user is known to Enterprise Server.

Changing the userid will affect any security or permission settings which depend on the userid. It will not normally affect group-based permissions assigned using the MLDAP ESM Module, as those are based on the user's "long name" (when using Micro Focus user groups) or Windows groups (when using Active Directory groups). Group-based permissions might be altered by other changes to the security data and incorporated by Update processing.

Old short name, new short name, and long name in update requests

Prior to the introduction of this feature, an ESF Update User request needed to be made using the user's short name (ES userid) to be effective.

With this feature, when a user's short name has been changed in the ESM which is performing name mapping, the old userid should be used in an ESF Update User request to process the rename. If an Update Users or Update All request is used instead, no user name is specified, so this issue does not arise.
Remember: That Users and All updates can significantly impact performance.

In addition, with this feature, if the MLDAP ESM Module does not find any ACEEs for the user named in an Update User request, it will search the ACEEs again looking for ones with a long name that matches the supplied name. That means it is now possible to do an Update User request using a user's long name.

Restrictions on ACEE renaming

ACEEs must be unique by primary key, which is formed from the short name and sign-on group. When all-groups mode is enabled, the sign-on group is always "*ALL", so in this case ACEEs must be unique by short name.

That means an ACEE cannot be renamed if the new name would cause it to match an existing ACEE. In this case, an error message is logged to the enterprise server region console and the rename operation fails.

Renaming an ACEE, and ESF Update in general, does not change the ACEE's sign-on group. If all-groups mode is not enabled, removing a user from a group they have used as a sign-on group will not alter any existing ACEEs for that user. That means a user can retain the permissions of that group until the enterprise server region has been restarted.

Parent topic: Using External Security Facility (ESF) Features


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


PAM ESM Module

The PAM ESM Module lets you use the Pluggable Authentication Modules (PAM) mechanism as an External Security Manager (ESM) for Enterprise Server.

The PAM ESM Module only supports user authentication (the SAFROUTE Verify operation), so it can only be used to control user signon to Enterprise Server, and not to provide resource access control.

PAM is a feature of Linux and some UNIX operating systems that provides a framework for authenticating users. PAM providers may authenticate users with the traditional Linux/UNIX passwd and shadow files, with NIS, or with another mechanism such as LDAP.

Note: PAM providers are included with the operating system or supplied by third parties. Micro Focus does not supply PAM provider modules.

The PAM ESM Module supports userid/password validation, and in some configurations user password changes. It supports retrieving user group information from the operating system as Enterprise Server user groups, so operating-system group names can be used in conjunction with the MLDAP ESM Module to assign resource access permissions. Retrieving group names is not a PAM function; this is done using standard OS APIs. The PAM ESM Module also supports External Security Facility (ESF) functions such as group federation, passtokens, and system user ACEE creation.

The PAM ESM Module is currently only shipped for Enterprise Server on Linux, but can be provided for UNIX on request. Contact your OpenText Support for Micro Focus Products representative regarding PAM ESM Module for UNIX.

  • Using the PAM ESM Module and MLDAP ESM Module together
  • PAM ESM Module Configuration
  • PAM ESM Module Configuration Fields
  • PAM ESM Module Custom Configuration Information
Parent topic: Securing an Enterprise Server Installation


Using the PAM ESM Module and MLDAP ESM Module together

You can secure an enterprise server with a single Security Manager using the PAM ESM Module. In this configuration there is no resource access control, only user access (signon).

To get user access control using PAM and resource access control, you will need two security mangers, one with the PAM ESM Module and one with the MLDAP ESM Module. Resource access rules will need to be configured in an LDAP repository.

In this configuration, the PAM security manager would typically appear first in the security configuration's manager list, so that PAM gets the first opportunity to verify the user. The MLDAP security manager would appear second.

If you wish to use the operating system's user-group information, you must configure group federation for the External Security Facility (ESF). See Security Federation for more information. This lets the PAM and MLDAP modules share group information. For example, if a user belongs to the operating system's group "dev", you can create access control entries for resources that refer to "dev group" in your resource control rules.

The Use all groups option on the enterprise server's Security tab, or on the Default ES Security tab, behaves typically in this configuration. If it is enabled, users will have all the permissions associated with any of their groups. If it is not enabled, users will only have the permissions associated with their signon group.

Parent topic: PAM ESM Module
Related reference
Security Federation


PAM ESM Module Configuration

The PAM ESM Module has a number of configurable parameters. Its configuration is administered with the Micro Focus Directory Server (MFDS). To add an ESM Module configuration:

  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. Click Add.
  4. To select the PAM ESM Module for a Security Manager, in the Module field, type pam_esm. See PAM ESM Module Configuration Fields for more information on settings.

You can create multiple Security Manager objects in MFDS using the PAM ESM Module, in order to use the module with different configurations for different enterprise servers or for MFDS itself.

Parent topic: PAM ESM Module
Related reference
PAM ESM Module Configuration Fields


PAM ESM Module Configuration Fields

The fields of the Security Manager tab are used by the PAM ESM Module as follows:

Name
The name of your PAM ESM security manager.
Module
This must be set to pam_esm to use the PAM ESM Module.
Connection Path
This is not used with this module.
Authorized ID
Specifies the PAM "service name". This is used to select the PAM configuration to use. The default value is microfocus-es. This name must be in lowercase, which is a requirement of PAM, and should correspond to a PAM configuration. You can use the name of an existing configuration such as sudo.
Note: PAM configurations are typically stored as stanzas in the /etc/pam.cfg file, or individual files in /etc/pam.d. This will vary by installation.
Password
This is not used with this module.
Enabled
If unchecked, the Security Manager will not be invoked.
Cache limit
This is not used with this module.
Cache TTL
This is not used with this module.
Description
Provided for your use. This information is not processed by ESF.
Configuration Information
Additional configuration settings. See PAM ESM Module Custom Configuration Information for more information.
Parent topic: PAM ESM Module
Related reference
PAM ESM Module Custom Configuration Information


PAM ESM Module Custom Configuration Information

The PAM ESM Module supports some additional configuration that can be set by editing the text in the Configuration Information field. Text in this area is organized into sections which begin with a tag in square brackets, followed by lines in the form name=value.

The following lists the various configuration sections, and the options that can be set in each section:

[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 value is 64 and the maximum value is 9999. Increasing this value consumes more shared memory and increases processing time for authorization requests. Micro Focus recommends keeping this value close to the actual number of user groups you have specified. It has no effect when the Use all groups option is not checked.

Note: If you have multiple PAM and/or MLDAP ESMs stacked in a security configuration, then you must have the same setting for maxgroups, unless Federation is explicitly disabled.
process groups=yes|no
This can be set to no to disable all processing of groups. When it is enabled, the PAM ESM Module attempts to determine the set of operating-system user groups that the user belongs to, using standard Linux/UNIX APIs. Group membership is not a PAM feature. If the Use all groups option is checked, the groups will be added to the user's group list. If Use all groups is unchecked, then if the user specified a signon group, the module confirms that the user belongs to that group and sets the ACEE group accordingly. Otherwise, the ACEE group is set to the user's default group.

The default value is yes or enabled.

group filter=string
If configured with a wildcard containing string, the PAM ESM module will only select groups whose names match the pattern given by the group filter configuration option. The default value is *.

For example:

  • group filter = mf* will only select groups beginning with mf.
  • group filter = *es* will only select groups starting with or containing es as a substring.
Note: This does not apply to the user's default group.

[Passtoken] section

enable=yes|no|self

This controls whether passtokens are supported by this security manager. If this is set to yes, self and surrogate passtokens are enabled. Setting it to no disables all passtokens. Setting it to self enables self-passtokens only. The default value is no.

Note: Even if passtokens are disabled in one security manager, another manager might provide them.
secret=string

Set the secret data which 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: Any setting here is not secret to 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 exchange passtokens.

secretfile=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, this is less secure.
duration=seconds
Set the duration for passtokens in seconds. A token is valid for this length of time after it is generated; after that it is rejected. The default value is 60 seconds.
table size=size

Sets the size of the table used to store passtokens. If passtokens are being used for multi-factor authentication, then this table must be larger than the peak number of users concurrently logging on. The default size is 64.

Note: Increasing the size degrades performance by increasing memory requirements.
short passtoken reuse=yes|no
Sets whether or not short passtokens, which are used for multi-factor authentication, can be used once or multiple times and until they expire based on the duration option. The default value is no.

[Trace] section

Config=yes|no
Setting this to yes triggures the module to emit a message for each valid configuration setting specified in the Configuration Information field of your Security Manager. This can be used for auditing and debug purposes. By defaut, this option is set to no.
Conversation=setting
Log various messages regarding the processing of PAM conversations, which are interactions between the PAM ESM Module and PAM providers. If this is set to a string beginning with "y" or to "1", the ESM Module makes a log message each time its conversation callback is invoked.
Conversation errors=setting
Log error messages and codes received during the processing of PAM conversations. If this is set to a string beginning with "y" or to "1", the ESM Module makes a log message with additional information regarding PAM errors. PAM errors cause the Verify operation to fail or be denied with the appropriate ESF return codes, but by default the exact details are not logged.
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 makes a log entry when it determines that a user belongs to a group during Verify. This is useful when debugging problems when Use all groups is checked.
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 through 8, the maximum number of filtered-tracing rules. For example, Trace1, Trace2, and so on. You can specify rules out of order and skip numbers - they only need to be unique and between 1 through 8.)

A tracing rule has the format:

function:actor:result

where:

function
The only function provided by the PAM ESM Modeule is verify.
actor
This is a username. You can use wildcards.
result
This can be one of the following values:
  • allow
  • deny
  • unknown
  • fail
  • any
  • debug

The request is traced if all of the conditions of the rule are met. Tracing means one or more informational messages about the request is written to the log. A result setting of debug is logged based on any result (like any), but may log additional information during processing a request that matches the function and actor.

For example:

verify:SYSAD:deny

This traces Verify (signon) requests where the SYSAD user is denied.

Filtered tracing can be used to isolate issues on busy systems, where normal tracing would produce excessive output. It does affect performance, since each request must be examined to see if it matches a trace rule.

Verify=setting
Log various messages regarding the processing of Verify requests. If this is set to a string beginning with "y" or "1", then the ESM Module makes one or more informational log entries with additional information about each Verify request.
Parent topic: PAM ESM Module


Enterprise Server Auditing

You can configure Enterprise Server to log auditable events that occur during operation, such as authentication attempts, and resource access requests.

Enterprise Server supports auditing using syslog events, which can be consumed by a wide range of Security Information and Event Management (SIEM) products. Syslog events can use either unencrypted TCP or encrypted SSL/TLS connections.
Note: In previous versions of Enterprise Developer similar functionality was provided by the Micro Focus Audit Manager. However, Micro Focus Audit Manager is now deprecated.
  • To Enable Auditing on Windows
  • Configuring Enterprise Server Auditing
  • Audit Event Codes
  • Understanding Audit Events
  • Creating Custom Audit Events
  • Syslog Auditing Performance
Parent topic: Enterprise Server Security


To Enable Auditing on Windows

To enable auditing on Windows, a third-party Syslog application should be installed and configured to listen for audit events on a specific port.

Note: It might be necessary to "allow" this port through any firewalls.
Parent topic: Enterprise Server Auditing


Configuring Enterprise Server Auditing

You can configure the audit facility to use syslog to create audit events and then specify where the events are sent. To enable auditing, you need to do the following:

  1. A syslog facility is required to listen on a specific port.
  2. The security configuration for the service you want to audit (for example, MFDS or a region) must be configured to generate audit events.
  3. The audit.cfg file must be configured to send audit events to the syslog port.

Configuring the External Security Manager

To generate audit events from MFDS or from a region, click Create audit events for the relevant External Security Manager (ESM). This is in the SAF Security Facility Configuration group for the relevant ESM as follows:

  • To enable auditing for MFDS, this option is in the MF Directory Server tab in the security options.
  • To enable auditing for a region, this option is available in the SAF configuration for the security manager that is in use for the region.
Note: If the region is configured to use the Default External Security manager (ESM) then this option located in the SAF configuration in the Default ES Security tab.

If the region is configured to use a specific ESM the SAF configuration can be found in the Security tab for the particular region.

In the relevant Security Facility, click Create audit events, and then click Apply.

Note: You must first create and configure the audit.cfg file. Without this file, auditing fails and the security manager is not initialized.

Creating and Configuring audit.cfg

Configuration is specified in the audit.cfg file, which you must create in the bin directory of your Enterprise Test Server installation, which by default is %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server.

The configuration file follows the standard INI file format containing sections, properties and values.

The audit.cfg file must be configured to point to the machine and port that is running the syslog facility.

The configuration file is read when the audit process is initialized. Changes made to the configuration file are not picked up by the audit process that is running. You must restart the audit process to reload a modified configuration file.

The following is an example of the audit.cfg configuration file:

[audit]
; The type of emitter used to output audit events, valid values [syslog]|[oldaudit].
emitter=syslog

; This section is for configuring the syslog emitter
[syslog]
; The hostname and port of the syslog collector, where the syslog packets are sent.
; The hostname may be a host name string, dotted IPv4 or hex IPv6 notation.
; If you are using TLS, the hostname value may be used for hostname verification. See serverCertHostname for more information.
hostname=
port=

; protocol: Specifies the protocol syslog should use, valid values [TCP]|[TLS].
protocol=TLS

; All configuration  values for syslog below this point are optional:
; tzKnown: If the timezone of this machine is known, this value should be 1.
; If not known, it should be 0.
tzKnown=1
; isSynced: If this machine's clock is synced to a known external source, this must be set to 1.
; Otherwise, it must be 0.
isSynced=0
; syncAccuracy: The accuracy to which the machine's clock is synced. This is an integer, in
; microseconds, that the machine's clock may be off.
syncAccuracy=
; ip: The IP address of this machine. This may be a comma-delimited list, in the case of
; multi-homed devices.
ip=192.168.0.1

; maxRetryTime: Configure how long (in seconds) the audit process should spend attempting to re-send data if a failure occurs.
; The application will continue retrying until a time greater than this value has elapsed.
; Negative values mean an infinite timeout. Defaults to 1.
maxRetryTime=1

; This section is for TLS configuration, which may be used by syslog.
[TLS]
; CARootFile: This is the certificate authority root file the client uses when connecting to verify
; the server's certificate.
CARootFile=C:\Program Files (x86)\Micro Focus\DemoCA\private\CARootcert.pem

; All configuration values for TLS below this point are optional
; verifyServer: Specifies whether the client should verify the server's certificate or not.
; Valid values: [true]|[false]. Default value is true.
verifyServer=true
; clientCertificate: The full file path to the client's certificate:
clientCertificate=C:\Program Files (x86)\Micro Focus\DemoCA\clicert.pem
; keyfile: The full file path to the client's key file:
keyfile=C:\Program Files (x86)\Micro Focus\DemoCA\clikey.pem
; keyfilePassphrase: If the keyfile has a passphrase, it is specified here:
keyfilePassphrase=srvrootpwd
; serverCertHostname: The value that is used to compare against the Hostname on the server's certificate.
; If this is not specified (not present/commented out), by default the hostname specified in the syslog section is used.
; If a value is not specified, for example 'serverCertHostname=', then the hostname verification is disabled.
serverCertHostname=
Parent topic: Enterprise Server Auditing


Audit Event Codes

These are the audit events emitted by the External Security Facility (ESF), Micro Focus Directory Server (MFDS), JCL, and Data File Tools. Events from ESF use the "mf.safmgr" component ID; those from MFDS use "mf.mfds", JCL uses "mf.jcl", and Data File Tools use "mf.cas".

ESF Events: Category and Type Codes, and Parameters

In the following list, the first number is the event category and the second number is the event type. Events are grouped by category, so "1:x" or "1 x" is the collection of events in category 1, the category for events generated by the audit facility itself.
Note: Different auditing emitters may separate the two numbers using a space or a colon character.

The following is a list of event categories and types with their parameters for either a 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.

Category 2: System

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 0
Component Initializing
  • No parameters
2 1
Component Started.
  • No parameters
2 2
Component Terminating.
  • No parameters
2 3
User exit called.
2 4
User exit halted processing of the request.
2 5
User exit returned an error.
2 6
Request Throttle
  • Request Type
  • Number of events per second
  • Time the process sleeps for (seconds)
The following are MFDS only:

Unless otherwise indicated, their parameters are:

  • Receive count
  • Object class
  • Object name
2 10
String parameter "MFDS process starting..."
2 11
String parameter "MFDS Request processor started."
2 12
String parameter "MFDS Request processor terminating."
2 13
Auditing turned on
  • Receive count
  • Account ID
  • String "MFDS auditing starting..."
2 14
Auditing turned off
  • Receive count
  • Account ID
  • String "MFDS auditing stopped..."
The following are ESCWA only:
2 15
ESCWA Starting
  • No Parameters
2 16
ESCWA Terminating
  • User - (Optional) The name of the user that actioned the shutdown, if any.
2 17
ESCWA Auditing Starting
  • User - (Optional) The name of the user that started auditing, if any.
2 18
ESCWA Auditing Stopping
  • User - (Optional) The name of the user that stopped auditing, if any.
2 19
ESCWA ESF Auditing Starting
  • OriginalUser - (Optional) The name of the supplied user which has permissions for the current ESF configuration. This ESF configuration does not have auditing enabled because there are no Security Managers in the stack or Create audit events is disabled.
  • NewUser - (Optional) The name of the supplied user which has permissions for the new ESF configuration. This ESF configuration has auditing enabled.
2 20
ESCWA ESF Auditing Stopping
  • OriginalUser - (Optional) The name of the supplied user which has permissions for the current ESF configuration. This ESF configuration has auditing enabled.
  • NewUser - (Optional) The name of the supplied user which has permissions for the new ESF configuration. This ESF configuration does not have auditing enabled because there are no Security Managers in the stack or Create audit events is disabled.
2 21
A user logs off or a session is first checked after having expired:
  • Session Removed - set to the session token string.
The following are MFDS only:
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
2 200
Page request
  • Receive count
  • User ID
  • Request description (format varies)
2 201
Logon request
  • Receive count
  • User ID
  • Return code (prefixed with "Logon attempt, rc=")
2 300
  • Receive count (Optional)
  • Account ID
  • String parameter "Auditing set to ON for default ES security..."

This event is emitted when the default ES security auditing option configuration is selected to be on. This event is only emitted if MFDS process audit is enabled.

Note: The "Account ID" value can only be known if Restrict administration access has been checked.
2 301
  • Receive count (Optional)
  • Account ID
  • String parameter "Auditing set to OFF for default ES security..."

This event is emitted when the default ES security auditing option configuration is selected to be off. This event is only emitted if MFDS process audit is enabled.

Note: The "Account ID" value can only be known if Restrict administration access has been checked.
2 302
  • Receive count (Optional)
  • Account ID
  • String parameter "Auditing set to ON for region [name] ES security....", where [name] is the name of the enterprise server region.

This event is emitted when the region-specific auditing option configuration is selected to be on, either explicitly (non-default ES security is selected and the Create audit events option is enabled) or when changing to use default ES security which has the audit option on and previously the region-specific audit option was off. This event is only emitted if MFDS process audit is enabled.

Note: The "Account ID" value can only be known if Restrict administration access has been checked.
2 303
  • Receive count (Optional)
  • Account ID
  • String parameter "Auditing set to OFF for region [name] ES security....", where [name] is the name of the enterprise server region.

This event is emitted when the region-specific auditing option configuration is selected to be off, either explicitly (non-default ES security is selected and the Create audit events option is disabled) or when changing to use default ES security which has the audit option off and previously the region-specific audit option was on. This event is only emitted if MFDS process audit is enabled.

Note: The "Account ID" value can only be known if Restrict administration access has been checked.

Category 3: Security API request

Only emitted by ESF. These are not emitted by default. See Security Configuration Custom Configuration Information for more information on the "category 3 audit" configuration option.

3 0
VERIFY
  • Username
  • Subsystem
  • Signon group
3 1
AUTH
  • User
  • Subsystem
  • Resource class
  • Resource entity
  • Requested access
3 2
XAUTH
  • User
  • Subsystem
  • 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

The following are ESF only:
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
5 6
Verifying with long mapped name
  • Short name
  • Long name
The following are Data File Tools only:

Unless otherwise indicated, its parameters are:

  • Username
  • Group
  • Call
  • DS Name
  • Operation
5 4
Data File Editor audit event
The following are JCL only:
5 5
JCL Audit Event

See MF_JCL_AUDIT for more information.

The following are ESCWA only:
5 10
ESCWA API modify request response
  • User - Session username
  • Path - Request URI
  • Method - Request method (for example, POST, PUT, DELETE)
  • Request body - The body of the incoming request
  • Response - HTTP response status code
  • Session Token - Set to session token string for all requests
  • Client Ip - set to a string, for logon requests
  • Stop Script - set to true or false, indicating whether stop script is enabled when stopping an enterprise server region.
  • Start Script - set to true or false, indicating whether start script is enabled when starting an enterprise server region.
Note: The request body is optional and is only received if the Audit Request Bodies option is checked in the ESCWA Tracing and Logging Settings.

Category 6: Allow

Only emitted by ESF.
Note: Specifying the category 3 audit=yes configuration option disables audit events 2 and 3. If you specify the password change success=yes configuration option, then audit event 2 will be generated. See Security Configuration Custom Configuration Information for more information.
6 0
Verify success
  • Username
  • Subsystem
  • Signon group
  • 1 = resolved using the ESF cache
6 1
Verify allowed for unknown user
  • Username
  • Subsystem
6 2
Verify password change success
  • Username
  • Subsystem
  • Signon group
6 3
Auth success
  • Username
  • Subsystem
  • Resource class
  • Resource entity
  • Request access
6 4
Auth query
  • Username
  • Subsystem
  • Resource class
  • Resource entity
  • Granted access level
6 5
XAuth success
  • Username
  • Subsystem
  • Resource class
  • Resource entity
  • Requested access
6 6
XAuth query
  • Username
  • Subsystem
  • Resource class
  • Resource entity
  • Granted access level

Category 7: Deny

Only emitted by ESF.

Unless otherwise indicated, the Verify deny events use these parameters:

  • User ID
  • Subsystem
  • Signon group

and the Auth/XAuth-deny events use:

  • User ID
  • Subsystem
  • Resource class
  • Resource entity
  • Requested access
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:

  • Username
  • Subsystem
  • ESM number
  • ESM name
  • ESM return code
  • Error description
8 0
Verify error
8 1
Auth error
  • Username
  • Subsystem
  • Resource class
  • Resource entity
  • Requested access
  • ESM number
  • ESM name
  • ESM return code
  • Error description
8 2
XAuth error
  • Username
  • Subsystem
  • Resource class
  • Resource entity
  • Requested access
  • ESM number
  • ESM name
  • ESM return code
  • Error description
8 3
Admin error
  • Admin command name
  • Command code
  • User
8 4
Update error
  • User
  • ESM number
  • Update action code
  • Resource entity
8 5
Map error

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

Category 100: ESM requests

100 1
Effective rule auditing
  • Security manager index
  • Security manager name
  • Username
  • Subsystem
  • Type of request
  • Name of resource
  • Access decision
  • Name of the rule

See MLDAP ESM Module Custom Configuration Information for more information on audit rule.

Category 200: mfsecrets requests

200 1
Open enter
  • Process username
  • Vault handle
  • Description
  • Config section
  • Provider name
200 2
Open provider exit
  • Process username
  • Vault handle
  • Description
  • Config section
  • Provider name
  • Provider return code
200 3
Close enter
  • Process username
  • Vault handle
200 4
Close provider exit
  • Process username
  • Vault handle
  • Provider return code
200 5
Read enter
  • Process username
  • Vault handle
  • Secret path
200 6
Read provider exit
  • Process username
  • Vault handle
  • Secret path
  • Provider return code
200 7
Write enter
  • Process username
  • Vault handle
  • Secret path
200 8
Write provider exit
  • Process username
  • Vault handle
  • Secret path
  • Provider return code
200 9
Delete enter
  • Process username
  • Vault handle
  • Secret path
200 10
Delete provider exit
  • Process username
  • Vault handle
  • Secret path
  • Provider return code
200 11
List enter
  • Process username
  • Vault handle
  • Secret path
200 12
List provider exit
  • Process username
  • Vault handle
  • Secret path
  • Provider return code
Parent topic: Enterprise Server Auditing


Understanding Audit Events

The Subsystem parameter that is present in many of the ESF audit events can be mapped using the following table:

Subsystem number | Description
0 | None (for example, command line program)
1 | CICS
2 | IMS
3 | JCL
4 | ESMAC
5 | Web service
6 | BINP
7 | CGI
8 | MF Directory Server
9 | MF Communications Server
10 | ES Common Web Admin
11 | Data File Tools

When using syslog auditing, the Structured Data section of the emitted syslog message contains a SYSTEM key, which contains the value representing the high-level component that emitted the syslog message. For example, SYSTEM="ESDEMO" indicates that the message originated from the ESDEMO region, or SYSTEM="-MFDS-" which indicates the message originated from MFDS. Every event that originates from a specific region will have the same SYSTEM value, and an appropriate Subsystem number in the events.

Parent topic: Enterprise Server Auditing


Creating Custom Audit Events

You can create your own audit events using the SAFROUTE API. This API handles security-related requests for Enterprise Server applications. Use the AUDIT request type to create your own audit entry point inside COBOL programs hosted by Enterprise Server.

Note: The SAFROUTE API does not work for standalone programs.

The SAFROUTE API is defined in the following copybook located in the cpylib directory of the product installation directory - default is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\SAFAPI.CPY.

An audit event is comprised of the ENTITY and LOGSTR items, which can contain arbitrary strings. You can also use the Username associated with any ACEE, if it is provided. Audit events can be attributed to either a "success" or "failure" which are mapped to the audit event codes 5:1 and 5:2, respectively.

The following program is an example of a "success" audit event:

identification division.
       program-id. testprog.

       environment division.
       configuration section.

       data division.
       working-storage section.

       copy "SAFAPI.cpy" replacing ==()== by ==ws==.

       01 ws-audit-entity    pic x(11) value "AuditEntity".
       01 ws-audit-string    pic x(11) value "AuditString".

       procedure division.
           move low-values to ws-safpb-parameter-block

           set ws-safpb-cur-ver-88 to true
           set ws-safpb-audit-req-88 to true
           set ws-safpb-audit-success-88 to true
           set ws-safpb-codeset-utf8-88 to true
           set ws-safpb-mod-CICS-88 to true

           set ws-safpb-audit-ENTITY-ptr to address of ws-audit-entity
           set ws-safpb-audit-ENTITY-len to length of ws-audit-entity

           set ws-safpb-audit-LOGSTR-ptr to address of ws-audit-string
           set ws-safpb-audit-LOGSTR-len to length of ws-audit-string

           call 'SAFROUTE' using ws-safpb-parameter-block

           if ws-safpb-api-rc > 0
               *> Audit call failed
           end-if

           goback.

       end program testprog.
Parent topic: Enterprise Server Auditing


Syslog Auditing Performance

If the syslog receiver is running on a separate server to the machine emitting the syslog events and there is a connectivity issue, the auditing process will resend the events. This can cause unacceptable performance degradation, for as long as events cannot be delivered.

This issue can be mitigated by running a local syslog daemon on the server doing the auditing. The daemon acts as a primary syslog receiver. It can then be configured to log to a file, log to arbitrary external SIEMs, or both. These daemons are also capable of handling network issues, by queueing messages in memory and sending them when the issues have resolved. This allows the auditing server to continue running with minimal reliance on external network connections for auditing purposes.

Parent topic: Enterprise Server Auditing


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
  • Support for Server Name Indication
  • Configuring Secure Communications for Client Applications
  • Setting Up Secure Communications
  • Troubleshooting a Secure Connection
  • Using the Demonstration Certificate Authority
  • Tutorial: Configuring SSL Security in the Server
  • 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.
  • Specifying a Server Protocol and Cipher Suite Preference
  • HTTP Strict Transport Security
  • 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 certificates from a trusted CA. The online help includes a tutorial that describes the process of using the Demo CA to secure your system.

Note: Demo CA is only to be used for development and testing purposes. It is not supported or secure for use in production environments.
Parent topic: Securing Communications


Support for Server Name Indication

Overview

A growing number of contemporary Web services are hosted on SNI servers. SNI servers are virtual environments where one server hosts many web sites each of which has a different TLS certificate. The server itself presents a single IP address to other systems.

In order to connect to a specific Web service, the client must present the hostname it is attempting to connect to the SNI server. This is done thanks to the SNI extension to TLS and a TLS request (handshake) from the client includes the hostname. The SNI server includes a database with a list of all certificates and selects the respective private key and certificate.

SNI was created as a solution to the IPv4 addresses shortage and mostly affects legacy services. If the host provider moves a service to a SNI-enabled server, and the Web service and the client do not support SNI, clients can lose connectivity.

Support

Micro Focus supports the Server Name Indication (SNI) protocol from version 5.0 Patch Update 1 of the product. You must have this version or later installed in order to avoid issues with clients trying to connect to SNI servers.

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
  • To configure TLS default properties for clients
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 directory if the file does not 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:

    • You must use the full pathnames for the files you specify.
    • If a certificate is not specified, no client-side certificate is used. In this case you can also omit key and passphrase.
Note:
  • If you use a client certificate, you can avoid having the passphrase appear in plain text in the mf-client.dat file by specifying a passphrase stored in the Micro Focus Secrets Facility also known as the Vault. To do this, configure a vault, use the mfsecretsadmin utility to store your key passphrase using the path of your choice, and then set the value of the passphrase setting to mfsecret:config:path, where config is the vault configuration name (blank for the default configuration) and path is the path to your passphrase in the vault. For example, passphrase=mfsecret::mycorp/client/key.
  • 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.

A collection of root certificates from public CAs can be found in the file CARootCerts.pem under your product installation. In earlier versions of the product, this file was part of the optional Demo CA component. You can use these certificates by configuring your client program to use that file for its collection of trusted root certificates also referred to as a "trust store", if it supports the PEM file format. Micro Focus client programs such as COBOL web service clients support this format.

If you have other root certificates you need to use, such as those from a corporate CA or from Demo CA used for development or test purposes only, then you can keep them in separate files and configure your clients to use the appropriate file, or you can add them to CARootCerts.pem.

For Micro Focus client programs which use the Micro Focus Common Client library, you specify the file containing the trusted root certificates in the mf-client.dat configuration 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 in the 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 will be replaced if the product is reinstalled or updated. If you add certificates to this file, you will need to repeat those additions. Micro Focus recommends you back up any modified CARootCerts.pem file. You might also want to copy the CARootCerts.pem to another location and modify it there, then configure your clients to use that copy.
Parent topic: Configuring Secure Communications for Client Applications


Installing a CA Root Certificate in a Client Browser

Web browsers use a collection of CA (Certificate Authority) root and intermediate certificates in the process of validating the certificates sent by web servers. The root certificates are sometimes called "trust anchors" and the collection is sometimes referred to as the "trust store". These certificates are published by trusted commercial and government CAs.

Some browsers, such as Firefox, use their own trust store. Others use a trust store maintained by the operating system.

When the browser is used to connect to a server that has a certificate issued by a well-known public CA, it must already have the necessary trust anchors and no further work by the user should be necessary. This is usually the case for public web servers.

Servers within an organization might use certificates issued by an organization CA, or generated using a test CA such as the optional Demo CA included with Enterprise Server. It might be necessary to install additional root and/or intermediate certificates into the trust store for the browser to let the browser connect to such a server.

The process for importing trusted certificates varies among browsers and browser versions. For browsers which use an OS-managed trust store, such as Microsoft Edge and some versions of Chrome on Windows, the certificates can be imported using OS tools. See your OS documentation for more information. For other browsers, typically there will be a certificate-import function available in the browser settings dialog, often under a Security tab or similar.

You might need to convert a certificate to a different format, since there are numerous certificate file formats and not all tools support all formats. The openssl utility program included with Enterprise Server can be used for this purpose. Other tools for converting certificate formats can be found online or bundled with the operating system.

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.

Note: Demo CA is only for development and testing purposes. It is not supported or secure for use in production systems.

To install a server certificate:

  1. Connect to ES Admin, for example by typing 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 that you want, if you cannot see the one you want, set the Process filter to All, and the click Edit .
  5. If Secure Sockets Layer is not checked, check it and configure this listener as a secure listener.
  6. Enter the full pathnames of your server certificate and private key in the Certificate and Keyfile fields. For example:
    DemoCA-dir/entities/hostname-dir/srvcert_CertChain.pem
    DemoCA-dir/entities/hostname-dir/svrcert_privkey.pem

    where DemoCA-dir is the absolute path of the directory you specified to Demo CA when creating certificates and keys, and hostname-dir is the directory under entities named for your system.

  7. Click OK.
Parent topic: Configuring Secure Communications for Client Applications


To configure TLS default properties for clients

You can configure default values for various TLS properties in the mf-client.dat file. When a TLS-enabled MFCC client is started, the file is checked for default values. If the client does not specify a value for a property, the value from the file is used instead.

Note: Not all properties in the mf-client.dat file overwrite the value set for a client. Some properties can only be set in the mf-client.dat file, and not by the client.

By default, the mf-client.dat file is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory. The MFC_CONFIG environment variable can be used to specify a different configuration file.

See Specifying a Server Protocol and Cipher Suite Preference chapter for more information.

[TLS]

; Set the depth to which the certificate chain of the peer should be verified
; If a connection does not specify a verify depth (or attempts to set a depth of 0)
; this value will overwrite it
;verify depth=5

; Flag for whether the client should verify the server's certificate
; If a connection does not specify this flag/sets it to 0, this value will be used
;verify peer=0

; The TLS protocols field specifies the list of protocols to be used and
; the order of preference in which they are to be used
;protocols=

; The Cipher Suites field specifies the list of ciphers to be used in
; order of preference of use.
;cipher suites=

; The TLS 1.3 specific cipher suites list
;TLS1.3 cipher suites=

; The minimum size in bits of the modulus length of the Diffie-Hellman (DH) group
; that is used to negotiate with connecting peers when using DH cipher suites.
;min dh size=

; The Cipher Groups (previously 'ECC curves') enable you to specify the list of
; ciphers to be used and the order of preference
;cipher groups=

; Set whether the middlebox workaround is disabled. Any setting here overwrites any value
; set on a client.
; Values: "disable" or "enable"
;middlebox workaround=
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.
    Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This takes the following form:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
  • 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 Create a Secure Communications Process
  • To Create a Secure Listener
  • To Start a Secure Listener and Set the Pass Phrase
  • To Configure the Passphrase in a File
  • To configure TLS default properties for listeners
  • Locating Certificate and Key Files
Parent topic: Securing Communications


To enable secure communications with SSL

To enable secure communications withTLS/SSL perform the follow the steps in ESCWA:

  1. In ESCWA, click Native.
  2. In the navigation pane, click Directory Servers and select the enterprise server region you require.
  3. Ensure that the enterprise server region you are going to configure, for example ESDEMO, is stopped.
  4. Click General > Listeners.
  5. Expand Communications Process 1 so you can see all the listeners.
  6. Click * New Listener to create a listener for HTTPS.
  7. Under Listener Properties, in the Name field, type the name of your listener.
  8. Create and configure an HTTPS listener.
  9. Click TLS Settings.
  10. Click Enable TLS.
  11. In the Certificate File and Keyfile fields, type the paths to the files:
    • For more security related options, click Advanced. See Listeners for more information.
  12. Select the Conversation Type for the listener.
  13. In the Custom Configuration field, type any optional textual configuration information that determines the start-up and run-time behavior of the listener.
  14. In the Description field, type a description of your listener.
  15. Click Save.
  16. Click General > Control.
  17. Click Start
  18. Check that all the listeners have started, by looking at the Process Status bars.
  19. Optionally, enable additional logging of listener startup for debugging purposes.
Parent topic: Setting Up Secure Communications


To Create a Secure Communications Process

For an enterprise server region, you can create a secure Communications Process control listener to encrypt the communications it handles:

  1. In ESCWA, click Native.
  2. In the navigation pane, expand Directory Servers, and then select your enterprise server region.
  3. Click General > Listeners
  4. Click Communications Processes that corresponds to the server which you want to secure.
  5. In the Communications Server Properties, click Configure to expand the list of properties.
  6. Click TLS Settings.
  7. Click Enable TLS.
  8. In the Certificate File field, type the absolute path to the certificate file.
  9. In the Keyfile field, type the absolute path to the keyfile.
    Note: The keyfile must reference a file containing the passphrase. See To Configure the Passphrase in a File for more information.
  10. Click Apply.

If the enterprise server is configured to use a security manager, then in addition to enabling TLS (SSL) for the Communications Process control listener, you can set resource access control rules for some Communications Process features. See Resource Classes for Communications Server for more information.

Parent topic: Setting Up Secure Communications
Related reference
To Configure the Passphrase in a File
Edit Communications Process


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

Perform the following steps in ESCWA to set the pass phrases for a secure listeners:

  1. In the menu bar, click Native.
  2. In the navigation tab, click Directory Servers and choose your enterprise server region.
  3. Click General > Listeners. This opens the Communications Processes page.
  4. In the Listeners list, click the Edit icon to modify the secure listener. This displays the listeners Listener Properties page.
  5. Click TLS Settings.
  6. Check Enable TLS.
  7. In the Certificate Passprhase and Keyfile Passphrase fields, type the location on disk, of the files. If multiple files are used then separate the paths with a semicolon ';'.
  8. Click Apply.
Note: If the listener fails to start, it can be useful to look in the console.log. 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 Passphrase in a File

You can configure the passphrases 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.

If you are securing the Communications Process use the name of the enterprise server region as the listener name.

By default, the mf-server.dat file is in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory:

  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.
    Note: If you are configuring the listener to start without a passphrase then use empty double quotes (keyfile="").
  3. Save the file and start the listener. The listener retrieves the passphrases from the file and starts.
Note: The passphrases 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, this is typically LOCAL_SYSTEM and the accounts of any users who run casstart from the command line.
Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This can be specified in the mf-server.dat file and takes the following form:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
Parent topic: Setting Up Secure Communications


To configure TLS default properties for listeners

You can configure default values for various TLS properties in the mf-server.dat file. When a TLS-enabled listener is started, the file is checked for default values. If the listener does not specify a value for a property, the value from the file is used instead.

Note: Not all properties in the mf-server.dat file overwrite the value set for a listener. Some properties can only be set in the mf-server.dat file, and not by the listener.

The mf-server.dat file is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory (Windows), or $COBDIR/bin folder (UNIX).

See Specifying a Server Protocol and Cipher Suite Preference for more information.

[TLS]
; The separator used for passwords if multiple certificates are specified
;password separator=

; The TLS protocols field specifies the list of protocols to be used and
; the order of preference in which they are to be used
;protocols=

; The Cipher Suites field specifies the list of ciphers to be used in
; order of preference of use.
;cipher suites=

; The TLS 1.3 specific cipher suites list
;TLS1.3 cipher suites=

; The minimum size in bits of the modulus length of the Diffie-Hellman (DH) group
; that is used to negotiate with connecting peers when using DH cipher suites.
;min dh size=

; The Cipher Groups (previously 'ECC curves') enable you to specify the list of
; ciphers to be used and the order of preference in which they are to be used.
;cipher groups=

; Set whether the middlebox workaround is disabled. Any setting here overwrites any value
; set in a listener.
; Values: "disable" or "enable"
;middlebox workaround=

; Set whether the server enforces all clients to use its cipher list
; Values: "yes"/"1", "no"/"0"
; Any setting here overwrites any value set in a listener.
;honor server cipher list=
Parent topic: Setting Up Secure Communications


Locating Certificate and Key Files

When enabling TLS you will typically need to configure the names and locations of files containing one or more certificates and sometimes private keys. See Certificate Files, Certificate and Key Formats, and PKCS #12 file for more information on types of certificate and key files.

The names of these files are specified in various places, such as in the configurations of enterprise server listeners in ESCWA and in the mf-client.dat file. Where a filename for a certificate or key file is required, you can use either a full name including the absolute path to the file, or a bare filename.

If a bare filename is specified, MFCC and MFCS use the following steps to try to locate the file:

  1. If the environment variable COBSSL is set, its value is used as the name of the directory to search.
  2. Otherwise, if the environment variable COBDIR is set, /DemoCA is appended to its value and that directory is searched.
  3. On Windows, if neither environment variable is set, the value in the Registry for the key HKLM\SOFTWARE\Micro Focus\DemoCA\1.0\Setup\DemoCAFolder is used, if it exists. This key was used in earlier product versions. The DemoCA provided with Enterprise Developer 9.0 does not use the Registry, but if you are upgrading from earlier releases you might still be using certificates and keys created using the old DemoCA.
  4. If none of those values are set, C:\ (Windows) or / (UNIX) is used.

Earlier product versions would sometimes log a message indicating a failure in GkGetSSLDir. As of Enterprise Developer 9.0 this function does not fail if the certificate and key file directory has not been configured, as it will return the root directory as a last resort, so that message is no longer generated.

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
  • Troubleshooting Certificate Problems
  • CertChecker Utility
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 Enterprise 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 individual 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


Troubleshooting 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 still fails 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


CertChecker Utility

The CertChecker utility provides diagnostic information for TLS certificates. You can use this utility to assist with TLS configuration. It can be found in the product's bin or bin64 directory. To set the environment correctly for certchecker run:

%COBDIR%/createenv.bat

As a minimum, you must specify at least a certificate and can optionally specify a private key and a CA collection.

The verification that CertChecker will perform depends on the input. If just a certificate is specified then CertChecker will check the validity of the certificate to make sure that it is properly formed, and in date, for example. CertChecker will also display warnings for issues such as weak encryption algorithms or extended key usage that is not suitable for TLS. The file specified for the -certfile option can also contain one or more untrusted intermediate certificates that can be used to help form a trust chain if a -cafile is specified. If the certificate file is encrypted, then the password can be specified with the -certpass option.

If a private key -keyfile is also specified then CertChecker will perform certificate checks and also check that the certificate and private key match and that the private key is correctly formed. If the private key is encrypted then the password can be specified with the -keypass option.

If the -cafile is specified then CertChecker will perform a full chain verification to check that it can form a trust chain from the certificates specified and the untrusted certificates in -certfile. It will also check the validity of each of the certificates in the chain.

The -host option can be used to check that the certificate includes the hostname or IP address specified in its Subject Alternative Names (SANs) or CN for a v1 certificate.

Syntax and Options

Use the following syntax. Note that you can place the parameters in any order:

certchecker -certfile filepath [-certpass passphrase] [-cafile filepath] [-keyfile filepath] [-keypass passphrase] [-host hostname] [-out outfile]
-certfile
Specifies the path to a file containing the certificate. This can be PEM or DER encoded. This file can also contain intermediate CA certificates that will be treated as untrusted but can be used to help establish a trust chain.
Note: This field is required.
-certpass
Specifies the passphrase for the certificate file if there is one. Many certificate files are not password protected, in this case, the option is not required.
-cafile
Specifies the path to a file containing the CA certificate. This file can also contain intermediate certificates which will be used to establish a trust chain.
-keyfile
Specifies the path to a file containing the private key. This private key must match the certificate specified in the -certfile option.
-keypass
Specifies the passphase for the keyfile if there is one. If the file is not password protected then this option is not required.
-host
Checks that the certificate includes the specified host in its SANs. This could be a hostname such as host.company.com, an IPv4 address such as 127.0.0.1, or an IPv6 address such as ::1. For older certificates, this will check if the hostname matches the CN instead of the SANs.
-out
Specify a file to send output to, instead of stdout. Program errors will still be sent to stderr.

Examples

Check the validity of a certificate:

certchecker -certfile /path/to/cert

Verify a certificate and trust chain:

certchecker -certfile /path/to/cert -cafile /path/to/ca_collection

Verify that a certificate and a private key match:

certchecker -certfile /path/to/cert -keyfile /path/to/keyfile -keypass passphrase

Check that a certificate matches a private key and can be used with the hostname somehost.org:

certchecker -certfile /path/to/cert -keyfile path/to/key -keypass passphrase -host somehost.org

Check the validity of a certificate and write the output to myfile.txt:

certchecker -certfile /path/to/cert -out /path/to/myfile.txt

Example Output Messages

For an expired certificate, CertChecker will display the following message:

*Error: The certificate has expired: The notAfter date is before the current time.

Similarly for an expired intermediate or root certificate it will display the following error message along with the subject of the certificate:

Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IntermediateTestCert1
*Error: The certificate has expired: The notAfter date is before the current time.

If a trust chain could not be established, CertChecker will display the following message with the subject of the certificate that is missing an issuer:

A problem was found with the following certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IdTestCert
*Error: The issuer certificate could not be found. This normally means the list of trusted certificates is incomplete or incorrect.

Similarly for an intermediate certificate with a missing issuer, note the different subject:

A problem was found with the following certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IntermediateTestCert1
*Error: The certificate's issuer could not be found. This normally means collection of trusted certificates is not complete.

As a warning about a private key with inadequate security, CertChecker will display a message similar to the following:

*Warning: Security bits: 80 - It is recommended to use a key with at least 128 security bits. This is equivalent to a 3072 bit RSA key or a 256 bit EC key.

If the certificate and private key do not match, CertChecker will display the following error message:

Verifying that the Certificate and private key match.
*Error: Verification Failed. Certificate and key do not match.

In the following example the CA certificate contains the extension:

X509v3 Name Constraints: Permitted: DNS:somedomain

which means that it can only issue certificates with SANs that match somedomain, but the certificate contains the SAN:

IP Address:127.0.0.1

which is outside of those constraints resulting in a verification error:

A problem was found with the following certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IdTestCert
*Error: A name constraint violation occurred in the permitted subtrees.

If a CA certificate contains the Basic Constraints extension with a pathlen, such as:

X509v3 Basic Constraints: critical CA:TRUE, pathlen:1

The pathlen specifies how many intermediate CAs can exist between the CA and the entity certificate. A pathlen of 0 means there can be no intermediates between the CA and the entity certificate, a pathlen of 1 means there can be 1 intermediate between the CA and the entity certificate and so on. If the path length constraint has been violated then CertChecker will display an error message similar to the following, which lists the CA whose pathlen was violated:

A problem was found with the following certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=RootTestCert
*Error: The basicConstraints path-length parameter has been exceeded.

Example Output Explanation

The following example explains the full output from CertChecker step by step. In this example, CertChecker is specified with an entity certificate and a valid collection of its intermediate certificates for the -certfile parameter. For the -cafile parameter, a CA certificate was specified that did not sign any of the intermediate certificates specified to -certfile. CertChecker will return a verification error highlighting that it failed to build the complete trust chain.

The following is the full input and output:

C:\TestCertificates>certchecker -certfile ./IDCertAndIntCollection.pem -cafile ./IncorrectRootCert.pem
Copyright 2024 Company or one of its affiliates.
CertChecker version 1.0.0
OpenSSL version 3.0.8
Loading certificate from file: C:\TestCertificates\IDCertAndIntCollection.pem
Loading trusted certficates from file: C:\TestCertificates\IncorrectRootCert.pem Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IDCert1708682316.351323
Signature algorithm: ecdsa-with-SHA256
Key type: EC prime256v1 256 bits
Security bits: 128
SAN: 127.0.0.1
SAN: localhost
SAN: 0000:0000:0000:0000:0000:0000:0000:0001
Verifying certificate and establishing the trust chain.
A problem was found with the following certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=RootCert1708682315.313869
*Error: The certificate chain could be built up using the untrusted certificates but the root could not be found locally.
Verification Failed.
Errors: 1 Warnings: 0

From an Enterprise Developer command prompt, consider the following example which specifies a collection of untrusted certificates. In this case, an entity certificate and its intermediates and a root certificate:

Note: You could have specified a collection of CA certificates to -cafile but in this case it is just the root.
C:\TestCertificates>certchecker -certfile ./IDCertAndIntCollection.pem -cafile ./IncorrectRootCert.pem

A similar message is displayed, including the CertChecker version and the OpenSSL API version being used:

Copyright 2024 Company or one of its affiliates.
CertChecker version 1.0.0
OpenSSL version 3.0.8

Followed by details about the certificate/key files that it is trying to load. If it fails to load certificates from any of the files specified then it will terminate and give an error message:

Loading certificate from file: C:\TestCertificates\IDCertAndIntCollection.pem
Loading trusted certficates from file: C:\TestCertificates\IncorrectRootCert.pem

Information about the entity certificate specified, including its subject, the signature algorithm used, key type, security bits which is a measure of how cryptographically secure the key is (a warning will be displayed if this value is too low), and the SANs included in the certificate:

Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=IDCert
Signature algorithm: ecdsa-with-SHA256
Key type: EC prime256v1 256 bits
Security bits: 128
SAN: 127.0.0.1
SAN: localhost
SAN: 0000:0000:0000:0000:0000:0000:0000:0001

Following this, information will be given about the types of verification that was performed, this is dependent on the input specified. In this case, a -certfile and a -cafile, so the identity certificate will be checked for any warnings and a full trust chain verification will be performed using the trusted and untrusted certificates specified. If a private key had been specified, then CertChecker would also check that the identity certificate and private key match.

Verifying certificate and establishing the trust chain.

CertChecker will display an error if it cannot complete the trust chain if the trusted certificates specified in -cafile do not contain the correct root CA:

A problem was found with the following certificate:
Certificate: /C=GB/ST=State or Province/L=Locality or City/O=Organization/OU=Comms/CN=RootCert1708682315.313869
*Error: The certificate chain could be built up using the untrusted certificates but the root could not be found locally.
Verification Failed.

Finally, a summary of the total number of warnings and errors is displayed:

Errors: 1 Warnings: 0
Parent topic: Troubleshooting a Secure Connection


Using the Demonstration Certificate Authority

The Demonstration Certificate Authority, or Demo CA, is an optional component included with Visual COBOL, Enterprise Developer, and Enterprise Server. It can be used to generate private keys and test certificates for development and testing purposes. Demo CA is not intended or supported for production use.

You can use Demo CA to generate certificates and their corresponding private keys to test your secure communications configurations, and for developer and test systems. For production systems, use certificates issued by a public CA or a CA controlled by your organization, and protect private keys carefully.

Demo CA is a set of scripts which use the OpenSSL utility program. Running the CreateDemoCA script will create the CA itself and test certificates for a server, a client machine, and a client user. The Demo CA component scripts are included in the product's installation bin directory; unlike in older product releases, there is no longer a Demo CA installer. When you run the scripts to create a Demo CA instance, you specify the destination directory for it.

Demo CA was rewritten for the 9.0 product release to improve usability, add features, and respect current standards and best practices. Users upgrading from earlier product versions should consult the Demo CA documentation to familiarize themselves with the differences.

  • About the Demo CA
  • Contents of Demo CA
  • OpenSSL and Micro Focus Demo CA
  • Your CA Certificate, Key and Password
Parent topic: Securing Communications
Related reference
Contents of Demo CA


About the Demo CA

Micro Focus Demo CA is an optional component which can be used to enable secure communications for an Enterprise Server listener, the Enterprise Server Common Web Administration (ESCWA) interface, and other Enterprise Server features, for development and test deployments. Demo CA is not supported or secure for production use.

Secure communications uses encryption and authentication of communications endpoints using the industry standard Transport Layer Security (TLS), formerly called Secure Sockets Layer (SSL). It is fully interoperable with standard (non-Micro Focus) SSL/TLS clients and servers. The base Enterprise Server product includes support for integration with Public Key Infrastructures (PKIs) and PKI functions, such as processing certificates; these features do not require creating a Demo CA instance.

The Demo CA software enables you to operate as a private Certificate Authority (CA). A CA creates certificates and signs them using its own certificates. Demo CA can set up your CA and create keys and certificates for servers and clients.

Demo CA comprises a number of script files in the Enterprise Developer bin directory. When the scripts are run, they create the CA itself and keys and certificates for a server and two kinds of clients, a machine client certificate and a user client certificate.

After successfully executing the main Demo CA script, CreateDemoCA, to create a Demo CA instance, you can find various certificate and key files under the directory you provided as a parameter to the CreateDemoCA script. See Contents of Demo CA for more information.

The private keys created by Demo CA are protected with a passphrase, which you supply when prompted by the Demo CA scripts.

Since Demo CA is a private, experimental CA, the certificates it creates can only be verified using the root and intermediate CA certificates created by that same instance of Demo CA. In order to use the client and server certificates from your Demo CA instance, you will need to configure the peer software - for example, a web browser that connects to an enterprise server listener which uses a Demo CA server certificate - with your Demo CA root and intermediate certificates.

For production systems, you should obtain certificates from a public or organizational CA. Demo CA is only suitable for development and testing purposes.

Parent topic: Using the Demonstration Certificate Authority
Related information
Contents of Demo CA
OpenSSL and Micro Focus Demo CA
Your CA Certificate, Key and Password


Contents of Demo CA

Starting with the 9.0 product release, the optional Demo CA component contains the following script files, with the .cmd file extension on Windows:

CreateDemoCA
Generates the root and intermediate CA certificates and their private keys, and the default set of client and server certificates and keys.
CreateNewUserCerts
Generates a new set of client and server certificates.
RevokeCertificate
Revokes a client or server certificate generated by Demo CA.

These utility scripts are executed by the main scripts listed above, and typically should not be run directly by the user:

  • GenRootCA
  • GenIntCA
  • GenUserCerts
  • GetSubject
  • IsIPAddr
  • SetDirectory

Demo CA also contains a file named 00Readme.txt which describes the scripts and how to use them, and some additional files used by the scripts.

See the topics listed below for more information on each of the main scripts.

After running CreateDemoCA, the Demo CA instance directory, which is specified to the script as a command-line parameter, will contain the following:

CA
Directory containing the files for the new root CA. Note the root CA is only used to issue certificates for the intermediate CA, and provide the root certificate for certificates issued by the intermediate.
intermediate
Directory containing the files for the new intermediate CA. The intermediate CA is used to issue all entity (client and server) certificates.
entities
A directory containing copies of all the certificates generated by Demo CA, and the private keys for entity certificates, for convenience when locating certificate files.
EC_openssl.conf ECintCA.conf
Configuration files used when generating certificates and related materials.

The EC prefix on many of the files indicates the use of Elliptic Curve Cryptography (ECC), which Micro Focus recommends for better security and performance. Within the CA and intermediate directories are various directories and files which implement the CAs.

Migrating from earlier releases

The new scripts listed above replace the scripts from earlier versions of Demo CA, such as reinstall_demoCA.

The file CARootCerts.pem, which contains trusted root and intermediate certificates from commercial CAs, is now part of the base product, not Demo CA.

The file CARootCert.pem (without the "s"), which in previous releases contained the root CA certificate for Demo CA, has been replaced with EC_CAcollection.pem and EC_CAcollection.p7b, which have the same contents in different formats, and can be found in the entities/CAs directory.

Note: There are now two CA certificates, a root and an intermediate, following current best practices for CAs.

If you wish to use Demo CA with enterprise server instances or server components such as ESCWA and MFDS, be sure to use the complete paths to your Demo CA certificate and key files when configuring TLS, since Demo CA no longer has a default installation directory. Similarly, if you wish to use Demo CA with client programs such as Enterprise Server utilities or COBOL Web service clients, edit the mf-client.dat file in the product installation location and set the values indicated in the file using full paths.

  • Understanding the CreateDemoCA Script
    This topic describes the use of the CreateDemoCA script in the new DemoCA.
  • Understanding the CreateNewUserCerts Script
    This topic describes the use of the CreateNewUserCerts script in the new Demo CA.
  • Understanding the RevokeCertificate Script
    This topic describes the use of the RevokeCertificate script in the new Demo CA.
Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
OpenSSL and Micro Focus Demo CA
Your CA Certificate, Key and Password


Understanding the CreateDemoCA Script

The CreateDemoCA command is a shell script included with the Demo CA optional component. It initializes a new instance of the Demo CA and creates a set of entity (client and server) keys and certificates. See About the Demo CA for more information.

You can run CreateDemoCA more than once, to create as many Demo CA instances as required.

Syntax:

CreateDemoCA destination-directory

Parameters:

destination-directory
The directory where you want the Demo CA instance to be created. The directory must already exist. If there is already a Demo CA instance there, it will be overwritten.

Comments:

CreateDemoCA will prompt you for various pieces of information used in generating the certificates. It executes several of the other Demo CA scripts as part of its processing.

The Enterprise Developer product must be configured properly in the shell environment before invoking this script.

Parent topic: Contents of Demo CA


Understanding the CreateNewUserCerts Script

The CreateNewUserCerts command is a shell script included with the Demo CA optional component. It generates a new set of entity (client and server) keys and certificates in an existing instance of the Demo CA. See About the Demo CA for more information.

You can run CreateNewUserCerts to generate additional sets of entity certificates. If you wish to replace existing entity certificates in a Demo CA instance, you must revoke the existing certificates first using RevokeCertificate.

Syntax:

CreateNewUserCerts DemoCA-directory [certificate-types]

Parameters:

DemoCA-directory
The directory containing your existing Demo CA instance.
certificate-types
An optional parameter specifying which types of entity certificates to create. If specified, this should be one of:
server
Creates a server certificate only.
client
Creates a client machine certificate only.
clientuser
Creates a client user certificate only.
all
Creates all of the above certificates.

The default value is all.

Comments:

CreateNewUserCerts will prompt you for various pieces of information used in generating the certificates. It executes several of the other Demo CA scripts as part of its processing.

CreateNewUserCerts will prompt for identification information for the new certificate(s). If a certificate with the same information already exists in this Demo CA instance, it must be revoked first using RevokeCertificate, or the creation attempt will be rejected.

The Enterprise Developer product must be configured properly in the shell environment before invoking this script.

Parent topic: Contents of Demo CA


Understanding the RevokeCertificate Script

The RevokeCertificate command is a shell script included with the Demo CA optional component. It revokes an existing certificate in an existing instance of the Demo CA. See About the Demo CA for more information.

Syntax:

RevokeCertificate DemoCA-directory certificate-path

Parameters:

DemoCA-directory
The directory containing your existing Demo CA instance.
certificate-path
The path to a file containing the certificate to be revoked.
Note: Each Demo CA instance includes copies of all the certificates it has signed, under the entities directory and under the intermediate/certs directory; these copies can be used to revoke specific certificates.

Comments:

Revoking a certificate in Demo CA informs the CA that the certificate is no longer valid. It updates the Demo CA instance's database of certificates, and also updates the Certificate Revocation List (CRL) that Demo CA maintains.
Note: That Enterprise Developer components do not currently make use of the CRL.

The main purpose in revoking a certificate in Demo CA is to make the same certificate identity Distinguished Name (DN) available for a new certificate to use.

The Enterprise Developer product must be configured properly in the shell environment before invoking this script.

Parent topic: Contents of Demo CA


OpenSSL and Micro Focus Demo CA

Micro Focus Demo CA comprises a set of scripts which use the openssl utility program. This utility is included in the Enterprise Developer and Enterprise Server products. Some operating systems also include a version of the openssl utility; for Demo CA, you should use the version supplied by Micro Focus to avoid any issues with differences among OpenSSL versions.

OpenSSL is an implementation of SSL/TLS and related tools maintained by the OpenSSL Project (openssl.org). Micro Focus includes customized portions of the OpenSSL distribution in Enterprise Developer. The openssl utility offers a number of functions which are useful for SSL/TLS and PKI tasks, such as creating and manipulating key and certificate files.

Additional documentation about OpenSSL can be found on openssl.org and other websites.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
Contents of Demo CA
Your CA Certificate, Key and Password


Your CA Certificate, Key and Password

The Demo CA follows the best practices for modern CAs. That includes using two levels of CA certificates. There is a root certificate, which is self-signed. The root is used to sign an intermediate certificate, and then entity (client and server) certificates issued by the CA are signed by the intermediate.

Using this structure in Demo CA mimics public CAs and many internal organizational CAs, and lets Enterprise Server administrators see how certificate chains are configured. A certificate chain is the full collection of certificates from the entity to the root. When one participant (client or server) in a TLS conversation receives a certificate from the other side, part of the process it uses to verify the certificate involves reconstructing the full chain from the entity certificate to a trusted root. The sender might send just its entity certificate, but good practice is to include any intermediate certificates in the chain, and possibly even the root itself to assist in problem resolution. On the receiving side, including not just the root but the intermediate as well in the collection of trusted certificates (also called trust anchors) can improve interoperability.

Each certificate is associated with a private key, which can be in a separate file, or in the case of some file formats, such as PKCS#12 (.p12), included in the same file as the certificate. The private key is needed to use the certificate to sign a message or prove identity; it is not needed by the recipient to verify identity. So for example, when you configure an enterprise server listener to use a server certificate, you will need the private key for that certificate as well; but when configuring the Demo CA root and intermediate certificates as trusted, you do not need their keys.

Private keys are typically protected using passphrases. The Demo CA scripts will prompt you for passphrases as it creates and uses private keys. It is important to keep these passphrases secure if you use any Demo CA certificates for security, even to secure an enterprise server instance on development or test systems.

Remember: Attackers who penetrate your network can make use of development and test systems to escalate their attacks.

When the Demo CA scripts have been run, certificates and the private keys for entity certificates can be found in the entities directory tree. There you will find:

  • A directory named CAs, which will contain the following:
    • CARootECCert.pem, the Demo CA root certificate in PEM format, including a text representation of the certificate contents. The "EC" indicates this is an ECC, or Elliptic Curve Cryptography, certificate.
    • CARootECCert.p7b, the root certificate in PKCS#7 format, which is used by some software for importing certificates.
    • EC_CAint.pem, the intermediate CA certificate.
    • EC_CAcollection.pem, the root and intermediate certificates in a single file. This is typically the file you will want to use when you need to specify a trust store for verifying Demo CA certificates, for example, if you are configuring an enterprise server listener to accept client certificates.
    • EC_CAcollection.p7b, the same in PKCS#7 format. This is suitable for importing into the Windows Certificate Manager, for example.
  • A directory named typically for the system where you ran Demo CA. If you run the CreateNewUserCerts script more than once, there should be one directory here for each Common Name (CN) you provided to the script. This directory typically includes the following:
    • Certificate Signing Request files, with an extension of .csr. These are used to request a certificate from the CA.
    • clientcert_*. these are various flavors of the "machine" client certificate and its private key, which can be used by a client program to identify itself to the server using the hostname of the system where you ran Demo CA. Besides the .pem and .p7b formats described above, you will see a .p12 (PKCS#12) file. PKCS#12 contains both the certificate chain and key, so it is useful for importing into systems that have a certificate import function, such as the Windows Certificate Manager. You can also use a PKCS#12 file with Enterprise Server by specifying the .p12 file for both the certificate and key file.
    • clientusercert_*. these are similar to the clientcert files, but identify the client as a person rather than a machine. Specifically, they use the operating system username of the user who ran the Demo CA scripts. Some applications which allow or require client certificates want to receive client certificates that identify the client machine; others want certificates that identify the client user. So Demo CA generates both.
    • srvcert_*. these are the server certificate and private key generated by Demo CA. They identify the machine where Demo CA was run, by its fully-qualified domain name and also by any alternative names or IP addresses supplied by the Demo CA user when prompted by the script.

The other directories created by Demo CA hold the files needed by the CA. There is one for the root CA certificate, and one for the intermediate. You can examine these if you wish, but their contents are not needed when configuring Enterprise Server for TLS.

If you use Demo CA for any purpose other than short-term experimentation, Micro Focus recommends backing up its contents to avoid disruption.

Parent topic: Using the Demonstration Certificate Authority
Related information
About the Demo CA
Contents of Demo CA
OpenSSL and Micro Focus Demo CA


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 forEnterprise Server.

    You create an HTTPS listener and you install the server certificate and private key file that you created using the demonstration CA.

  • 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 commercial Certificate Authorities. Organizations which have their own Certificate Authority will also usually ensure their root certificates are installed for their end users. However, if you are using certificates created with Micro Focus Demo CA, the demonstration CA software, you will need to install your DemoCA root certificate in your browser.

See Using the Demonstration CA for more information on how to generate certificates for use in this tutorial.

In this tutorial, you configure a listener for the ESDEMO server to use secure communications. ESDEMO is created by the Enterprise Server installation. Within an enterprise server instance, you can create listeners for different kinds of communication.

Note: Do not use the http-echo conversation type in production. It is intended only for connection testing.
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. In ESCWA, click Native.
  2. In the navigation pane, click Directory Servers > Default.
  3. In the Region and Server List, ensure that ESDEMO has a status of stopped.
  4. In the navigation pane, click ESDEMO.
  5. Click General > Listeners.
  6. Expand Communications Process 1 so you can see all the listeners.
  7. Click * New Listener to create a listener for HTTPS.
  8. Under Listener Properties, in the Name field, type HTTPS Echo.
  9. In the Hostname or IP Address field, type *.
  10. In the Port field, type 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
  11. To specify that this listener will be a simple response to HTTP requests, under Conversation Type, click Custom and type http-echo in the field alongside.
  12. In the Description field, type Simple secure HTTP test.
  13. Click Save.

    The new HTTPS Echo listener is displayed under Communications Process 1.

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, under Communications Process 1, click HTTPS Echo.
  2. Click TLS Settings.

    This expands the TLS Settings.

  3. Check Enable TLS.
  4. In the Certificate File field, type the full path of your certificate.
  5. In the Keyfile field, type the full path to the private key.
  6. Click Apply.
Note: Do not set the http-echo conversation type to use in production. It is intended for connection testing only.
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 region 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 . 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 ESCWA.

    Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This can be specified in the mf-server.dat file and takes the following form:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
    Note: If you are configuring the listener to start without a passphrase then use empty double quotes (keyfile="").
  3. Start Enterprise Server Common Web Administration (ESCWA), in the menu bar, click Native.
  4. Expand Directory Servers > Default.
  5. Click ESDEMO , and click General > Control.
  6. Click Start.
  7. When ESDEMO has started, click General > Listeners to make sure that the new listener HTTPS Echo has started, as with the other listeners.

If you ever have problems starting or running an SSL-enabled listener, it can be useful to look at the MFCS log, click Monitor > Logs > Communications Log.

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 to ensure that the Web site's certificate is accepted. At this point in the tutorial, the necessary Demo CA's self-signed certificate is not installed in your browser. This is intentional so that you can see the messages that this generates.

  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.

Note: Do not use the http-echo conversation type in production. It is intended only for connection testing.
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 typically download it from the CA's website.

CAs typically use both "root" and "intermediate" certificates. Entity certificates, such as server, client, and user certificates, are signed by an intermediate certificate. Intermediate certificates are signed by other intermediate certificates or a root certificate. The entity, intermediates, and root form a "chain" of certificates that ends in a trusted root certificate. While clients and servers will sometimes send the necessary intermediate certificates along with their entity certificate, for best interoperability you should import both root and intermediate certificates into your collection of trusted certificates.

The demonstration CA uses a root and a single intermediate certificate. These can be found in the file entities/CAs/EC_CAcollection.p7b under the Demo CA location. The "EC" prefix indicates these are ECC, or Elliptic Curve Cryptography, certificates. There is another version of this file in a different format with the .pem file extension. The .p7b file is in PKCS#7 format, which more browsers support. This is the file you will import into your collection of trusted certificates.

The import process differs between browsers. In particular, some browsers have their own collection of trusted certificates, and others use one maintained by the operating system. In either case, you can usually get to a wizard or other tool for importing trusted certificates from your browser's Settings page, typically under a Security tab or similar.

Typically, to import the certificates:

  1. Locate the certificate import function for your browser.
  2. Select the file EC_CAcollection.p7b from your Demo CA instance.
  3. Confirm the browser will import these certificates as trusted roots.
    Note: Different browsers use different terms for this.
  4. After importing, you can view your browser's trusted roots and confirm the Demo CA root is present. The Demo CA root has a common name like "Demo CA on host", where host is the hostname of the system where Demo CA was executed.
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, type https://localhost:9443.
  2. Read the security alert again. This time it shows only one problem, which is that the name in the certificate does not match the URL you tried to connect to. This is a warning that the certificate might not have come from the desired website, but from another website masquerading as it.
  3. Since this is in fact the desired website, 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 typical 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

If you do not intend to continue using this instance of Demo CA, you should remove the Demo CA root certificate from your browser's set of trusted CA certificates, to avoid any possible security exposure.

Follow the instructions for your browser for removing a root certificate. Typically this is done under the "Security" area of the browser options.

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


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.
  • 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
  • SHA2
  • SHA3
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?

Earlier, we established that the SSL software compares a certificate to a list of known CAs. We will now describe this process in more detail.

A CA itself has a certificate, in the case of a root CA it will be a self-signed certificate. 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. In addition, Windows might provide automatic updates that install additional CA certificates in your Web browser.

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.
  • 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 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 of the certificates, this opens the Certificate dialog box. 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 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.
  5. Click OK to close the Certificate dialog box.
  6. Click the Intermediate Certification Authorities tab. This displays a list of subordinate CAs whose certificates have been installed in Internet Explorer.
  7. Double-click one of the certificates.
  8. Click Certification Path tab. You now see the chain of CAs, from the subordinate CA that issued this certificate, back up through the hierarchy to the root CA.
  9. Click OK to close the dialog box.
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 Open Application Menu > Settings > Privacy & Security.
  2. Click View Certificates.

    This opens the Certificate Manager dialog box.

  3. 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 best known ones, is installed when Firefox is installed.
  4. Double-click any of the certificates to display the certificate's details. In many cases the issuer and who the certificate was issued by are the same, indicating a self-signed certificate - one issued by a root CA to itself.
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. Click the Content tab, and then double-click Certificates.

    This opens the Certificates dialog box.

  3. Click the Trusted Root Certification Authorities tab and find the certificates marked VeriSign. 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. Choose the format required by your target browser. If you do not 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 Internet Explorers 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, click Open Application Menu Settings > Privacy & Security.
  2. Click View Certificates.

    This opens the Certificate Manager dialog box.

  3. Click the Authorities tab and click Import.
    • 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 will be displayed 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
  • Do Not Edit Certificates and Key Files
  • To Convert Certificate Formats
  • Multi-Certificate files
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 #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.
  • PKCS #8. This format can contain private keys and encrypted private key information. It stores the data in base64 encoded data, usually using a DER or PEM structure which is then encrypted. The standard extension is .p8.
  • 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.
Parent topic: Certificates
Parent topic: SSL and PKI Technology Primer
Previous topic: Certificates
Next topic: Do Not Edit Certificates and Key Files


Do Not 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: Do Not Edit Certificates and Key Files
Next topic: Multi-Certificate files


Multi-Certificate files

Typically, 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.

PEM, PKCS7, and PKCS12 format files can contain multiple certificates. This is useful for storing a bundle of the root certificates of the CAs you trust, a certificate verification chain, or a complete endpoint identity within a single file. To create one of these files you need to concatenate the individual certificates into one file.

For PEM and PKCS7 files, concatenation can be performed by appending one file to another using a text editor. If required, you can split the original files using a text editor. You must ensure that you do not change the data for each individual certificate. Each certificate takes the following format and is terminated by an 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's integrity is maintained. A certificate is rendered useless if it does not maintain its binary composition from the point it was originally signed.

For PKCS12 files, you will need to use OpenSSL to perform the concatenation or splitting process. The number of certificate and key content in a PKCS12 file varies depending on its intended use. It can contain any or all of the following:

  • CARoot certificate
  • Intermediate CA certificates
  • Identity certificate and Private Key content within a single file.
    Note: Only one filesystem item requires protection for an endpoint's identity information.

The most common PKCS12 variant is a file containing a single ID certificate, plus its associated signing CA Intermediate Certificate Authorities collection. Typically without the final CARoot certificate and the Private Key file that matches the Public Key held within the Identity Certificate. This enables the client to verify the identity of the possession of the single CARoot certificate, which is the only missing element from the whole chain of trust.

When creating a PKCS12 ID, Certificate Chain, and Private Key file, the file will typically be protected with its own password. Just as a Private Key file is typically protected with a password. As a result of this, when using a PKCS12 file, it is standard practice to require a Certificate Password and no Keyfile Password in system endpoint configuration options.

To generate such a certificate perform the following steps:

  1. Concatenate the PEM format certificates into a single PEM file. For example, you can name the file CertChainID.pem.
  2. Identify the private key file associated with the identity certificate in the chain, if any. For example, you can name the file PrivKey.pem, and specify its password as Passwd.
  3. Choose a password for the newly created PKCS12 file. For example, you can specify this as P12Passwd.
  4. Choose an output name for the PKCS12 file. For example, you can name the file CertChainID.p12.
  5. Identify the Common Name (CN) in the ID certificate in the chain. For example, you can specify this as CN_name.
  6. On the command line, type the following:
    openssl pkcs12 -export -in <CertChainID.pem> -inkey <PrivKey.pem> -passin pass <Passwd> -passout pass <P12Passwd> -out <CertChainID.p12> -name <CN_name>
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. See the RSA website for more information.

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. A key length of 256 bits is generally considered adequate for reasonable security using a symmetric algorithm or elliptic curve cryptography. While with an other asymmetric algorithm 2048 bits is considered adequate. Although more bits are preferable.

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 was a widely-used cipher which has the following related algorithms, RC2, RC5, and RC6.
Important: Multiple vulnerabilities have been discovered in the RC4 cipher, rendering it insecure. Micro Focus no longer uses this cipher in its products. Attempts to configure the RC4 algorithm will result in configuration errors.
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.

Important: DES is now considered to be a weak algorithm. Micro Focus no longer supports this algorithm in its products. Attempts to configure the DES algorithm will result in configuration errors.
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, 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
AES Algorithm (Rijndael) Information


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.

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
The Blowfish Encryption Algorithm


Twofish

This too was developed by Bruce Schneier, and is efficient when implemented in hardware and smart cards.

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
Twofish


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. In SSL, it can still be used for most purposes as part of security level zero. Micro Focus recommends that you use SHA2 or SHA3 in preference to MD5.

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 in the SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions document on the NIST Web site.

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
SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions


SHA2

The Secure Hash Algorithm 2 (SHA2) is a cryptographic hash functions designed by the United States National Security Agency (NSA).

SHA2 supersedes the less secure SHA1. SHA2 includes significant changes from its predecessor and is currently the most widely used hash algorithm. It is in the process of being superseded by SHA3. SHA2 comes in a range of digest sizes 224, 256, 384, and 512 bits.

When specifying these digests within log or trace files, they are typically referred to as:

SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256.

Parent topic: Hashing


SHA3

The Secure Hash Algorithm 3 (SHA3) is the latest member of the Secure Hash Algorithm group of standards. Released by the National Institute of Standards and Technology (NIST). SHA3 uses a Sponge function which is different from the algorithm used in SHA1, SHA2, and MD5.

SHA3 provides the same range of digest sizes (224, 256, 384, and 512 bits) as SHA2 and is intended to replace SHA2.

Parent topic: Hashing


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
Digital Signature Standard


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.
  • ASN.1
  • Base64 Encoding
  • SSLeay
Parent topic: SSL and PKI Technology Primer
Parent topic: SSL and PKI Technology Primer
Next topic: ASN.1


ASN.1

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. As an analogy, you can 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 might never see an example of ASN.1, as 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 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 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: ASN.1
Parent topic: SSL and PKI Technology Primer
Previous topic: ASN.1
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: ASN.1
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: ASN.1
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. The branches of the tree are referred to as arcs, and various organizations have been allocated responsibility for registering OIDs by 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: ASN.1
Parent topic: SSL and PKI Technology Primer
Previous topic: Distinguished or Canonical Encoding Rules
Next topic: Octets
Related information
OID Registry


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: ASN.1
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: ASN.1
Parent topic: SSL and PKI Technology Primer
Previous topic: Octets
Next topic: Further Information


Further Information

For detailed information on ASN.1, see ITU-T ASN.1 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: ASN.1
Parent topic: SSL and PKI Technology Primer
Previous topic: UTF8String
Next topic: Base64 Encoding
Related information
ITU-T ASN.1 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


Specifying a Server Protocol and Cipher Suite Preference

During the initial connection handshaking process clients send an ordered cipher suite list to use for the duration of the connection. The server selects a cipher suite from the client's preferred order list of supported cipher suites.

By default, because the TLS honor server cipher list option is checked in a listener's SSL Options or the MF Directory Server tab, the conversation will use the server's preferred protocol and cipher suites list. If you have not specified a value for the TLS protocols or Cipher suites fields, then the default is used. The TLS protocols field now supports TLS1.3. See Configuring a TLS Protocols List and Configuring a Cipher Suites List for more information. You can use the TLS honor server cipher list to force the use of a strong, ordered list of protocols and cipher suites. This controls the strength of cryptography used between server and client.

Note: A server using the SSL protocol is subject to a number of well documented security vulnerabilities. This is why the SSL2 protocol is no longer supported by Micro Focus products. Micro Focus recommends using the TLS1.1 and TLS1.2 protocols.
  • Configuring a TLS Protocols List
  • Configuring a Cipher Suites List
  • Dependencies Between TLS Protocols and the Cipher Suites
  • Dual Cryptographic Identities on a Single Network Endpoint
  • Security Levels
  • Middlebox Compatibility with TLS v1.3
  • Using Elliptic Curve Cryptography
  • Using Diffie-Hellman Cryptography
  • Certificate Files
  • PKCS #12 File
  • Configuring the MF Directory Server to use TLS Protocols and Cipher Suites
  • Configuring a Listener to use TLS Protocols and Cipher Suites
Parent topic: Securing Communications


Configuring a TLS Protocols List

The TLS protocols field enables you to specify the list of protocols to be used and the order of preference in which they are to be used. The TLS protocols field has the following default state:

Protocol | Default state
SSL2 | Disabled (permanently)
SSL3 | Disabled
TLS1 | Enabled (deprecated)
TLS1.1 | Enabled (deprecated)
TLS1.2 | Enabled
TLS1.3 | Enabled
Note: The Internet Engineering Task Force (IETF) have published RFC 8996, which officially makes TLS versions 1.0 and 1.1 deprecated. Micro Focus strongly recommends you avoid their use unless they are required for compatibility with older devices or applications which cannot be upgraded. A future release of Enterprise Server will disable these protocols by default.

You can use the following protocol options when configuring the TLS protocols field:

Option | Note
ALL | All the protocols listed here.
SSL2 | Supported to match syntax in Apache. SSL2 is always disabled.
SSL3 |
TLS1 | TLS 1.0
TLS1.1 |
TLS1.2 |
TLS1.3 |
TLS1.4 | Provided for future compatibility.1
Note: 1 The TLS1.4 option is provided to support future compatibility.

Each option must be preceded by an operator with the exception of the special option ALL. The following is a list of valid operators:

!
Exclude. Permanently excludes the following option and ignores any subsequent attempt to add an option back in.
+
Add. Adds the following option to the existing protocol list.
-
Delete. Delete the following option. This option can be added again if it is found at a subsequent point.

This is the same syntax used in Apache configurations. You can copy configurations from Apache installations to use in Enterprise Developer with little need for modifications.

There are several different ways to insert protocol definitions into each connection definition making these options additive.

To remove SSL3 from the default list while keeping the remaining default options you can add -SSL3 to the SSL protocol list.

To ensure that all default options are removed from the TLS protocols list you must specify -ALL at the start of each string. You can then specify a new string of options by adding them after the -ALL option.

Example TLS protocols options:

TLS protocols | Description
ALL | Use the whole collection supported by the underlying security module.
-ALL | Clear all protocols. This option precedes any new definitive list, for example, see the following two rows.
-ALL+TLS1.1+TLS1.2 | Only use TLS1.1 and TLS1.2.
-ALL-TLS1.1+TLS1.1+TLS1.2 | Only use TLS1.1 and TLS1.2.
-ALL+TLS1.1 +TLS1.2-TLS1.2 | Only use TLS1.1.
!ALL | This is syntactically correct but logically it is undesirable as it permanently removes all protocols. Its use results in an error state that prevents a client or server from starting.
Note:
  • A zero-length TLS protocols field string does not result in any change to the default behavior.
  • A TLS protocols field string which only contains a space character does not result in any change to the default behavior.
  • Space and tab characters within the string are ignored, other characters result in an error condition (0089).
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Configuring a Cipher Suites List

There are two different methods for configuring a cipher suite list depending on the version of TLS being used:

  • Configuring a Cipher Suites List Using TLS v1.2 and Earlier
  • Configuring a Cipher Suites List Using TLS v1.3
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Configuring a Cipher Suites List Using TLS v1.2 and Earlier

The Cipher suites field enables you to specify the list of ciphers to be used in order of preference of use. You can modify the Cipher suites available for use with your chosen TLS protocols string. The Cipher suites string is made up of:
  • Operators, such as those used in the TLS protocols string.
  • Keyword ciphers such as ALL, HIGH, MEDIUM, and LOW.
  • Cipher suites using a specific authentication or key agreement, such as ECDH.
The full list of permitted cipher strings is defined by OpenSSL. See the OpenSSL documentation for more information.
Note: The Cipher suites string is limited to 255 characters.

The default setting for the Cipher suites list is specified as follows:

@SECLEVEL=1 kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM !3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP

This list provides the following security in order of priority:

@SECLEVEL=1
Restricts the available signature algorithms and cipher suites in OpenSSL to a baseline secure collection. This is to prevent the accidental use of weaker or broken cryptography. This breaks compatibility with older certificates such as MD5 and those using small keys. This will also prevent connections to systems using TLS 1.1 and earlier, and connections from clients that do not send the signature algorithms extension.
kEECDH+ECDSA
The faster Elliptic Curve Cryptography (ECC) collection which supports Perfect Forward Security (PFS).
kEECDH
The remaining collection also supports PFS but uses the slower RSA keys.
kEDH
The remaining Diffie-Helman suites.
HIGH
All remaining high security suites not listed above.
MEDIUM
All remaining medium security suites not listed above.
!3DES
Specifies not to use any 3DES ciphers.
+SHA
Move all the older SHA suites to the end of the list.
!RC4
Specifies not to use any RC4 suites.
!aNULL
Specifies not to use any ciphers that do not authenticate.
!eNULL
Specifies not to use any ciphers that do not encrypt.
!LOW
Specifies not to use any low strength security cipher suites.
!MD5
Specifies not to use any MD5 ciphers.
!EXP
Specifies not to use any EXPORT strength ciphers.

The default cipher list results in the following cipher collection, which contains medium strength ciphers when used with an RSA certificate:

Cipher Suite Name (OpenSSL) | Key Exchange | Encryption | Key Length
ECDHE-RSA-AES256-GCM-SHA384 | ECDH 256 | AES GCM | 256
ECDHE-RSA-AES256-SHA384 | ECDH 256 | AES | 256
ECDHE-RSA-AES256-SHA | ECDH 256 | AES | 256
DHE-RSA-AES256-GCM-SHA384 | DH 1024 | AES GCM | 256
DHE-RSA-AES256-SHA256 | DH 1024 | AES | 256
DHE-RSA-AES256-SHA | DH 1024 | AES | 256
DHE-RSA-CAMELLIA256-SHA | DH 1024 | Camellia | 256
AES256-GCM-SHA384 | RSA | AES GCM | 256
AES256-SHA256 | RSA | AES | 256
AES256-SHA | RSA | AES | 256
CAMELLIA256-SHA | RSA | Camellia | 256
ECDHE-RSA-AES128-GCM-SHA256 | ECDH 256 | AES GCM | 128
ECDHE-RSA-AES128-SHA256 | ECDH 256 | AES | 128
ECDHE-RSA-AES128-SHA | ECDH 256 | AES | 128
DHE-RSA-AES128-GCM-SHA256 | DH 1024 | AES GCM | 128
DHE-RSA-AES128-SHA256 | DH 1024 | AES | 128
DHE-RSA-AES128-SHA | DH 1024 | AES | 128
DHE-RSA-SEED-SHA | DH 1024 | SEED | 128
DHE-RSA-CAMELLIA128-SHA | DH 1024 | Camellia | 128
AES128-GCM-SHA256 | RSA | AES GCM | 128
AES128-SHA256 | RSA | AES | 128
AES128-SHA | RSA | AES | 128
SEED-SHA | RSA | SEED | 128
CAMELLIA128-SHA | RSA | Camellia | 128
ECDHE-RSA-DES-CBC3-SHA | ECDH 256 | 3DES | 168
EDH-RSA-DES-CBC3-SHA | DH 1024 | 3DES | 168
DES-CBC3-SHA | RSA | 3DES | 168

Micro Focus suggests using the following Cipher suites string to provide improved security:

HIGH:!SSLv2:!RC4:!aNULL@STRENGTH

When used with an RSA certificate this Cipher suites string provides the following cipher collection:

Cipher Suite Name (OpenSSL) | Key Exchange | Encryption | Key Length
ECDHE-RSA-AES256-GCM-SHA384 | ECDH 256 | AES GCM | 256
ECDHE-RSA-AES256-SHA384 | ECDH 256 | AES | 256
ECDHE-RSA-AES256-SHA | ECDH 256 | AES | 256
DHE-RSA-AES256-GCM-SHA384 | DH 1024 | AES GCM | 256
DHE-RSA-AES256-SHA256 | DH 1024 | AES | 256
DHE-RSA-AES256-SHA | DH 1024 | AES | 256
DHE-RSA-CAMELLIA256-SHA | DH 1024 | Camellia | 256
AES256-GCM-SHA384 | RSA | AES GCM | 256
AES256-SHA256 | RSA | AES | 256
AES256-SHA | RSA | AES | 256
CAMELLIA256-SHA | RSA | Camellia | 256
ECDHE-RSA-AES128-GCM-SHA256 | ECDH 256 | AES GCM | 128
ECDHE-RSA-AES128-SHA256 | ECDH 256 | AES | 128
ECDHE-RSA-AES128-SHA | ECDH 256 | AES | 128
DHE-RSA-AES128-GCM-SHA256 | DH 1024 | AES GCM | 128
DHE-RSA-AES128-SHA256 | DH 1024 | AES | 128
DHE-RSA-AES128-SHA | DH 1024 | AES | 128
DHE-RSA-CAMELLIA128-SHA | DH 1024 | Camellia | 128
AES128-GCM-SHA256 | RSA | AES GCM | 128
AES128-SHA256 | RSA | AES | 128
AES128-SHA | RSA | AES | 128
CAMELLIA128-SHA | RSA | Camellia | 128

You can add or remove individual cipher suites as required. To order the available cipher suites you can use a combination of cipher operators. See Configuring a TLS Protocols String for more information.

Cipher suites can be included in your preferred list but they may not be offered to clients if their certificate and keys do not support that cipher suite.

If both the ECDSA and RSA methods of authentication are supported by the cipher list, then configuring a strong cipher list is independent of the type of authentication being supported. For example, when being used with RSA certificates the ECDSA aspect of the cipher list is ignored.

The Cipher suites string is ordered in priority with the highest preference first and the lowest preference last.

Note: The default Security Level will be increased to 2 (@SECLEVEL=2) in the 10 release of Enterprise Developer .
Parent topic: Configuring a Cipher Suites List


Configuring a Cipher Suites List Using TLS v1.3

Support for TLS v1.3 is enabled by default and will be negotiated in preference to older TLS protocols when the peer also supports TLS v1.3.

TLS v1.3 is the most secure TLS protocol available and brings with it new cipher suites and configuration options. It uses a shortened and more efficient initial connection negotiation sequence resulting in quicker connection times.

When updating existing installations, it is good practice to configure earlier TLS versions to operate alongside TLS v1.3. Once all peers have been upgraded to support TLS v1.3 you can disable the earlier TLS variants.

TLS v1.3 has reduced the requirement for long descriptive option lists that were used in TLS v1.2 and earlier. The following three aspects of negotiation have different configuration requirements from earlier version of TLS:

  • Cipher & Hash
  • Key Exchange
  • Signature Algorithm

The three aspects of negotiation are now configured separately. This means that the Cipher suites field cannot be used to configure the TLS v1.3 Cipher and Hash collections. You can specify the TLS v1.3 cipher suites in the TLS1.3 Cipher Suites field in ESCWA.

TLS1.3 Cipher Suites

The following are the new collections of cipher suites used in TLS v1.3:

  • TLS_AES_256_GCM_SHA384 (Enabled by default)
  • TLS_CHACHA20_POLY1305_SHA256 (Enabled by default)
  • TLS_AES_128_GCM_SHA256 (Enabled by default)
  • TLS_AES_128_CCM_8_SHA256
  • TLS_AES_128_CCM_SHA256
Note: The last two collections need to be explicitly added if required. When creating a list, each collection is space separated, for example:
TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 TLS_AES_128_GCM_SHA256
Parent topic: Configuring a Cipher Suites List


Dependencies Between TLS Protocols and the Cipher Suites

The TLS protocols list options are used in conjunction with the Cipher suites list options to determine the exact collection of ciphers that are offered to a client.

If a cipher list is specified and is part of the protocol that is selected by this option then it is offered for use for the connecting peer. For example, if only the SSL3 protocol is specified and an RSA certificate is used and the cipher suites specified are:

kEECDH+ECDSA kEECDH kEDH HIGH +SHA !RC4 !aNULL !eNULL !MEDIUM !LOW !3DES !MD5 !EXP

Then the available collection is limited to the following cipher suites:

Cipher Suite Name (OpenSSL) | Key Exchange | Encryption | Bits
ECDHE-RSA-AES256-SHA | ECDH 256 | AES | 256
DHE-RSA-AES256-SHA | DH 1024 | AES | 256
DHE-RSA-CAMELLIA256-SHA | DH 1024 | Camellia | 256
AES256-SHA | RSA | AES | 256
CAMELLIA256-SHA | RSA | Camellia | 256
ECDHE-RSA-AES128-SHA | ECDH 256 | AES | 128
DHE-RSA-AES128-SHA | DH 1024 | AES | 128
DHE-RSA-CAMELLIA128-SHA | DH 1024 | DH 1024 | 128
AES128-SHA | RSA | AES | 128
CAMELLIA128-SHA | RSA | Camellia | 128

If the SSL3 protocol is replaced by a more modern and secure protocol, such as the TLS1.2 protocol then the following cipher suites would be available for use:

Cipher Suite Name (OpenSSL) | Key Exchange | Encryption | Bits
ECDHE-RSA-AES256-GCM-SHA384 | ECDH 256 | AESGCM | 256
ECDHE-RSA-AES256-SHA384 | ECDH 256 | AES | 256
ECDHE-RSA-AES256-SHA | ECDH 256 | AES | 256
DHE-RSA-AES256-GCM-SHA384 | DH 1024 | AESGCM | 256
DHE-RSA-AES256-SHA256 | DH 1024 | AES | 256
DHE-RSA-AES256-SHA | DH 1024 | AES | 256
DHE-RSA-CAMELLIA256-SHA | DH 1024 | Camellia | 256
AES256-GCM-SHA384 | RSA | AESGCM | 256
AES256-SHA256 | RSA | AES | 256
AES256-SHA | RSA | AES | 256
CAMELLIA256-SHA | RSA | Camellia | 256
ECDHE-RSA-AES128-GCM-SHA256 | ECDH 256 | AESGCM | 128
ECDHE-RSA-AES128-SHA256 | ECDH 256 | AES | 128
ECDHE-RSA-AES128-SHA | ECDH 256 | AES | 128
DHE-RSA-AES128-GCM-SHA256 | DH 1024 | AESGCM | 128
DHE-RSA-AES128-SHA256 | DH 1024 | AES | 128
DHE-RSA-AES128-SHA | DH 1024 | AES | 128
DHE-RSA-CAMELLIA128-SHA | DH 1024 | Camellia | 128
AES128-GCM-SHA256 | RSA | AESGCM | 128
AES128-SHA256 | RSA | AES | 128
AES128-SHA | RSA | AES | 128
CAMELLIA128-SHA | RSA | Camellia | 128
Note: The relevant protocol cipher list definitions can be found in the IETF RFC covering each protocol.

Enterprise Server now uses OpenSSL 3.0. With OpenSSL 3.0, TLS protocol versions older than 1.2 are not available unless the security level is set to 0 by specifying @SECLEVEL=0 in the cipher-suite list..

Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Dual Cryptographic Identities on a Single Network Endpoint

Enterprise Developer supports the concurrent use of Elliptic Curve Cryptography (ECC) and RSA public key cryptography on a single listener endpoint.

This is achieved by specifying two identity certificates, two private key files, and two corresponding passwords for those key files to a single network endpoint definition. The use of certificate file passwords is also supported along with supplying one or both sets of intermediate Certificate Authority (CA) certificate chains.
Note: Only one password per certificate file is permitted. Passwords are rarely used for certificate files.

When specifying dual cryptographic support the order of the certificate, key, and password files is important. You must maintain the order of the configuration elements as follows:

Configuration Element | Syntax
Certificate File | [certfile1];[certfile2]
Certificate Password | [certfilepassword1];;;;;[certfilepassword2]
Key File | [keyfile1];[keyfile2]
Key Password | [keypassword1];;;;[keypassword2]

Where files and paths are listed a single semicolon ";" is used as a delimiter.

When required, different key file passwords must be supplied in the same order as the files that they are used to unlock:

[Password 1][delimiter character sequence][Password 2]

When listing multiple key file passwords the delimiter used must be four consecutive semicolons ";;;;".

The only exception is when the same password is used for both files. In this case, the password can be configured once but is used for both files.

If only one of the two key files has a password, only the single password should be configured. It will be used for the appropriate file.

Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Security Levels

OpenSSL supports the concept of security levels to specify groups of cipher suites and key strength behavior.

To check the different security levels on your system and the ciphers associated with them, at the command prompt, type:

openssl ciphers -s -v ALL;@SECLEVEL=<n>

Where:

<n>
Can be 0 through 5.

Security increases with the security level. Items such as MD5 signatures and other weak items such as broken cipher suites and low security keys will be rejected at higher security levels.

Most new products default to security level 1, including but not limited to recent updates of Java, Chrome, and Firefox.

The default TLS security level starting with release 6.0 is 1. When using the default TLS security options, some very old clients that are restricted to the use of short RSA keys will no longer be able to connect. To preserve the behavior of such clients, you can change the security level to 0. This, however, is a deprecated behavior is only available for backward compatibility.

If you are setting your own cipher suite collections then they will inherit the OpenSSL 3.0 security level 1 behavior unless you modify their cipher suite collection to enforce a security level of 0. You can do this by prefixing @SECLEVEL=0 to the cipher suite collection.

Note: The default Security Level will be increased to 2 (@SECLEVEL=2) in the 10 release of Enterprise Developer .

With OpenSSL 3.0, security level 1 disables SSL and TLS versions prior to TLS 1.2, and will also prevent connections from TLS 1.2 clients which do not send the signature algorithms extension. Set security level 0 (@SECLEVEL=0) to permit interoperability with older TLS versions and clients.

Example Security Level 0

@SECLEVEL=0 kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM !3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP

Example Security Level 1

@SECLEVEL=1 kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM !3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
This matches the default configuration.
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Middlebox Compatibility with TLS v1.3

Connections between a server and client that both support TLS v1.3 can fail if other network infrastructure called middleboxes are not compatible with the protocol and prevent the connection from occurring.

Examples of middleboxes that can cause this problem include network routers and network switches with ISO Level 2/3 routing functionality. They typically recognise TLS v1.3 exchanges as corrupted packets of earlier versions of TLS protocols and discard them.

To work around this issue, extra Change Cipher Spec (CCS) messages can be sent by TLS v1.3 exchanges to make them look like TLS v1.2. These messages are not required to support TLS v1.3 content exchanges and are an inefficient use of both processing time and network traffic capacity.

The workaround is in place for all default installations to provide the widest network compatibility. If your network infrastructure is of a sufficient standard that does not require the extra CCS messages then you can turn them off to reduce traffic and time during connections.

To avoid sending the unnecessary CCS packets during negotiation exchanges, Micro Focus provides the ability to toggle the use of an application configuration option.

Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Using Elliptic Curve Cryptography

You can control both the priority ordering and range of Elliptic Curves used to negotiate with connecting peers when establishing connections using Elliptic Curve Diffie-Hellman Exchange (ECDHE) or Elliptic Curve Diffie-Hellman (ECDH) cipher suites.

Note: In the 5.0 release, the client selects a group of supported key exchange cipher groups that are used for a Diffie-Hellman key exchange. In previous products this collection used to be referred to as the ECC Curves List.
Important: If you are using any identity or Certificate Authority (CA) certificate that contains an ECC public key. The Key Exchange Cipher Groups used for that key must be specified in the Key Exchange Cipher Groups field in a listener's SSL options (I601) or the MF Directory Server tab (e041).

If the key's key exchange cipher group is not present, no Elliptic Curve Digital Signature Algorithm (ECDSA) cipher suite connections can be established. Any certificate bearing an unconfigured or misconfigured key exchange cipher group is treated as untrusted because its key exchange cipher group is unknown to the system.

To maximize performance, Micro Focus recommends that servers are configured to support at least two groups. Clients will use one of those two groups for its initial key sharing exchange. In a dual certificate configuration and if the connecting client is not configured for ECDSA only, then the RSA identity certificate and any issuing CA chain might still establish a listening endpoint using the alternative certificate and RSA key. In these circumstances ECDHE-RSA or ECDH-RSA cipher suites are used.

When listing key exchange cipher groups, the priority order is read from left to right with the highest priority on the left. Any combination of spaces, commas, and semicolons can be used as separators for key exchange cipher group. By default, the following key exchange cipher groups are used:

secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1

You can specify your preferred key exchange cipher groups in the Key Exchange Cipher Groups field. If key exchange cipher group curves are duplicated in the list, the first example encountered sets its priority position. All subsequent duplicates are ignored. For example, secp521r1 is the highest priority key exchange cipher group. While secp256k1 is the fourth highest priority curve despite also being found at position ten in the list:

secp521r1;secp384r1;prime256v1,secp256k1,secp224r1;secp224k1;secp521r1;secp384r1;prime256v1;secp256k1;secp224r1;secp224k1;prime192v1

Any specified curve collection replaces the default collection. If no configuration is specified, the default Key Exchange Cipher Groups is the Key Exchange Cipher Groups listed above. The priority order is determined by the cryptographic service provider.

Note: The default collection of elliptic curves is suitable for most users.
Micro Focus recommends you use the following supported ECC Prime Curves:
Note: Only ECC Prime Curves are supported.
  • X25519 (TLS v1.3 only)
  • X448 (TLS v1.3 only
  • brainpoolP512r1
  • brainpoolP384r1
  • brainpoolP256r1
  • secp521r1
  • secp384r1
  • secp256r1
  • secp256k1
  • secp224r1
  • secp224k1
  • secp192r1
Note: secp256r1 is synonymous and interchangeable with prime256v1. Also, secp192r1 is synonymous and interchangeable with prime192v1.

Micro Focus recommends placing X25519 and X448 as the highest priority key exchange groups in your list if you are using TLS v1.3.

To optimize the key exchange cipher groups to have the highest level of security while providing the greatest level of compatibility with clients, Micro Focus recommends you specify the following Key Exchange Cipher Groups:

secp521r1;brainpoolP512r1;brainpoolP384r1;brainpoolP256r1;secp384r1;prime256v1;secp256k1;secp224k1;secp224r1;prime192v1

Unlike the TLS1.3 Cipher Suites field which is unique to TLS1.3. The Key Exchange Cipher Groups that are specified also control the groups for TLS v1.2 and earlier.

Micro Focus recommends you avoid using the following key exchange cipher groups which are now considered insecure:

  • secp192k1
  • secp160r2
  • secp160r1
  • secp160k1
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Using Diffie-Hellman Cryptography

You can control the minimum size in bits of the modulus length of the Diffie-Hellman (DH) group that is used to negotiate with connecting peers when using DH cipher suites.

You can specify modulus sizes of 512, 1024, 2048 and 4096 bits.

The default modulus group size is 2048 bits. If you need to work with peers that only support a smaller key size, or you wish to set support to 4096 bits, then you can specify a new value for the DH minimum group size field in either a listener's SSL options (I601) or the MF Directory Server tab.

Note: If you specify a minimum group size that does not match one of the permitted values listed above, then the value is rounded to the next highest in the list. For example, 1034 is rounded up to 2048 bits.
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Certificate Files

The certificate file can contain one or more locations of server or client identity certificates and potentially a collection of intermediate Certificate Authority (CA) certificates supporting the identity certificates.

The file takes the following format:

[Absolute or relative file path][Delimiter character][Absolute or relative file path]

Currently the semicolon (;) is the only supported delimiter. Supported certificate file format types include DER, CER, PKCS #7, PKCS #12, and PEM. File extensions do not have to match the file format type in order for them to be recognised and work correctly. Micro Focus recommends that the file extensions match the appropriate certificate type.

PKCS #12 files might contain an identity certificate and possibly an optional CA root certificate chain collection plus an optional private key.

Multiple certificates can be contained within one file when using PEM file format content. Individual PEM files can be concatenated together to form a multiple certificate PEM file.

In any one PEM ID file:

  • There must be at least one ID certificate.
  • The PEM ID file can have two ID certificates, if it does then their public keys must be of different types (one RSA and the other EC)
    Note: Three or more ID certificates results in an error. Two ID certificates with the same public key type results in an error.
  • There can be a collection of intermediate CA chain certificates. If present these could be in support of either of the two possible ID certificates.
    Note: Any additional intermediate CA or CA root certificates are ignored.
  • There must not be any private keys.

PEM files containing multiple certificates must include at least one identification certificate. It may also contain an optional supporting collection of intermediate CA chain of certificates for that identification certificate.

In a dual identity installation one PEM file may also contain both identity certificates. In addition, it may contain both or neither of the optional Intermediate CA chains of certificates. In this configuration the two supporting key files must be specified as two files. The order of the two certificates within the one certificate file does not have to match the order of the two key files. The key file configuration order still has to match that of the keyfile's passwords.

Parent topic: Specifying a Server Protocol and Cipher Suite Preference


PKCS #12 File

The PKCS #12 file format is supported. Common extensions are .p12 and .pfx.

PKCS #12 format files may contain the following certificates:

  • An x509 identity certificate.
  • A CA root chain collection of certificates.
  • A private key which is paired with a public key in the identity certificate.

Any or all of these certificate types can be enclosed in a PKCS #12 file.

Micro Focus recommends that your PKCS #12 file is password protected.

The most common content combination for a PKCS #12 file is for it to contain an identity certificate and its private key.

When using a combined PKCS #12 file containing an identity certificate and a private key the file name must be presented as a certificate file and the password as the certificate file password. The matching key file and key file password entries in the configuration can be left blank.

PKCS #12 files containing only a private key or an identity certificate can be treated like any other certificate file or key file.

Restrictions

The content of the PKCS #12 file has the following restrictions:

  • A PKCS #12 file cannot contain only a CA root chain certificate.
  • A PKCS #12 file can only contain one identity certificate.
Parent topic: Specifying a Server Protocol and Cipher Suite Preference


Configuring the MF Directory Server to use TLS Protocols and Cipher Suites

To configure an MF Directory Server to force the use of a cipher suite list:

  1. Open the Enterprise Server Administration page.
  2. In the left pane under Configure, click Security.
  3. Click the MF Directory Server tab.
  4. Check Restrict administration access.
  5. In the Authenticated Client Sessions group, click Use encrypted connections.
  6. In the Secure Ports field, type a port number.
    • Check Use custom server ID certificates.

      This enables you to specify a certificate and keyfile.

  7. By default, the TLS honor server cipher list is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
    Note: If the TLS protocols and Cipher suites list are not specified then it uses the default. The TLS protocols field now supports TLS1.3. See Specifying a Server Protocol and Cipher Suite Preference for more information.
  8. In the TLS protocols field, type the list of protocols in order of priority, for example:
    -ALL+SSL3+TLS1
  9. In the Cipher suites field, type the list of cipher suites in order of priority, for example:
    HIGH:!SSLv2:!RC4:!aNULL@STRENGTH
  10. Click OK.

See MF Directory Server Security for more information on configuration options.

Parent topic: Specifying a Server Protocol and Cipher Suite Preference
Related reference
Specifying a Server Protocol and Cipher Suite Preference
MF Directory Server Security


Configuring a Listener to use TLS Protocols and Cipher Suites

To configure a listener to force the use of a cipher suite list:

  1. Open the Enterprise Server Administration page.
  2. Click Edit next to the region you want to configure a listener for.
  3. Click the Listeners tab.
  4. Click Edit on the row containing the listener you want to configure.
  5. In the Endpoint options group, check Secure Sockets Layer.
  6. In the Certificate field, type the full path to the certificate.
  7. In the Keyfile field, type the full path to the keyfile.
  8. Click Options.

    This opens the SSL Options page.

  9. By default, the TLS honor server cipher list is checked. This forces clients to use the protocols and cipher suites specified in order of their priority.
    Note: If the TLS protocols and Cipher suites list are not specified then it uses the default. The TLS protocols field now supports TLS1.3. See Configuring a TLS Protocols List and Configuring a Cipher Suites List for more information.
  10. In the TLS protocols field, type the list of protocols in order of priority, for example:
    -ALL+SSL3+TLS1
  11. In the Cipher suites field, type the list of cipher suites in order of priority, for example:
    HIGH:!SSLv2:!RC4:!aNULL@STRENGTH
  12. Click OK.

See SSL Options for more information on configuration options.

Parent topic: Specifying a Server Protocol and Cipher Suite Preference


HTTP Strict Transport Security

HTTP Strict Transport Security, or HSTS, is a standard mechanism defined by RFC 6797 to enforce HTTPS (secure communications) rather than plaintext HTTP.

Web browsers and other clients that support HSTS maintain a list of servers that enable it, and refuse to connect to those servers using plain HTTP. Clients learn which servers have enabled HSTS using a 'preload list' or by receiving an HTTP response from a server that contains the Strict-Transport-Security header.

HSTS is primarily useful for the conventional web-browsing use case, where servers support both HTTP and HTTPS, and clients might accidentally connect by HTTP, or be tricked into doing so. For Enterprise Test Server, HSTS generally serves no purpose, because very few organizations will configure an Enterprise Test Server component with both plaintext HTTP and TLS-enabled HTTPS listeners for the same purpose. Thus, there is no danger of clients connecting by plaintext HTTP if TLS has been enabled, because plaintext HTTP won't be available.

Also, HSTS does not function well in use cases other than conventional web browsing. In particular, it does not adequately address use cases where ports other than the standard 80 (for plaintext HTTP) and 443 (for HTTPS) are used. It also can cause problems when there is a mix of HSTS-enabled and non-HTTPS web servers within a domain, since the HSTS setting may cause browsers to refuse to connect to the non-HSTS servers.

For these reasons, Micro Focus does not recommend the use of HSTS with Enterprise Test Server.

However, some organizations have blanket rules regarding enabling HSTS on all web servers, or need to enable HSTS in order to satisfy security auditors.

Enterprise Test Server 5.0 (Patch Update 12 or later), 6.0 (Patch Update 2 or later), and subsequent releases have the following support for HSTS:

  • Enterprise Server Common Web Administration (ESCWA): Enables HSTS automatically if it is TLS-enabled.
  • Enterprise Server Monitor and Control (ESMAC) and COBOL Web Services: These are both served by listeners using the 'Web Services and J2EE' conversation type. (If your Enterprise Test Server region uses the 'SOAP and J2EE (legacy)' conversation type, change it to 'Web Services and J2EE'.) HSTS can be enabled for these listeners by adding the following to the listener's configuration text area:
    [Response Headers]
Strict-Transport-Security=max-age=31536000; includeSubDomains

    See RFC 6797 for more information on the value of the Strict-Transport-Security header.

  • COBOL Service Deployment: This function is provided by the 'Web' conversation type, which does not currently support HSTS. Micro Focus strongly recommends not enabling service deployment for production servers. See Security Considerations for Service Interface Deployment.
  • Micro Focus Enterprise Server Administration (MFDS): This component currently does not support HSTS. Micro Focus recommends disabling the MFDS web user interface or restricting it to local connections (currently the default), and using ESCWA instead.
Parent topic: Securing Communications


Secure Communications (SSL) Legal Information

OpenSSL Acknowledgment

The SSL support provided by the Enterprise Server 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. See http://www.openssl.org for more information.

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 provided these in the SSL support included with this COBOL system.

The use of some key lengths might be legally restricted in some countries, because longer key lengths give stronger protection, and therefore may be considered of military value.

Important: Micro Focus recommends that 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


Multi-Factor Authentication

Multi-factor authentication allows users to sign on to Enterprise Server CICS without entering a username and password. A secure user identifier, such as a certificate, is mapped to a username and is used to generate a passtoken. Users may use smartcards, biometrics, or other authentication systems to identify themselves to the system. The username and passtoken can then be used to log on to CICS in an automated way.

There are two main solutions for multi-factor authentication:

  • Express Logon Feature (ELF)
  • Automated Sign-On for Mainframe

The Express Logon Feature is supported by most TN3270 emulators. It uses an SSL/TLS connection from the client to the TN3270 server which provides a user's certificate for identification. Placeholder username and password tokens are used on the CICS logon screen. The server reads the client certificate used in the SSL connection, then examines its certificate store to determine if there is a username mapped to that certificate. If there is it can generate a passtoken and replace the username and password tokens with the actual username and passtoken, allowing the client to log on.

Automated Sign-On for Mainframe is an alternative logon mechanism, where the server assumes that the user's credentials have already been authenticated, for example, by software such as Micro Focus Host Access Management and Security Server. This verification can take several forms, the details of which are product-specific. Products that can be used for Automated Sign-On for Mainframe map a user's certificate, or other identifying credentials, to a CICS username and then generate a passtoken. The ID and passtoken can then be used to log on. Enterprise Server processes the username and passtoken as it would a username and password entered by a user.

Both of these logon solutions rely on the Digital Certificate Access Server (DCAS). The DCAS service performs the certificate mapping lookup required by ELF and the passtoken generation used for both ELF and Automated Sign-On for Mainframe. The certificate mapping can be administered with the command-line utility cascertreg.

See DCAS Security for important information regarding DCAS security considerations and features.

  • Configuring a region for Express Logon Feature
  • Configuring a region for Automated Sign-On for Mainframe
Parent topic: Enterprise Server Security
Related concepts
ESF Passtokens
DCAS Security
User Certificate Registration for CICS Web Interface Servers and DCAS
Related information
Features Added in Enterprise Test Server 2.3 Update 2


Configuring a region for Express Logon Feature

This topic guides you through the steps required to configure an enterprise server region with Mainframe Subsystem Support to enable ELF functionality. The region must be secured with a Security Manager which allows you to generate and sign on with passtokens. See ESF Passtokens for more information.

As of Enterprise Server versions 5.0 Patch Update 9 and 6.0, a DCAS listener is no longer required for ELF. You can either add a DCAS listener (or use an existing one), or configure your TN3270 listener to use DCAS in "internal" mode. A DCAS listener is useful if you need it for other purposes, such as Automated Sign-On for Mainframe. Otherwise, Micro Focus recommends using internal DCAS to avoid any possible additional security exposure from a DCAS listener.

To add a new DCAS listener to the region:

  1. Start the Enterprise Server Administration Home page, and then click Edit for the region you want to create the listener for.
  2. Click the Listener tab, and then click Add.
  3. In the Support Conversation Type group, click Custom.
  4. In the field next to the Custom option, type dcas.
  5. Configure the listener as required. DCAS listeners must be configured for SSL communication. See DCAS conversation type and Secure Communications (SSL) for more information.
    Note: Micro Focus recommends you configure both the DCAS and TN3270 listeners with the same SSL server certificate and key. Failure to do so might result in users being able to incorrectly acquire or fail to acquire passtokens from DCAS.

To use internal DCAS:

  1. Start the Enterprise Server Administration Home page, and then click Edit for the region you want to create the listener for.
  2. Click the Listener tab, and then click Edit for your TN3270 listener.
  3. In the TN3270 listener's configuration text area, add the following:
    [DCAS]
internal=yes

[DCAS Certificate]
certificate directory=path-to-certificate-registration-directory
    where path-to-certificate-registration-directory is the full path to the directory where you will keep your certificate registrations. See Understanding certificate registration and cascertreg for more information.
  4. You might want to configure additional parameters for internal DCAS in the TN3270 listener configuration areas using the [DCAS Operation] and [DCAS Tracing] sections. See DCAS conversation type for more information.

To complete ELF configuration:

  1. Use the cascertreg command line utility to map a user certificate to a user ID. See cascertreg for more information.
    Note: Regions that use certificate mapping for CICS Web Interface can use the same certificate mappings for DCAS.
  2. You might need to perform additional configuration for an existing TN3270 listener, either to configure SSL or explicitly reference a DCAS connector. Depending on how your users' certificates are created, you might need to configure the Maximum Chain Length and Match Client Hostname settings. See To set certificate validation options and TN3270 conversation type for more information.

Once these steps are complete, users need to configure their clients to allow ELF negotiation, also referred to as Certificate Express Logon (CEL), and to connect using their certificate. Once this is done, users can to log on to the server using their certificate as identification. The logon process itself is often performed using a macro that inserts the two well-known placeholder strings into the logon fields, which the server sees and replaces with the mapped user ID and passtoken. These strings are:

")USR.ID("
For the user ID.
")PSS.WD("
For the password.

See DCAS Security for additional information regarding DCAS security considerations and features.

Parent topic: Multi-Factor Authentication
Related concepts
DCAS Security
DCAS conversation type
ESF Passtokens
Understanding User Certificate Registration
TN3270 conversation type
Related reference
cascertreg
cascertreg
DCAS conversation type
ESF Passtokens
TN3270 conversation type


Configuring a region for Automated Sign-On for Mainframe

This topic guides you through the necessary steps to configure an enterprise server region with Mainframe Subsystem Support to enable Automated Sign-On for Mainframe. It is assumed that you are using a separate system to authenticate your users, for example, Host Access Management and Security Server. That system must also request a passtoken from DCAS.

You must add a new DCAS listener to the region:

  1. Start the Enterprise Server Administration home page, and then click Edit for the region you want to create the listener for.
  2. Click the Listener tab, and then click Add.
  3. In the Support Conversation Type group, click Custom.
  4. In the field next to the Custom option, type dcas.
  5. Configure the listener as required. DCAS listeners must be configured for SSL communication. See DCAS conversation type and Secure Communications (SSL) for more information.
    Note: Micro Focus recommends you configure both the DCAS and TN3270 listeners with the same SSL server certificate and key. Failure to do so might result in users being able to incorrectly acquire or fail to acquire passtokens from DCAS.
  6. You might need to perform additional configuration for an existing TN3270 listener regarding SSL settings. Depending on how your users' certificates are created, it might be necessary to configure the Maximum Chain Length and Match Client Hostname settings. See To set certificate validation options and TN3270 conversation type for more information.

Once these steps are completed users can log in using the username and passtoken returned from the management software in use. This process is usually automated by a macro which automatically populates the username and password fields with the values returned from the authentication software.

See DCAS Security for additional information regarding DCAS security considerations and options.

Parent topic: Multi-Factor Authentication
Related concepts
DCAS Security
Related reference
DCAS conversation type
TN3270 conversation type


Vault Facility

The vault facility enables certain Enterprise Server components to store sensitive data, such as passwords, in a form of storage defined as a vault, accessible via a configurable vault provider.

A vault is a form of storage that provides more protection than typical file storage. A vault might be implemented using encryption, an operating system feature, a network service, specialized hardware, or some other mechanism.

Note: Micro Focus strongly recommends that users restrict access to the Vault Facility. See Restricting Access to the Vault Facility for more information.
  • Vault Providers
    Defines the terms vault and vault provider.
  • The mfsecretsadmin Utility
    Use the mfsecretsadmin command line utility to setup, administer, and perform vault migration tasks.
  • Restricting Access to the Vault Facility
    Micro Focus strongly recommends that you configure additional security to restrict access to your vault.
Parent topic: Enterprise Server Security
Related concepts
Using the Vault Facility with the XA Open String
Restricting Access to the Vault Facility
Related information
MFDBFH_VAULT


Vault Providers

A vault provider is the software module used by the Vault Facility to interact with a particular kind of vault. The mfsecretsaes vault provider included with Enterprise Developer supports both Windows and UNIX platforms. See The mfsecretsaes Vault Provider for more information.

Note: Micro Focus does not currently provide support for customer-written providers.

Enterprise Server comes configured with a default vault that uses the mfsecretsaes vault provider. Some components, such as Enterprise Server Common Web Administration (ESCWA), store secrets in this vault automatically. By editing the secrets.cfg file, you can modify configuration parameters for these components, and configure some additional components to use the vault.

Attention: Before changing the values for the password or salt parameters, consider the following:
  • The installation process automatically creates values for mfsecretsaes that enable valid encryption.
  • After storing information in the vault, if the password or salt values are then changed, secrets stored before the change become inaccessible.
  • Because some components store secrets in the vault automatically, be sure to create a backup of the secrets.cfg file before making any changes. When doing this, be sure that your secrets are backed up in securely, for example, in a file on an encrypted USB flash drive, to ensure recovery.
  • Micro Focus strongly recommends that you secure and control access to the secrets.cfg file using your operating system file permissions, and that you monitor its access. See Restricting Access to the Vault Facility for more information.

By default, the secrets.cfg file is located in the %PROGRAMDATA%\Micro Focus\Enterprise Server\mfsecrets directory.

Use the comments contained in the secrets.cfg file to guide your changes.

The following is a sample secrets.cfg file for the default mfsecretsaes vault provider:

# This file controls the operation of applications which access the
# vault interface for storing "secret" values such as passwords and
# other sensitive information. It is strongly recommended that
# appropriate OS file permissions are set and that its contents are
# monitored for any changes.

# NOTE: if configuration values are changed, then "secrets" that
# were previously accessible may become inaccessible. It is strongly
# recommended that appropriate change management is used, and backups
# are made before changes are applied.

# NOTE: A vault is a logical configuration set which determines the
# location and method used to store secrets. The "provider" is the
# software module which implements access to the vault.

# A default vault can be set in the "global" configuration.
# Unless a particular applications/software component requires or
# allows use of a specific named vault, the "default" vault
# will be used.
[global]
default vault=aesvault
# To enable audit using mfaudit configure audit enabled to TRUE or YES
# For details on configuring mfaudit consult product documentation.
audit enabled=FALSE

# Specify vaults and their configuration below here.

# Individual "vaults" will have individual configuration
# requirements. The key=value pairs beneath the logical [vault] label
# will be used by the provider module to control its behavior.
[aesvault]

# This should be the name of the provider so/dll. No file extension
# required.
provider name=mfsecretsaes

# The "location" key specifies the physical or logical (depending on
# provider type) directory where secrets will be stored. For the
# "mfsecretsaes" provider, the target directory needs to pre-exist and
# have appropriate file permissions to allow application processes to
# access the location.
#
# The product installer will initially set a product-specific
# file location by default.
location=<location>

# Different vault types may also support different sub-modes of operation.
mode=AES256-CBC

# For AES256-CBC a plain text password is used to generate a key and iv.
# By default, the product installer will generate a value.
password=<password>

# Salt is an optional base64 value. By default, the product installer will
# generate a value.
salt=<salt>
  • The mfsecretsaes Vault Provider
    Describes the mfsecretsaes vault provider.
  • The mfsecretsmscpd Vault Provider
    Describes the mfsecretsmscpd optional vault provider.
  • The mfsecretshashicorp Vault Provider
    Describes the mfsecretshashicorp optional vault provider.
  • The mfsecretsaws Vault Provider
    Describes the mfsecretsaws optional vault provider.
Parent topic: Vault Facility
Related concepts
The mfsecretsaes Vault Provider
The mfsecretsmscpd Vault Provider
The mfsecretshashicorp Vault Provider


The mfsecretsaes Vault Provider

The mfsecretsaes vault provider implements a simple vault that keeps data encrypted in a file. The encryption cipher is AES256-CBC, and the password and salt values are supplied in the secrets.cfg configuration file.

See Vault Providers for more information.

Parent topic: Vault Providers
Related concepts
Vault Providers


The mfsecretsmscpd Vault Provider

The mfsecretsmscpd vault provider is an optional provider that keeps data encrypted in a file using Microsoft Windows encryption functionality. To decrypt an encrypted file, the user must:
  • Log onto the same computer where the original encryption was done, or on another machine on the network only when the user has a roaming profile that allows decryption of data from another computer on the network
  • Log on using the same credentials as were used when the file was originally encrypted

To configure the mfsecretsmscpd vault, edit the secrets.cfg file to include values for the provider name, location, and optional base64-encoded entropy.

See Vault Providers for more information.

Parent topic: Vault Providers
Related concepts
Vault Providers


The mfsecretshashicorp Vault Provider

The mfsecretshashicorp vault provider is an optional provider that keeps data encrypted within a preconfigured HashiCorp Vault.

  • Restrictions and Limitations
  • Configuration
  • Authentication Types
  • Token Management
  • Optional TLS Settings
  • Cipher Lists and Suites
Parent topic: Vault Providers
Related concepts
Vault Providers


Restrictions and Limitations

The following restrictions and limitations exist when using the mfsecretshashicorp vault provider:

  • The vault must be TLS enabled. However, client certificates are optional.
  • The kv2 secrets engine must not be used as a file storage system on Windows when the vault is being used for ESCWA or MFDS. The kv2 secrets engine will encrypt the path of the secret, increasing its length. The increased length of the secrets path will result in Windows maximum path length being exceeded. Micro Focus recommends that you use an alternative file storage system on your HashiCorp server, or use the kv1 secrets engine which does not encrypt paths.
Parent topic: The mfsecretshashicorp Vault Provider


Configuration

To configure the mfsecretshashicorp vault, edit the secrets.cfg file to include values for the provider name, TLS connection details, authorization credentials, and details of the secrets engine.

The following is an example configuration file for the mfsecretshashicorp vault provider. See Vault Providers for more information on the structure of the config file:

[global]
default provider=hashicorpvault

[hashicorpvault]
provider name=mfsecretshashicorp

### Connection Details ###
# The location of the Hashicorp server to connect to
host=127.0.0.0
port=8200
# The certificate authority to validate the server's certificates against
# This is required as MfSecretsApi only supports TLS connection
ca_path=C:/certs/ca_collection.pem

### Optional TLS Client Verification ###
client_cert=C:/certs/client_cert.pem
client_key=C:/certs/client_key.pem
client_password=key_password
# The format that the certificate and key are given in
# Supported formats are PEM and DER. Defaults to PEM if nothing is given
client_cert_type=PEM
client_key_type=PEM

### Optional Connection Settings ###
# The timeout in seconds for a single attempt at *connecting* to a Hashicorp server via HTTPS
# Default: 20 seconds
# Negative values will become the maximum possible timeout time
# Zero values will become the default value
# If this is not set, the default value is used
connection_timeout_seconds=20

# The maximum number of *retries* to attempt
# Will stop retrying when this or max_total_connection_time_seconds is exceeded
# Default: 1
# Negative values will retry infinitely
# If this is not set, the default value is used
max_retry_count=1

# The maximum length of time in seconds to attempt to resolve a HTTPS transaction (retries and all)
# Will stop retrying when this or max_retry_count is exceeded
# Default: 60 seconds
# Negative values indicate no limit
# If this is not set, the default value is used
max_total_connection_time_seconds=60

# Turn on verbose transport layer debugging (optional)
# WARNING: This will print out HTTP headers and bodies which could contain sensitive data such as passwords
# Note: this should not be turned on unless asked to do so by the Micro Focus support team
transport_debugging=true

### Hashicorp server settings ###
# These options must correspond with the options set up on the Hashicorp server being connected to

# Supported secrets engines: 'kv1', and 'kv2'
secrets_engine_type=kv2
# The location the secrets engine of the desired type has been enabled on the Hashicorp server
secrets_engine_path=kv2

# The desired method of authentication. Supported: 'approle', 'tls', and 'userpass'
auth_type=approle
# The location the authenticator of the desired type has been enabled on the Hashicorp server
auth_path=approle

### Authentication Credentials ###
# These will change based on auth_type, see each auth_type's docs for what is required
role_id=db02de05-fa39-4855-059b-67221c5c2f63
secret_id=6a174c20-f6de-a53c-74d2-6018fcceff64
Parent topic: The mfsecretshashicorp Vault Provider


Authentication Types

The mfsecretshashicorp vault provider offers three authentication methods with the HashiCorp vault. In the configuration file, specify the authentication method to use by assigning a value to the auth_type variable. You can use one of the following values methods:

approle
The AppRole authentication method enables you to authenticate with Vault-defined roles.
tls
The TLS authentication method enables authentication using SSL/TLS client certificates which can be signed either by a CA or self-signed.
userpass
The userpass authentication method enables you to authenticate using a username and password combination.
Note: The auth_path configuration item, required for all authentication types, specifies where in the HashiCorp Vault the authenticator has been enabled. This is typically the same as the authenticator type.
  • AppRole (approle)
  • TLS Certificates (tls)
  • Username & Password (userpass)
  • Required Permissions
Parent topic: The mfsecretshashicorp Vault Provider


AppRole (approle)

If you have specified the AppRole authentication method in the configuration file, then you should also specify the role_id and secret_id configuration items.

For example, in the configuration file:

auth_type=approle
auth_path=approle
role_id=db02de05-fa39-4855-059b-67221c5c2f63
secret_id=6a174c20-f6de-a53c-74d2-6018fcceff64
Parent topic: Authentication Types


TLS Certificates (tls)

If you have specified the TLS authentication method in the configuration file, then you should also specify the following configuration items:

  • client_cert
  • client_key
  • client_password
  • auth_type
  • auth_path
  • name

For example, in the configuration file:

client_cert=C:/certs/client_cert.pem
client_key=C:/certs/client_key.pem
client_password=key_password

auth_type=tls
auth_path=cert
name=name_of_certificate
Parent topic: Authentication Types


Username & Password (userpass)

If you have specified the username & password authentication method in the configuration file, then you should also specify the username and password configuration items.

For example, in the configuration file:

auth_type=userpass
auth_path=userpass
username=username
password=password
Parent topic: Authentication Types


Required Permissions

In order for mfsecretshashicorp vault provider to function correctly, it requires a token that has create, read, update, delete, and list permissions for the given secrets engine path. Micro Focus recommends that you give the token the following policy as a minimum:

# Where `secrets/engine/path` is the same as `secrets_engine_path` provided in the config file
path "secrets/engine/path/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
}
Parent topic: Authentication Types


Token Management

The first request made to the vault will be an authorisation request using the credentials given in the secrets.cfg file. The token retrieved when authenticating will be stored in memory and used to make requests to the vault.

If the token expires, mfsecretshashicorp will try to re-authenticate using the same credentials as before.

At the end of the transaction, mfsecretshashicorp attempts to revoke the token using the token itself. The transaction will be successful even if the token is unable to be revoked, providing only a warning message in the log. Micro Focus does not recommended that you give a token permissions to revoke itself. Micro Focus recommends that authentication is set up on the HashiCorp server to provide tokens with a short Time To Live (TTL).

Parent topic: The mfsecretshashicorp Vault Provider


Optional TLS Settings

The following are optional TLS settings:

verify_host=ENABLE|DISABLE
When enabled, verify that the certificate provided by the server has a Common Name (CN) field or a Subject Alternate Name (SAN) field which matches the hostname in the URL that the mfsecretshashicorp vault provider is connecting to.

The default value is ENABLE.

For example, in the configuration file:

verify_host=ENABLE
verify_peer=ENABLE|DISABLE
When enabled, the mfsecretshashicorp vault provider will verify the authenticity of the server's certificate against the certification authority (CA) certificates supplied to the ca_path config option.

The default value is ENABLE.

For example, in the configuration file:

verify_peer=ENABLE
tls_protocol=TLSv1_0|TLSv1_1|TLSv1_2|TLSv1_3
Specifies which TLS protocols the mfsecretshashicorp vault provider can use.

where:

TLSv1_0
TLS v1.0 or later. This is the default value.
TLSv1_1
TLS v1.1
TLSv1_2
TLS v1.2
TLSv1_3
TLS v1.3

For example, in the configuration file:

tls_protocol=TLSv1_3
Parent topic: The mfsecretshashicorp Vault Provider


Cipher Lists and Suites

The cipher_list and tls13_cipher_suites options allow you to specify the list of ciphers to be used. For TLS 1.3 ciphers suites, the tls13_cipher_suites option should be used, otherwise the cipher_list option should be used.

Value: one or more cipher suites separated by colons (see possible cipher suites below).

cipher_list example in config file:

cipher_list= AES256-SHA256:AES128-GCM-SHA256:AES256-GCM-SHA384

tls13_cipher_suites example in config file:

tls13_cipher_suites=TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256
  • TLS v1.0 Cipher Suites
  • TLS v1.2 Cipher Suites
  • TLS v1.3 Cipher Suites
Parent topic: The mfsecretshashicorp Vault Provider


TLS v1.0 Cipher Suites

The following TLS v1.0 cipher suites are available for use with the cipher_list option:

  • ECDHE-ECDSA-AES256-SHA
  • ECDHE-RSA-AES256-SHA
  • DHE-RSA-AES256-SHA
  • ECDHE-ECDSA-AES128-SHA
  • ECDHE-RSA-AES128-SHA
  • DHE-RSA-AES128-SHA
  • AES256-SHA AES128-SHA
Parent topic: Cipher Lists and Suites


TLS v1.2 Cipher Suites

The following TLS v1.2 cipher suites are available for use with the cipher_list option:

  • ECDHE-ECDSA-AES256-GCM-SHA384
  • ECDHE-RSA-AES256-GCM-SHA384
  • DHE-RSA-AES256-GCM-SHA384
  • ECDHE-ECDSA-CHACHA20-POLY1305
  • ECDHE-RSA-CHACHA20-POLY1305
  • DHE-RSA-CHACHA20-POLY1305
  • ECDHE-ECDSA-AES128-GCM-SHA256
  • ECDHE-RSA-AES128-GCM-SHA256
  • DHE-RSA-AES128-GCM-SHA256
  • ECDHE-ECDSA-AES256-SHA384
  • ECDHE-RSA-AES256-SHA384
  • DHE-RSA-AES256-SHA256
  • ECDHE-ECDSA-AES128-SHA256
  • ECDHE-RSA-AES128-SHA256
  • DHE-RSA-AES128-SHA256
  • ECDHE-ECDSA-AES256-SHA
  • ECDHE-RSA-AES256-SHA
  • DHE-RSA-AES256-SHA
  • ECDHE-ECDSA-AES128-SHA
  • ECDHE-RSA-AES128-SHA
  • DHE-RSA-AES128-SHA
  • AES256-GCM-SHA384
  • AES128-GCM-SHA256
  • AES256-SHA256
  • AES128-SHA256
  • AES256-SHA
  • AES128-SHA
Parent topic: Cipher Lists and Suites


TLS v1.3 Cipher Suites

The following TLS v1.3 cipher suites are available for use with the tls13_cipher_suites option:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256
Parent topic: Cipher Lists and Suites


The mfsecretsaws Vault Provider

The mfsecretsaws vault provider is an optional provider that keeps data encrypted within a preconfigured Amazon Web Services (AWS) vault.

  • Vault Permissions
  • Configuration
  • Authentication
  • Optional Secrets Polling Settings
  • Optional Settings
Parent topic: Vault Providers


Vault Permissions

When preconfiguring an AWS vault for use with mfsecretsaws, ensure the following permissions are enabled under the access level for the appropriate AWS Secrets Manager:

  • ListSecrets
  • GetSecretValue
  • CreateSecret
  • DeleteSecret
  • DescribeSecret
Parent topic: The mfsecretsaws Vault Provider


Configuration

To configure the mfsecretsaws vault, edit the secrets.cfg file to include values for the provider name, authorization credentials, geographical region endpoint, optional secrets base paths, and secret recovery and polling options.

The following is an example configuration file for the mfsecretsaws vault provider:

[awsvault]

# This should be the name of the provider so/dll. No file extension
# required.
provider name=mfsecretsaws

# The geographical region endpoint
region=us-east-2

# AWS credentials required to authenticate a connection
access_key=
secret_access_key=

# Optional path to store and access all secrets under
secrets_base_path=

# Optional secret recovery window, between 7 and 30 days inclusive
# Recommended: leave as 0 if using mfsecrets with Enterprise Developer
recovery_window=0

# Polling options for deleted secrets polling

# Maximum times to poll a secret waiting to be deleted
maximum_polls_delete=20

# Time in seconds between polls
time_between_polls_delete=3

# Polling options for written secrets polling

# Maximum times to poll a secret waiting to be written
maximum_polls_write=10

#  Time in milliseconds between polls
time_between_polls_write=500

See Vault Providers for more information.

Parent topic: The mfsecretsaws Vault Provider


Authentication

The mfsecretsaws vault provider is authenticated using a credentials key pair containing a key ID and key. Generate a credentials key pair for the AWS vault and specify them in the configuration file. The key pair will take the form of hashes.

A geographical regional endpoint should also be configured. Micro Focus recommends that you specify the region closest to the systems current physical location.

For example:

region=us-east-2
access_key=MY_AWS_ACCESS_KEY
secret_access_key=MY_AWS_ACCESS_KEY_VALUE
Note: By default, mfsecretsaws uses the TLS 1.2 protocol. You cannot specify mfsecretsaws to use other versions of the TLS protocol.
Parent topic: The mfsecretsaws Vault Provider


Optional Secrets Polling Settings

As write secret and delete secret requests are performed asynchronously by the AWS vault, there can be a delay for the requests to be completed. Configuration options are provided to enable or disable secrets polling, maximum number of polls, and time between polls, and for individual write and delete polling. Micro Focus recommends you enable polling by default. However, polling requires additional API calls. Disabling polling might result in subsequent requests failing if they are made in rapid succession.

Note: If a recovery window is configured, no polling will be performed for deleted secrets.

Micro Focus recommends the following values for delete requests:

maximum_polls_delete=20
time_between_polls_delete=3 [measured in seconds]

Micro Focus recommends the following values for write requests:

maximum_polls_write=10
time_between_polls_write=500 [measured in milliseconds]
Note: The time taken to wait for written secrets polling is significantly shorter than for deleted secrets.
Parent topic: The mfsecretsaws Vault Provider


Optional Settings

The following additional configuration options can be specified:

secrets_base_path
The secrets base path specifies the absolute path to where all secrets are read, written, deleted, and listed from. For example:
secrets_base_path=/my/path/
recovery_window
A recovery window can be specified to enable recovery of secrets that have been deleted. Specify a value between 7 and 30 days inclusive to set a recovery window, or specify 0 for no recovery window. Micro Focus recommends you leave the recovery window as 0. You must perform recovery manually from the AWS Web console.
Parent topic: The mfsecretsaws Vault Provider


The mfsecretsadmin Utility

Use the mfsecretsadmin command line utility to setup, administer, and perform vault migration tasks.

Syntax:

To read from the vault:

mfsecretsadmin [options] read <secret name> [outpath]

where:

<secret name>
This is the name of the secret to read.
outpath
This is the path to write the secret to and is optional. This is only available with the -file option.

To write to the vault:

mfsecretsadmin [options] write <secret name> [secret]

where:

<secret name>
This is the name of the secret to write/delete.
secret
This is the value of the secret to be writen and is optional. If this is not specified, then the secret name is deleted.

To list the secrets in the path specified:

mfsecretsadmin [options] list <secret path> [outpath]

where:

<secret path>
This is the path to the secrets to be listed. You can use the * and ? wildcards.
outpath
This is the path to write the list to and is optional. This is only available with the -file option.

To migrate secrets to a new vault destination:

mfsecretsadmin [options] migrate <secret path> <to vault> <to secret path>

where:

<secret path>
This is the path to the secrets that you want to migrate. You can use the * wildcard to migrate all secrets from the specified location.
<to vault>
This is the name of the vault to be migrate to.
<to secret path>
This is the path to the vault you are migrating the secrets to. A * value maintains the secrets path.

To delete a secret:

mfsecretsadmin [options] delete <secret name>

where:

<secret name>
This is the name of the secret to be deleted.

Options:

-vault <vault>
Specifies the name of the source vault. The default vault is used if this is not set.
-file
Specifies if the read or write action is performed to or from a file rather than standard out. secret on write is expected to be a path and outpath on read is expected to be set.
-config <config>
Specifies the full path of the secrets.cfg file. The default config is used if this is not specified.
-targetconfig <config>
Specifies the full path of the secrets.cfg file to migrate to. The default config is used if this is not specified.
-overwrite
Specifies that the write or migrate action will only replaces existing secrets.
-move
Specifies that the secrets are deleted once they have been sucessfuly migrated to the new vault.
-loglevel <level>
Specifies the level of messages output:
1
Information (all messages).
2
Warnings and errors only.
3
Only errors.

Examples

To store a secret to use with the PASS SQL compiler directive option, having a secret name of MFV_MySecretName, and storing the credentials of MyUser as the user ID and a password of MyPassword:

mfsecretsadmin write Microfocus/ODBCECM/MFV_MySecretName MyUser.MyPassword

To store a secret to use with the PASS DB2 compiler directive option, having a secret name of MFV_MySecretName, and storing the credentials of MyUser as the user ID and a password of MyPassword:

mfsecretsadmin write Microfocus/DB2ECM/MFV_MySecretName MyUser.MyPassword
Parent topic: Vault Facility
Related concepts
Using the Vault Facility with the XA Open String
Related information
HACloud Configuration File


Restricting Access to the Vault Facility

Micro Focus strongly recommends that you configure additional security to restrict access to your vault.

Restrict access to the vault files and to the secrets.cfg file, which contains information required to read secrets from the vault. Modifying the filesystem permissions can be used to achieve this.

  1. Create a group named, for example, "Micro Focus ES". Add the Administrators group and the LOCAL_SYSTEM account to that group.
  2. Set an inheritable Access Control List (ACL) on %PROGRAMDATA%\Micro Focus\Enterprise Developer\mfsecrets so that only the "Micro Focus ES" group can read, write, and delete.
Note: All users who start enterprise server regions from the command line need to be members of the "Micro Focus ES" group; similarly any accounts used to start enterprise server regions by running casstart (for example, schedulers) need to be members of that group; and similarly if the MFDS service account is changed, it needs to be a member of that group.

See Hardening filesystem permissions for more information.

Parent topic: Vault Facility
Related concepts
Vault Facility


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 .
  • 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 Test Server 10.0


MSS Configuration and Administration

  • Introduction to Mainframe Subsystem Support
  • Assembler 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 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 Test Server.

You use Enterprise Test Server for running your CICS, IMS and JCL applications, for testing and for production use. Enterprise Test 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 Managing Licenses topics. For information about deployment licensing, see Deploying Applications.

Parent topic: Introduction to Mainframe Subsystem Support
Related concepts
Managing Licenses


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. They deploy the application to Enterprise Server.
  5. 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 Test Server and the facilities provided therein specifically for monitoring CICS, IMS and JCL applications.

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.
    Important: You must serialize CICS access to each DDname that refers to the INTRDR writer. To achieve this, issue a CICS ENQ command for the DDname before opening the file, and a corresponding DEQ command after closing the file.
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.

In the Enterprise Server (ES) configuration, you enable JCL support by setting the ES_SSTM_envr environment variable to a fully qualified path to the JCL used to initialize the SSTM environment, where envr is CICS or IMS, depending on the environment that you want to initialize.

From the Enterprise Server Administration Console, set ES_SSTM_envr 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\sstmcics.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).
    Important: You must serialize CICS access to each DDname that refers to the INTRDR writer. To achieve this, issue a CICS ENQ command for the DDname before opening the file, and a corresponding DEQ command after closing the file.
//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


Assembler Support

  • To turn on Assembler support for CICS-enabled enterprise servers
  • Configuring Runtime Memory Requirements
Parent topic: MSS Configuration and Administration


To turn on Assembler support for CICS-enabled enterprise servers

To turn on Assembler support for a CICS-enabled enterprise server:

  1. On the Enterprise Servers Administration page, click Edit in the row for the server for which you want to enable Assembler support.
  2. Select the General tab and type the following in the Configuration Information section:
    [ES-Environment]

ES_MFASM_SUPPORT=Y
  3. Click Apply and then OK.
Parent topic: Assembler Support
Parent topic: Shared Memory Area


Configuring Runtime Memory Requirements

The topics in this section describe how to configure memory requirements.

  • About Memory Requirements
  • Setting Addressing Mode and Residency Mode
  • Configuring the Default SQA Memory Size
  • Reserving Memory for Execution
  • Run Time Memory Environment Variables
Parent topic: Assembler Support


About Memory Requirements

On the mainframe, an area of memory can be located either below the line or above the line. The term 'the line' means the point at which the address of an area of memory requires four bytes to hold it. Three-byte addresses can point to memory up to 16Mb. Any area of memory starting at a higher point than this requires a four-byte address. Four-byte addresses are actually 31-bit addresses, since bit 0 is used for other purposes. A 31-bit address can point to memory up to 2Gb.

The memory requirements of an Assembler program are indicated by its AMODE (or addressing mode) and RMODE (or residency mode). AMODE governs the type of addresses the program uses, while RMODE indicates where the program must be located when it is loaded for execution.

There are two AMODE values:

  • AMODE(24) indicates 24-bit (three-byte) addressing - memory below the line
  • AMODE(31) indicates 31-bit addressing - memory above and below the line.

You can set AMODE to 24 or 31 for Assembler, since we emulate both types of addressing by mapping mainframe-style above and below the line addresses to real 32-bit PC memory addresses. An AMODE (24) program can only access memory below the line, while an AMODE(31) program can access memory both below and above the line.

There are two RMODE values:

  • RMODE(24) indicates that the program must be loaded into memory below the line.
  • RMODE(31) indicates that the program can be loaded either below or above the line.
Parent topic: Configuring Runtime Memory Requirements


Setting Addressing Mode and Residency Mode

The memory requirements of an Assembler program are indicated by its AMODE and RMODE:

  • AMODE (or addressing mode) governs the type of addresses the program uses.
  • RMODE (or residency mode) indicates where the program must be located when it is loaded for execution.
We support two AMODE values:
  • AMODE(24) - Tells the assembler run-time system to set the addressing mode bit in the Processor Status Word (PSW) to 0 when the module is called from a COBOL program. This sets the initial addressing mode to 24-bit.
  • AMODE(31) - Tells the assembler run-time system to set the addressing mode bit in the PSW to 1 when the module is called from a COBOL program. This sets the initial addressing mode to 31-bit.
Note:
  • When an assembler program loads and branches into another assembler module, Assembler ignores the AMODE setting of the called module and preserves the current setting of the address mode bit in the PSW.
  • You can use the DATA(24) COBOL compiler directive to ensure that the addresses assigned in the Working-Storage Section of the COBOL module are below the 16 MB threshold, irrespective of any AMODE setting.
Parent topic: Configuring Runtime Memory Requirements


Configuring the Default SQA Memory Size

You can use the MF370CTL.CFG file set the default SQA memory. You can also set the default memory above and below the line through the user interface.

Note: The settings in the user interface override any settings in the MF370CTL.CFG file.
For example, the following entry sets the SQA memory size to 3 Mb:
VM370=3000   ; set SQA size to 3Meg
Parent topic: Configuring Runtime Memory Requirements


Reserving Memory for Execution

When the Assembler run-time system is initialized, it allocates an area of memory called the system queue area to the executable program. You can specify how much of this memory is below the line and how much is above the line.

The main executable program and any other executables that it loads are loaded into memory below or above the line depending on the program's RMODE settings. When a program issues requests for extra memory using the macros GETMAIN or STORAGE OBTAIN, it can specify whether the memory needs to come from the below-the-line allocation or the above-the-line allocation, depending on its addressing needs.

In general the assembler run time allocates memory addresses bottom up from absolute address 0, while the COBOL run time allocates memory addresses top down, either from the 2 gigabyte line down, or the 16 megabyte line down.

  • Setting the Run Time Virtual Memory Environment
  • Example: Runtime Virtual Memory Configuration
Parent topic: Configuring Runtime Memory Requirements


Setting the Run Time Virtual Memory Environment

Run time virtual memory is controlled by environment variables set in the MF370CTL.CFG file

This file is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.

These control the amount of virtual memory which the 370 assembler emulator uses when the first assembler module is called:

Parent topic: Reserving Memory for Execution


Example: Runtime Virtual Memory Configuration

The following is a typical MF370CTL.CFG virtual memory configuration file located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory:
*--------------------------------------------------------------------------
* RUN TIME VARIABLES
MFPM=ON                   ; mainframe pointer manager is on by default
SVC370=MFI                ; set engine to MFI-mode
MEMSIZE=00000000,7FFFFFFF ; set valid address range
VM370=3000                ; set SQA size to 3Meg
AMODE370=31               ; run in 31-bit mode
Parent topic: Reserving Memory for Execution


Run Time Memory Environment Variables

The following environment variables control the run time virtual memory

MFMP
This must be set to ON for assembler to execute.
Example:

MFMP=ON

SVC370
This switch is related to backward compatibility. It must always be set to MFI.
Example:

SVC370=MFI

MEMSIZE=<LOW>,<HIGH>
Maximum 370 linear address that assembler modules can address. A value of 0,7FFFFFFF addresses the bottom 2 gigabytes of 370 virtual memory
Example:

MEMSIZE=0,7FFFFFFF

VM370
Amount of memory, starting at absolute address 0, to be allocated for the use of 370 assembler modules to be loaded into. Default is 3 meg below the 16 meg address line.
Example:

VM370=3000

AMODE370
Tells the assembler emulator which addressing mode to initially start in when the first assembler module is called.
Example:

AMODE370=31

Parent topic: Configuring Runtime Memory Requirements


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

From your Windows desktop:
Windows 8, 8.1, and Windows Server 2012
  • From the Windows Start screen, click the Enterprise Server Administration tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Enterprise Test Server > Enterprise Server Administration.
From :
  • On the Server Explorer, right-click ; then click .

    The Enterprise Server Common Web Interface (ESCWA) starts in your default browser.

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 DEMOSIT in System Initialization Table.
  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, the verification enterprise server entry is: C:\ProgramData\Micro Focus\Enterprise Developer\MFDS\MSSIVP.
  2. Select the verification enterprise server entry and click Select, and then click Next.
  3. Click Next two more times to accept the default settings, then on the Import server information (Page 4 of 4) screen, click OK.
  4. Click Edit to the left of the MSSDEMO server row. 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. The Micro Focus Host Access for the Cloud (HACloud) TN3270 emulator is available with this product's installation.

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


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
  • To turn on Assembler support for CICS-enabled enterprise servers
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 environment 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.

The environment variable ES_STAGING_FOLDER is not supported for NEWCOPY and Phase In for a PAC environment. The caspac command should be used instead. See caspac for more information.

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 EIBRCODE, EIBRESP2 and EIBRESP.

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

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

>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 Test 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 reference
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 (deprecated)
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 (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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


CICS Resource Definitions

In Mainframe Subsystem 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 Subsystem Support, for example LSRPOOL and SESSIONS. Mainframe Subsystem Support does not support these resource types because they are meaningless on the target environment.

Mainframe Subsystem Support provides Micro Focus extensions for some resource types. These are extra keywords that define attributes specific to Mainframe Subsystem 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 Subsystem 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 BUNDLE
    Defines a CICS Transform Bundle.
  • DEFINE CONNECTION
    Defines a remote system with which ES communicates via inter-region communication (IRC).
  • DEFINE DOCTEMPLATE
    Defines the attributes of a CICS Application Document Template.
  • DEFINE FILE
    Defines the attributes and characteristics of a file used by Enterprise Server.
  • 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 PROGRAM
    Defines a program used to process transactions in Enterprise Server.
  • DEFINE _SIGNON
    Defines user IDs and their level of access security to Enterprise Server resources.
  • 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 TCPIPSERVICE
    Defines internal CICS interfaces for TCP/IP services.
  • DEFINE _TEMPSTORAGE
    Defines the attributes of a temporary storage (TS) record set.
  • DEFINE TERMINAL
    Defines the characteristics of display devices and printers used by Enterprise Server.
  • DEFINE_THRESHOLD
    Defines system thresholds for CICS, JES, IMS, or CGI resources.
  • 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 URIMAP
    Defines system thresholds for CICS, JES or IMS resources.
  • 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: Resource Definitions
Related reference
casrdtup


DEFINE BUNDLE

Defines a CICS Transform Bundle.
Keyword | Description
Bundle(name) | Name of the Transform Bundle record. Can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group | 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 bundle. 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.
STatus(ENABLED|DISABLED) | Status of the Bundle when it is installed.
BUndledir(string/) | Full path to the directory of the bundle. Must end with the forward slash (/).

Example

DEFINE BUNDLE(SAMPBUN) GROUP(SAMPGRP)
DESCRIPTION(Sample BUNDLE)
       BUNDLEDIR($SAMPDIR/bundles/)
       STATUS(ENABLED)
Parent topic: CICS 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

_SYnclevel(1|2) | Allows for two-phase commit if set to 2. By default, this is set to 1.
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..
_FQPARTNRNAM(name) Identifies a fully qualified partner name for LU62 connection definitions. This field is formed of a NETWORK ID and a Partner LU name (both must be eight characters at the most) separated by a period ('.').

If the Fully Qualified Partner name in the connection is validated and installed, it will be used at run time on the APPC Allocate verb, whereas the PARTNER LU Alias is set to binary zeroes.

For example:

DEFINE CONNECTION(T88A) GROUP(MYCONNS)
NETNAME(OFLLU0AA) INSERVICE(YES) ATTACHSEC(LOCAL) PROTOCOL(APPC)
_OPERPRTY(0) _NATLANG(E) _SESSIONMAX(4) _LUALIAS(OFLLU0AA)
_PARTNRALIAS(CICSDEV1) _ALIASAPPLID(OFLLU0AA) _MODETABLE(#INTER)
_SYNCLEVEL(2) _FQPARTNRNAM(BBNET.CICSDEV1)

Example

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: CICS Resource Definitions


DEFINE DOCTEMPLATE

Defines the attributes of a CICS Application Document Template.
Keyword | Description
Doctemplate(name) | Name of the Document Template record. Can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
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 bundle. 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.
TEmplatename(name) | The name by which the template is known to application programs.
File(name) | A CICS file that contains the template.
Appendcrlf(YES|NO) | When YES, CICS deletes trailing spaces and appends a carriage return for each logical record of the template.
TYpe (ASCII|EBCDIC|BINARY) The format of the template contents:
  • ASCII - Template contents is parsed as ASCII text when loaded.
  • EBCDIC - Template contents is parsed as EBCDIC text when loaded.
  • BINARY - No parsing of the template contents is done.
TSqueue(tsqueue) | A temporary storage queue containing the template.
TDqueue(tdqueue) | A transient storage queue containing the template.
Program(program) | The CICS program that contains the template.
Exitpgm(program) | The exit program that generates this template.
DDname(name) | The partitioned data set (PDS) containing the template. Default is DFHHTML.
Membername(name) | A member in the PDS containing the template.
Hfsfile(string) | Path to a z/OS UNIX System Services file containing the template.

Example

DEFINE DOCTEMPLATE(SAMPDOCT) GROUP(SAMPGRP)
DESCRIPTION(Sample MVS PDS TEMPLATE)
       TEMPLATENAME(MY TEMPLATE NAME) DDNAME(MYDDNAME)
       MEMBERNAME(MYMEMBER) APPENDCRLF(YES) TYPE(EBCDIC)
Parent topic: CICS 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

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: CICS Resource Definitions


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

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: CICS 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


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.
_ABEnddump(NO | YES) Indicates that MSS should produce a dump if an abend occurs in any of your transaction programs.

Default is NO.

_AUTORsttime (IMMEDIATE|NO|YES) | The action that CICS should take to handle automatic time changes.
_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.
_AUXtrace(NO | YES) Indicates whether MSS is to enable or disable auxiliary tracing.

Default is NO.

_CHAincmd(string) Specifies the character string that BMS control is to interpret as the BMS paging command CHAIN.

Default value is C/.

_CICsrel | Obsolete.
_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)
_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.

_COPycmd (string) Specifies the character string that BMS control is to interpret as the BMS paging command COPY.

Default value is T/.

_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 (/).

_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.
_DEVelopment | Obsolete.
_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 run time 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.
_DUMponsysab(NO | YES) Indicates whether MSS should produce a dump if an abend occurs in its own code.

Default is NO.

_ENAbtclass (NO|YES) | Indicates whether MSS is to enable or disable TRANCLASS.
_ENAbtn3270(NO | YES) Indicates whether TN3270 is enabled or not.

Default is NO.

_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.
_FILeshare(NO | YES) Indicates whether MSS should create a dedicated Fileshare server process as part of region startup.

Default is NO.

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

_GMtran (EXIT|DISCONNECT) | The disconnect parameter for CESN transaction. If set to EXIT, a user can do F3/Clear to terminate CESN/CESL. If set to DISCONNECT, a user will see the TN3270 disconnected if F3 or clear is used.
_GRPLIST | Specifies the names of up to four lists of resource definition groups.
_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 run time by changing the ID Timeout on the ESMAC Control screen.
_INITIaltran(tranid) | Specifies the ID of an initial transaction that runs on every terminal when it logs on to the region.
_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.

_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.
_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)
_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)
_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.

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

_NRECTDFshr (name) | Specifies a Fileshare server ID for non-recoverable transient data queues.
_NRECTDPath (path) | Specifies the path for non-recoverable transient data queues.
_NRECTSFshr(name) | Specifies a Fileshare server ID for non-recoverable temporary storage queues.
_NRECTSPath(path) | Specifies the path for non-recoverable temporary storage queues.
_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.
_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.
_PF1Cmd(string) | Specifies a character string that is to equate to a BMS paging command for the PF1 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.
_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.
_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.
_PRINTDest(name) | Specifies the printer destination, up to 14 characters in length. You must also specify 3270 printer support when specifying a printer destination.
_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)
_PURgecmd (string) Specifies the character string that BMS control is to interpret as the BMS paging command PURGE.

Default value is D/.

_RECTDFshr (name) | Specifies a Fileshare server ID for recoverable transient data queues.
_RECTDPath (path) | Specifies the path for recoverable transient data queues.
_RECTSFshr (name) | Specifies a Fileshare server ID for recoverable temporary storage queues.
_RECTSPath (path) | Specifies the path for recoverable temporary storage queues.
_RETrievecmd(string) Specifies the character string that BMS control is to interpret as the BMS paging command RETRIEVE.

Default value is P/.

_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 run time 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 run time 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.
_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.

_SERvers(value) | Specifies the number of service execution processes that are to be started at server initialization.
_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.
_STArtuplist(name) Specifies the startup list which determines the resources to be loaded when the server is initialized.

Default value is DFHLIST.

_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

_SYSid(sysid) | Specifies the system ID of the region. This is the name by which it is known to other regions.
_TDColdstart(NO | YES) Indicates whether or not MSS should reset transient data queues at region start up.

Default is NO.

_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)
_TDNColdstrt (NO|YES) | Indicates whether or not MSS should reset transient data queues at region startup. Recoverable.
_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)
_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 (:).

_TN3270port(23 | value) Specifies the port number on which MSS listens for TN3270 requests.

Default value is 23.

_TRACEAPi(NO | YES) Indicates whether MSS is to enable or disable CICS API tracing.

Default is NO.

_TRACECCi(NO | YES) Indicates whether MSS is to enable or disable CCI tracing.

Default is NO.

_TRACECOmms(NO | YES) Indicates whether MSS is to enable or disable communications tracing.

Default is NO.

_TRACECWs (NO|YES) | CICS Web Service tracing.
_TRACEDump(NO | YES) Indicates whether MSS is to enable or disable dump control tracing.

Default is NO.

_TRACEFile(NO | YES) Indicates whether MSS is to enable or disable file control 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.

_TRACEMFCm (NO|YES) | Configuration Manager tracing.
_TRACEMessg(NO | YES) Indicates whether MSS is to enable or disable message tracing.

Default is NO.

_TRACEPcp (NO|YES) | Program management function tracing.
_TRACESRv (NO|YES) | Service handler tracing.
_TRACEStore(NO | YES) Indicates whether MSS is to enable or disable storage control tracing.

Default is NO.

_TRACETABle(NO | YES) Indicates whether MSS is to enable or disable table management tracing.

Default is NO.

_TRACETASk(NO | YES) Indicates whether MSS is to enable or disable task control tracing.

Default is NO.

_TRACETErm(NO | YES) Indicates whether MSS is to enable or disable terminal control tracing.

Default is NO.

_TRACETStd(NO | YES) Indicates whether MSS is to enable or disable temporary storage/transient data tracing.

Default is NO.

_TRACEUExit(NO | YES) Indicates whether MSS is to enable or disable user exit tracing.

Default is NO.

_TRACEUSer(NO | YES) Indicates whether MSS is to enable or disable user tracing .

Default is NO.

_TRAnsthold(-1 | 0-65535) | Specifies the amount of time in seconds that a transaction is allowed to execute before it is abended.
_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.

_TSColdstart(NO | YES) Indicates whether or not MSS should reset temporary storage queues at region start up.

Default is NO.

_TSNColdstrt (NO|YES) | Indicates whether or not MSS should reset temporary storage queues at region startup. Recoverable.
_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.
_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

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 TCPIPSERVICE

Defines internal CICS interfaces for TCP/IP services.
Keyword | Description
TCpipservice(name) | Name of the TCP/IP Service record. Can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
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 bundle. 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.
AUthenticate (NO|AUTOMATIC|BASIC|AUTOREGISTER|CERTIFICATE) | The authentication and identification scheme to use.
CErtificate(tabel) | The certificate to use for the SSL handshake.
CIphers(value) | Used when encrypting inbound messages.
Host (ANY|DEFAULT|name) | IPv4 or IPv6 address or host name which CICS listens to for incoming connections. This takes precedence over the Ipaddress attribute.
Ipaddress (ANY|INADDR_ANY|address) | IPv4 which CICS listens to for incoming connections.
Maxdatalen(value) | The maximum length of data CICS can receive. Default is 32.
POrtnumber(value) | The port CICS will listen on for incoming client requests.
PROtocol (HTTP|USER) | The application-level protocol used.
Realmr(string) | The realm used for HTTP basic authentication.
SOCketclose (NO|hhmmss) | Whether CICS should close the socket after an amount of time.
STAtus (OPEN|CLOSED) | Indicates whether or not CICS is to listen for this service after installation.
SSL(NO|YES|CLIENTAUTH) | Whether the service should use SSL.
TRansaction (name) | The ID of the CICS transaction to process new requests received. Default is CWXN for PROTOCOL(HTTP), CWXU for PROTOCOL(USER).
Urm (name) | A user-replaceable program this service invokes. Default is DFHWBAAX.

Example

DEFINE TCPIPSERVICE(SAMPTCP) GROUP(SAMPGRP)
DESCRIPTION(Sample SSL TCPIPSERVICE)
       HOST(ANY) IPADDRESS(INADDR_ANY) PORTNUMBER(5663) SOCKETCLOSE(NO)
       MAXDATALEN(32) STATUS(OPEN) TRANSACTION(CWXN) PROTOCOL(HTTP)
       AUTHENTICATE(AUTOMATIC) SSL(CLIENTAUTH) CERTIFICATE(localhost)
       CIPHERS(050435363738392F303132330A1613100D0915120F0C03060201)
       REALM(SSL AUTOMATIC please logon) MAXDATALEN(32) URM(DFHWBAAX)
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 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

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: CICS Resource Definitions


DEFINE_THRESHOLD

Defines system thresholds for CICS, JES, IMS, or CGI resources.
Keyword | Description
_THreshold (name) | Name of the Threshold record. Can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
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 bundle. 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.
_THType (CICS|JES|IMS|CGI) | Type of resource the threshold belongs to. Note: The CGI type will apply to the ESCWA and ESMAC casrdxxx modules.
_Stepname | Stepname for a JES type threshold to apply to.
_CPUWarn | Amount of CPU usage (ms) to reach before a warning message is sent.
_CPUPurge | Amount of CPU usage (ms) to reach before the process is purged (killed).
_MEMWarn | Amount of MEM usage (kB) to reach before a warning message is sent.
_MEMPurge | Amount of MEM usage (kB) to reach before the process is purged (killed).
_ETWarn | Amount of elapsed time (ms) to reach before a warning message is sent.
_ETPurge | Amount of elapsed time (ms) to reach before the process is purged (killed).

Example:

DEFINE _THRESHOLD(=CIC) GROUP(SAMPGRP)
DESCRIPTION(Sample General CICS _THRESHOLD)
       _THTYPE(CICS) _CPUWARN(5000) _CPUPURGE(10000) _MEMWARN(300)
       _MEMPURGE(8192) _ETWARN(0) _ETPURGE(0)
Parent topic: CICS 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|MMSS) 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
MMSS
The length of time after which deadlock timeout ends a suspended task. The maximum value that you can specify is 6800, representing 68 minutes, zero seconds.
DUmp(No|Yes) | Indicates whether or not Mainframe Subsystem Support produces a program dump if this transaction abends.
Runaway(SYSTEM|0|Milliseconds) 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
Milliseconds
On this system, must be a value between 1000and 270000. If less than 1000 milliseconds, changes are ignored.
Note: The mainframe allows 500 milliseconds.
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

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: CICS 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. A terminal definition must exist. If the terminal ID is unspecified, then the queue will be treated as having a destination of 'file'.
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).

Example

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: CICS 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.

_Ewa (NO|YES) | Enables a 3270 device to shift its display into its alternate mode.
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.
_Numlock (NO|YES) | Enables the Numeric lock.
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

_Tctuashr (NO|YES) | TCT User Area Shared.
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

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: CICS Resource Definitions


DEFINE URIMAP

Defines system thresholds for CICS, JES or IMS resources.
Keyword | Description
Urimap (name) | Name of the URI Map record. Can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) | Names the group the URIMAP 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 bundle. 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.
STatus (ENABLED|DISABLED) | Specifies if the URIMAP is to be enabled when installed.
HOST(name) The host name of the URI or its IPv4 or IPv6 address. | PAth(string) The full path of the URI the resource definition applies to. An asterisk can be used as a wildcard character to match more than one path.
PAth(string) | The full path of the URI the resource definition applies to. An asterisk can be used as a wildcard character to match more than one path.
SCheme(HTTP|HTTPS) | The scheme of the URI the resource definition applies to.
USAge (SERVER|CLIENT|PIPELINE) | Specifies whether this resource definition is for a HTTP server, HTTP client, or PIPELINE.
Mediatype | The media type of the static response provided to the HTTP request. (For USAGE(SERVER))
CHaracterset(string) | Character set which CICS converts the static response body into. Default is iso-8859-1. (For USAGE(SERVER))
HOSTCodepage(value) | Code page in which the document that forms the static response is encoded. Default is 037. (For USAGE(SERVER))
TEmplatename(name) | Specifies the name of the CICS document template for the static response body. (For USAGE(SERVER))
HFsfile(name) | The HFS file that will be sent as part of the static response to the HTTP request. (For USAGE(SERVER))
ANalyzer(NO|YES) Whether an analyzer program is used in processing the HTTP request. It must be associated with the given tcpipservice. (For USAGE(SERVER)) | Whether an analyzer program is used in processing the HTTP request. It must be associated with the given tcpipservice. (For USAGE(SERVER))
COnverter(name) | The program used to convert on the request and response. (For USAGE(SERVER))
TRansaction(name) | The transaction alias used to run the application or start the pipeline. Default is CWBA for USAGE(SERVER), CPIH for USAGE(PIPELINE))
PRogram(name) | The user application program that composes the HTTP request. (For USAGE(SERVER))
USErid(id) The user ID to be used in the transaction. (For USAGE(SERVER)) | The user ID to be used in the transaction. (For USAGE(SERVER))
CErtificate(label) | The certificate to use for the SSL handshake. (For USAGE(CLIENT))
CIphers(value) | Used when encrypting inbound messages, can be a string of up to 56 hexadecimal digits interpreted as a list of 28 2-digit cipher codes or the name of an SSL cipher suite specification file. Default is 050435363738392F303132330A1613100D0915120F0C03060201 (For USAGE(CLIENT))
PIpeline(name) | The pipeline from the inbound web service request made by the client. (For USAGE(PIPELINE))
Webservice(name) | The inbound web service request made by the client. (For USAGE(PIPELINE))
AUthenticate(NO|BASIC) | Whether to send basic authentication information in the HTTP response. (For USAGE(CLIENT))
POrt(NO|value) | The port used by the application when communicating with the server. (For USAGE(CLIENT))
SOcketclose(NO|hhmmss) | Specifies if and how long CICS keeps a client connection open after the CICS application finishes using it. (For USAGE(CLIENT))

Example

DEFINE URIMAP(SAMPURI) GROUP(SAMPGRP)
DESCRIPTION(Sample URIMAP for a server application response)
       STATUS(ENABLED) USAGE(SERVER) SCHEME(HTTPS) HOST(localhost)
       PATH(/tests/*) TCPIPSERVICE(TCPNOURM) ANALYZER(NO)
       CONVERTER(CICS) TRANSACTION(CWBA) PROGRAM(MYPROG) USERID(FREE)
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


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 (dfhucry1.cbl) form is provided in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits. 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.dll 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.exe 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 dfhucryp.dll . You then run the dfhpcryp utility, which uses the existing module (dfhucryp) 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).

To run dfhpcryp:

  1. Compile the new encryption module to .dll .
    Note:

    Do not replace the existing dfhucryp.dll at this stage. Your new module must only replace the existing dfhucryp.dll after you have run the dfhpcryp utility to perform the conversion.

  2. Rename your new encryption module to dfhucryu.dll and copy it into the same directory as the existing dfhucryp.
  3. Ensure that no part of MSS is active.
  4. Run the dfhpcryp.exe utility.
  5. When dfhpcryp completes, remove dfhucryp and rename dfhucryu to dfhucryp.
  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 Test 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\src\enterpriseserver\exits. 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 Test Server. 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


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
x'03000000' | CSM3 | Function shipping QUEUE model requests1
CVMI | CVMI | Function shipping mirror transaction for EBCDIC
CRTE | CRTE | Transaction routing transaction
CRSR | CRSR | Internal CICS housekeeping transaction
1You must upgrade the resource definition file, dfhdrdat, for the CSM3 transaction to be made available to the system as part of the DFHISC group. To do this, execute the caspcupg command. See the caspcupg reference topic for details.

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
Related reference
caspcupg


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 Host Access for the Cloud (HACloud).

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 Test 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 Test 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=ON 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=ON 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 DFHUPRNT to redirect printed output to different print type 3270 devices with multiple physical printers or print spooler queues.

DFHUPRNT 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 DFHUPRNT 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 DFHUPRNT 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 enterprise server 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.

  • 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 Test 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 Test 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 TCPCICP Service 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 or EBCDIC 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
Related information
Mainframe Subsystem Support (Known Issues)


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
Related concepts
Importing Data Conversion Templates


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 concepts
Data Conversion
Related reference
cascnvim


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 (deprecated)
  • 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 (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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


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


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 Test Server extensions designed to enhance usability, performance, and to allow more granular control.
  • Files and Data Sets
    This section provides introductory information on how MSS uses the following types of file: Project files, System catalog files, User catalog files, Catalog files, Data set files, and Spool files
  • Catalog Maintenance
  • Configuring JCL Timeouts
  • JCL Aspects of Troubleshooting
  • JCL Support Tasks
Parent topic: MSS Configuration and Administration
Related information
Features Added in Enterprise Test Server 2.3 Update 2


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
  • 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 Region for IMS


Enabling JCL for an Enterprise Server

You enable JCL on an enterprise server 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 with an Out Hold status, from the Complete 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.

Micro Focus also recommends that you enhance your spool housekeeping process, by adding the ability to merge the spool files into a central location once they have been archived. Once they are merged, you can easily browse the spool files using the Data File Editor.

  • MVSP0027 Spool Housekeeping Process
  • MVSSPLHK Spool Housekeeping Process
  • Merging Archived Spool Files
  • Spool Housekeeping-specific Environment Variables
  • Spool Housekeeping Return and Reason Codes
Parent topic: Configuring Enterprise Servers for JCL
Related information
MF_MVSJOB


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
  • Running the Spool Housekeeping Program from JCL
Parent topic: Spool Housekeeping
Related information
MVSSPLHK Spool Housekeeping Process
Merging Archived Spool Files
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
Running the Spool Housekeeping Program from JCL


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 in the spool print status)

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
Running the Spool Housekeeping Program from JCL
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
Running the Spool Housekeeping Program from JCL


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: MVSP0027 Spool Housekeeping Process
Related information
Setting the Retain Periods
Setting the Default Retain Period and Run Frequency
Setting the Retain Period and Archive Flag for Specific Held Classes


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.

This process also supports both 5- and 7-digit job numbering. If you enable 7-digit job numbering (using the MF_MVSJOB environment variable), any existing spool archive history files (that is, data sets define by INDEXO DD) need to be converted to a new format; see Configuring the MVSSPLHK Housekeeping Process for details. If you only use 5-digit job numbering, you do not need to run the conversion.

  • Configuring the MVSSPLHK Housekeeping Process
  • Running the MVSSPLHK Housekeeping Process
  • Sample Parameters File
Parent topic: Spool Housekeeping
Related concepts
JCL Support (Known Issues)
Related information
MVSP0027 Spool Housekeeping Process
Merging Archived Spool Files
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 a copybook (splhkarc.cpy for 5-digit job numbering, or splhkar7.cpy for 7-digit job numbering) you can read the file and output the details to a location of your choice.
Note: When you enable 7-digit job numbering, any existing <dataset> files must be converted to a new 7-digit format in order for them to continue recording a history of the spool files that have been archived. To convert the file, use the CONVERT.JCL file (which is located in the cpylib sub-directory of your product installation directory), changing the data set names to suit your requirements. When run, it calls the MFHKHCOV utility (also supplied). Once converted, the data set will process both 5- and 7-digit job numbers.
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.
MFDBFH performance options for database-hosted catalog and spool housekeeping
To enable optimized I/O for database-hosted catalog and spool file housekeeping:
USE_DB_OPTIO Y

When optimized I/O is enabled, you can perform the bulk delete of SPLDSN records in a single database operation by setting:

USE_DB_OPTIO_BULK_DEL_DSN Y

When optimized I/O is enabled, you can perform the bulk delete of SPLJOB records in a single database operation by setting:

USE_DB_OPTIO_BULK_DEL_JOB Y

When all three optimized I/O options are enabled, you can also enable local disk processing, which downloads database-hosted spool files and the catalog onto disk and performs spool housekeeping on the local disk files, and updates the database spool files and catalog using a bulk delete operation:

USE_DISK_HK Y
When all three optimized I/O options and local disk processing are enabled, use this option to disable the read locks on the database spool files and catalog during the bulk delete operation:
DISABLE_LOCK_FOR_BULK_DELETE Y
Note: You can use an equals, space, or comma as the delimiter between the option and the value. Valid values to enable the option are "Y" and "y" or "N" and "n" to disable the option. The default value is "N".
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 output dataset class
You can specify a retain period for jobs in a particular output data set 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.
Note: Only the date portion of this parameter is used when determining the eligibility of a spool file for archiving and/or deleting. The time portion is used when constructing the archive folder name.
Prevent the removal of data sets from an active job
Time-expired, non-active data sets are usually removed from active jobs. To prevent this, include the parameter:
CLEAN-DS-FROM-ACTIVE N
Suppress the creation of profile files
When a data set is to be archived, a profile file (.PRO file) is created; the profile file contains the data set's attributes. This file enables you to view the data set in the Data File Editor, or to use another program to perform file operations upon it. If you do not require profile files for your archived data sets, you can suppress their creation using the following:
MF_SPOOL_HK_WRITE_PROFILES N
Tip: You can also use the MF_SPOOL_HK_WRITE_PROFILES=N environment variable to suppress the creation of profile files.

The following configuration options can be used to reduce the run time of the housekeeping process. It is recommended that a housekeeping run be performed with none of them in effect, after recovery from any system failure, and periodically to ensure the integrity of the spool subsystem. How often this is done depends on the throughput of your batch system.

Suppress the purge of orphaned SYSOUT records
By default, when regular housekeeping has completed, the SPLDSN file is scanned, searching for records for which there is no associated SPLJOB record. You can suppress this search by setting the following configuration option:
MF_SPOOL_HK_ORPHAN_PURGE N
Suppress the purge of old CATALOG records
By default, when regular housekeeping has completed, the CATALOG is scanned, searching for spool record entries older than the maximum retain date, which conform to the standard naming convention (e.g. Y2017.S0323.S083544.J0001000.D00001.SYSPRINT). You can suppress this search by setting the following configuration option:
MF_SPOOL_HK_CATALOG_PURGE N

Alternatively, you can extend this search to encompass ALL spool data sets, regardless of their name, by setting the configuration option:

MF_SPOOL_HK_CATALOG_PURGE A
Warning: If you choose to extend the search in this way, and have a large catalog, spool housekeeping run times will increase significantly.
Suppress the check for orphaned LEX records

By default, when regular housekeeping has completed, the spool data directory is scanned, searching for LEX files (used internally by the job submission and restart functions) for which there is no associated SPLJOB record. You can suppress this search using the following configuration option:

MF_SPOOL_HK_LEX_SCAN N
Tip: You can also use the MF_SPOOL_HK_LEX_SCAN=N environment variable to suppress the search.
Suppress the detail records on SYSPRINT
By default, every successful housekeeping action is reported on SYSPRINT, which can result in a very large report. You can suppress the detail records by using the following configuration option:
MF_SPOOL_HK_SYSPRINT_DETAIL N
Parent topic: MVSSPLHK Spool Housekeeping Process
Related reference
Spool Housekeeping-specific Environment Variables
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 FROM 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
* --------------------------------------------------------
*   PREVENT DATA SETS BEING REMOVED FROM ACTIVE JOB
* --------------------------------------------------------
CLEAN-DS-FROM-ACTIVE N
* --------------------------------------------------------
*   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
*---------------------------------------------------------
*   SUPPRESS CREATION OF PROFILE FILES FOR ARCHIVED DATASETS
*---------------------------------------------------------
MF_SPOOL_HK_WRITE_PROFILES 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(61 0) -
                   RECSZ(401 401) -
                   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


Merging Archived Spool Files

Your housekeeping policy may result in a large number of archived spool files, located in different folders, that you must retain for audit trail purposes. It is possible to view the job details and file contents in each of those separate archive folders, but not all together.

These separate archives may be merged together into a central location through use of the Merge Archives process. This copies the archived spool files and merges them into a new, combined, archive. It does not change the original archive, so the audit trail remains untouched, but the combined archive allows viewing of all the jobs that have been merged. The combined files have similar names to the original spool control files but are prefixed with 'M_'. Opening M_SPLJOB.DAT in the Data File Editor allows you to view all the jobs and job details.

You run the merge process in one of two ways: submitting a JCL job, or by running a command line utility. Both the sample JCL (MERGESPL.JCL) and the command line utility (MergeArchives.exe) are shipped with Enterprise Developer.

  • Running the Process to Merge Archived Spool Files
  • Viewing Merged Archived Spool Through ESCWA
  • Viewing Merged Spool Files in the Data File Editor
    Administrators of a JES-enabled Enterprise Server can now merge archived spool files to one central location by running the Merge Archived Spool File process. After which, they can view them from one data file, from within the editor.
Parent topic: Spool Housekeeping
Related reference
Viewing Merged Spool Files in the Data File Editor
Related information
MVSP0027 Spool Housekeeping Process
MVSSPLHK Spool Housekeeping Process
Spool Housekeeping-specific Environment Variables
Spool Housekeeping Return and Reason Codes


Running the Process to Merge Archived Spool Files

You can run the process using a JCL job or using a utility from an Enterprise Developer command prompt.

Using the JCL job

The JCL job MERGESPL.JCL is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib directory by default. Configure the following parameters within the source code to suit your requirements, and then submit the job in the usual way:

ARCHIVE LOC
The location of a folder containing archived spool files. Use this option or the SCAN option to select the spool files to archive.
ARCHIVE LOC full-path-to-archive
SCAN LOC
A top-level directory, where each containing sub-directory is scanned for archived spool files. Use this option or the ARCHIVE option to select the spool files to archive.
SCAN LOC full-path-to-archive
MERGE LOC and MERGE SUBLOC
Both of these identify locations where archived spool files identified by one of the two previous parameters are copied. Merged versions of the JES spool control files and catalog.dat are created (all prefixed with M_), and it is the M_SPLJOB.DAT data file that you open in the Data File Editor to view the merged spool files.
Note: If a merge location already contains merged archive spool files, the existing control files (files prefixed M_) are amended to accommodate the new spool files.

MERGE LOC and MERGE SUBLOC differ as follows:

MERGE LOC
A parent folder that identifies one location into which all archived spool files are copied.
MERGE LOC full-path
MERGE SUBLOC
Identifies a sub-folder or folders of MERGE LOC where spool files are copied.
MERGE SUBLOC {INDEX|WEEK|MONTH|USERNAME user-name|MIRROR}
Important: Each JCL job takes only one parameter for MERGE SUBLOC. If you specify more than one MERGE SUBLOC parameter on a single line or you add multiple MERGE SUBLOC entries into your MERGESPL.JCL file, the job uses only the last parameter it finds.
INDEX
Spool files for the first merge archive job are stored in a sub-folder of MERGE LOC named using an index of 000000001. Subsequent runs increment that index and store spool files in a sub-folder named for the incremented index.
WEEK
Spool files are stored in a sub-folder identified by the week of the current year as follows:
merge-loc/current-year_week-num

Where week-num is a two-digit representation of the week of the year. For example:

2023_32

Represents the 32nd week of the year 2023.

MONTH
Spool files are stored in a sub-folder identified by the month of the current year as follows:
merge-loc/current-year_month-num

Where month-num is a two-digit representation of the month of the year. For example:

2023_07

Represents the 7th month of the year 2023.

USERNAME user-name
Spool files are stored in a sub-folder of the same name as the string entered as user-name.
MIRROR
Stores spool files in a sub-folder bearing the same name as the original archive folder from the spool-housekeeping archive location.For example, if the spool housekeeping archive is /home/user/Archive/20230310, the spool files are stored in a sub-folder of MERGE LOC named 20230310.

Example:

The following JCL, scans the C:\spl-arc\ directory for sub-directories containing archived spool files. The files it finds are merged into the C:\spl-merge\Nov-18\ directory.

//MERGESPL JOB 'MERGE SPOOL ARCHIVES',CLASS=A,MSGCLASS=A
//**********************************************************************
//*<CR_TAG_JCL\>//*//* Copyright (C) Micro Focus 1984 - 2022 or one of its affiliates.
//* This sample code is supplied for demonstration purposes only
//* on an "as is" basis and "is for use at your own risk".
//*
//*<CR_TAG_JCL_END\>
//**********************************************************************
//* Merge a spool archive into a merged archive
//**********************************************************************
//ARCHIVE  EXEC PGM=MERGESPL//SYSPRINT DD SYSOUT=*//SYSOUT   DD SYSOUT=*
//SYSERR   DD SYSOUT=*//* SYSIN or CONFIGI dataset contains the program parameters
//SYSIN  DD *
* --------------------------------------------------------
*   MERGED SPOOL HOUSEKEEPING CONFIGURATION FILE
* --------------------------------------------------------
*   ARCHIVE LOCATION - the archive to read
* --------------------------------------------------------
* ARCHIVE   LOC C:\ES_ERRORS\MERGED_ARCHIVES\SET_A\2018052611114975
* --------------------------------------------------------
* TOP LEVEL DIRECTORY TO SCAN
  SCAN      LOC C:\ES_ERRORS\MERGED_ARCHIVES
* --------------------------------------------------------
*   MERGED ARCHIVE LOCATION - The location of the merged archive
* --------------------------------------------------------
  MERGE LOC C:\ES_ERRORS\MERGED_ARCHIVES\MERGED_ARCHIVE
* --------------------------------------------------------
*   MERGED ARCHIVE SUB-FOLDER SPEC - INDICATES TYPE OF SUB-FOLDER(S)
* --------------------------------------------------------
  MERGE SUBLOC MONTH
/*
//
Tip: The ARCHIVE step in the above JCL could well be added as a new step at the end of your existing spool housekeeping job. Also, note how you can specify the merge parameters using a configuration file by using the CONFIGI parameter shown above.

Using the command line utility

Use the following syntax from an Enterprise Developer command prompt:

MergeArchives SCAN|ARCH arch-spool-file-directory/directories directory-for-merged-spool-files

Where:

SCAN|ARCH
Use SCAN to specify a parent directory in which its sub-directories are scanned for possible spool files to merge, or use ARCH to specify a single directory in which only its contents are merged.
arch-spool-file-directory/directories
When using the SCAN parameter, specify a parent directory with sub-directories that each contain sets of archived spool files, or when using the ARCH parameter, specify a directory that contains a set of archived spool files.
directory-for-merged-spool-files
Specify the directory in which the merged spool files will reside. Merged versions of the JES spool control files are created in this location (all prefixed with M_), and it is the M_SPLJOB.DAT data file that you open in the Data File Editor to view the merged spool files.
Note: If the merge location already contains merged archive spool files, the existing control files (files prefixed M_) are amended to accommodate the new spool files.

Example:

The following command reads the C:\spl-arc\2018111211042198 directory, and then creates a merged version of the archived spool files in a MERGE sub-directory of the current working directory.

MergeArchives ARCH C:\spl-arc\2018111211042198 MERGE
Parent topic: Merging Archived Spool Files
Related reference
Viewing Merged Spool Files in the Data File Editor


Viewing Merged Archived Spool Through ESCWA

ESCWA offers support for viewing the merged archived spool. The following steps show you how to archive the spools in your regions, and how to merge these and view them from another region:

  1. In ESCWA, specify the same value for the environment variable MF_SPOOL_ARCHIVE_LOC for each region. You specify the variable in the [ES-Environment] block in the region's Additional section on the General Properties page.
  2. Restart the region(s).
  3. Submit the archiving JCL from each one of these regions - see MVSSPLHK Spool Housekeeping Process in your product Help.
  4. Submit the merging archive JCL from a JES region from which you want to see the merged archived spool - see Running the Process to Merge Archived Spool Files in your product Help.
    • MERGE LOC is to be used in as path in the next step.
  5. In the JES region, specify the Merged Spool Filepath in the Advanced region properties page - click General > Advanced to access the page.
  6. Start the region that you want to use to view the merged archived spool.
  7. Browse to the JES > Spool region page to view the spools.
  8. To only view the merged spools, click List, and then Filter.
  9. In the Filter pane, check Merged Spool, specify any other parameters, and click Apply.
Parent topic: Merging Archived Spool Files


Viewing Merged Spool Files in the Data File Editor

The Merge Archived Spool File process, which is run as a JCL job or from the command line, creates a merged set of archive files made up of separate sets of spool archive files, from different locations. Creating merged spool files requires that you have an enterprise-related Micro Focus product; see Merging Archived Spool Files in the full product help.

One of the files in this merged set is M_SPLJOB.DAT; open this file in the editor to view the spool job entries and their associated data sets.

  • Open a Merged Spool File
Parent topic: Merging Archived Spool Files
Parent topic: Using the Data File Editor
Related concepts
Merging Archived Spool Files
Running the Process to Merge Archived Spool Files


Open a Merged Spool File

You must have first created a merged spool file, either using the JCL job or command line utility supplied with your product.

  1. From the Micro Focus Data File Tools window, click File > Open > Spool Archive.

    The Open dialog box appears.

  2. Navigate to the required merged spool file (M_SPLJOB.dat), then click Open.

    The spool file is displayed in the main window.

  3. Double-click the required spool job.

    A dialog box appears, listing the data sets associated with the spool job.

  4. Double-click the required data set.

    The Open Data File dialog box appears.

  5. Click Open Shared.
    Note: There are a number of other options that you can set on this dialog box, but you probably only want to view the data set in Shared mode.

    The data set appears. Use the filter options to search for information in the data set.

Parent topic: Viewing Merged Spool Files in the Data File Editor
Related concepts
Merging Archived Spool Files


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. The default is Y.

MF_SPOOL_HK_LEX_SCAN=Y|N
MF_SPOOL_HK_OUTPRT

Determines if files from the Complete queue with a status of Output or Printed are also deleted when spool housekeeping is run. The default is Y.

MF_SPOOL_HK_OUTPRT=Y|N
MF_SPOOL_HK_TESTDATE Overrides the normal date for the spool housekeeping.
MF_SPOOL_HK_TESTDATE=YYYYMMDD
MF_SPOOL_HK_WRITE_PROFILES Determines the creation of profile files (.PRO files) when a data set is archived. The default is Y.
MF_SPOOL_HK_WRITE_PROFILES=Y|N
Parent topic: Spool Housekeeping
Related information
MVSP0027 Spool Housekeeping Process
MVSSPLHK Spool Housekeeping Process
Merging Archived Spool Files
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 SPLDSN.dat, SPLJOB.dat, SPLMSG.dat, SPLSUB.dat, SPLOUT.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.
14 | Unable to find the SPLJOB file.
15 | Failed to open the SPLMSG file.
16 | Start of SPLMSG failed.
17 | Delete record from SPLMSG failed.
18 | Read next record of SPLMSG failed.
19 | Read keyed record of SPLMSG 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.
45 | Catalog record insert failed.
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
79 | Error writing archive SPLMSG record.
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
84 | Error opening archive SPLSUB file.
85 | Write to archive SPLSUB failed.
86 | Error closing the archive SPLSUB file.
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
Merging Archived Spool Files
Spool Housekeeping-specific Environment Variables


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
Related information
ES_ALLOC_OVERRIDE


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.

  • Comment lines must be prefixed with # in column 1.

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 - DSNAME10
Name of the dataset name element, number one to five: DSNAME1.DSNAME2.DSNAME3.DSNAME4.DSNAME5.DSNAME6.DSNAME7.DSNAME8.DSNAME9.DSNAME10
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 > 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, spool 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\SPLDSN.dat /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\SPLJOB.dat /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\SPLMSG.dat /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\SPLSUB.dat /s SPOOLSERVER
/f C:\ES_ERRORS\FAST_CAT_FS\SPLOUT.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
  • Advanced Restart Functionality
  • Non-restartable steps
  • Processing during restart
  • GDG Processing during Restart
  • Job Restart Return Codes
    Describes the return codes produced by the job restarts.
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.
Note: casrdo42 has a text input field for passing advanced job restart parameters visible when the environment variable ES_JES_RESTART is set to Y for the enterprise server region.

If this field is specified then the Step and P.Step are ignored.

Job number must not be specified, it accepts the advanced restart parameter format without this. For example, #f<step-name(instance-number)>

MF_UCC11
Note: This environment variable works independently of the JCL RESTART parameter.

JCL job restart functionality is disabled by default. It can be enabled, with varying behaviors, using one of the following values:

  • When set to Y, restarting a job with DISP=(NEW,CATLG) data sets will not result in job failure caused by the data set already being cataloged.
  • When set to YA, running a job with DISP=(NEW,CATLG) data sets will not result in job failure caused by the data set already being cataloged.
  • When set to M, MA or MR, when restarting a job, cataloged data sets are presumed to have an initial disposition of MOD, rather than NEW . As a result, any new data is appended to the existing data set.
  • When set to N, MF_UCC11 is not set so a data set with an initial disposition of NEW may cause an error when restarting the job if the data set already exists. The setting of the MF_UCC11 value can be made on a job-by-job basis using either the JCL user exit, MFJUXIT, or the Advanced Restart Functionality.

Additionally, when set to Y or YA, if the job uses GDG data sets, the GDG generation is reset to the level used in the previous job, ensuring that the restart will automatically pick up the correct GDG generation.

When restarting a job with any of the above values set, 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.

Parent topic: Restarting Jobs
Related concepts
Advanced Restart Functionality


Restarting a job

As long as a job has not been hard-killed, you can restart the job through:

  • The ESCWA Spool Window in the Job details pane for a job in the Hold queue.
  • The casout command line. For example:
    casout /r<Servername> /j<jobnumber:step:procstep>
  • Driving the casout callable API
Parent topic: Restarting Jobs
Related reference
casout


Advanced Restart Functionality

Use the casout or the cassub command with the /jrestart parameter to restart a job with specifications that let you identify or change steps, procs, conditions, MF_UCC11 values, and so on.

Notes:
  • You can substitute a dash character (-) as an alternative to the forward slash (/).
  • Most parameters are case sensitive. For example, step and procstep names must be specified in upper cases.

When a job is restarted, the stored cond codes for each step within the range are updated using its corresponding the step result. For example, say you run a four-step job. The system records the result for each of the four steps. However, when you restart the job, you set the range to run only steps 2 and 3. The cond codes for steps 2 and 3 are updated, but the cond codes for steps 1 and 4 are not. Instead, they retain the results recorded the first time you ran the job.

Identify the step or procstep on which to restart a job

To restart a job at a specified step, and optionally a procstep, use the following form:
casout /r<Servername>
/jrestart:<job-number>#f<step-name(instance-number)>[:
<proc-step-name>]

For example, to restart job 1051 at step 20:

casout /rTST /jrestart:1051#fSTEP20

To restart the job from the first step in the job, use $FIRST in place of the step specification. For example, to restart job number 1006 at the first step:

casout /rTST /jrestart:1006#f$FIRST

Identify the step on which to restart in a job that contains duplicate step names

When a job contains duplicate step names, you can specify which step to start by using the #f parameter with <step-name> and optionally <proc-step-name> in the following form:
casout /r<Servername>
/jrestart:<job-number>#f<step-name(instance-number)>[:
<proc-step-name(instance-number)>]

For example, to restarts the job at the third instance of STEP2 and first instance of PSTEP within that step:

casout /rTST /jrestart:1006#fSTEP2(3):PSTEP(1)

Change the value of the MF_UCC11 environment variable on restart

Use the #m parameter to change the value of MF_UCC11 on each restart. For example:
casout /rTST /jrestart:1006#fSTEP2(3):PSTEP(1)#mY

Valid values for #m are:

Y
Switch on MF_UCC11 processing, this is the same as MF_UCC11=Y
N
Switch off MF_UCC11 processing, this is the same as MF_UCC11=N
M
Set MF_UCC11 processing to MOD, this is the same as MF_UCC11=M

See Enabling Job Restart Functionality and MF_UCC11 for more information on this environment variable.

Identify the step on which to end

Use the #t parameter to identify the step on which to end a restarted job using the following form:
casout /r<Servername>
/jrestart:<job-number>#f<step-name(instance-number)>[:
<proc-step-name(instance-number)>]#t<step-name(instance-number)>[:
<proc-step-name(instance-number)>]

For example, to restarts job 1006 at the third instance of STEP2 and the first instance of PSTEP within that step, and finishes running after the first instance of STEP4 and the second instance of PSTEP within that step:

casout /rTST /jrestart:1006#fSTEP2(3):PSTEP(1)#tSTEP4(1):PSTEP(2)

The end step is included in the run.

Restart using condition and abend codes from a previous run

Abend and Cond Code Recovery (ACR) enables you to use step COND and ABEND codes from a previous run when restarting a job by using the #k parameter.

The #k parameter has two fields - the first to indicate use of previous ABEND codes, and the second to indicate use of previous COND codes:

#k<abend-field><condition-field>

Acceptable values for both fields are:

Y
Yes, use previous codes.
N
No, do not use previous codes.
R
Reset to RC=0.
D
Default. This is the same as Y.

Default value is Y.

For example, to reset steps that abended in the previous run to RC=0, and other steps maintain the COND code from the previous run:

casout /rTST /jrestart:1006#fSTEP2(3):PSTEP(1)#tSTEP4(1):PSTEP(2)#kRY

Restart using step-specific condition codes

As a supplement to, or independent of the ACR option, you can use the #c parameter to specify individual COND codes, or to specify use of all previous COND codes. These options enable you to rerun a job and change a step COND code that is used later in a conditional evaluation. The #c parameter identifies the step name, proc name, and optionally, the instance of the step together with the value to use:
#c{<step-name(instance-number)>[:
<proc-step-name(instance-number)>] | $ALL}:value}[...]
where value is any number from 1 to 255, which is the maximum number of steps in a job.

For example, to set the COND code of the second instance of PSTEP10 in the third instance of proc STEP20 to a value of 1:

#cSTEP20(3):PSTEP10(2):1

The following example shows the #c parameter in use with the casout /jrestart and other options:

casout /rTST /jrestart:1006#fSTEP2(3):PSTEP(1)
#tSTEP4(1):PSTEP(2)#c$ALL:5#cSTEP20(1):4
#cSTEP20(3):10

All steps are set to a COND code of 5, but the first instance of STEP20 is set to a value of 4, and the third instance of STEP20 is set to a value of 10.

Note: If ACR is not set and step-specific condition codes are not set, then step condition codes from the last run are loaded. However, step COND checks are performed only against steps starting at the restart step. Steps prior to the restart step are considered not having been executed and, therefore, evaluated to FALSE. However, IF/THEN/ELSE tests use the step results from the previous run. This is equivalent to the existing Micro Focus restart processing.

Restart using a combination of condition codes

You can use a combination of COND and ABEND codes from a previous run (#k) and step-specific condition codes (#c). In this case, consider the following:
  • Setting ACR to any value (Y, N, R, or D) using the #k parameter, and/or setting step-specific condition codes using the #c parameter causes the step COND and IF/THEN/ELSE checks to be performed against all steps.
  • To provide simulation of running the job from the start but actually starting at a specified step the ACR and step-specific condition codes parameters enable detailed control of evaluation of step COND and IF/THEN/ELSE tests.
  • If ACR = YY, then step CCs are loaded from the last run, and COND and IF tests are performed against all steps as though a full job run had taken place.
  • If ACR = NN, then step CCs are not loaded, and all steps are marked as not executed. COND and IF conditions evaluated against steps that did not execute evaluate to FALSE, so steps prior to the restart step are ignored.
  • ACR values for Abend and Cond Code recovery can be mixed, so it is possible, for example, to reset Abends to 0 and load the existing condition codes for the steps that did not abend using #kRY.
  • If step COND codes are given, using the #c parameter, for example, #cSTEP(1):10, then evaluation of step COND and IF conditions take place against all steps, as when ACR is set to a value.
  • Setting a step CC value causes that step to be marked as executed with the result of the CC value. For example, if ACR = NN and the step CC code is set, then all steps are marked as not executed except for the steps with COND CODES set on the restart parameter. Checks are made against all steps but if a step is marked as not executed then the test is evaluated as FALSE.
  • Using the legacy casout /j<job number> restart functionality results in existing step COND codes to be loaded and overwritten with those from the newly restarted run. Using the Advanced Restart Functionality uses the step COND codes from the job run and does not overwrite these at the end of the newly restarted run, so that step COND codes are always those from the original job run. Micro Focus recommends that you do not mix legacy and new job restart calls against the same job.

Restart using Micro Focus Batch Scheduler Integration (MFBSI)

You can restart JCL jobs with the Micro Focus Batch Scheduler Integration mfbsijcl command using either the original or modified JCL.
Original JCL
The following example shows the restart of a job using the mfbsijcl command and the original JCL, with some sample standard options for /jrestart:
mfbsijcl /jrestart:1234567#fSTEP2:PSTEP(1)
Modified JCL
To restart a job with modified JCL using the mfbsijcl command, use the following syntax:
mfbsijcl {/j<modified-JCL-file> | <basejcl>} /jrestart:<standard-parms>

where:

modified-JCL-file
The full or relative path to and filename of the modified JCL file.
basejcl
The JCL base that is resolved using JCL-Submit and JCL-Exit found in the mfbsi.cfg file.
standard-parms
Any valid parameters for the /jrestart option as documented elsewhere in this topic.

For example:

mfbsijcl  /jC:\Temp\modified.jcl /jrestart:1234567#fSTEP2:PSTEP(1)
mfbsijcl  /j/tmp/modified.jcl /jrestart:1234567#fSTEP2:PSTEP(1)
mfbsijcl basejcl /jrestart:1234567#fSTEP2:PSTEP(1)
When restarting a job using modified JCL:
  • A new job number is assigned to the job.
  • The JESYSMSG and associated MFELX*.dat file of the initial JOB number (specified in /jrestart:nnnnnnn) must be available.
Notes: When using the mfbsijcl command:
  • Most errors related to Advanced Restart are returned with the OS Rc 220 code.
  • If you need to re-execute the mfbsijcl substitution phase (standard or Control-M), use the modified JCL syntax even no change has been made to the JCL itself.

Restart with changed JCL code

You can edit the JCL code for a job and then resubmit it using both the /j and /jrestart parameters with the cassub command.

When you resubmit the edited job, you must specify the original job number on which you have based your edits. The COND codes and GDG information from the original job are used when running the changed job. For example, to submit TEST1.JCL as a restart of job 1006 with execution starting at STEP3:

cassub /rTST -jTEST1.JCL /jrestart:1006#fSTEP3

Auto-adjust restart

The restart step is adjusted automatically to account for datasets that would have been created in an earlier bypassed step, but that are required in a later step. The #a parameter determines whether or not to use auto-adjust. The default value, Y, turns on auto-adjust and N turns off auto-adjust. For example, to look for datasets used at or after STEP2(3):PSTEP(1) to determine where they are defined, and adjusts the restart step and procstep accordingly:
casout /rTST /jrestart:1006#fSTEP2(3):PSTEP(1)#aY

Because #aY is the default, omission of the #a parameter yields the same behavior. When #aN is used, no auto-adjustment is performed.

Note: Syntax for both casout and cassub can be specified using either a forward slash (/) or a hyphen to indicate the start of a parameter. For example:
cassub -rTST -jTEST1.JCL -jrestart:1006#fSTEP3

is equivalent to:

cassub /rTST -jTEST1.JCL /jrestart:1006#fSTEP3
Parent topic: Restarting Jobs
Related concepts
Enabling Job Restart Functionality
Related reference
MF_UCC11
casout
cassub


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.

Restart processing might issue one or more messages about steps that are skipped and the COND CODES used for those steps when conditional evaluations are performed. For details, see the message topics listed below under Related reference.

Notes:
  • 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
Related reference
JCLCM0940S All steps have been bypassed.
JCLCM0941I STEP step-name not executed due to restart decision.
JCLCM0942I Number of steps skipped on restart number-of-steps.
JCLCM0943I Total number of steps skipped on restart number-of-steps.
JCLCM0189I job-number job-name STEP BYPASSED STEPNAME.PROCSTEPNAME


GDG Processing during Restart

When a job that uses GDG generations is restarted, all references to a GDG relative generation (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 generation to be rolled off, scratched, or deleted.

When a restarted job contains GDG datasets and restart information has been enabled for GDGs, then information about the original high version number and, for GDGs that have a rollover disposition of EMPTY, the empty count is restored when the job is restarted. The JCLCM0945I and JCLCM0946I messages give details of the changes.

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 generation being rolled off, that generation will not be available on the restart, and any step that references the generation will fail with a dataset not found message.
  2. Where a different job, which references the relevant GDGs and creates new relative generations, runs between the end of the job in question and before the job restart takes place, it is possible that the generation 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 generation that doesn't exist as a result of the prior abnormal termination.
Parent topic: Restarting Jobs
Related reference
JCLCM0945I GDG model dataset-name current high version has been reset from original-value to new-value.
JCLCM0946I GDG model dataset-name empty count has been reset from original-value to new-value.


Job Restart Return Codes

Describes the return codes produced by the job restarts.

If an error occurs setting up the restart of a job, one of the following codes might be returned. The table shows the return code, a summary of the reason for the error, and the corresponding message code.

Return Code | Reason | Message Code
181 | parser error, restart parameter error | JES000150 to JES000159
212 | Restart 'from' step could not be found | JES000014
213 | Restart not permitted at this step | JES000017
214 | Job restart files could not be found | JES000018
218 | Restart 'TO' step could not be found | JES000022
219 | Restart 'TO' step found before 'FROM' step | JES000023
220 | Unable to create file for storing restart information | JES000043
221 | Unable to store restart information | JES000044
222 | Could not find JESYSMSG spool record for original job | JES000045
223 | Could not get catalog record of JESYSMSG for original job | JES000046
224 | Unable to load original job Cond Codes | JES000047
225 | Unable to store Cond Codes for new job | JES000048
226 | New job and old job are not the same | JES000061
227 | Unable to store restart GDG information for new job | JES000062
228 | Could not find a restartable step | JES000063

See JES Error Messages for more information on the message codes.

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 (deprecated)
  • 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 (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.

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


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 region
  • 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 | Details
Input | Jobs waiting to start (usually waiting for an initiator for the correct class to be available)
In Hold | Jobs that are held (HOLD on the job card, or Hold button on a job’s entry in the Input Queue)
Dispatch | Jobs that are scheduled to a batch or printer process but not yet actioned (transient state)
Active | Jobs currently running
Complete Contains three filters (Output, OutHold, and Printed), any combination of which can be selected to be displayed. The filters are:
  • Output - the output files waiting to be printed (usually waiting for a printer for the correct class to be available)
  • OutHold - the output files that are held (Hold button on a job’s entry in the Complete Queue)
  • Printed - the 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 JOBnnnnnnn page, where nnnnnnn is the number of the job. This page gives you access to a number of actions that you can perform on the job or output files:

  • 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 Complete 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 or output file
  • View the details of any of the outputs from the job or contents of an 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 restarts
    Describes the effect of running jobs when a region is restarted.
Parent topic: Running and Controlling JCL Jobs
Parent topic: Administering JCL-enabled Enterprise Servers


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.

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 restarts

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 Complete 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 Complete as a result of a server restart, the Completion Code as viewed in the JES Complete queue is set to RFLS. This indicates that the job was flushed as a result of a restart.

To modify this behavior, 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 Complete queue when the region is restarted.

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.

Note: When running in a PAC or with the MFDBFH database locking for multiple regions, active jobs are not flushed at region start-up. This is to avoid incorrectly removing jobs that are currently active in another region with the same name as the one starting up.
Parent topic: Managing and Viewing Spool Queues
Related information
ES_JES_DISABLE_RESTART_FLUSH


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 Enterprise Server Administration for the remote machine.
  2. On the Home page of Enterprise Server Administration 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:\demo\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 c:\demo\esjcl.jcl 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

The following commands start a batch initiator SEP for the classes A, B and C on the enterprise server JCLDEMO.

casstart -rJCLDEMO
start casout -iABC -rJCLDEMO

The following commands start 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

The following commands are the same as above, with the addition of a printer exit (SAMPPRNX) installed, to gain more control over the output handling.

casstart -rJCLDEMO
start casout -bA -n"HP LaserJet 4L" -rJCLDEMO -xSAMPPRNX

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 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 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 Test 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 Enterprise Test Server 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 Test Server.
  • IDCAMS Extensions
    Describes the extensions Enterprise Test 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 Test 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.
%CONSOLE_MSGS=Y|N | Enables you to configure the behavior of ES_JES_CONSOLE_MESSAGES on a job by job basis.
 | Y | CASMG0001I messages will be included even if the following environment variable is set: ES_JES_CONSOLE_MESSAGES=N. In either case they will still be added to the JESYSMSG log for the job.
 | N | CASMG0001I messages generated by "display upon console" calls in the user programs will not be included in the splmsg.dat file and will not be displayed on the Web page when viewing a job's details.

Examples:

%CATMAINT example:

//MFIDSAR9 JOB (MFIDSART),CLASS=A,
//             MSGCLASS=X,MSGLEVEL=(1,1),USER=MFIDSA,
//             REGION=0M
//*MFE:%CATMAINT=(Y,MFI01.DSA)

%HLQ example:

//MFIDSAR9 JOB (MFIDSART),CLASS=A,
//             MSGCLASS=X,MSGLEVEL=(1,1),USER=MFIDSA,
//             REGION=0M
//*MFE:%HLQ=MFI01.DA

%MFA example:

//MFIDSAR9 JOB (MFIDSART),CLASS=A,
//             MSGCLASS=X,MSGLEVEL=(1,1),USER=MFIDSA,
//             REGION=0M
//*MFE:%MFA=RJSE

%CONSOLE_MSGS example:

//NOMSG JOB 'CONSOLE MSGS',CLASS=A,MSGCLASS=X
//*MFE:%CONSOLE_MSGS=N
//***********************************************
Parent topic: JCL Extensions
Related reference
JCL Environment Variables
Related information
ES_JES_CONSOLE_MESSAGES


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 Test 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 Test 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 Test 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 behavior 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 contains spaces or if it extends to multiple JCL lines.

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:        '

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')

You can use the %PCDSN extension to set the location of a GDG. In this case the PCDSN location must be a directory. You can optionally use environment variables as in the following example, where GDG3DIR has been set in the region running the job:

    DEFINE GENERATIONDATAGROUP -
            (NAME(MFI03.GDGTEST.GDG2) -
            EMPTY -
            NOSCRATCH -
            LIMIT(3) ) -
            ;MFE:%PCDSN('$GDG3DIR[\]GDG2[\]MFIGDG[\]')

Note the use of [\] to define a directory separator. [\] will be replaced with the directory separator appropriate to the Operating System - '\' on Windows, and '/' on UNIX and Linux systems.

Parent topic: z/OS Enterprise Server Extensions


Files and Data Sets

This section provides introductory information on how MSS uses the following types of file: Project files, System catalog files, User catalog files, Catalog files, Data set files, and Spool files
  • Catalog Files
    MSS uses a catalog file to hold information about the data sets needed for the JCL jobs that run in an enterprise server. You specify the name and location of the catalog file when you configure an enterprise server for JCL. If the catalog file does not exist, MSS creates it when the enterprise server starts.
  • Data Set Files
  • Spool Files
  • mfsplcnv Spool Conversion Utility
    Provides details necessary to run the mfsplcnv spool conversion utility, which is required for spool files created using Enterprise Developer version 7.0 and earlier.
Parent topic: JCL Support


Catalog Files

MSS uses a catalog file to hold information about the data sets needed for the JCL jobs that run in an enterprise server. You specify the name and location of the catalog file when you configure an enterprise server for JCL. If the catalog file does not exist, MSS creates it when the enterprise server starts.

The location and name of the catalog file is shown in the System Catalog field on the Server > Properties > MSS > JES page in ES Admin. You can change this field to use a different catalog file.

If the catalog file becomes corrupt, you can rebuild it using the fixcat utility.

To maintain a connection with the mainframe environment, you can continue to use MVS data set names in JCL statements and TSO commands. However, these names have no meaning in a non-mainframe environment, so MSS also requires the name of the local file that represents the data set. Both names are included in the catalog entry.

Tip: Although you can share a catalog between servers if access to it is controlled by Fileshare, Micro Focus recommends you do not do so.
Parent topic: Files and Data Sets


Data Set Files

This section contains basic information about using MSS with data sets. See Advanced Data Set Information for more information.

All data sets that are referenced in JCL statements or TSO commands must have an entry in the catalog so that MSS can locate the local file that represents the data set. These data sets include:

  • Cataloged procedures referenced by EXEC statements.
  • JCL procedures referenced by INCLUDE statements or TSO SUBMIT commands.
  • Input and output data sets referenced in DD statements supported by MSS. See JCL Features in the JCL Support chapter for more information.
  • Input and output data sets referenced in TSO ALLOCATE, FREE, and DELETE commands.
  • REXX execs referenced by TSO EXEC commands.
  • Partitioned data sets (libraries) that contain any of the above data sets.

On the mainframe, data sets can be either cataloged or uncataloged. You can locate cataloged data sets using their catalog entry, and locate uncataloged data sets using their VOLUME number. In the Windows and UNIX environments, you cannot use the VOLUME to map physical locations as you can on the mainframe. Therefore, you should catalog all data sets on Windows and UNIX. The catalog entry for every data set contains a flag that indicates whether a data set is cataloged or uncataloged; however, all data sets, both cataloged and uncataloged, are actually located using the catalog.

When viewing the catalog you can choose to see just the cataloged data sets or to see both the cataloged and uncataloged data sets.

Data sets that are not referenced in JCL statements or TSO commands do not need entries in the catalog. For example, you can write a program that accesses a file that has no entry on the system catalog by specifying its physical filename in the SELECT clause in the Environment division.

There are three methods of including an entry in the catalog:

  • New on the Catalog page in ESMAC

    Click New on the Catalog page in ESMAC. You need to specify both the MVS name and the local physical filename.

  • Through the allocation of a new data set (DISP=NEW or DISP=MOD for a new file) by means of a DD statement in a jobstream or an ALLOCATE command in REXX exec. MSS assigns the physical filename.
  • Dynamically, by MSS, if a data set is used which does not already have an entry. MSS assigns the physical filename.

When MSS assigns the physical filename, it uses the default data file path set on the Properties > JES page of ES Admin, followed by the mainframe name with the extension .dat, For example, if the default path for data files is c:\catalog\data sets then a file with an MVS name of MFE2004.S1217.S160553.J01013.D00006.SYSOUT, will be stored locally as C:\CATALOG\data setS\MFE2004.S1217.S160553.J01013.D00006.SYSOUT.DAT .

Note: The default behavior is to enable new data sets to be cataloged without specifying a SPACE parameter. If you prefer that JCL missing the SPACE parameter fails in the same way it does on the mainframe, set the MF_NEWSPACE=Y environment variable.
  • Using Fileshare to Access Data Files
  • Partitioned Data Sets (PDSs)
Parent topic: Files and Data Sets
Related information
Partitioned Data Sets (PDSs)


Using Fileshare to Access Data Files

You can share files on networks and multi-user systems using Fileshare. As you can connect up to sixteen Fileshare servers to your COBOL system, you can split your data across several machines.

There are three ways of configuring the use of Fileshare:

  • Specify explicit Fileshare server locations in the catalog
  • Specify explicit Fileshare server locations in SELECT clauses, for files that are not cataloged
  • Provide a Fileshare client configuration file that defines which files are located on Fileshare servers

You can use these methods in combination.

  • Specifying Fileshare Locations in the Catalog
  • Specifying Fileshare Locations in SELECT Clauses
  • Specifying Fileshare Locations in the Fileshare Client Configuration File
Parent topic: Data Set Files


Specifying Fileshare Locations in the Catalog

To specify that a file is located on a Fileshare server, give the full pathname of the file prefixed by $$servername in Physical File when you create a new catalog entry using New on the ESMAC Catalog page. Use the conventions appropriate to the server. For example, the file data01.dat on a UNIX server would require a pathname similar to:

$$unixserver/usr/accounts/data01.dat

while the same file located on a mainframe would require a pathname similar to:

$$MAINFRAME\FILES.ACCOUNTS.DATA01

Parent topic: Using Fileshare to Access Data Files


Specifying Fileshare Locations in SELECT Clauses

If you write programs that access files that are not cataloged, because they are not mainframe-style files, and you want to store these files on Fileshare servers, you can include the fileshare server name in the SELECT clause in the I-O-Section of the Environment Division, for example:

select datafile assign to "$$unixserver/usr/accounts/data01.dat".
Parent topic: Using Fileshare to Access Data Files


Specifying Fileshare Locations in the Fileshare Client Configuration File

The Fileshare client configuration file is called fhredir.cfg. If there is an fhredir.cfg file present, MSS checks it whenever it needs a file that has no explicit Fileshare server location specified in its catalog entry or SELECT clause. It does not check it if an explicit Fileshare server location is specified.

If you want to specify a Fileshare location in the fhredir.cfg file for a cataloged file you must ensure you specify an explicit filename in Physical File that matches an entry in the fhredir.cfg file, rather than letting MSS allocate a name. Fileshare is case sensitive so filenames in the catalog and the fhredir.cfg file must use the same case.

You can either let the location of the fhredir.cfg file default to the current folder, or specify the location in the FHREDIR environment variable.

You must set the FHREDIR environment variable before you start the enterprise server instance. See Fileshare in the Configuration chapter in your Configuration and Administration Guide for more information.

You can use entries in the fhredir.cfg file in a variety of ways. For example, you can:

  • Name one or more Fileshare servers, and MSS will search those servers in the order in which they appear in the configuration file.
  • Specify full path names for every file located on a Fileshare server.
  • Use wild cards in path names, for example, to indicate that all the files in a certain directory are held on a Fileshare server.
  • Specify that certain files are actually located locally.

See Standard Operation and Configuration in your Fileshare Guide for more information.

Parent topic: Using Fileshare to Access Data Files
Related information
FHREDIR
Fileshare
Standard Operation


Partitioned Data Sets (PDSs)

In an MVS mainframe environment, a file can be defined as an individual data set or as part of a partitioned data set (PDS). MSS supports both of these methods.

In a partitioned data set (organization = PO), the individual data sets are known as members (organization = PDSM). You define a partitioned data set and its members to MSS like any other data set.

  • Procedure Libraries
  • Dynamic PDSs
Parent topic: Data Set Files


Procedure Libraries

Procedure libraries are partitioned data sets that contain procedures that can be specified in JCL jobstreams. MSS searches for the JCL procedures executed via an EXEC statement in the following order:

  1. In-stream procedures.
  2. Libraries specified on a JCLLIB statement in the JCL.

    You must allocate these libraries to the catalog.

  3. The libraries that you specified when you enabled JCL Support. This can be performed in ESCWA:
    1. In the menu bar, click Native.
    2. In the navigation tab, click Directory Server and then select the enterprise server region.
    3. Click JES > Configuration.

      This takes you to the JES Configuration page.

    4. In the System Procedure Library field, type the libraries.
    5. Click Apply.
    Note: This change will be applied next time the enterprise server region is restarted.
Parent topic: Partitioned Data Sets (PDSs)


Dynamic PDSs

In MSS, each member of a PDS is implemented as a separate physical PC file. By default, you have to create a separate catalog entry for each such member, giving the filename of the physical file. This is not practicable if a PDS has a great many members. You can avoid it by using a dynamic PDS.

To define a dynamic PDS you create just one catalog entry. On its Catalog Entry page in ESMAC, you set the DS Org field to PO and then put a check mark by Dynamic PDS. This enables the Physical Filename and PDS Exts fields. The value you enter in the Physical File field is assumed to be the name of an existing directory. The members of the PDS are implemented as individual physical files within this directory.

The Physical Filename field must end with a backslash ("\") on Windows or a forward slash ("/") on UNIX. As in any catalog entry, it must specify the full path. You can use the string "<CATALOGFOLDER>" to represent the directory where the catalog is stored.
Restriction: No other formats for the Physical Filename (for example paths containing an environment variable) are supported.

In the PDS Exts field you can specify what files to include by typing in a list of one or more filename extensions separated by spaces, or, to include all files regardless of the filename extension and to also include files that have no filename extension at all, specify * (asterisk).

On UNIX, all member names used in a dynamic PDS must be upper case. Any file that uses a lower case member name will not be found.

Example

If you define a Catalog Entry with

Field | Value
DS Name | SOURCE.PDS
Physical Filename | <CATALOGFOLDER>\PAYROLL\
DS Org | PO
Dynamic PDS | checked
PDS Exts | *

where the catalog folder is C:\CATALOG, and you then run the following JCL:

/FILE1	   DD DSN=SOURCE.PDS(PAYUPD),DISP=OLD
/FILE2	   DD DSN=SOURCE.PDS(PAYREP),DISP=OLD

(note DISP=OLD because SOURCE.PDS already exists), then as long as ES_OLD_DYN_PDS=Y is set then the JCL creates physical files PAYUPD.CBL and PAYREP.CBL in directory C:\CATALOG\PAYROLL. It creates catalog entries for these individual PDS members (DSOrg = PDSM) automatically. If ES_OLD_DYN_PDS=N (the default) is set, physical files for the PDS members are only created and cataloged when you run JCL similar to that outlined in Creating a Dynamic PDS with JCL.

When a PDS member is being sought, the directory is searched for a file with the member's name plus each of the specified extensions in turn, and the first match is used. For example, if the directory contains PAYUPD.CBL, PAYUPD.CPY and PAYREP.CPY, then an attempt to access SOURCE.PDS(PAYUDP) will find PAYUPD.CBL. Because the search terminates once a match has been found, PAYUPD.CPY will never be found. An attempt to access SOURCE.PDS(PAYREP) will find PAYREP.CPY.

  • Creating a Dynamic PDS with JCL
Parent topic: Partitioned Data Sets (PDSs)


Creating a Dynamic PDS with JCL

You can create dynamic PDSs with JCL, by using the extension syntax illustrated in the following examples.

You must set the following variables in your JCL depending on whether the file is for data or source.
Variable | Value for a data PDS | Value for a source PDS
LRECL | Any number greater than zero | 0
RECFM | Either FB, V, VB, or F | LSEQ

Using a PDS for data files

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

Using a PDS for source files

//DD1      DD DSN='LORINCE.CTLLIB.PDS',DISP=(NEW,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(3,1,1)),
//            DCB=(RECFM=LSEQ,LRECL=0,DSORG=PO)
//*MFE: %PCDSN=C:\DCCPDS\*.TXT

This will create LORINCE.CTLLIB.PDS as a dynamic PDS that can be used for control cards or source for SORT, IDCAMS, REXX, JCL, and PROCs.

Deleting a Dynamic PDS

When you delete a dynamic PDS, this does not automatically delete the underlying PC files. To delete the underlying PC files, set the MF_DEL_DYNPDS environment variable to Y.

Parent topic: Dynamic PDSs


Spool Files

Attention: If you are upgrading from Enterprise Developer version 7.0 or earlier, you must convert your JCL spool files to the format used for versions 7.0 Patch Update 1 and later. See mfsplcnv Spool Conversion Utility for details.

MSS emulates the spooler functions of the mainframe's job entry system. You can select emulation of VSE, JES2 or JES3.

MSS creates a spool file for each of the following:

  • Each job that is run. The spool file lists the jobstream and shows the results of each job step.
  • Each output data set that is directed to SYSOUT. The spool file shows the contents of the data set.

In MSS, a JCL jobstream can have only one job but the job can contain multiple job steps. You use an EXEC statement to specify the program to be executed by a job step. You can do this either directly:

EXEC PGM=program-name

or indirectly, using a cataloged procedure:

EXEC PROC=procedure-name ---------> EXEC PGM=program-name.

Although the Catalog page does not include spool files, they are assigned data set names.

If the data set name is not specified, the MVS name has the form:

Yyyyy.Smmdd.Shhmmss.Jjjjjjjj.Dnnnnn.ddname

If the data set is temporary, the MVS name has the form:

Yyyyy.Smmdd.Shhmmss.Jjjjjjjj.ANDAND.tempname

where:

  • yyyy is the year
  • mmdd is the month and day
  • hhmmss is the time
  • jjjjjjj is the job number
  • nnnnn is a number assigned by MSS. It indicates the order in which the data set was created by the job (00000 for the JOBLOG(JCL) file that shows the results of scanning or running a jobstream).
  • ddname is the DD name (for SYSOUT files only)
  • tempname is the temporary name, specified as &&tempname in the DD statement.
Parent topic: Files and Data Sets
Related information
mfsplcnv Spool Conversion Utility


mfsplcnv Spool Conversion Utility

Starting with Enterprise Developer 7.0 Patch Update 1, the spool file format has changed. If your spool files were created with an earlier release, and you are running Enterprise Developer 7.0 Patch Update 1 or later, you must convert them using the mfsplcnv utility.

This documentation references the two spool file formats as follows:

version 1 format
This is the spool file format used by Enterprise Developer versions earlier than 7.0 Patch Update 1.
version 2 format
This is the spool file format used by Enterprise Developer version7.0 Patch Update 1 and later.

The mfsplcnv utility locates your spool files based on the value set for the Enterprise Server MVSSPOOLDIR environment variable, which must be set before you run mfsplcnv. Running the utility creates a backup of your original spool file and a new version in the same location. Your original spool files are renamed with the file extension .bak. The new spool files take on the name of the original .dat file.

mfsplcnv is a command-line utility that you must run from an Enterprise Developer command prompt.

Syntax

mfsplcnv -{1|2}

Parameters

1
Convert spool files to the version 1 format from the version 2 format. Use this only when you have created spool files using Enterprise Developer version7.0 Patch Update 1 and later, and need to use those spool files with an earlier version of Enterprise Developer.
2
Convert spool files to the version 2 format from the version 1 format. You must use this option after upgrading to version 7.0 Patch Update 1 or later on all version 1 spool files created using an earlier release.
Note: If your spool files reside in a database environment, the SPLJOB.dat must be downloaded to a local disk to be converted and then upload the converted file back to the database.

In addition, before downloading the SPLJOB.dat file, ensure that there are no duplicate alternate keys in the file.

Parent topic: Files and Data Sets
Related concepts
Spool Files
Related reference
MFSYSCAT


Catalog Maintenance

  • MFCATMNT Utility
    Use the MFCATMNT utility to remove time expired dataset from the catalog.
  • MFCATNML Utility
    This command-line utility normalizes the SQL URLs of catalog entries.
  • Catalog Maintenance User Exit (MFCATMNTUE)
    The MFCATMNTUE user exit program can be used to enhance the catalog maintenance when searching for expired data sets (the MFCATMNT utility).
  • Catalog Return Codes
Parent topic: JCL Support


MFCATMNT Utility

Use the MFCATMNT utility to remove time expired dataset from the catalog.

When you run it, it inspects the catalog records, comparing the expiry date of the dataset against the check date (usually the current date). Any datasets that have an expiry date less than the check date are processed for removal. If a dataset does not have an expiry date, it is not removed.

You can limit the datasets considered for removal by passing a high level qualifier as a parameter to the MFCATMNT program; for example, the sample job below will only check datasets that begin with 'MFI101':

//CATMNT1 JOB 'CATALOG MAINTENANCE',CLASS=A,
//             MSGCLASS=X,MSGLEVEL=(1,1),
//             REGION=0M
//* =========================================================
//* Drive the catalog maintenance utility for MFI101 datasets
//* =========================================================
//MFCATMNT EXEC PGM=MFCATMNT,
// PARM='MFI101'
//SYSOUT DD SYSOUT=*

The process scans the catalog, looking for datasets that begin with 'MFI101'. For each one that it finds, it will attempt to allocate the dataset to the current job and ENQ it. This ensures that the dataset is not in use by another process at the time the check takes place. If the process cannot ENQ a dataset, it skips over that dataset and moves to the next one. Once enqueued, the expiry date is checked against the check date: if the dataset should be deleted, it is deallocated and deleted; otherwise, it is deallocated and kept.

Datasets that are deleted by the process are reported in the SYSOUT file assigned to the step.

You can also use the special job extension %CATMAINT in a JCL job step to perform catalog maintenance; see JOB Statement Extensions for more information on the required syntax.

Parent topic: Catalog Maintenance
Related reference
JOB Statement Extensions


MFCATNML Utility

This command-line utility normalizes the SQL URLs of catalog entries.

Run MFCATNML against an existing catalog before doing an incompatible upgrade from Enterprise Developer, Enterprise Test Server, or Enterprise Test Server version 7.0.

Important: Before running MFCATNML, we strongly recommend that you back up your existing catalog.

You may execute MFCATNML against the database-hosted catalog, or you can download the catalog from the database and run MFCATNML locally.

Set the following environment variables before running MFCATNML:

ES_DB_FH=Y
MFSYSCAT=full path and filename of the catalog to be updated
Syntax
mfcatnml [-q] [-s] [-d]
Parameters
-q
Performs the normalization process in quiet mode, meaning that normalized datasets are not listed. When omitted, all normalized datasets are listed.
-s
Stops processing when it fails to normalize an entry. When omitted, normalization proceeds with the remaining catalog entries after a failure.
-d
Excludes processing of cataloged spool files if they are on disk.
Parent topic: Catalog Maintenance


Catalog Maintenance User Exit (MFCATMNTUE)

The MFCATMNTUE user exit program can be used to enhance the catalog maintenance when searching for expired data sets (the MFCATMNT utility).

Use the user exit to determine the processing that should be done, as it provides an expanded range of options. Initially, the user exit is called to set the expiry check date and the high level qualifier used in the catalog search. Then, for each data set found, it is called again to decide if the data set should be:

  • processed normally (check expiry date if set).
  • ignored (ignore this data set).
  • deleted without checking the expiry date.
  • removed (uncatalog but do not delete) without checking the expiry date.

Dataset information passed to MFCATMNTUE includes the expiry date (GETCT-EXPDT) and the last changed date (GETCT-CHG-DATE). The user exit is also called when the data set was not allocated for checking.

View the sample user exit program (mfcatmntue.cbl), which is located in the \src\enterpriseserver\exits sub-directory of your installation directory, to see how you can enhance the process.

If you compile the user exit using a different program name, use the MFCATMNTUE variable to specify the new name. (If you compile the program to MFCATMNTUE, you do not need to set the variable.)

Parent topic: Catalog Maintenance


Catalog Return Codes

The following table contains a list of return codes resulting from operations on the catalog:
Return code | Description
0 | OK, record is in the main catalog ($MFSYSCAT)
4 | OK, record is in a user catalog
8 | Record not found - non-fatal
14 | Delete operation tried on a non-expired dataset. Use PURGE command.
16 | Record not found
17 | Get Cluster called with a non-VSAM dataset
18 | Get Cluster found non-VSAM record or record did not have expected VSAM relationship information
20 | Fatal error processing the request - e.g. unexpected file status opening catalog file, invalid directory for dynamic PDS
24 | The user cancelled the operation while waiting for a lock
81 | Too many PDS sub-records
913 | Failed authorisation to create new dataset
9902 | Index corrupted
9904 | Invalid file status not covered by more specific error codes - an unexpected file status was returned from a file operation
9906 | Out of disk space
9907 | (Windows API call) Failed to get the full path and name of the catalog file
9908 | Catalog file error
9913 | Invalid function. The catalog module was called with an invalid function.
Parent topic: Catalog Maintenance


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:

  • 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 when a "soft kill" can be issued. The DBMS commit/rollback can be used, and will process as expected

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


IMS Support

  • Creating and Configuring an Enterprise Server Region for IMS
    Describes the creation and configuration of an enterprise server region that runs an IMS application.
  • IMS Database Administration
    BTS Trace, IMS Database Locking and IMS Database Recovery.
  • WebSphere MQ Support
    Describes Enterprise Test 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


Using Fileshare with Enterprise Server

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. This is the recommended approach for VSAM file support in Enterprise Server.

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: MSS Configuration and Administration


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: Using Fileshare with Enterprise Server


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 ccitcp /cm ccism

In this example, ccitcp and ccism 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 ccitcp /pf fs.pwd

Refer to Using a Fileshare Password File for details on how password checking works.

Parent topic: Using Fileshare with Enterprise Server
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: Using Fileshare with Enterprise Server
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: Using Fileshare with Enterprise Server


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.
  • 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
Monitoring Fileshare Activity
FSView
Installing Fileshare as a Service
Optimizing the Fileshare Server
ES_RLS_FILE_SUPPORT
Starting a Fileshare Server


Fileshare Options

Note: In this section, options are shown starting with a forward slash (/).

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.

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 16KB. If you specify a value greater than 64, the Fileshare Server uses a buffer size of 64KB.
/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:

ccitcp, or ccism

/pf password-file
 The name of the password file that the Fileshare Server uses.
/cf file-name

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.

/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
/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. After which, it runs a disk stats check, to calculate the disk usage and the amount of space remaining, generating a warning if disk space is low. Use /fds to control the frequency of this check.

If the file is unable to be flushed to disk due to low disk space, the operation will be suspended for 30 seconds, and then retried.

Also, 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.
Warning: Setting this option will degrade the performance of Fileshare.
/fds <value>
 Controls the frequency of the disk stats check performed after a flush, and so this option only has an effect when /fc is also specified.

By default, this check is performed after every flush, but you can use /fds to change the frequency.

Set this option to a value between 1-65536 to represent the nth flush on which to run the checks. (A value less than 1 equates to 1, and a value greater than 65536 equates to 65536.)

/lw
 Enables write through for the transaction log file, 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.
/sm

Starts Fileshare in sharing mode. It enables files to be shared using the 'Sharing with all other' sharing mode model.

This option is only applicable to stand-alone Fileshare, and only for those files not marked as transactional files (that is, not flagged with advanced logging). Transactional files will still be opened exclusively.

/uv

Instructs Fileshare to use the specified password file that is stored in the Vault Facility.

The password file must have been uploaded to a vault, with a prepended path of microfocus/fh, before you start Fileshare using this option. Upload the file using the mfsecretsadmin command; for example:

mfsecretsadmin write microfocus/fh/pass.dat  -file pass.dat  -vault aesvault
Note: If you update your password file, you must upload the updated version to the vault; see The mfsecretsadmin Utility for more information.
/clp
 Upgrades the password file to enable support for long usernames and passwords, up to 100 characters in length. It must be combined with the /pf option to upgrade a specific password file.
Note: Password files that are upgraded to enable long username and password support are no longer compatible with versions of Enterprise Developer prior to version 3.0. Once the /clp option has been run, all future password files created on the server now support long usernames and passwords.

Examples

Assume the file fs.cfg contains the following lines:

/s fsserv1
/cm ccitc32
/cm ccism
/pf serv1.pwd

If you enter the command:

fs

Fileshare reads fs.cfg and starts a server named FSSERV1, with TCP/IP and Shared Memory enabled. It uses the file serv1.pwd for password security.

  • Using a Fileshare Password File
    Specifying a password file when you start a Fileshare server enables you to restrict unauthorized access to files.
Parent topic: Fileshare Server Configuration
Related information
Using a Fileshare Configuration 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 username 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. The username can be up to 100 characters. The username must be quoted if it contains spaces.
/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. The password can be up to 100 characters. The password must be quoted if it contains spaces.
/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 usernames and passwords are case-sensitive. Valid characters must be invariant under transformation from ASCII to EBCDIC, which is dependent on the code page you are using. Usernames and passwords do not support the following characters "/\-". In addition, Micro Focus does not support long usernames and passwords for MFA.

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 Options
Related reference
Long Usernames and Passwords
Related information
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
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
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
    Note: Long usernames and passwords that contain spaces must be surrounded with double quotes. In addition, if the username or password contains a double quote then you must escape it by adding an extra double quote immediately after.

    This creates a password file called pass.dat, containing an entry for the user ID FSVIEW with password Meryton. The contents of this file (except for the username) 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

You can install Fileshare as a Windows service, which allows you to start and stop the server from the Windows Control Panel.
Restriction: This is only applicable to Windows platforms.

You can install Fileshare as a Windows service using the following syntax

fsservice -i <service-name> /wd <path\to\fs\working\dir> /cf <path\to\fs\config-file>
-i <service-name>
A unique name for the service.
/wd <path\to\fs\working\dir>
The Fileshare working directory. This can also be specified in the configuration file.
/cf <path\to\fs\config-file>
The fully-qualified path to the Fileshare server configuration file.

For example, the following command installs a service called FS32SEV1, that when started uses a working directory of C:\support\FS32\DATA, and uses the configuration file C:\support\FS32\FSAD32.CFG.

fsservice -i FS32SEV1 /wd C:\support\FS32\DATA /cf C:\support\FS32\FSAD32.CFG

From the Services screen (available from the Windows Control Panel), you can start and stop the Fileshare service.

To uninstall the Fileshare service, enter:

fsservice -u <service-name>

When Fileshare is running as a service, there is no Fileshare console window, and so you cannot control it interactively via this window. Consequently:

  • You have to use FSView to control Fileshare, and therefore must create a password file.fs.
  • 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
Monitoring Fileshare Activity
FSView
Optimizing the Fileshare Server


Walkthrough - Fileshare as a Service

Restriction: This is only applicable to Windows platforms.

This walkthrough takes you through starting a Fileshare server as a Windows service. It uses a server configuration file that names the Fileshare server (/s), sets the working directory (/wd), specifies a password file (/pf) - this enables you to utilize FSVIEW, enables synchronous communications (/sc), and sets full tracing (/tr).

Before you start, ensure that you do not have a Fileshare server currently running.

  1. Create the following directory: C:\fsdir.
  2. In that directory, create an fs.cfg file containing:
    /s server1
/wd C:\fsdir
/pf pass.dat
/sc
/tr f
  3. From an Enterprise Developer command prompt, navigate to c:\fsdir and enter:
    fs /pf pass.dat /u FSVIEW /pw Meryton

    This creates the password file specified by /pf in the configuration file. It is required to use FSView.

  4. To install the Fileshare service, at a command prompt, enter:
    fsservice -i FSserv /cf C:\fsdir\fs.cfg

    Where FSserv is the name of the service to create.

  5. To check the service status, enter:
    fsservice -v FSserv

    A message stating that the service is currently installed is displayed.

  6. Open a Windows command prompt and enter services.msc.

    The Services screen appears.

  7. From the list, select Micro Focus Fileshare Service: FSserv and click Start.
    Tip: Double-click Micro Focus Fileshare Service: FSserv 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
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

Note: If you are using long usernames and passwords you are not required to quote or escape the FS user name or FS password fields of the enterprise server's SIT. See Long Usernames and Passwords for more information.
Parent topic: Fileshare Client Configuration
Related reference
Long Usernames and Passwords
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 region so that all datasets are accessed via Fileshare.

To do this, perform the following steps in ESCWA:

  1. In the menu bar, click Native.
  2. In the navigation tab, click Directory Server and then select the enterprise server region.
  3. Click JES > Configuration.

    This takes you to the JES Configuration page.

  4. In the Default Allocated Dataset Location field, type the path and name of the Fileshare server.

    This means you no longer need to specify anything for individual datasets, unless you want to override this.

  5. Click Apply.
Note: This change will be applied next time the enterprise server region is restarted.
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 region so that the catalog itself is accessed via Fileshare.

To do this, perform the following steps in ESCWA:

  1. In the menu bar, click Native.
  2. In the navigation tab, click Directory Server and then select the enterprise server region.
  3. Click JES > Configuration.

    This takes you to the JES Configuration page.

  4. In the Fileshare Configuration Location field, type the path and name of the Fileshare server.
  5. Click Apply.
Note: This change will be applied next time the enterprise server region is restarted. In addition, setting this configuration will result in Fileshare being able to access the spool files.
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.
Note: When calling the casfile 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.

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 data sets 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 data sets 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, run from within an Enterprise Developer command prompt.

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.

If running in Windows, you should also set the following environment variable if you need to preserve the case of the physical file name:

MFJ_STRICT_CASE=Y

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 data _sets.

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
MFJ_STRICT_CASE


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 Region
  3. Configure All Datasets to go via Fileshare
  4. Run a JCL Job
Parent topic: Using Fileshare with Enterprise Server


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 ESCWA Administration home page visible at this point, you may notice that an entry appears for SERVER1. This is because Fileshare is implemented using the Micro Focus Common Communications Interface (CCI), and a Fileshare server is an example of a CCI server. ESCWA shows CCI servers as well as enterprise servers.

    Fileshare server in ESCWA

Parent topic: Walkthrough
Next topic: Add an Enterprise Server Region


Add an Enterprise Server Region

We will create a new enterprise server region to use for this walkthrough. You could alternatively apply your changes to an existing region.

  1. On the ESCWA Administration page, click Native.
  2. Under the Directory Servers node, select the local directory server (by default, this is named 'Default'), and then click *New.

    The New Region dialog box is displayed.

  3. Enter FSDEMO as the name for the new server, and then ensure MSS Enabled is selected.
    Note: If your working mode is 64-bit, ensure 64-Bit Working Mode is also selected.
  4. Click Save.

    The region is added to the list under the selected directory server.

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 region to send all I/O requests for all datasets accessed by applications running in it to the Fileshare server.

  1. On the ESCWA Administration page, select FSDEMO from the directory server list.

    The instance details are displayed in the right-hand pane.

  2. In the Region Features group, ensure that the following options are selected, and then click Apply:
    • MSS Enabled
    • JES Enabled
  3. Click the JES tab.

    The JES Configuration details are displayed.

  4. Complete the following fields:
    Option | Description | Set to:
    JES Program Path | The path for the directory containing executable files to be run by your JCL jobs. | path-to-fsdir
    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. | \$\$server1\datasets\catalog.dat
    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. | SYS1.PROCLIB
  5. Click Apply.

  6. To start the region, hover over FSDEMO in the left-hand pane, and then click Start instance (Start).

    The Region Start Options dialog box is displayed.

  7. Click Start.
Parent topic: Walkthrough
Previous topic: Add an Enterprise Server Region
Next topic: Run a JCL Job


Run a JCL Job

Now that your Fileshare server server1 and your enterprise server region 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. On the ESCWA Administration page, click JES > Control, drag the file you just created to the area in the Submit JCL to JES section, and then click Submit.

    A message box is displayed confirming that the job has been submitted.

  4. Within the Start JES Initiators and Printers section, type A in the Classes field and then click Start.

    The JCL job now runs.

  5. Click JES > Spool to display the JES Output Queue, and then click the View job details (View) icon to the right of the job to display its details.

    JCL job overview

  6. Click View job details (View) to the right of the entry shown in DD Entries.

    The joblog is displayed. You can see the Fileshare server name ($$SERVER1) used when processing the dataset.

This ends the walkthrough.

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

EZASOKET in Enterprise Test Server 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. 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 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 Test 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
  • EZASOKET (standard interface) threadsafe transation
  • EZACICAL: Original COBOL application programming interface
  • EZACICSO (Sockets extended module) call-interface APIs
  • 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:

  • 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 behavior 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 behavior 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 (EZASOKET function)

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 Test 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)
  • Performance Issues
  • 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) is a VSAM file that 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 EZACONFG file is a VSAM file with an associated FCT entry. After adding DFHEZA group to your region startup list, running EZAC transaction will create the file for the associated FCT entry if the file does not exist.

The file's actual location and name used by your Enterprise Server are governed by an EZACONFG FCT entry, which resolves to a physical file exactly as any other FCT entry (such as via a catalog DSN entry, to an explicit file path and filename, or to the default File Path and name EZACONFG).

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


Performance Issues

You can improve the performance of an EZASOKET CICS application deployed to Enterprise Server using either or both of these configuration options:

Supress messages
By default the CICS CSKL listener puts out messages to the console when a client application connects to run a transaction. For example:
000000 16482581      12472 EZATEST  CASOP0000I 01 of 02 From (,,CSKL) EZY1325I
00/00/00 16:48:25 START SUCCESSFUL TRANID=EZT1 PARTNER INET
000000 16482601      12472 EZATEST  CASOP0000I 02 of 02 From (,,CSKL) ADDR=127.0.0.1
PORT=  8087

With many clients, these messages can cause unwanted overhead.

You can suppress the generation of these messages using the EZAC ALTER CICS transaction. Run EZAC ALT CICS to set SMSGSUP as shown here:

EZAC SMSGSUP setting
Turn off Terminal control
The default configuration for a CICS enterprise server region dictates that terminal control and send operations are buffered, which improves performance. To be sure that this setting is configured for optimal performance, go to the Enterprise Server Administration CICS SIT page for your enterprise server region, and see that the Terminal box is unchecked.
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. Run the EZAC transaction from a 3270. Use the ALTER command for the 3270 Listener to change the attributes for your enterprise server region by 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
1121 | ECONNRESET | The connection was reset, usually because the firewall has detected inactivity and the has time period expired.
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


Reference for MSS Deployment

  • CICS Commands
  • Data Conversion
  • CICS Resource Definitions
  • CICS Supplied Transactions
  • CICS Internal Transactions
  • IMS Support in Enterprise Server
  • JCL Commands
  • TSO Support in Enterprise Test Server
    Describes use of TSO commands in Enterprise Test Server using the ISAEDT01 utility.
  • MSS Error Messages
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, but you can specify another path on disk, or a database path (for example, sql://my-db/my-datastore?folder=/myrd - see The Datastore URL for details of the full SQL notation required).
/o | Overwrite existing files

Dependencies:

You must have started the enterprise server before you can issue a caspcrd command.

Comments:

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
The Datastore URL


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 .

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
Importing Data Conversion Templates


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][/z[userid]]
[/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. You can use this option to change the current path of a closed file or, if the file is cataloged, to change the DSNAME from the specified DD NAME.
/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.
/z[userid]
The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /a.
/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.

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] [/xm]

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 , but could be another path on disk, or a database path (for example, sql://my-db/my-datastore?folder=/myrd - see The Datastore URL for details of the full SQL notation required).
/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. Up to 4 startup lists are supported with the new GRPLIST parameter on the SIT. GRPLIST is the same parameter as on the mainframe GRPLIST specified in the JCL to startup CICS. See IBM documentation for more information on GRPLIST.
/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
/xm | Export resources and generate output in XML format

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"

or

casrdtex /oresfile.rdt /ggroup1,group3 /m /x /ipsql://localhost/CAS?folder=/FILES

or

The above command exports the PPT and PCT entries for the groups group1 and group3, from the dfhdrdat file on disk ("e:\dev mto\files"), or in the datastore (sql://localhost/CAS?folder=/FILES), to the file resfile.rdt.

casrdtex /oresfile.rdt /s /g /f /ip"e:\devmto\files"

or

casrdtex /oresfile.rdt /s /g /f /ipsql://localhost/CAS?folder=/FILES

or

The above commands export all SITs, and the FCT entries for all groups, to the file resfile.rdt.

Parent topic: CICS Commands
Related concepts
The Datastore URL


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, and can be a path on disk, or a database path, for example, sql://my-db/my-datastore?folder=/myrd. See The Datastore URL for details of the full SQL notation required.
/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 , but could be another path on disk or a database path.
/rregion-name | The name of the enterprise server 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 the input file containing the CICS resource definitions has been generated on the mainframe, the file must be converted from EBCDIC to ASCI. To do the conversion you can:

  • Use the dfconv command. See DFCONV Batch File Conversion for more information.
  • Use the Data File Converter tool available from the Classic Data File Tools utility. See Data File Converter for more information.
  • Convert the input file during the transfer from the mainframe.

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

This utility supports the DEFINE and DELETE commands only.
Note: The combination of DEFINE with the command line option /o can be used to overwrite existing definitions as an alternative to ALTER.

See Resource Definitions for more information on the resource definitions that you can use with Enterprise Server MSS.

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 concepts
CICS Resource Definitions
The Datastore URL


caspcupg

Updates a resource definition file.

Syntax:

caspcupg [/dp=resource-defn-path]
         [/s(sit,fs-server-id)]
         [/f(group,fs-server-id)]
         [/o]
         [/uuserid]
         [/ppassword]
         [/sparameter]
         [/ssparameter]
         [/bpath]
         [/t=]
         [/td]
         [/z]
         [/%]

Parameters:

/dp=resource-defn-path | Resource Definition Path - specify a path on disk or a database path (for example, sql://my-db/my-datastore?folder=/myrd - see The Datastore URL for details of the full SQL notation required)
/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 where the backup file is created - specify a path on disk or a database path.
/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
/% | Quiet mode

Comments:

The /s and /f options are alternatives and are mutually exclusive.

On Windows, 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
The Datastore URL


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]
    [/z[userid]]
    [/bdata-table-name]

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)
/z[userid]
The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /a.
[-bdata-table-name]
The specified Assembler data table name which uses RLD is to be reloaded from disk.
Note: If CPMT is used to reload the Assembler data table, optional parameter AMODE is required.

If -b option is used but no data-table-name is specified, the value provided for the -n option will be used.

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

See CICS Resource Definitions in the CICS Support section.

Parent topic: Reference for MSS Deployment


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.
  • CDMT - Document Template Master Transaction
    Issues an INQUIRE, NEWCOPY or DISCARD on a DOCTEMPLATE.
  • 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
  • CESL - Sign On
    Signs on to a terminal using long password/pass phrase.
  • 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


CDMT - Document Template Master Transaction

Issues an INQUIRE, NEWCOPY or DISCARD on a DOCTEMPLATE.

Syntax:

CDMT function doctemplate-name

Parameters:

function
Specify one of the following commands:
  • NEwcopy
  • DISCard
  • INquire
doctemplate-name
Specifies the name of the CICS resource that is the target of the command.

Notes:

If this transaction is not available in your existing resource definition file, it will need to be upgraded using the caspcupg command. See caspcupg for more information.

For NEWCOPY, CDMT issues an EXEC CICS SET DOCTEMPLATE NEWCOPY command for the specified DOCTEMPLATE.

For DISCARD, CDMT issues an EXEC CICS DISCARD DOCTEMPLATE command for the specified DOCTEMPLATE.

For INQUIRE, CDMT issues an EXEC CICS INQUIRE DOCTEMPLATE command for the specified DOCTEMPLATE and displays the results.

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


CESL - Sign On

Signs on to a terminal using long password/pass phrase.

Syntax:

CESL

Notes:

A list of environment variables and their values is displayed on the screen.

You do not enter any options at the command line. A screen appears when you enter the command, prompting you for:

  • Userid - must be between one and eight characters
  • Password - must be between 1 and 100 characters. Your password is not displayed on the screen when you type it in.
  • New password - must be between 1 and 100 characters. This field is shown only if you have the authority to change your password.
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 [AMODE]

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.

AMODE must be specified for Assembler tables which use RLD and are accessed by programs compiled with the AMODE Compiler directive.

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


CICS Internal Transactions

The following is a list of CICS internal transactions and their descriptions:

CDEQ
Data file editor DEQ file on timeout.
CKBC
CICS-MQ bridge - DPL container.
CKBP
CICS-MQ bridge - DPL commarea.
CKBR
CICS-MQ bridge - monitor task.
COFF
Input timeout logoff transaction.
CPIH
CICS Web Services PIPELINE processing.
CPIL
CICS Web services SOAP MQ inbound listener.
CPIQ
CICS Web services SOAP message MQ inbound router.
CPIR
CICS Web services pipeline resolution transaction.
CSOC
EZASOKET PLTPI auto start listeners.
CTRN
Castran internal transaction.
CTSC
TS expiry transaction.
CZM1
Send message to all terminals from ESCWA/ESMAC page. Used as a class 3 transaction, no RLS.
CZMG
Send message to all terminals from ESCWA/ESMAC page.
CZTS
ESCWA/ESCWA delete TS.
MERQ
IMTK CICS service interface EBCDIC runtime.
MERT
IMTK CICS service interface EBCDIC trace.
MMTM
IMTM CICS Service Interface EBCDIC WebSphere MQ trigger monitor.
MQMW
IMTK CICS service interface EBCDIC WebSphere MQ triggered program.
PIP1
PLTPI Phase 1 startup enterprise server region runs programs in PLTPI list once.
PIP2
PLTPI Phase 2 startup enterprise server region runs programs in PLTPI list in each process.
SDP1
PLTSD Phase 1 enterprise server region shutdown PLTSD runs once only.
SDP2
PLTSD Phase 2 enterprise server region shutdown PLTSD runs in each process.
x'6dffffff'
Clear screen transaction.
x'fbbffbbe
MQ listener transaction.
x'fbbffbbf
XA recover in-doubt transactions.
x'fccffccf
XA MFDS dynamic settings.
Parent topic: Reference for MSS Deployment


IMS Support in Enterprise Server

  • IMS DB system commands
    IMS DB system commands supported by Enterprise Test 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
  • 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 Test Server, which are a subset of all IMS DB commands.
/DIS
Displays the current status of specified databases.
Syntax:
/DIS[PLAY] DB {ALL | database1 [database2 [... database16]]}
Parameters:
ALL
Returns a status for all databases known to the enterprise server region, meaning databases that have been started or opened during the current enterprise server region session, and therefore does not necessarily include all databases defined in the enterprise server region.
Note: The list of known databases grows dynamically as they are accessed by system commands and applications running on the enterprise server region.
database1 [database2 [... database16]]
One or more database names separated by a space. Returns the status of each specified database, up to sixteen total databases.
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
Stops all specified databases. When stopped, a database cannot be accessed from MPP, BMP, or CICS-DLI programs; however, the database is still accessible from IMSDBU or batch DLI programs.
Note: This command is run synchronously. It suspends until the database is closed and stopped.
Syntax:
/STO[P] DB database1  [database2 [... ]]
Parameters:
database1 [database2 [...]]
One or more database names separated by a space. Stops each specified database.
/STA
Syntax:
Starts one or more specified databases, making them available to online, BMP, and CICS-DLI programs.
/STA[RT] DB database1  [database2 [... ]]
Parameters:
database1 [database2 [... ]]
One or more database names separated by a space. Starts each specified database.
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.

ESCWA

  • DB commands can be entered via the IMS Control page in ESCWA.
  • The response output is sent back to ESCWA.

See the IMS chapter in Enterprise Server Common Web Administration for more information.

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
Related concepts
Automatic Backward Recovery Process


IMS Tracing Flags

A list of Enterprise Server IMS tracing flags used by MSS. Check all that apply.

Flag | Traces
api | IMS API calls
bts | Batch Terminal Simulator
cli | Client processing
data | (Not used)
db-ctl | DB control processing
db-enq | DB lock management
db-thread | DB thread management
db-trd-stg | DB thread storage management
es-db | DB control processing
es-stg | Storage management for MFS processing
i/o | Database I/O
rims | Remote IMS
stg | DB storage management
sys | (Not used)
tm-buffer | TM buffer management
tm-ctl | TM control processing
tm-enq | TM lock management
tm-mon | TM buffer monitor
tm-thread | TM thread management
tm-trd-stg | TM thread storage management
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
    This utility enables you to interact with different enterprise server process types, such as IMS processes, MQ listeners, and printers.
Parent topic: Reference for MSS Deployment


cassub

Runs a JCL batch job.

Syntax:

cassub {[/rserver-name]|[/saddress]|[/lserver-name]}
       {[/jjobfile-name-by-content]|[/jrestart]|[/xjobfile-name-by-reference]}
       [/uuser-ID]
       [/ppassword]
       [/cgroup]
       [/z[userid]]
       [/v{1|2|3}]
       [/i{correlator}]

Parameters:

Options /r, /s, /l are alternative ways of identifying the enterprise server that you want to connect to.

/rserver-name
Name of the enterprise server region 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.

The JCL command cassub is now designated as a system program and as such will not be cancelled by runtime container de-initialization.

/saddress
Submits the job to a remote server. The 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 host name or IP address of the enterprise server listener.
  • port is the port number value.
/lserver-name
This is an alternative to using the /r and /s options. This is the name of the enterprise server region 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 an enterprise server region with the specified 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 for more infromation.
/jrestart
Used to restart jobs using the advanced restart functionality. See Advanced Restart Functionality for more infromation.
/xjobfile-name-by-reference
Path and filename of the file containing the JCL to run. See Comments below for more information.
/u user-id
Authorization user ID. See Security below for more infromation.
/p password
Authorization password. See Security below for more infromation.
/cgroup
Authorization group (optional). See Security below for more infromation.
/z[userid]
The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /p.
/v{1|2|3}
The version of the job control system software to use:
1
VSE/Power
2
JES2
3
JES3

The default value is 2 (JES2).

/i{correlator}
This parameter enables you to supply a correlator, up to 32-bytes long, comprised of ASCII printable characters. The JCL engine will ensure this correlator has not previously been supplied for a JCL JOB, if a duplicate correlator is detected then the job submission will be rejected and the previous JOB ID will be returned.

Dependencies

To use this command:

  • If you specify the /r parameter, you must have started the enterprise server region 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 region identified by the /s parameter, using ES Admin.
  • You must be running under the same user ID as the enterprise server region named with the /r parameter. If the Directory Server was started as a system service, and the enterprise server region was started using the Administration interface, then the enterprise server region 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
Related concepts
Advanced Restart Functionality


casout

This utility enables you to interact with different enterprise server process types, such as IMS processes, MQ listeners, and printers.

Syntax:

casout {/res-name|/sprototype:host:port|/lservername}
       [/-process-ID]
       [/uuserid]
       [/ppassword]
       [/cgroup]
       [/z[userid]]
       [/gnumber]
       [/gnumber:reldd]
       [/doutput-dsn]
       [/iclasses]
       [/jjobnumber:step[:procstep]]
       [/jrestart]
       [/knumber]
       [/mnumber]
       [/fnumber]
       [/oStart]
       [/oStart:QM:Q[:listener-name]]
       [/oStop:listener-name]
       [/oDelete:listener-name]
       [/oList]
       [/oList:name]
       [/qmessage-classes]
       [/eIMScommand]
       [/wmpr-name]
       [/nprinter-name]
       [/boutput-classes]
       [/xprinter-exit]
       [/tprocess-ID]
       [/v]
       [/ynumber:msg]
       [/#]
       [/@]
       [/%jnumber|/%tnumber]

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.

The /r, /s and /l options are alternatives and are mutually exclusive.

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.
/z[userid]
The parameter enables you to pass user credentials through an interactive prompt or as a redirection from the console, the userid is optional. This can be used to pass credentials stored in the Vault Facility.
Note: Micro Focus recommends that you use this option in preference to /u and /p.

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.
/jrestart
Used to restart jobs using advanced restart functionality. See Advanced Restart Functionality for details, syntax, and examples.
/knumber
Kill job number number.
/mnumber:class
Modify job number number to use the specified class.
/fnumber
Flush the output of job number number.
/ynumber:msg
Reply to job number number with message msg.
/@
Retrieve the list of all jobs waiting for input from the console.
/%jnumber
Lists all job steps for a specified job number, output in JSON format.
/%tnumber
Lists all job steps for a specified job number, output in table format.
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 Test 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
/-process-ID
Use to stop and replace an IMS MPR with the same class.
/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.
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.
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.
/#
List standard and transient SEPs.
Note: You can specify job numbers that have a maximum length of 7-digits.

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.
  • A number of security checks are performed in addition to the verification against casout under the OPERCMDS class.

    Depending on what options are used, checks are also performed to ensure that the user has access to a particular job - such as for restarting, modifying, or viewing datasets.

    The corresponding rules are under the JESSPOOL class. When trying to retrieve a dataset, additional checks are made for the particular dataset being accessed. This is also under the JESSPOOL class.

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

List standard and transient SEPs on Enterprise Server MYREG:

casout /rMYREG /#

Example list of returned standard and transient SEPs:

  PID       TYPE     TRAN
--------- --------- ------
    14076 SEP
    26180 SEP
    12412 SEP
      916 SEP
    26064 SEP       CEBR
    22058 Transient CSKL

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 status, or does not exist
8 | The job is in the Output Hold status, 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 in the Held Output status
8 | Job is in the Complete queue, with an Output status
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 concepts
Restarting a job
Advanced Restart Functionality
Related information
Restarting Jobs


TSO Support in Enterprise Test Server

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

Enterprise Test 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 Test 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
  • 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 Test 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
  • 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 Test 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 Test 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 Test 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 REXX statements.

The following example executes the REXX statements contained in the PDS member SBCS4315 of the TEST.SYSEXEC PO.

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


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


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


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


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


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


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


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


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


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 that 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 base generation.

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


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


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


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


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


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


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


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


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


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


JCLAM0164S Left parenthesis missing after "keyword"

You need to insert the missing left parenthesis 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


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 OpenText Support for Micro Focus Products.

Parent topic: JCLAM0160 - JCLAM0179


JCLAM0173I Excess VOLUME specification "%" ignored

Message

An excess VOLUME has been specified and it has been ignored.

Resolution

This is informational message only.

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 OpenText Support for Micro Focus Products.

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 OpenText Support for Micro Focus Products.

Parent topic: JCLAM0160 - JCLAM0179


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


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.
  • JCLAM0190I Incompatible data set attributes. OSCOPYLAX OK
  • JCLAM0191I Incompatible file formats. OSCOPY ignored
  • JCLAM0194W Number of records read was less than COUNT(<value>)
  • JCLAM0195W <value> records were padded to minimum record length
  • JCLAM0196S Input dataset is not a VSAM KSDS
  • JCLAM0198S Dataset <name> is not empty
  • JCLAM0199S Input and output datasets are the same
  • JCLAM0200I Dataset attribute <value> altered
  • JCLAM0201S Cluster may not be REUSEABLE value
  • JCLAM0202S Relate may not be LINEAR value
  • JCLAM0203S Relate may not be RRDS value
  • JCLAM0204S Relate is not a CLUSTER value
  • 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


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 OpenText Support for Micro Focus Products. 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 OpenText Support for Micro Focus Products.

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 OpenText Support for Micro Focus Products.

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

Message

A REPRO of a file failed due to an error returned by the OS.

Resolution

Check the File Handler section in the product help for the returned file status code returned in order to understand and resolve the issue.

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


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


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


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


JCLAM0190I Incompatible data set attributes. OSCOPYLAX OK

Message

A REPRO of a file has been performed and it has been detected that one or more of the dataset attributes (CHARSET, EXTENDED-TYPE, REUSE/NOREUSE, UNIQUEKEY/NONUNIQUEKEY) do not match. The system still proceeds with the operating system's "file copy".

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0191I Incompatible file formats. OSCOPY ignored

Message

The file format for the input and output files for a REPRO did not match and the OSCOPY was ignored.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0194W Number of records read was less than COUNT(<value>)

Message

The number of records read during the REPRO was less the count.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0195W <value> records were padded to minimum record length

Message

Details the number of records read from the input dataset whose records were smaller than the minimum length of the output dataset and were then padded to meet the minimum length.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0196S Input dataset is not a VSAM KSDS

Message

The input data is expected to be a VSAM KSDS file and it has been detected that it is not.

Resolution

Check that the operation is correct for the file or that your job is pointing at the correct file.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0198S Dataset <name> is not empty

Message

REUSE is specified for a VSAM dataset and the dataset is not empty.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0199S Input and output datasets are the same

Message

A REPRO cannot specify the same input and output datasets.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0200I Dataset attribute <value> altered

Message

The dataset detailed has had its SHAREOPTIONS altered.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0201S Cluster may not be REUSEABLE value

Message

A CLUSTER cannot be defined as reusable.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0202S Relate may not be LINEAR value

Message

A RELATE dataset must not be LINEAR.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0203S Relate may not be RRDS value

Message

A RELATE dataset may not be RRDS.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0204S Relate is not a CLUSTER value

Message

A RELATE dataset must be a VSAM CLUSTER.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0221S Insufficient authority to define new dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0222S Insufficient authority to read dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0223S Insufficient authority to update dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0224E Insufficient authority to delete dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

Parent topic: JCLAM0180 - JCLAM0230


JCLAM0225E Insufficient authority to alter/change 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


JCLAM0227U Insufficient authority for SYSIN dataset %

Lack of permissions to perform this action.

Resolution:

Contact your system administrator.

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


JCLAM0230S Insufficient authority to use PCDSN 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.
  • JCLAM0232S Maximum ERROR LIMIT reached
  • JCLAM0233S Parameter value <value> is not within permitted range 0-4
  • JCLAM0234I Command bypassed. Condition code is <value>
  • JCLAM0235E Insufficient authority to delete dataset <value> member.
  • JCLAM0236E Duplicate record "record number"
  • JCLAM0237S Rename/Replace failed. Catalog return code is <return code>
  • JCLAM0238S (JCLAM0238E) Invalid data type for ALTER dataset
  • JCLAM0239I Dataset attribute attribute-name unchanged
  • JCLAM0240S MANAGEMENTCLASS class-name not found
  • JCLAM0241E GDG Base not found "GDG base"
  • JCLAM0242I REPRO ignored - only valid for CLUSTER or PATH when dataset is VSAM
  • JCLAM0243U Dataset name <data-set> does not adhere to name restrictions
    The data set name contravenes the naming rules.
  • JCLAM0244S MASK keyword required for DELETE of dataset name <data-set>
    The data set, <data-set>, used a wildcard combination that also requires use of the MASK keyword.
  • JCLAM0245E No member names match the mask <ds-member-mask>
    No members were found that conform to the wildcards used in the member name.
  • JCLAM0246E No entries found for mask <data-set>
    No entries were found that conform to the wildcards used in the data set name.
  • JCLAM0247S MASK parameter not allowed for PDSM delete
    You cannot use the MASK parameter when also specifying a PDS member.
  • JCLAM0248S Only 1 dataset permitted with MASK keyword
    You cannot use multiple data set names with the MASK parameter.
  • JCLAM0250I Provides the physical name of the dataset file
  • JCLAM0256S "TO" date invalid "<TO parameter>"
  • JCLAM0257S "FOR" days invalid "<FOR parameter>"
  • JCLAM0258S Incorrect specification of expiration date.
  • JCLAM0259E Unexpired purge date. Entry "<dataset name>" not deleted.
  • JCLAM260S Invalid combination of parameters. "<parameter1, parameter2>"
  • JCLAM0261I Expiry date limited by management class.
Parent topic: JCLAM 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 -


JCLAM0232S Maximum ERROR LIMIT reached

Message

Too many errors have been detected. Further errors will not be reported.

Parent topic: JCLAM0231 -


JCLAM0233S Parameter value <value> is not within permitted range 0-4

Message

The parameter value is not within the permitted range.

Parent topic: JCLAM0231 -


JCLAM0234I Command bypassed. Condition code is <value>

Message

The command was bypassed with the specified condition code.

Parent topic: JCLAM0231 -


JCLAM0235E Insufficient authority to delete dataset <value> member.

Message

The job has been executed with insufficient authority to delete the specified dataset member.

Resolution

Rerun the job with the appropriate authority.

Parent topic: JCLAM0231 -


JCLAM0236E Duplicate record "record number"

A duplicate record error has been generated.

Resolution:

No action is required.

Parent topic: JCLAM0231 -


JCLAM0237S Rename/Replace failed. Catalog return code is <return code>

The rename of a catalog dataset failed due to an error reported by the catalog control module. Refer to Catalog Return Codes for a further explanation of the return code.

Parent topic: JCLAM0231 -
Related concepts
Catalog Return Codes


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 -


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 -


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 -


JCLAM0241E GDG Base not found "GDG base"

The GDG base generation could not be found in the catalog; GDG base is the name of the Generation Data Group.

Resolution:

Use IDCAMS DEFINE GENERATIONDATAGROUP to defined the GDG.

Parent topic: JCLAM0231 -


JCLAM0242I REPRO ignored - only valid for CLUSTER or PATH when dataset is VSAM

Message

A REPRO command was ignored because it is only valid for a CLUSTER or a PATH when the dataset is VSAM.

Parent topic: JCLAM0231 -


JCLAM0243U Dataset name <data-set> does not adhere to name restrictions

The data set name contravenes the naming rules.
Parent topic: JCLAM0231 -


JCLAM0244S MASK keyword required for DELETE of dataset name <data-set>

The data set, <data-set>, used a wildcard combination that also requires use of the MASK keyword.

Add the MASK keyword to your DELETE command.

Parent topic: JCLAM0231 -


JCLAM0245E No member names match the mask <ds-member-mask>

No members were found that conform to the wildcards used in the member name.
Parent topic: JCLAM0231 -


JCLAM0246E No entries found for mask <data-set>

No entries were found that conform to the wildcards used in the data set name.
Parent topic: JCLAM0231 -


JCLAM0247S MASK parameter not allowed for PDSM delete

You cannot use the MASK parameter when also specifying a PDS member.

The MASK parameter is not required when using wildcards in PDS member names.

Parent topic: JCLAM0231 -


JCLAM0248S Only 1 dataset permitted with MASK keyword

You cannot use multiple data set names with the MASK parameter.
Parent topic: JCLAM0231 -


JCLAM0250I Provides the physical name of the dataset file

Informational only.

Resolution:

No action is required.

Parent topic: JCLAM0231 -


JCLAM0256S "TO" date invalid "<TO parameter>"

Informational only.

Resolution:

No action is required.

Parent topic: JCLAM0231 -


JCLAM0257S "FOR" days invalid "<FOR parameter>"

Informational only.

Resolution:

No action is required.

Parent topic: JCLAM0231 -


JCLAM0258S Incorrect specification of expiration date.

The date calculated from the "TO" date is invalid.

Resolution:

Correct the parameter values used.

Parent topic: JCLAM0231 -


JCLAM0259E Unexpired purge date. Entry "<dataset name>" not deleted.

The dataset has not reached its expiration date, and the PURGE keyword was not used.

Resolution:

Use the PURGE keyword when removing unexpired datasets.

Note: You can see the expiration date of a dataset in the IDCAMS LISTCAT ALL command for the dataset.
Parent topic: JCLAM0231 -


JCLAM260S Invalid combination of parameters. "<parameter1, parameter2>"

The combination of parameter1 and parameter2 is not permitted.

Resolution:

Review the usage of these parameters and correct the JCL.

Parent topic: JCLAM0231 -


JCLAM0261I Expiry date limited by management class.

The value set for the expiration date of the dataset was limited by the management class.

Resolution:

No action required.

Parent topic: JCLAM0231 -


JCLCM Error Messages

Select the number of the message you require details about:

  • JCLCM0000 - JCLCM0199
  • JCLCM0200 - JCLCM0299
  • JCLCM0300 - JCLCM0399
  • 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 <cat-file> FS: <file-status>
    Reports the catalog file and the file status.
  • 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.
  • JCLCM0118E Unexpected error from function <value>
    An unexpected error occurred when executing the function detailed.
  • JCLCM0119E Previous JCLCM0118E message is for DD/DSN <value>.
    Details the DD/DSN for the error JCLCM0118E.
  • JCLCM0121
    The return type from the RJSE "get joblog" function was unexpected.
  • JCLCM0122E Incorrect password caused SAF failure on the host.
    An incorrect password causes a SAF failure on the host.
  • JCLCM0123E Expired password caused SAF failure on the host.
    The password expiration date has passed causing a SAF failure on the host.
  • JCLCM0124E Invalid user id caused SAF failure on the host.
    An invalid user id has been used to causing a SAF failure on the host.
  • JCLCM0125E <value> is not supported.
    The function detailed is not supported.
  • JCLCM0126E <value> is not yet supported.
    The function detailed is not currently supported.
  • JCLCM0127E Host dataset <value> unexpectedly created by alien job.
    The host dataset detailed was unexpectedly created by an external process.
  • JCLCM0128E Host dataset <value> unexpectedly deleted by alien job.
    The host dataset detailed was unexpectedly deleted by an external process.
  • JCLCM0129W LRECL of host RECFM F dataset <value> assumed to be 80.
    The LRECL for a Fixed LSEQ file is assumed to by 80.
  • JCLCM0130W LRECL of host RECFM V dataset <value> assumed to be 255.
    The LRECL for a LSEQ Variable file is assumed to by 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
    The JCL has been 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. If Abend and Cond Code Recovery are disabled, (e.g., #kNN), then the Cond Code value used for evaluations is NOT EXECUTED.
  • 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 PROGRAM NOT LOADED - <program name>. RTS CODE: <rts code>
    The specified program cannot be loaded.
  • 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 generation, using (+1) or (-1), but no GDG base 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


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 <cat-file> FS: <file-status>

Reports the catalog file and the file status.
Parent topic: JCLCM0000 - JCLCM0199


JCLCM0010W SYSOUT Limit limit exceeded by DD name

One of the output limits has been exceeded.

Resolution:

None.

Parent topic: JCLCM0000 - JCLCM0199


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


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


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


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.

Note: One or more non-JCL statements preceding the first STEP also generate a JCLCM0642U error.
Parent topic: JCLCM0000 - JCLCM0199
Related reference
JCLCM0642U Misplaced DD statement.


JCLCM0118E Unexpected error from function <value>

An unexpected error occurred when executing the function detailed.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0119E Previous JCLCM0118E message is for DD/DSN <value>.

Details the DD/DSN for the error JCLCM0118E.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0121

The return type from the RJSE "get joblog" function was unexpected.

This may be caused by a failure to retrieved the job log from the mainframe.

Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0122E Incorrect password caused SAF failure on the host.

An incorrect password causes a SAF failure on the host.
Resolution:
correct the password to allow the connection to succeed.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0123E Expired password caused SAF failure on the host.

The password expiration date has passed causing a SAF failure on the host.
Resolution:
Reset the expiration date for the password.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0124E Invalid user id caused SAF failure on the host.

An invalid user id has been used to causing a SAF failure on the host.
Resolution:
check and reset the password used.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0125E <value> is not supported.

The function detailed is not supported.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0126E <value> is not yet supported.

The function detailed is not currently supported.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0127E Host dataset <value> unexpectedly created by alien job.

The host dataset detailed was unexpectedly created by an external process.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0128E Host dataset <value> unexpectedly deleted by alien job.

The host dataset detailed was unexpectedly deleted by an external process.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0129W LRECL of host RECFM F dataset <value> assumed to be 80.

The LRECL for a Fixed LSEQ file is assumed to by 80.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


JCLCM0130W LRECL of host RECFM V dataset <value> assumed to be 255.

The LRECL for a LSEQ Variable file is assumed to by 255.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
RJSE Error Messages


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 OpenText Support for Micro Focus Products 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


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 OpenText Support for Micro Focus Products.

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


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


JCLCM0169I JCL copied

The JCL has been copied.
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


JCLCM0180I job-number job-name Job ready for execution.

The job named is ready for execution.
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. If Abend and Cond Code Recovery are disabled, (e.g., #kNN), then the Cond Code value used for evaluations is NOT EXECUTED.
Parent topic: JCLCM0000 - JCLCM0199
Related concepts
Processing during restart


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 PROGRAM NOT LOADED - <program name>. RTS CODE: <rts code>

The specified program cannot be loaded.

Resolution:

Refer to the Run-time System Error Messages section for more information on the <rts code>, and then take any appropriate action given.

Parent topic: JCLCM0000 - JCLCM0199
Related concepts
Run-time System Error Messages


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 generation, using (+1) or (-1), but no GDG base by the same name exists in the catalog.

Resolution:

Define the GDG base 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


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 (base) present
  • 006 - gdg max < 1 or > 99
  • 007 - gdg roll disp is incorrect
  • 008 - charset is not ascii, ebcdic or unknown
  • 009 - the PC-DSN (physical file name) is not valid for a Dynamic PDS
  • 082 - failed to open I-O catalog file
  • 083 - unable to allocate host PDS members
  • 086 - file read/write error
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


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


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
  • Big-Endian
amode-type
One of:
  • AMODE31
  • AMODE24
  • NOAMODE
Parent topic: JCLCM0000 - JCLCM0199


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.
  • JCLCM0204S GDG MODEL LOCKED - <value>
    The GDG model (base) specified has been locked.
  • 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.
  • JCLCM0220I Job restart will not be permitted at this step.
    An informational message indicating that a job restart is not permitted at the current step.
  • JCLCM0232I Scanned input DSN <dataset>
    An informational message detailing the dataset that was scanned.
  • JCLCM0233I Parsed input DSN <dataset>
    An informational message detailing the dataset that was parsed.
  • JCLCM0243U Unable to access catalog file for dataset <data-set>, <cat-file>, FS: <file-status>
    Reports the dataset that was requested, the catalog file that was being read, and the file status.
  • JCLCM0260W <JOBLIB|STEPLIB> dataset <Library Name> is a Dynamic PO and would not be loaded when using enhanced security settings
  • JCLCM0261E <JOBLIB|STEPLIB> dataset <Library Name> is a Dynamic PO and will not be loaded. Dynamic PDS entries for load modules are NOT permitted under enhanced JCL security
  • JCLCM0262W "PROGRAM" security class not defined - Program <Program Name> in library <Library Name> would not be run under higher level JCL security
  • JCLAM0263S Number of records to be skipped exceeds the number to be copied
    The number of records read during the REPRO was less than the number to be skipped.
  • JCLCM0263W User <User ID> does not have permission to run program <Program Name> in library <Library Name>. Program would not be run under higher level JCL security
  • JCLCM0264S User <User ID> does not have permission to run program <Program Name> in library <Library Name>
  • JCLCM0265S User <User ID> does not have permission to run program <Program Name> in library <Library Name>
  • JCLCM0266W "PHYSFILE" security class not defined - Creation of physical dataset <Physical Dataset Location> would not be permitted under higher level JCL security
Parent topic: JCLCM Error Messages


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
Related information
MF_UCC11


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


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


JCLCM0204S GDG MODEL LOCKED - <value>

The GDG model (base) specified has been locked.
Parent topic: JCLCM0200 - JCLCM0299


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 OpenText Support for Micro Focus Products. 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 OpenText Support for Micro Focus Products.

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


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


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 OpenText Support for Micro Focus Products.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0217S Internal system error "internal code"

Internal error.

Resolution:

Contact OpenText Support for Micro Focus Products. Please mention the internal code.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0218S System error "internal code"

System error.

Resolution:

Contact OpenText Support for Micro Focus Products. Please mention the internal code.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0220I Job restart will not be permitted at this step.

An informational message indicating that a job restart is not permitted at the current step.
Parent topic: JCLCM0200 - JCLCM0299


JCLCM0232I Scanned input DSN <dataset>

An informational message detailing the dataset that was scanned.
Parent topic: JCLCM0200 - JCLCM0299


JCLCM0233I Parsed input DSN <dataset>

An informational message detailing the dataset that was parsed.
Parent topic: JCLCM0200 - JCLCM0299


JCLCM0243U Unable to access catalog file for dataset <data-set>, <cat-file>, FS: <file-status>

Reports the dataset that was requested, the catalog file that was being read, and the file status.
Parent topic: JCLCM0200 - JCLCM0299


JCLCM0260W <JOBLIB|STEPLIB> dataset <Library Name> is a Dynamic PO and would not be loaded when using enhanced security settings

This warning message is issued when a JOBLIB or STEPLIB dataset is a dynamic PDS and the ES_JES_HIGHER_SECURITY_LEVEL=1 (NONE) or is not set. Programs should be moved to static PDS so that they can be loaded when running under higher security settings.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0261E <JOBLIB|STEPLIB> dataset <Library Name> is a Dynamic PO and will not be loaded. Dynamic PDS entries for load modules are NOT permitted under enhanced JCL security

This message is issued when a JOBLIB or STEPLIB program is in a dynamic PDS and one of the higher security levels is set (2 or greater).

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0262W "PROGRAM" security class not defined - Program <Program Name> in library <Library Name> would not be run under higher level JCL security

When running with the higher security level of ENHANCED the 'PROGRAM' class must be defined within your security configuration. When running with the higher security level of 'WARN' this warning message will be issued if the PROGRAM class has not been defined.

Parent topic: JCLCM0200 - JCLCM0299


JCLAM0263S Number of records to be skipped exceeds the number to be copied

The number of records read during the REPRO was less than the number to be skipped.
Parent topic: JCLCM0200 - JCLCM0299


JCLCM0263W User <User ID> does not have permission to run program <Program Name> in library <Library Name>. Program would not be run under higher level JCL security

The user does not have PROGRAM permission to run the program.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0264S User <User ID> does not have permission to run program <Program Name> in library <Library Name>

The user does not have PROGRAM permission to run the program.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0265S User <User ID> does not have permission to run program <Program Name> in library <Library Name>

"PROGRAM" security class not defined in security configuration.

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0266W "PHYSFILE" security class not defined - Creation of physical dataset <Physical Dataset Location> would not be permitted under higher level JCL security

Parent topic: JCLCM0200 - JCLCM0299


JCLCM0300 - JCLCM0399

  • JCLCM0301I Procedure proc-name was expanded using the librarylibrary-name
    The specified procedure was expended using the specified library.
  • JCLCM0302I Include group member-name was expanded using the librarylibrary-name
    The specified group was expended using the specified library.
  • JCLCM0303I Program <Program Name> loaded from library <Library Name>
  • JCLCM0304E Error loading program <Program Name> from library <Library Name>. RC: <RTS Error Code>
  • JCLCM0305I Failed to find program program-name in private libraries and SYS1.LNKLIB
  • JCLCM0306I Number of SYS1.LNKLIB entries: <Number of entries>
  • JCLCM0307I SYS1.LNKLIB : <List of SYS1.LNKLIB entries>
  • JCLCM0308W Program program-name is loaded from Dymanic PO loadlib and would not be loaded when using enhanced security settings.
    This warning message is issued when a program is loaded from a Dynamic PDS and the ES_JES_HIGHER_SECURITY_LEVEL=1 (NONE) or is not set. Such locations for programs would not be permitted under enhanced JCL security.
Parent topic: JCLCM Error Messages


JCLCM0301I Procedure proc-name was expanded using the librarylibrary-name

The specified procedure was expended using the specified library.
Parent topic: JCLCM0300 - JCLCM0399


JCLCM0302I Include group member-name was expanded using the librarylibrary-name

The specified group was expended using the specified library.
Parent topic: JCLCM0300 - JCLCM0399


JCLCM0303I Program <Program Name> loaded from library <Library Name>

Parent topic: JCLCM0300 - JCLCM0399


JCLCM0304E Error loading program <Program Name> from library <Library Name>. RC: <RTS Error Code>

Parent topic: JCLCM0300 - JCLCM0399


JCLCM0305I Failed to find program program-name in private libraries and SYS1.LNKLIB

The specified program was not found in any of the defined private libraries or in the default SYS1.LNKLIB library.

Resolution:

This problem is related to enhanced JCL security checks. See JCL Enhanced Security Checks for more information.

Parent topic: JCLCM0300 - JCLCM0399


JCLCM0306I Number of SYS1.LNKLIB entries: <Number of entries>

Parent topic: JCLCM0300 - JCLCM0399


JCLCM0307I SYS1.LNKLIB : <List of SYS1.LNKLIB entries>

Parent topic: JCLCM0300 - JCLCM0399


JCLCM0308W Program program-name is loaded from Dymanic PO loadlib and would not be loaded when using enhanced security settings.

This warning message is issued when a program is loaded from a Dynamic PDS and the ES_JES_HIGHER_SECURITY_LEVEL=1 (NONE) or is not set. Such locations for programs would not be permitted under enhanced JCL security.
Note: You can suppress this message by setting ES_JES_HIGHER_SECURITY_LEVEL=0.

Resolution:

Move programs to static PDSs so that they can be loaded when running under higher security settings.

Parent topic: JCLCM0300 - JCLCM0399
Related reference
ES_JES_HIGHER_SECURITY_LEVEL


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
    The number of EXEC statements specified has exceeded the limit.
  • JCLCM0478E Missing OUTPUT statement label.
    The OUTPUT statement label is missing.
  • JCLCM0479E DEFAULT parameter <value> is invalid.
    Teh parameter specified for DEFAULT is invalid.
  • JCLCM0480E Duplicate OUTPUT statement label <value>.
    A duplicate OUTPUT statement for the label detailed has been found.
  • JCLCM0481E OUTPUT reference <value> is invalid unknown or illegal.
    The OUTPUT reference detailed is not recognized.
  • JCLCM0482E More than 128 OUTPUT= references.
    The number of OUTPUT= references has exceeded the supported limit.
  • JCLCM0483E More than 65536 OUTPUT statements.
    The number of OUTPUT statements has exceeded the supported limit.
  • JCLCM0484S More than 1 EXEC statement in a SSTM Job.
    Only 1 EXEC statement is permitted for an SSTM job.
  • JCLCM0485E JES2 statement <value> is invalid.
    The JES2 statement detailed is not recognised.
  • 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
  • JCLCM0499I FILE IS EMPTY
    The JCL file is empty.
Parent topic: JCLCM Error Messages


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


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


JCLCM0408I UNKNOWN OUTPUT STMT OPERAND IGNORED

You have used an unknown keyword.
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


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


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


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


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


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


JCLCM0477S More than 255 EXEC statements

The number of EXEC statements specified has exceeded the limit.
Resolution:
Reduce the number of EXEC statements to 255 or less.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0478E Missing OUTPUT statement label.

The OUTPUT statement label is missing.
Resolution:
Insert an OUTPUT statement label.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0479E DEFAULT parameter <value> is invalid.

Teh parameter specified for DEFAULT is invalid.
Resolution:
Correct the parameter.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0480E Duplicate OUTPUT statement label <value>.

A duplicate OUTPUT statement for the label detailed has been found.
Resolution:
Remove the duplicate OUTPUT statement label.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0481E OUTPUT reference <value> is invalid unknown or illegal.

The OUTPUT reference detailed is not recognized.
Resolution:
the reference may be unknown or could have been mispelt. Correct the reference.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0482E More than 128 OUTPUT= references.

The number of OUTPUT= references has exceeded the supported limit.
Resolution:
Reduce the number of OUTPUT= references to 128 or less.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0483E More than 65536 OUTPUT statements.

The number of OUTPUT statements has exceeded the supported limit.
Resolution:
Reduce the number of OUTPUT statements to 65535 or less.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0484S More than 1 EXEC statement in a SSTM Job.

Only 1 EXEC statement is permitted for an SSTM job.
Resolution:
Ensure any SSTM job has only 1 EXEC statement.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0485E JES2 statement <value> is invalid.

The JES2 statement detailed is not recognised.
Resolution:
Check the spelling of the statement. Check the statement is supported.
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


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


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


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


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


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


JCLCM0499I FILE IS EMPTY

The JCL file is empty.
Parent topic: JCLCM0400 - JCLCM0499


JCLCM0500 - JCLCM0599

  • JCLCM0500E SPACE parameter <value> is invalid or misplaced.
    The parametmer specified is invalid or mispelt.
  • JCLCM0501E UNIT parameter <value> is invalid or misplaced.
    The parametmer specified is invalid or mispelt.
  • JCLCM0502E VOLUME parameter <value> is invalid or misplaced.
    The parametmer specified is invalid or mispelt.
  • JCLCM0503E Invalid USER parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0504E TYPEXEC parameter <value> is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0505E DSNTYPE parameter <value> is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0506E account parameter or its length in error.
    The parametmer specified is invalid or mispelt.
  • JCLCM0507E programmer parameter or its length in error.
    The parametmer specified is invalid or mispelt.
  • JCLCM0508E Invalid ACCODE parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0509E Invalid CCSID parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0510E Invalid BYTES parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0511E Invalid CARDS parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0512E Invalid GROUP parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0513E Invalid LINES parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0514E Invalid NOTIFY parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0515E Invalid PAGES parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0516E Invalid PASSWORD parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0517E PARM parameter or its length in error.
    The parametmer specified is invalid or mispelt.
  • JCLCM0518E Invalid RESTART parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0519E Invalid SECLABEL parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0520E Invalid UPLOAD parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0521E Invalid DOWNLOAD parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0522E Invalid MEMBER parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0523E Invalid PCDSN parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0524E COPIES parameter <value> has invalid value or syntax.
    The parametmer specified is invalid or mispelt.
  • JCLCM0525E Excess COPIES specification <value> rejected.
    The parametmer specified is invalid or mispelt.
  • JCLCM0526E FCB parameter <value> has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0527E FLASH parameter <value> has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0528E HOLD parameter <value> has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0529E PRTSP parameter <value> has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0530E SPIN parameter <value> has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0531E TRTCH parameter <value> is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0532E <value> parameter is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0533E <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0534E CHARSET parameter <value> is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0535E /*ROUTE parameter <value> is invalid or too long.
    The parametmer specified is invalid or mispelt.
  • JCLCM0536E ADDRESS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0537E BUILDING <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0538E BURST <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0539E CHARS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0540E CKPTLINE <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0541E CKPTPAGE <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0542E CKPTSEC <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0543E CLASS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0544E COLORMAP <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0545E COMPACT <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0546E COMSETUP <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0547E CONTROL <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0548E COPIES <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0549E DATACK <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0550E DEFAULT <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0551E DEPT <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0552E DEST <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0553E DPAGELBL <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0554E DUPLEX <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0555E FCB <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0556E FLASH <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0557E FORMDEF <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0558E FORMLEN <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0559E FORMS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0560E FSSDATA <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0561E GROUPID <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0562E INDEX <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0563E INTRAY <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0564E JESDS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0565E LINDEX <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0566E LINECT <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0567E MODIFY <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0568E NAME <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0569E NOTIFY <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0570E OFFSETXB <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0571E OFFSETXF <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0572E OFFSETYB <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0573E OFFSETYF <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0574E OUTBIN <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0575E OUTDISP <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0576E OVERLAYB <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0577E OVERLAYF <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0578E OVFL <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0579E PAGEDEF <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0580E PIMSG <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0599I Excess VOLUME specification <value> ignored.
    The parametmer specified is invalid or mispelt.
Parent topic: JCLCM Error Messages


JCLCM0500E SPACE parameter <value> is invalid or misplaced.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0501E UNIT parameter <value> is invalid or misplaced.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0502E VOLUME parameter <value> is invalid or misplaced.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0503E Invalid USER parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0504E TYPEXEC parameter <value> is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0505E DSNTYPE parameter <value> is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0506E account parameter or its length in error.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0507E programmer parameter or its length in error.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0508E Invalid ACCODE parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0509E Invalid CCSID parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0510E Invalid BYTES parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0511E Invalid CARDS parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0512E Invalid GROUP parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0513E Invalid LINES parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0514E Invalid NOTIFY parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0515E Invalid PAGES parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0516E Invalid PASSWORD parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0517E PARM parameter or its length in error.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0518E Invalid RESTART parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0519E Invalid SECLABEL parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0520E Invalid UPLOAD parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0521E Invalid DOWNLOAD parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0522E Invalid MEMBER parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0523E Invalid PCDSN parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0524E COPIES parameter <value> has invalid value or syntax.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0525E Excess COPIES specification <value> rejected.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0526E FCB parameter <value> has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0527E FLASH parameter <value> has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0528E HOLD parameter <value> has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0529E PRTSP parameter <value> has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0530E SPIN parameter <value> has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0531E TRTCH parameter <value> is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0532E <value> parameter is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0533E <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0534E CHARSET parameter <value> is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0535E /*ROUTE parameter <value> is invalid or too long.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0536E ADDRESS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0537E BUILDING <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0538E BURST <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0539E CHARS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0540E CKPTLINE <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0541E CKPTPAGE <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0542E CKPTSEC <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0543E CLASS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0544E COLORMAP <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0545E COMPACT <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0546E COMSETUP <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0547E CONTROL <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0548E COPIES <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0549E DATACK <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0550E DEFAULT <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0551E DEPT <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0552E DEST <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0553E DPAGELBL <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0554E DUPLEX <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0555E FCB <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0556E FLASH <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0557E FORMDEF <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0558E FORMLEN <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0559E FORMS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0560E FSSDATA <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0561E GROUPID <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0562E INDEX <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0563E INTRAY <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0564E JESDS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0565E LINDEX <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0566E LINECT <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0567E MODIFY <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0568E NAME <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0569E NOTIFY <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0570E OFFSETXB <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0571E OFFSETXF <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0572E OFFSETYB <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0573E OFFSETYF <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0574E OUTBIN <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0575E OUTDISP <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0576E OVERLAYB <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0577E OVERLAYF <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0578E OVFL <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0579E PAGEDEF <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0580E PIMSG <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0599I Excess VOLUME specification <value> ignored.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0500 - JCLCM0599


JCLCM0600 - JCLCM0699

  • JCLCM0600E PORTNO <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0601E PRMODE <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0602E PRTERROR <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0603E PRTOPTNS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0604E PRTQUEUE <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0605E PRTY <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0606E RESFMT <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0607E RETAINS/RETAINF <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0608E RETRYL/RETRYT <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0609E ROOM <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0610E SYSAREA <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0611E THRESHLD <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0612E TITLE <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0613E TRC <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0614E UCS <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0615E USERDATA <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0616E USERLIB <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0617E WRITER <value> parameter has invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0618E Excess operand(s) starting with <value> are ignored.
    Too many operands starting with the value given have been detected.
  • JCLCM0619E LSEQRECF parameter <value> is invalid.
    The parameter specified is invalid or misspelled.
  • JCLCM0620E RESTART parameter <value> is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0621E HOSTJOB parameter <value> is invalid.
    The parametmer specified is invalid or mispelt.
  • JCLCM0622U System error writing <value> file.
    An error occurred writing to an internal JES file.
  • JCLCM0623E SUBSYS parameter <value> is longer than 2698 bytes.
    The SUBSYS parameter value has exceeded the allowed limit.
  • JCLCM0624E JESLOG parameter has an invalid value.
    The parametmer specified is invalid or mispelt.
  • JCLCM0625E Invalid RELATED parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0626E Invalid HLQ parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0627E Invalid CATMAINT parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0628E Invalid MFA parameter.
    The parametmer specified is invalid or mispelt.
  • JCLCM0629E Invalid JOBRC parameter.
    The parameter specified is invalid or misspelled.
  • JCLCM0630E User user-name has insufficient authority to access dataset dataset-name
    This message is reported when the user does not have permission to access the dataset.
  • JCLCM0640U Too many duplicate DD statements for DD <DD NAME>.
    The number of duplicate DD statements for the DD name has exceeded the 999 limit.
  • JCLCM0642U Misplaced DD statement.
    One or more non-JCL statements, such blank lines, were detected in a JCL job preceding the first STEP entry.
  • JCLCM0643E Invalid parameter for DSENQSHR value
    The value of the DSENQSHR parameter is incorrect. Valid values are ALLOW, USEJC, and DISALLOW.
  • JCLCM0644I EXPDT specifies zero days.
    The value of the days sub-parameter of the EXPDT parameter is zero. This value is accepted and stored.
Parent topic: JCLCM Error Messages


JCLCM0600E PORTNO <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0601E PRMODE <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0602E PRTERROR <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0603E PRTOPTNS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0604E PRTQUEUE <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0605E PRTY <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0606E RESFMT <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0607E RETAINS/RETAINF <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0608E RETRYL/RETRYT <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0609E ROOM <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0610E SYSAREA <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0611E THRESHLD <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0612E TITLE <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0613E TRC <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0614E UCS <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0615E USERDATA <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0616E USERLIB <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0617E WRITER <value> parameter has invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0618E Excess operand(s) starting with <value> are ignored.

Too many operands starting with the value given have been detected.
Resolution:
Check that the number of operands is within the limit for this type.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0619E LSEQRECF parameter <value> is invalid.

The parameter specified is invalid or misspelled.

See RECFM=LSEQ Datasets for details of supported options.

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0620E RESTART parameter <value> is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0621E HOSTJOB parameter <value> is invalid.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0622U System error writing <value> file.

An error occurred writing to an internal JES file.
Resolution:
Check that the Default Allocation Location or spool file location can be written to, that the disk is not full or the system constrained. If the error continues please contact your Micro Focus support engineer.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0623E SUBSYS parameter <value> is longer than 2698 bytes.

The SUBSYS parameter value has exceeded the allowed limit.
Resolution:
Reduce the SUBSYS parameter limit to 2698 or below.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0624E JESLOG parameter has an invalid value.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0625E Invalid RELATED parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0626E Invalid HLQ parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0627E Invalid CATMAINT parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0628E Invalid MFA parameter.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0629E Invalid JOBRC parameter.

The parameter specified is invalid or misspelled.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0630E User user-name has insufficient authority to access dataset dataset-name

This message is reported when the user does not have permission to access the dataset.

Resolution:

Check the user security permissions and change if required - see Resource Classes for JES Security for more information.

Parent topic: JCLCM0600 - JCLCM0699
Related concepts
Resource Classes for JES Security


JCLCM0640U Too many duplicate DD statements for DD <DD NAME>.

The number of duplicate DD statements for the DD name has exceeded the 999 limit.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0642U Misplaced DD statement.

One or more non-JCL statements, such blank lines, were detected in a JCL job preceding the first STEP entry.
Note: This error is preceded by the following generated //SYSIN statement:
//SYSIN DD * ***MFE JCL GENERATED STMT*** For more info, see
JCLCM0094I
Resolution:
Correct the JCL code to remove non-JCL statements.
Parent topic: JCLCM0600 - JCLCM0699
Related reference
JCLCM0094I Non-JCL record in the input stream has caused this SYSIN DD statement to be generated.


JCLCM0643E Invalid parameter for DSENQSHR value

The value of the DSENQSHR parameter is incorrect. Valid values are ALLOW, USEJC, and DISALLOW.

Resolution:

Correct the value and resubmit the job.

Parent topic: JCLCM0600 - JCLCM0699


JCLCM0644I EXPDT specifies zero days.

The value of the days sub-parameter of the EXPDT parameter is zero. This value is accepted and stored.
Parent topic: JCLCM0600 - JCLCM0699


JCLCM0800 - JCLCM0899

  • JCLCM0801I Event-job-concluded. Job ended normally.
    The parametmer specified is invalid or mispelt.
  • JCLCM0802I Event-job-concluded. Job ended abnormally.
    The Job ended abnormally.
  • JCLCM0803I Event-job-concluded. Job failed - JCL error.
    The Job failed due to a JCL error.
  • JCLCM0804I Event-job-concluded. Job scanned - No Errors.
    The Job was scanned and no errors were identified.
  • JCLCM0805I Event-job-concluded. Job scanned - JCL error.
    The Job was scanned and JCL errors were identified.
  • JCLCM0806I Event-job-concluded. Job flushed - No JOB stmt.
    The Job was flush - no statements found.
  • JCLCM0807I Event-job-concluded. Job flushed - Bad JOB stmt.
    The Job was flushed - A bad statement was identified.
  • JCLCM0808I Event-job-concluded. Job flushed by User Exit req.
    The Job was flushed by a user exit request.
  • JCLCM0809I Event-job-concluded. Job copied
    Job copied.
  • JCLCM0810I Event-job-concluded. Job cancelled.
    The Job has been cancelled.
  • JCLCM0811I Event-job-concluded. Job authentication failed.
    Authentication for job failed check ????????.
  • JCLCM0812I Event-job-concluded. Catalog file error
    JCL Event message indicating the job was concluded because of a catalog file error.
Parent topic: JCLCM Error Messages


JCLCM0801I Event-job-concluded. Job ended normally.

The parametmer specified is invalid or mispelt.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0802I Event-job-concluded. Job ended abnormally.

The Job ended abnormally.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0803I Event-job-concluded. Job failed - JCL error.

The Job failed due to a JCL error.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0804I Event-job-concluded. Job scanned - No Errors.

The Job was scanned and no errors were identified.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0805I Event-job-concluded. Job scanned - JCL error.

The Job was scanned and JCL errors were identified.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0806I Event-job-concluded. Job flushed - No JOB stmt.

The Job was flush - no statements found.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0807I Event-job-concluded. Job flushed - Bad JOB stmt.

The Job was flushed - A bad statement was identified.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0808I Event-job-concluded. Job flushed by User Exit req.

The Job was flushed by a user exit request.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0809I Event-job-concluded. Job copied

Job copied.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0810I Event-job-concluded. Job cancelled.

The Job has been cancelled.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0811I Event-job-concluded. Job authentication failed.

Authentication for job failed check ????????.
Parent topic: JCLCM0800 - JCLCM0899


JCLCM0812I Event-job-concluded. Catalog file error

JCL Event message indicating the job was concluded because of a catalog file error.
Parent topic: JCLCM0800 - JCLCM0899


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.
  • JCLCM0925I Event-job-stmt-info action is: <value>.
    The value is the action specified by the user exit.
  • JCLCM0927I Event-job-queued. Queue: <value>.
    The job has been added to the Queue specified.
  • JCLCM0928I Event-job-restart action is: <value>.
    The <value> is the action specified by the user exit.
  • JCLCM0945I GDG model dataset-name current high version has been reset from original-value to new-value.
    The value of the current high version, which is used to calculate the relative version of a GDG dataset, has been changed to allow the same versions to be used in a restarted job as in the original.
  • JCLCM0940S All steps have been bypassed.
    No steps were executed, possibly because of conditional checks. The job COND CODE is set to a value of 8.
  • JCLCM0941I STEP step-name not executed due to restart decision.
    Indicates a step that was skipped because of a restart setting. For example, when a restart is configured to start with STEP02, this message reports that STEP01 was skipped.
  • JCLCM0942I Number of steps skipped on restart number-of-steps.
    Indicates the number of steps that were skipped before the first step that was actually executed.
  • JCLCM0943I Total number of steps skipped on restart number-of-steps.
    Indicates the number of steps that were skipped before the first step that was actually executed when the range of steps has been constrained by a TO step (#t parameter).
  • JCLCM0944I STEP step-name Cond Code "previous-cc-value" is used in evaluations.
    When Abend and Cond Code recovery has been enabled, this message indicates that the last time step-name ran, it returned the referenced CC value, which has been used in evaluations.
  • JCLCM0946I GDG model dataset-name empty count has been reset from original-value to new-value.
    On restarting a job, the empty count for the GDG model has been changed from the current value to the value used at the start of the original job.
  • JCLCM0960E Authorization failed for job
  • JCLCM0961E User authorization failed for job
  • JCLCM0962E User authorization failed for job, invalid password
  • JCLCM0963E User authorization failed for job, password expired
  • JCLCM0964E User authorization failed for job, ID error
  • JCLCM0965E User authorization failed for job, ID not in group
  • JCLCM0966E User authorization failed for job, ID revoked
  • JCLCM0999I JobDiag: <value>.
    Display the JobDiag value.
Parent topic: JCLCM Error Messages


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


JCLCM0925I Event-job-stmt-info action is: <value>.

The value is the action specified by the user exit.
Resolution:
See the documentation about MFJUXIT for action options.
Parent topic: JCLCM0900 - JCLCM0999


JCLCM0927I Event-job-queued. Queue: <value>.

The job has been added to the Queue specified.
Parent topic: JCLCM0900 - JCLCM0999


JCLCM0928I Event-job-restart action is: <value>.

The <value> is the action specified by the user exit.
Parent topic: JCLCM0900 - JCLCM0999


JCLCM0945I GDG model dataset-name current high version has been reset from original-value to new-value.

The value of the current high version, which is used to calculate the relative version of a GDG dataset, has been changed to allow the same versions to be used in a restarted job as in the original.
Parent topic: JCLCM0900 - JCLCM0999
Related concepts
GDG Processing during Restart


JCLCM0940S All steps have been bypassed.

No steps were executed, possibly because of conditional checks. The job COND CODE is set to a value of 8.
Parent topic: JCLCM0900 - JCLCM0999
Related concepts
Processing during restart


JCLCM0941I STEP step-name not executed due to restart decision.

Indicates a step that was skipped because of a restart setting. For example, when a restart is configured to start with STEP02, this message reports that STEP01 was skipped.
Parent topic: JCLCM0900 - JCLCM0999
Related concepts
Processing during restart


JCLCM0942I Number of steps skipped on restart number-of-steps.

Indicates the number of steps that were skipped before the first step that was actually executed.
Parent topic: JCLCM0900 - JCLCM0999
Related concepts
Processing during restart


JCLCM0943I Total number of steps skipped on restart number-of-steps.

Indicates the number of steps that were skipped before the first step that was actually executed when the range of steps has been constrained by a TO step (#t parameter).
Parent topic: JCLCM0900 - JCLCM0999
Related concepts
Processing during restart


JCLCM0944I STEP step-name Cond Code "previous-cc-value" is used in evaluations.

When Abend and Cond Code recovery has been enabled, this message indicates that the last time step-name ran, it returned the referenced CC value, which has been used in evaluations.
Parent topic: JCLCM0900 - JCLCM0999


JCLCM0946I GDG model dataset-name empty count has been reset from original-value to new-value.

On restarting a job, the empty count for the GDG model has been changed from the current value to the value used at the start of the original job.
Parent topic: JCLCM0900 - JCLCM0999
Related concepts
GDG Processing during Restart


JCLCM0960E Authorization failed for job

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0961E User authorization failed for job

You have specified invalid credentials for this job.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0962E User authorization failed for job, invalid password

You have specified an invalid password.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0963E User authorization failed for job, password expired

The password for the specified user has expired.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0964E User authorization failed for job, ID error

An incorrect user name has been specified.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0965E User authorization failed for job, ID not in group

The specified user name is not included in the group.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0966E User authorization failed for job, ID revoked

The user name has been revoked.

Parent topic: JCLCM0900 - JCLCM0999


JCLCM0999I JobDiag: <value>.

Display the JobDiag value.
Parent topic: JCLCM0900 - JCLCM0999


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.
  • JCLCM2000E Unable to acquire global lock for job <value>.
    A global lock could not be acquired for job.
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


JCLCM2000E Unable to acquire global lock for job <value>.

A global lock could not be acquired for job.
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
  • JCLGN0009U MISSING 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 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


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


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


JCLGN0007U MISSING SYSPRINT

Message

SYSPRINT has not been defined.

Resolution

Define the SYSPRINT dataset in the jobstep.

Parent topic: JCLGN Error Messages


JCLGN0009U MISSING SYSIN

Message

A definition for SYSIN is missing from your job.

Resolution

Ensure there is a definition for SYSIN in your job.

Parent topic: JCLGN Error Messages


JCLGN0011U I/O ERROR ON SYSPRINT

Message

A file I/O error has occurred while accessing SYSPRINT.

Resolution

Look up the file status detailed in the message in order to understand and resolve the issue.

Parent topic: JCLGN Error Messages


JCLGN0012U I/O ERROR ON SYSIN

Message

A file I/O error has occurred when accessing SYSIN.

Resolution

Check the file status code specified in the following message for information about the issue and about how to fix it.

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.

Message

The DSORG specified for the dataset has not been recognized.

Resolution

Ensure that the value of DSORG is valid.

Parent topic: JCLGN Error Messages


JCLGN0102U I/O ERROR ON filename

Message

A file I/O error has occurred while accessing the file detailed in JCLGN0103U.

Resolution

Check the file status code specified in the following message for information about the issue and about how to fix it.

Parent topic: JCLGN Error Messages


JCLGN0103U I/O STATUS = file status

Message

Reports an unexpected file status for a file detailed in the previous message, JCLGN0102U.

Resolution

Search for the file status code in the File Handler section of the product help for information about the issue and about how to fix it.

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

Message

Specifies the number of records copied from sysut1 to sysut2.

Parent topic: JCLGN Error Messages


JCLGN0111I number RECORDS COPIED

Message

The specified number of records have been copied to member name detailed in JCLGN0112.

Parent topic: JCLGN Error Messages


JCLGN0112I TO MEMBER NAME name

Message

See JCLGN0111.

Parent topic: JCLGN Error Messages


JCLGN0200E PARAMETER TOO LONG [value]

Message

A parameter exceeds the maximum allowed length of 128.

Resolution

Ensure that the size of the parameter is within the supported limits.

Parent topic: JCLGN Error Messages


JCLGN0201E CONTINUATION ERROR [value]

Message

A line has been continued across multiple lines and has caused an error.

Resolution

Check that continuation is present and is in the correct place.

Parent topic: JCLGN Error Messages


JCLGN0202E MISMATCHED QUOTES OR PARENTHESIS [value]

Message

A matching end quote or parenthesis is missing.

Resolution

Ensure that opening quotes or parenthesis have a matching end quote or parenthesis.

Parent topic: JCLGN Error Messages


JCLGN0210E UNRECOGNIZED OPERATOR KEYWORD [value]

Message

An operator keyword has not been recognized.

Resolution

Check that the spelling of the operand keyword and whether it is supported.

Parent topic: JCLGN Error Messages


JCLGN0211E DUPLICATE CONTROL STATEMENT [value]

Message

A control statement been used multiple times.

Resolution

Correct your job to remove the duplicate statements.

Parent topic: JCLGN Error Messages


JCLGN0220E UNRECOGNIZED OPERAND KEYWORD [value]

Message

The specified operand keyword has not been recognized.

Resolution

Check that the spelling of the operand keyword and whether it is supported.

Parent topic: JCLGN Error Messages


JCLGN0221E DUPLICATE OPERAND KEYWORD [value]

Message

An operand keyword has been used multiple times.

Resolution

Correct your job to remove the duplicate operand keywords.

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


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 value
  • 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 value
  • JCLIM0208U - I/O Error On value
Parent topic: JCL 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 OpenText Support for Micro Focus Products.

Parent topic: JCLIM Error Messages


JCLIM0005U - Program Parm Contains Invalid Character value

Message

The program parm contains an invalid character.

Resolution

Recode the parm to avoid the invalid character.

Parent topic: JCLIM Error Messages


JCLIM0201U MISSING DDITV02 DD STATEMENT

Message

A DDITV02 statement has not been found.

Resolution

Update your job to include a DDITV02 statement.

Parent topic: JCLIM Error Messages


JCLIM0202U INVALID DDITV02 PARM STATEMENT

Message

An invalid DDITV02 parm statement has been detected.

Parent topic: JCLIM Error Messages


JCLIM0203U INVALID DDITV02 PROGRAM PARM

Message

An invalid DDITV02 program parm has been detected.

Parent topic: JCLIM Error Messages


JCLIM0204U I/O ERROR ON DDITV02 DATASET

Message

A file I/O error has been detected for DDITV02.

Parent topic: JCLIM Error Messages


JCLIM0205U - Missing DD Statement nnnnnn

Message

A DD statement was not found for SYSIPT.

Resolution

Recode your JCO to include a DD statement for SYSIPT.

Parent topic: JCLIM Error Messages


JCLIM0206U - Invalid Dsorg For n

Message

The specified dataset has an invalid DSORG.

Resolution

Correct the DSORG for the DATASET to be either none, ps, psu, po, pou or pdsm.

Parent topic: JCLIM Error Messages


JCLIM0207U - Invalid/Missing Control Statement On value

Message

The control statement is either missing or invalid for the job.

Parent topic: JCLIM Error Messages


JCLIM0208U - I/O Error On value

Message

A file I/O error has occurred when accessing the specified dataset.

Resolution

Check the information on file statuses in the product help to understand the cause of the issue.

Parent topic: JCLIM Error Messages


JCLPT Error Messages

  • JCLPT0001E PRINT/PUNCH statement not first
  • JCLPT0002E MEMBER INVALID - TYPORG not PO
  • JCLPT0003E INVALID COMMAND - no MAXNAME parameter
  • JCLPT0004E INVALID COMMAND - RECORD command already found
  • JCLPT0005E MAXNAME parameter is too small
  • JCLPT0006E INVALID COMMAND - NO NAME parameter
  • JCLPT0007E MORE THAN TWO TITLE CARDS
  • JCLPT0008E Unrecognised command - [command]
  • JCLPT0009E SYSIN IS EMPTY
  • JCLPT0010E MISSING COMMAND PRECEDING COL 71
  • JCLPT0011E TYPORG value not found
  • JCLPT0012E TYPORG value is not PO or PS - [value]
  • JCLPT0013E TOTCONV value not found
  • JCLPT0014E TOTCONV value is not XE or PZ - [value]
  • JCLPT0015E Option only valid for PRINT - [command]
  • JCLPT0016W Option is not supported (ignored) - parameter
  • JCLPT0017E Unrecognised keyword - [parameter]
  • JCLPT0018E parameter value not found
  • JCLPT0019E parameter value is not numeric
  • JCLPT0020E Allocation failure for [parameter]
  • JCLPT0021E No RECORD command parameters found
  • JCLPT0022E FIELD specification not found
  • JCLPT0023E MAXFLDS parameter is too small
  • JCLPT0024E FIELD length value not found
  • JCLPT0025E FIELD length value is not numeric - [length]
  • JCLPT0026E FIELD input location is not numeric - [input location]
  • JCLPT0027E FIELD conversion option is invalid - [conversion]
  • JCLPT0028E FIELD output location is not numeric - [output location]
  • JCLPT0029E MAXGPS parameter is too small
  • JCLPT0030E IDENT length value not found
  • JCLPT0031E IDENT length value is not numeric - [length]
  • JCLPT0032E IDENT length value is greater than 8 - [length]
  • JCLPT0033E Closing quote for IDENT text was not found
  • JCLPT0034E IDENT text is shorter than the specified length - [length]
  • JCLPT0035E IDENT text is longer than the specified length - [length]
  • JCLPT0036E IDENT location is not numeric - [location]
  • JCLPT0037E No TITLE command parameters found
  • JCLPT0038E ITEM location is not numeric - [location]
  • JCLPT0039E Closing quote for ITEM text was not found
  • JCLPT0040E Continuation not found
  • JCLPT0041E Continuation starts before Col 4
  • JCLPT0042I SYSUT1 is partitioned, but TYPORG is PS - directory assumed
  • JCLPT0043E SYSUT1 is sequential, but TYPORG is PO
  • JCLPT0044E Invalid SYSUT1 record format - [recfm]
  • JCLPT0045E SYSUT2 record length exceeds maximum
  • JCLPT0046E Invalid SYSUT2 record format - [recfm]
  • JCLPT0047W Incorrect RECORD statement - FIELD extends beyond sysut2 LRECL
  • JCLPT0048E Continuation not started in 4-16
  • JCLPT0049E SYSPRINT record length must be 121
  • JCLPT0050E I/O error on [filename]
  • JCLPT0051E MEMBER not valid for the action [action] - TYPORG not PO
  • JCLPT0052E SYSIN record length must be 80
  • JCLPT0053E SYSUT1 concatenation error - Concatenated libraries are not supported
  • JCLPT0054E Invalid syntax - [command]
  • JCLPT0055W Command "command-name" is not currently supported
  • JCLPT0056E File status is [status code]
  • JCLPT0057E IDENT location is greater than SYSUT1 record length - [location]
  • JCLPT0058E FIELD output location is greater than SYSUT2 record length - [location]
  • JCLPT0059E Fatal error returned by [utility]
  • JCLPT0060E Error writing to SYSUT2 - File status is [status code]
  • JCLPT0061E Fatal error returned by CBL_DIR_SCAN_START - [status-code]
  • JCLPT0062E Error returned by CBL_DIR_SCAN_READ - [status-code]
  • JCLPT0063E Error reading SYSUT1 - File status is [status-code]
  • JCLPT0064E IDENT location is not found
  • JCLPT0065E ERROR READING SYSIN - File status is [status-code]
  • JCLPT0066E DDNAME SYSIN cannot be opened - File status is [status-code]
  • JCLPT0067W MEMBER [member name] cannot be found
  • JCLPT0068E DDNAME SYSUT1 cannot be opened - File status is [status-code]
  • JCLPT0069E DDNAME SYSUT2 cannot be opened - File status is [status-code]
  • JCLPT0070W SYSUT1 DATA SET IS EMPTY, RETURN CODE IS 4
Parent topic: JCL Error Messages


JCLPT0001E PRINT/PUNCH statement not first

The first statement in the control data set must be either a PRINT or a PUNCH statement.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0005E MAXNAME parameter is too small

The specified MAXNAME parameter is less than the total number of member names specified in subsequent MEMBER statements.

Parent topic: JCLPT Error Messages


JCLPT0006E INVALID COMMAND - NO NAME parameter

A NAME parameter is missing from the MEMBER statement.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0008E Unrecognised command - [command]

A command statement syntax error.

Parent topic: JCLPT Error Messages


JCLPT0009E SYSIN IS EMPTY

The specified SYSIN is empty.

Parent topic: JCLPT Error Messages


JCLPT0010E MISSING COMMAND PRECEDING COL 71

There are no command statements in columns 1 - 71 of the control data set.

Parent topic: JCLPT Error Messages


JCLPT0011E TYPORG value not found

No value is specified for the TYPORG parameter.

Parent topic: JCLPT Error Messages


JCLPT0012E TYPORG value is not PO or PS - [value]

The value of TYPORG must be either PS or PO.

Parent topic: JCLPT Error Messages


JCLPT0013E TOTCONV value not found

No value is specified for the TOTCONV parameter.

Parent topic: JCLPT Error Messages


JCLPT0014E TOTCONV value is not XE or PZ - [value]

The value of TOTCONV must be either XE or PZ.

Parent topic: JCLPT Error Messages


JCLPT0015E Option only valid for PRINT - [command]

The specified control statement can only be coded with the PRINT statement.

Parent topic: JCLPT Error Messages


JCLPT0016W Option is not supported (ignored) - parameter

The specified parameter is not currently supported and is ignored.

Parent topic: JCLPT Error Messages


JCLPT0017E Unrecognised keyword - [parameter]

The specified parameter for PRINT or PUNCH is not valid.

Parent topic: JCLPT Error Messages


JCLPT0018E parameter value not found

No value is specified for this parameter.

Parent topic: JCLPT Error Messages


JCLPT0019E parameter value is not numeric

The value of the specified parameter should be numeric.

Parent topic: JCLPT Error Messages


JCLPT0020E Allocation failure for [parameter]

Memory allocation failed for the specified parameter.

Parent topic: JCLPT Error Messages


JCLPT0021E No RECORD command parameters found

No parameters are specified for the RECORD statement.

Parent topic: JCLPT Error Messages


JCLPT0022E FIELD specification not found

No parameter value is specified for the RECORD FIELD statement.

Parent topic: JCLPT Error Messages


JCLPT0023E MAXFLDS parameter is too small

The specified MAXFLDS parameter is less than the total number of FIELD parameters specified in subsequent RECORD statements.

Parent topic: JCLPT Error Messages


JCLPT0024E FIELD length value not found

No length is specified in the RECORD FIELD statement.

Parent topic: JCLPT Error Messages


JCLPT0025E FIELD length value is not numeric - [length]

The value of the FIELD length must be numeric.

Parent topic: JCLPT Error Messages


JCLPT0026E FIELD input location is not numeric - [input location]

The FIELD input location must be numeric.

Parent topic: JCLPT Error Messages


JCLPT0027E FIELD conversion option is invalid - [conversion]

The specified FIELD conversion option is not valid.

Parent topic: JCLPT Error Messages


JCLPT0028E FIELD output location is not numeric - [output location]

The FIELD output location must be numeric.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0030E IDENT length value not found

No length is specified in the RECORD IDENT statement.

Parent topic: JCLPT Error Messages


JCLPT0031E IDENT length value is not numeric - [length]

The value of the IDENT length must be numeric.

Parent topic: JCLPT Error Messages


JCLPT0032E IDENT length value is greater than 8 - [length]

The IDENT length must not exceed eight bytes.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0034E IDENT text is shorter than the specified length - [length]

The IDENT text is shorter than the length specified in the control statement.

Parent topic: JCLPT Error Messages


JCLPT0035E IDENT text is longer than the specified length - [length]

The IDENT text is longer than the length specified in the control statement.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0037E No TITLE command parameters found

The TITLE statement is specified without any parameters.

Parent topic: JCLPT Error Messages


JCLPT0038E ITEM location is not numeric - [location]

The output location specified in the TITLE ITEM statement must be numeric.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0040E Continuation not found

No continuation character was found in column 72 in SYSIN.

Parent topic: JCLPT Error Messages


JCLPT0041E Continuation starts before Col 4

Continuation must start in column 4.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0043E SYSUT1 is sequential, but TYPORG is PO

SYSUT1 is a sequential dataset, but the specified TYPORG is PO.

Parent topic: JCLPT Error Messages


JCLPT0044E Invalid SYSUT1 record format - [recfm]

SYSUT1 can have only fixed, variable and line sequential record formats.

Parent topic: JCLPT Error Messages


JCLPT0045E SYSUT2 record length exceeds maximum

The maximum record length of SYSUT2 is 145.

Parent topic: JCLPT Error Messages


JCLPT0046E Invalid SYSUT2 record format - [recfm]

The record format of SYSUT2 is always FBA.

Parent topic: JCLPT Error Messages


JCLPT0047W Incorrect RECORD statement - FIELD extends beyond sysut2 LRECL

The FIELD must not exceed the SYSUT2 LRECL.

Parent topic: JCLPT Error Messages


JCLPT0048E Continuation not started in 4-16

Continuation must be between columns 4 and 16.

Parent topic: JCLPT Error Messages


JCLPT0049E SYSPRINT record length must be 121

The record length of SYSPRINT must be 121.

Parent topic: JCLPT Error Messages


JCLPT0050E I/O error on [filename]

I/O error on filename.

Parent topic: JCLPT Error Messages


JCLPT0051E MEMBER not valid for the action [action] - TYPORG not PO

No MEMBER statements were found but the specified TYPORG is not PO.

Parent topic: JCLPT Error Messages


JCLPT0052E SYSIN record length must be 80

The record length of SYSIN must always be 80.

Parent topic: JCLPT Error Messages


JCLPT0053E SYSUT1 concatenation error - Concatenated libraries are not supported

SYSUT1 concatenation is not currently supported.

Parent topic: JCLPT Error Messages


JCLPT0054E Invalid syntax - [command]

A command statement syntax error.

Parent topic: JCLPT Error Messages


JCLPT0055W Command "command-name" is not currently supported

The specified command is not currently supported.

Parent topic: JCLPT Error Messages


JCLPT0056E File status is [status code]

Specifies the returned file status code.

Parent topic: JCLPT Error Messages


JCLPT0057E IDENT location is greater than SYSUT1 record length - [location]

The specified IDENT input-location must not be greater than the SYSUT1 LRECL.

Parent topic: JCLPT Error Messages


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.

Parent topic: JCLPT Error Messages


JCLPT0059E Fatal error returned by [utility]

The utility returned an error.

Parent topic: JCLPT Error Messages


JCLPT0060E Error writing to SYSUT2 - File status is [status code]

The SYSUT2 write failed with the specified file status code.

Parent topic: JCLPT Error Messages


JCLPT0061E Fatal error returned by CBL_DIR_SCAN_START - [status-code]

CBL_DIR_SCAN_START has failed.

Parent topic: JCLPT Error Messages


JCLPT0062E Error returned by CBL_DIR_SCAN_READ - [status-code]

CBL_DIR_SCAN_READ has failed.

Parent topic: JCLPT Error Messages


JCLPT0063E Error reading SYSUT1 - File status is [status-code]

The SYSUT1 read failed with the specified file status code.

Parent topic: JCLPT Error Messages


JCLPT0064E IDENT location is not found

The specified IDENT location is not found.

Parent topic: JCLPT Error Messages


JCLPT0065E ERROR READING SYSIN - File status is [status-code]

The SYSIN read failed with the specified file status code.

Parent topic: JCLPT Error Messages


JCLPT0066E DDNAME SYSIN cannot be opened - File status is [status-code]

OPEN failed for SYSIN.

Parent topic: JCLPT Error Messages


JCLPT0067W MEMBER [member name] cannot be found

The specified SYSUT1 member cannot be found.

Parent topic: JCLPT Error Messages


JCLPT0068E DDNAME SYSUT1 cannot be opened - File status is [status-code]

OPEN failed for SYSUT1.

Parent topic: JCLPT Error Messages


JCLPT0069E DDNAME SYSUT2 cannot be opened - File status is [status-code]

OPEN failed for SYSUT2.

Parent topic: JCLPT Error Messages


JCLPT0070W SYSUT1 DATA SET IS EMPTY, RETURN CODE IS 4

The SYSUT1 provided contains no data.

Resolution

Recode the job to provide the information in a valid SYSUT1.

Parent topic: JCLPT 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
  • JCLUT0109I Utility output dataset (datasetname) DD CARD not found, Treating as dummy
  • 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
  • JCLUT0207I No members found for PO "dataset name".
  • JCLUT0230S Insufficient authority to use PCDSN dataset "%". where '%' is the physical file or the dataset name
  • JCLUT0208E MFPOADD cannot be used with dynamic PDS
Parent topic: JCL Error Messages


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


JCLUT0006E

Message

SYSUT1 = SYSUT2 nothing to do

Message Information

SYSUT1 and SYSUT2 reference the same file

Parent topic: JCLUT Error Messages


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


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


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


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


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


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


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


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


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 OpenText Support for Micro Focus Products.

Parent topic: JCLUT Error Messages


JCLUT0109I Utility output dataset (datasetname) DD CARD not found, Treating as dummy

Message

A DD CARED was not found for the output dataset detailed and is being treated as dummy.

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


JCLUT0207I No members found for PO "dataset name".

Message

No members found for PO "dataset name".

Message Information

No members for the partitioned dataset "dataset name" could be found.

Resolution

No action required.

Parent topic: JCLUT Error Messages


JCLUT0230S Insufficient authority to use PCDSN dataset "%". where '%' is the physical file or the dataset name

After checking access rights in the PHYSFILE resource class, you do not have the required authority to create or change the physical file named by %.

Resolution:

Update the access rights in the PHYSFILE class.

Parent topic: JCLUT Error Messages
Related concepts
Resource Classes for JES Security


JCLUT0208E MFPOADD cannot be used with dynamic PDS

The utility program MFPOADD cannot be used to transfer user programs into a dynamic PDS but only into a standard PO.

Parent topic: JCLUT 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


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


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


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 OpenText Support for Micro Focus Products 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


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


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


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


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


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


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.
  • SORT229E job-number job-name ARITHMETIC OPERATION ON ANOTHER ARITHMETIC OPERATION NOT SUPPORTED
    MFJSORT attempted to perform an arithmetic operation on another arithmetic operation and failed, because it is not supported.
  • 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


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


SORT229E job-number job-name ARITHMETIC OPERATION ON ANOTHER ARITHMETIC OPERATION NOT SUPPORTED

MFJSORT attempted to perform an arithmetic operation on another arithmetic operation and failed, because it is not supported.

Resolution:

Ensure you only perform arithmetic operations between two fields.

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


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:

  • JES000002E JCL parser not available.
  • JES000003Ennnnn duplicates an existing job number.
  • JES000004I <job-num> <job-name> JOB DISPATCHED
  • JES000006I SSTM Startup Phase 1 (<sstm-type>) - starting job <sstm-job-file>
  • JES000007I SSTM Startup Phase 1 (<sstm-type>) - processing <sstm-job-id>
  • JES000008I SSTM Startup Phase 2 (<sstm-type>) - starting job <sstm-job-id>
  • JES000011E Batch Spool File Error; Status <operation> <file status>.
  • JES000012I Batch Input Spool has been cold-started.
  • JES000013I Jnnnnnnn requeued for restart at xxxxxx.
  • JES000014E Jnnnnnnn not restarted. Job, Step or Procstep xxxxxx restart information not found.
  • JES000015I Jnnnnnnn does not exist for restart.
  • JES000016E Jnnnnnnn not executed. Undefined JES error, FEP-RC: (RC).
  • JES000017E Jnnnnnnn restart not allowed at Step/Procstep xxxxxx.
  • JES000018E Jnnnnnnn restart information could not be loaded.
  • JES000019E Unable to allocate job number for job.
  • JES000020W Allocated job number percentage znn exceeds warning level nn.
  • JES000022U Jnnnnnnn restart 'TO' Step/Procstep <STEP(instance):PROCSTEP(instance)> not found
  • JES000023U Jnnnnnnn restart 'TO' Step/Procstep <STEP(instance):PROCSTEP(instance)> before 'FROM' Step <STEP(instance):PROCSTEP(instance)>.
  • JES000024I Batch Printer: xxxxxx
  • JES000025E Printer not found: xxxxxx
  • JES000025I Printer not found: xxxxxx
  • JES000026O Exit Module: xxxxxxxx
  • JES000027E Printer assignment failed. RC = nnnnn
  • JES000028E Load failed for exit Module: xxxxxxxx
  • JES000029I xxxxxx on yyyyyy
  • JES000030E xxxxxx
  • JES000031E Printer open failed. RC = nnnnn
  • JES000032E Printer write failed. RC = nnnnn
  • JES000033E Printer error accessing spool data: xxxxxx
  • JES000034E Jnnnnnnn - TIME parameter exceeds 65533 seconds after applying class multiplier (value).
  • JES000040I SSTM environment established successfully. nnnnn
  • JES000041E SSTM initialization failure nnnnn
  • JES000042I SSTM not enabled: nnnnn
  • JES000043E Jnnnnnnn Unable to create file for holding restart information. Status: <File Status>.
  • JES000044E Jnnnnnnn - Failed to store restart information. Status: <File Status>.
  • JES000045E Jnnnnnnn - Failed to retrieve JESYSMSG record for job <Original Job Number> specified in restart parameter.
  • JES000046E Jnnnnnnn - Failed to retrieve catalog information for JESYSMSG record for job <Original Job Number> specified in restart parameter. Status: <File Status>.
  • JES000047E Jnnnnnnn - Error reading previous job (Original Job Number) CC information. Status: <File Status>.
  • JES000048E Jnnnnnnn - Failed to store restart CC information. Status: <File Status>.
  • JES000050E JCL parsing error: RC = nnnnn.
  • JES000051I Job Entry Subsystem (JES) services initialized.
  • JES000052E Job Entry Subsystem (JES) initialization failed. Environment improperly configured. xxxxxxxx
  • JES000053E JES Validation - Catalog Open Failed - RC = <return code>, FS = <file status>
  • JES000054E JES Validation - Allocate File Failed - RC = <return code>, FS = <file status>
  • JES000055E JES validation - MFALLOC_PROP undefined or invalid: <MFALLOC_PROP setting>
  • JES000056E JES Validation - MVSJOBNO Check Failed - reason = <reason code>, FS = <file status>
  • JES000057E JES validation - MFJCLCFG failed - RC = <return code> Reason = <reason code>
  • JES000058E JES validation - Product requires new spool control files. Run spool conversion utility, splconv, to create them.
  • JES000059I JES value digit job numbering support enabled
  • JES000060E JES validation - invalid url for URL
  • JES000061E Jnnnnnnn - Job '<Job Name>' is not a restart of Job J<Original Job Number>, 'Original Job Name>'.
  • JES000062E Jnnnnnnn - Error setting up GDG restart information from previous job (<Original Job Number>). Status: <File Status>.
  • JES000063E Jnnnnnnn - Unable to find restartable step.
  • JES000065E JES validation - Catalog Open failed (MFALLOC_LOC) - RC = return code, Reason = reason code
  • JES000066E JES validation - Program Path invalid - RC = return code
  • JES000067I(W) JES Validation - <Number of> SYS1.LNKLIB entries
  • JES000068I SYS1.LNKLST: <List of SYS1.LNKLIB entries>
  • JES000069W SYS1.LNKLIB entry <Library Name> is a Dynamic PO. Dynamic PDS entries will not be loaded under enhanced JCL security
  • JES000070E SYS1.LNKLIB entry <Library Name> is a Dynamic PO. Dynamic PDS entries for load modules are NOT permitted under enhanced JCL security
  • JES000074I Job already submitted. (JOBNAME=job-name,JOBNUM=job-number) CID: "correlator-ID"
  • JES000120S Failed to get SPLJOB record lock. FS: <file status>, Job# <job number>, Loc: <source location>
  • JES000121S Failed to get SPLJOB record. FS: <file status>, Job# <job number>, Loc: <source location>
  • JES000122S Failed to get SPLDSN record lock. FS: <file status>, Job# <job number>, DD# <DD number>, Loc: <source location>
  • JES000123S Too many SYSOUT records for Job number <job number>
  • JES000124S Failed to get SPLDSN record. FS: <file status>, Job# <job number>, DD# <DD number>, Loc: <source location>
  • JES000125S Failed to update SPLJOB record. FS: <file status>, Job# <job number>, Loc: <source location>
  • JES000126S Failed to update SPLDSN record. FS: <file status>, Job# <job number>, DD# <DD number>, Loc: <source location>
  • JES000127I Attempting to get SPLJOB record lock. FS: <file status>, Job# <job number>, Loc: <source location>, Tries: <retry count>
  • JES000128I Attempting to get SPLDSN record lock. FS: <file status>, Job# <job number>, DD# <DD number>, OUT# <OUTPUT number>, Loc: <source location>, Tries: <retry count
  • JES000129S Failed to write SPLJOB record. FS: <file status>, Job# <job number>, Loc: <source location>
  • JES000131E Unrecoverable file error FS: <file status>, Work suspended until operator input received
  • JES000132S Failed to write SPLDSN record. FS: <file status>, Job# <job number>, Loc: <source location>, DD# <DD number>, OUT# <OUTPUT number>, Loc: <source location>
  • JES000140E Printer Exit reported error printing <dataset information>. RC = <return code>.
  • JES000150U Command-line parsing failure : <Failure Detail>
  • JES000151U Command-line length is invalid : <Failure Detail>
  • JES000152U Initial option is invalid : <Failure Detail>
  • JES000153U Flag is invalid : <Failure Detail>
  • JES000154E (Internal error)bracket fault : <Failure Detail>
  • JES000155U Parameter too large : <Failure Detail>
  • JES000156U Unexpected end of parameter : <Failure Detail>
  • JES000157U Parameter choice invalid here : <Failure Detail>
  • JES000158U Expected braces don't match : <Failure Detail>
  • JES000159U Unexpected character : <Failure Detail>
  • JES000220E <job-num> JOB ABENDED - <cond-code>
    Reports that <job-num> abended and the condition code.
  • JES000222E Jnnnnnnn canceled by operator
  • JES000243U <job-num> Unable to access catalog file for dataset <data-set>, <cat-file>, FS: <file-status>
    Reports job number, requested dataset, catalog file, and file status.
  • JES000913E Jnnnnnnn User xxxxxx has an invalid password or no longer has auth to exec JCL.
  • JES000914E Jnnnnnnn User xxxxxx is not a surrogate of User zzzzzz.
  • JES000915E Jnnnnnnn User xxxxxx does not have authority to submit job zzzzzz.
  • JES000916E Jnnnnnnn User xxxxxx has insufficient authority to create job log.
  • JES000917E Jnnnnnnn User xxxxxx has insufficient authority to access dataset ddd.ddd
  • JES000918E Jnnnnnnn User user-id password is invalid
  • JES000919E Jnnnnnnn User user-id password has expired
  • JES000920E Jnnnnnnn User user-id ID error
  • JES000921E Jnnnnnnn User user-id ID not in group " gggggggg"
  • JES000922E Jnnnnnnn User user-id ID revoked
Parent topic: JCL Error Messages


JES000002E JCL parser not available.

Parent topic: JES Messages


JES000003Ennnnn duplicates an existing job number.

The job # specified during submission duplicates an already existing job #. You need to reset your job # mechanism.

Parent topic: JES Messages


JES000004I <job-num> <job-name> JOB DISPATCHED

A request for a job to execute has been received by the JCL engine, which has been processed and passed back.

Parent topic: JES Messages


JES000006I SSTM Startup Phase 1 (<sstm-type>) - starting job <sstm-job-file>

During SSTM Phase 1 startup, the JCL system is preparing to parse the indicated SSTM job file.

Parent topic: JES Messages


JES000007I SSTM Startup Phase 1 (<sstm-type>) - processing <sstm-job-id>

During SSTM Phase 1 startup, the JCL system is preparing to run the indicated SSTM job.

Parent topic: JES Messages


JES000008I SSTM Startup Phase 2 (<sstm-type>) - starting job <sstm-job-id>

During SSTM Phase 2 startup, the JCL system is preparing to run the indicated SSTM job.

Parent topic: JES Messages


JES000011E Batch Spool File Error; Status <operation> <file status>.

This error occurs while trying to access the spool and an unexpected file status was encountered. The operation is the action being performed, such as read or write. The file status is the file status returned from the operation. The file status is returned as 2 digits or as 9/nnn. Look up the file status error returned and take the appropriate remedial action.

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000013I Jnnnnnnn requeued for restart at xxxxxx.

The job nnnnnnn has been queued for restart at the step (and where applicable the procstep) specified by xxxxxx.

Parent topic: JES Messages


JES000014E Jnnnnnnn not restarted. Job, Step or Procstep xxxxxx restart information not found.

The job nnnnnnn cannot be restarted because it does not contain the specified step (and where applicable the procstep) specified by xxxxxx.

Parent topic: JES Messages


JES000015I Jnnnnnnn 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.

Parent topic: JES Messages


JES000016E Jnnnnnnn not executed. Undefined JES error, FEP-RC: (RC).

An attempt was made to restart a job that was not run with restart in effect, or files associated with the job have been deleted.

Parent topic: JES Messages


JES000017E Jnnnnnnn restart not allowed at Step/Procstep xxxxxx.

This error is displayed when the job or the step specified is non-restartable.

Parent topic: JES Messages


JES000018E Jnnnnnnn restart information could not be loaded.

There is no restart data available. This may be because the environment variable ES_JES_RESTART was not set to Y when the job was first run.

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000020W Allocated job number percentage znn exceeds warning level nn.

The number of allocated job numbers, expressed as a percentage of all possible job numbers, exceeds the percentage defined in SPLJNO.dat as the warning level. Consider running spool housekeeping to free some job numbers.

Parent topic: JES Messages


JES000022U Jnnnnnnn restart 'TO' Step/Procstep <STEP(instance):PROCSTEP(instance)> not found

The STEP (and PROCSTEP, if specified) to run the job has not been found when using the#t parameter.

Correct step name:procstep name and instance numbers, if given.

Parent topic: JES Messages


JES000023U Jnnnnnnn restart 'TO' Step/Procstep <STEP(instance):PROCSTEP(instance)> before 'FROM' Step <STEP(instance):PROCSTEP(instance)>.

When using the #t parameter, the restart TO step was resolved to a step before the FROM step specified by the #f parameter.

Correct the names and, if duplicate step names are causing the error, use step and procstep instance numbers to identify the starting and ending steps.

Parent topic: JES Messages


JES000024I Batch Printer: xxxxxx

The printer named ‘xxxxxx’ has been initialized.

Parent topic: JES Messages


JES000025E Printer not found: xxxxxx

The printer named ‘xxxxxx’ was not located while enumerating through the printers defined on this machine.

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000026O Exit Module: xxxxxxxx

The batch printer specified in the previous JES000024I message is using a printer exit named ‘xxxxxxxx’.

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000028E Load failed 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.

Parent topic: JES Messages


JES000029I xxxxxx on yyyyyy

An information message relating to batch printers - yyyyyy = printer name. When issued during printer initialization, it indicates which printer device is being searched for by this batch printing SEP, or that the printer device is available (xxxxxx = "Locating" or "Available"). When issued while a document is being printed, it indicates which printer device is being used (xxxxxx = "<document name> on").

Parent topic: JES Messages
Related information
JES_PRINT_SPOOL_MSG


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.

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000032E Printer write failed. RC = nnnnn

A failure 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

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000034E Jnnnnnnn - TIME parameter exceeds 65533 seconds after applying class multiplier (value).

The time on the job card when multiplied by the time class multiplier exceeds 65535 seconds.

Resolution

Either reduce the time parameter or the time class multiplier.

Parent topic: JES Messages


JES000040I SSTM environment established successfully. nnnnn

The SSTM process has been initialised. The string xxxxx contains the subsystem type (CICS/IMS) and job number.

Parent topic: JES Messages


JES000041E SSTM initialization failure nnnnn

Initialisation of the SSTM process failed. The string xxxxx contains the failure type and the return code.

Parent topic: JES Messages


JES000042I SSTM not enabled: nnnnn

The JCL file specified for SSTM could not be found. The string xxxxx contains the subsystem type (CICS/IMS).

Parent topic: JES Messages


JES000043E Jnnnnnnn Unable to create file for holding restart information. Status: <File Status>.

The file used to hold restart information could not be created. The File Status gives an indication of the reason.

Parent topic: JES Messages


JES000044E Jnnnnnnn - Failed to store restart information. Status: <File Status>.

The restart information could not be stored in the file used to hold the information. The File Status gives an indication of the reason.

Parent topic: JES Messages


JES000045E Jnnnnnnn - Failed to retrieve JESYSMSG record for job <Original Job Number> specified in restart parameter.

The job could not be started as a restart of the original job number because the JESYSMSG record for that job could not be found in the spool DSN file. If the original job is not listed in the spool completed jobs view in ESCWA then a new job cannot be submitted as a restart of it.

Parent topic: JES Messages


JES000046E Jnnnnnnn - Failed to retrieve catalog information for JESYSMSG record for job <Original Job Number> specified in restart parameter. Status: <File Status>.

The catalog record for the original job's JESYSMSG file could not be returned. The File Status gives an indication of the reason. The JESYSMSG record for the original job must be in the catalog for the new job to be submitted as a restart of it.

Parent topic: JES Messages


JES000047E Jnnnnnnn - Error reading previous job (Original Job Number) CC information. Status: <File Status>.

The Cond Code information from the original job could not be loaded. The File Status gives an indication of the reason. The parsed job detail files, known as LEX files, must still exist for the original job so that a new job can be submitted as a restart of that original job.

Parent topic: JES Messages


JES000048E Jnnnnnnn - Failed to store restart CC information. Status: <File Status>.

The Cond Code information from the original job could not be stored (written to file). The File Status gives an indication of the reason.

Parent topic: JES Messages


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.

Parent topic: JES Messages


JES000051I Job Entry Subsystem (JES) services initialized.

The JES services for the process have been initialized.

Parent topic: JES Messages


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
Parent topic: JES Messages


JES000053E JES Validation - Catalog Open Failed - RC = <return code>, FS = <file status>

Failed to open the catalog, MFSYSCAT. See the catalog return codes for information about the particular return code.

Parent topic: JES Messages


JES000054E JES Validation - Allocate File Failed - RC = <return code>, FS = <file status>

Failed to allocate an IVP dataset. See the catalog return codes for information about the particular return code.

Parent topic: JES Messages


JES000055E JES validation - MFALLOC_PROP undefined or invalid: <MFALLOC_PROP setting>

The MFALLOC_PROP setting is invalid. The valid values are: MVSNAME (recommended), SNAME, or DOTDIR.

Parent topic: JES Messages


JES000056E JES Validation - MVSJOBNO Check Failed - reason = <reason code>, FS = <file status>

Reason codes:

04
Failed to open the output job number file.
05
An error when writing record to file.
06
uUnexpected file status when closing file.
07
Unexpected file status when rewriting file.
08
Unexpected file status when reading file.
09
Unexpected file status when opening an I-O file.
10
Unexpected file status when writing new initial record to file.
11
Unexpected file status when opening extend new file.
Parent topic: JES Messages


JES000057E JES validation - MFJCLCFG failed - RC = <return code> Reason = <reason code>

Validation of MFJCLCFG has failed. The return codes indicate:

1
Configuration setting not found.
2
Configuration too large (limit is 260). The reason code is the same size as the returned value.
3
Memory allocation error. The reason code contains the allocation status.
4
Free memory error. The reason code contains the deallocation status.
5
Configuration name not given
6
MFSYSCAT not set 7.
7
MFSYSCAT invalid URL.
254
Unsupported operation.
Parent topic: JES Messages


JES000058E JES validation - Product requires new spool control files. Run spool conversion utility, splconv, to create them.

The region has been started with a casspool.dat file, but without a SPLJOB.dat file. The SPLCONV conversion program should be run to create SPLJOB.dat (and the other SPL* files) from the existing casspool.dat records.

Parent topic: JES Messages


JES000059I JES value digit job numbering support enabled

Specifies the number of digits job numbering is enabled to.

Parent topic: JES Messages


JES000060E JES validation - invalid url for URL

Parent topic: JES Messages


JES000061E Jnnnnnnn - Job '<Job Name>' is not a restart of Job J<Original Job Number>, 'Original Job Name>'.

The job submitted as a restart of the original job is not the same job. When submitting a new job as a restart of an existing job, the job numbers should be the same.

Parent topic: JES Messages


JES000062E Jnnnnnnn - Error setting up GDG restart information from previous job (<Original Job Number>). Status: <File Status>.

The GDG restart information from the original job could not be used for the new job. The File Status gives an indication of the reason.

Parent topic: JES Messages


JES000063E Jnnnnnnn - Unable to find restartable step.

The step given for restart was not restartable and no other restartable step could be found. Ensure the job has restartable steps and adjust the restart step to suit.

Parent topic: JES Messages


JES000065E JES validation - Catalog Open failed (MFALLOC_LOC) - RC = return code, Reason = reason code

Issued when a fault occurs when opening the catalog at system startup. Return code 21 indicates a problem with the Default Allocation Location setting. Reason codes are as follows:

Reason code | Description
11 | Invalid value. The value of the location is invalid.
12 | Multiple directories have been specified.
13 | The name has not been set.
14 | The value is too long (limit is 260).
15 | No value has been given.
16 | Memory constrained - unable to store the value.
Parent topic: JES Messages


JES000066E JES validation - Program Path invalid - RC = return code

The JES Program Path has not been set, or is invalid. The return code indicates the nature of the fault. Return codes are:

Return code | Description
1 | Configuration not found
2 | Value too long (limit is 4095)
3 | Memory constrained - unable to store the value
8 | Configuration name is invalid
Parent topic: JES Messages


JES000067I(W) JES Validation - <Number of> SYS1.LNKLIB entries

This will be a Warning level message if no SYS1.LNKLIB entries have been defined.

Parent topic: JES Messages


JES000068I SYS1.LNKLST: <List of SYS1.LNKLIB entries>

This will display the SYS1.LNKLST entries if one of the SYS1.PARMLIB(IEASYSNN) indicates that the list should be shown. You can also see the list of entries by using IDCAMS to LISTCAT ENTRIES(SYS1.LNKLIB).

Parent topic: JES Messages


JES000069W SYS1.LNKLIB entry <Library Name> is a Dynamic PO. Dynamic PDS entries will not be loaded under enhanced JCL security

This warning message is issued if a program library in the SYS1.LNKLIB concatenation is a dynamic PDS and the ES_JES_HIGHER_SECURITY_LEVEL= 1 (NONE) or is not set.

Parent topic: JES Messages


JES000070E SYS1.LNKLIB entry <Library Name> is a Dynamic PO. Dynamic PDS entries for load modules are NOT permitted under enhanced JCL security

This error message is issued if a program library in the SYS1.LNKLIB concatenation is a dynamic PDS and the ES_JES_HIGHER_SECURITY_LEVEL=2 (BASIC) or greater.
Parent topic: JES Messages


JES000074I Job already submitted. (JOBNAME=job-name,JOBNUM=job-number) CID: "correlator-ID"

A job has already been submitted with this unique correlator ID and cannot be submitted again.
Parent topic: JES Messages


JES000120S Failed to get SPLJOB record lock. FS: <file status>, Job# <job number>, Loc: <source location>

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.

Parent topic: JES Messages


JES000121S Failed to get SPLJOB record. FS: <file status>, Job# <job number>, Loc: <source location>

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

Parent topic: JES Messages


JES000122S Failed to get SPLDSN record lock. FS: <file status>, Job# <job number>, DD# <DD number>, Loc: <source location>

This error, together with JES000124S is generated by the spool module when it fails to obtain the required lock on a SPLDSN record.

Parent topic: JES Messages


JES000123S Too many SYSOUT records for Job number <job number>

The SPLDSN DD sequence number exceeds the maximum possible number.

Parent topic: JES Messages


JES000124S Failed to get SPLDSN record. FS: <file status>, Job# <job number>, DD# <DD number>, Loc: <source location>

This error, together with JES000122S is generated by the spool module when it fails to obtain the required lock on a SPLDSN record.

Parent topic: JES Messages


JES000125S Failed to update SPLJOB record. FS: <file status>, Job# <job number>, Loc: <source location>

An error was encountered while attempting to rewrite an existing SPLJOB record.

Parent topic: JES Messages


JES000126S Failed to update SPLDSN record. FS: <file status>, Job# <job number>, DD# <DD number>, Loc: <source location>

An error was encountered while attempting to rewrite an existing SPLDSN record.

Parent topic: JES Messages


JES000127I Attempting to get SPLJOB record lock. FS: <file status>, Job# <job number>, Loc: <source location>, Tries: <retry count>

A locked record was encountered on SPLJOB. This message will be issued after every 50 unsuccessful attempts to lock the record.

Parent topic: JES Messages


JES000128I Attempting to get SPLDSN record lock. FS: <file status>, Job# <job number>, DD# <DD number>, OUT# <OUTPUT number>, Loc: <source location>, Tries: <retry count

A locked record was encountered on SPLDSN. This message will be issued after every 50 unsuccessful attempts to lock the record.

Parent topic: JES Messages


JES000129S Failed to write SPLJOB record. FS: <file status>, Job# <job number>, Loc: <source location>

An error was encountered while attempting to write a new SPLJOB record.

Parent topic: JES Messages


JES000131E Unrecoverable file error FS: <file status>, Work suspended until operator input received

A fatal error was detected on a file operation. For example, the file name SPLJOB, and file status code are displayed in the message text.

Parent topic: JES Messages


JES000132S Failed to write SPLDSN record. FS: <file status>, Job# <job number>, Loc: <source location>, DD# <DD number>, OUT# <OUTPUT number>, Loc: <source location>

An error was encountered while attempting to write a new SPLDSN record.

Parent topic: JES Messages


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

Parent topic: JES Messages


JES000150U Command-line parsing failure : <Failure Detail>

The restart function parser has been called with the wrong function. The Failure Detail shows the function used. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000151U Command-line length is invalid : <Failure Detail>

The length of the -jrestart parameter is invalid. The Failure Detail shows the length.

Parent topic: JES Messages


JES000152U Initial option is invalid : <Failure Detail>

The parameter was not recognized. The Failure Detail shows the parameter. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000153U Flag is invalid : <Failure Detail>

The parameter flag is not recognized. Failure Detail includes the parameter and the character position that caused the parsing failure, e.g. @0001 "xYY" shows the parameter "xYY" was not recognized and the failure occurred when processing the first character.

Parent topic: JES Messages


JES000154E (Internal error)bracket fault : <Failure Detail>

An error occurred decoding the brackets in the restart parameter. The Failure Detail gives an indication of where the failure occurred. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000155U Parameter too large : <Failure Detail>

The parser has detected a parameter that is larger than expected. The Failure Detail shows the parameter. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000156U Unexpected end of parameter : <Failure Detail>

The parser has reached the end of the parameter and is missing some information. The Failure Detail shows the parameter. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000157U Parameter choice invalid here : <Failure Detail>

The parameter values are not valid. The Failure Detail shows the parameter. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000158U Expected braces don't match : <Failure Detail>

A mismatch in braces has been detected. The Failure Detail shows the parameter. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000159U Unexpected character : <Failure Detail>

The character is not valid. The Failure Detail shows the parameter. Check that the -jrestart parameter has been constructed correctly.

Parent topic: JES Messages


JES000220E <job-num> JOB ABENDED - <cond-code>

Reports that <job-num> abended and the condition code.
Parent topic: JES Messages


JES000222E Jnnnnnnn canceled by operator

Job # job-number was canceled via the casout command -k option or via the ESMAC Spool view function.

Parent topic: JES Messages


JES000243U <job-num> Unable to access catalog file for dataset <data-set>, <cat-file>, FS: <file-status>

Reports job number, requested dataset, catalog file, and file status.

You can use the ES_CAT_RETRY_COUNT and ES_CAT_RETRY_WAIT environment variables to automatically re-attempt to open the catalog file.

Parent topic: JES Messages


JES000913E Jnnnnnnn User xxxxxx has an invalid password or no longer has auth to exec JCL.

Jnnnnnnn represents the job number, and User xxxxxx represents the user.

Parent topic: JES Messages


JES000914E Jnnnnnnn User xxxxxx is not a surrogate of User zzzzzz.

Jnnnnnnn represents the job number, and User xxxxxx represents the user.

Parent topic: JES Messages


JES000915E Jnnnnnnn User xxxxxx does not have authority to submit job zzzzzz.

Jnnnnnnn represents the job number, and User xxxxxx represents the user.

Parent topic: JES Messages


JES000916E Jnnnnnnn User xxxxxx has insufficient authority to create job log.

Jnnnnnnn represents the job number, and User xxxxxx represents the user.

In order for a job log to be created, a relevant PHYSFILE rule must exist to allow this user access to the required directory.

See Resource Classes for JES Security for more information.

Parent topic: JES Messages
Related concepts
Resource Classes for JES Security


JES000917E Jnnnnnnn User xxxxxx has insufficient authority to access dataset ddd.ddd

Jnnnnnnn represents the job number, User xxxxxx represents the user, and ddd.ddd represents the dataset.

The user requires READ access to the dataset.

See Resource Classes for JES Security for more information.

Parent topic: JES Messages
Related concepts
Resource Classes for JES Security


JES000918E Jnnnnnnn User user-id password is invalid

Jnnnnnnn represents the job number and User xxxxxx represents the user.

A job failed a job submission security check. You have specified an invalid password.

Parent topic: JES Messages


JES000919E Jnnnnnnn User user-id password has expired

Jnnnnnnn represents the job number and User xxxxxx represents the user.

A job failed a job submission security check. The password for the specified user has expired.

Parent topic: JES Messages


JES000920E Jnnnnnnn User user-id ID error

Jnnnnnnn represents the job number and User xxxxxx represents the user.

A job failed a job submission security check. The specified user does not exist.

Parent topic: JES Messages


JES000921E Jnnnnnnn User user-id ID not in group " gggggggg"

Jnnnnnnn represents the job number, User xxxxxx represents the user, and gggggggg represents the group name.

A job failed a job submission security check. The specified users is not included in the group.

Parent topic: JES Messages


JES000922E Jnnnnnnn User user-id ID revoked

Jnnnnnnn represents the job number and User xxxxxx represents the user.

A job failed a job submission security check. The user is revoked.

Parent topic: JES Messages


Securing Enterprise Server

Securing a computing system is usually a combination of enabling security features, which are parts of the system that exist specifically to improve security; configuring security restrictions, which are aspects of the system and its environment (such as the OS) which are not security features as such but improve security by restricting who can perform which actions; and following other security-sensitive practices, such as installing software updates.

By default, Enterprise Server has many features enabled and few security restrictions, so users can quickly begin to explore and work with it. While this is convenient, in many cases it is prudent to configure Enterprise Server for greater security. For production installations, the best practice is to enable only required features and set security controls to restrict access to authorized users only, in order to safeguard enterprise data and processes. For developer installations, enterprise production systems and data are usually not directly at risk, but developers have access to corporate networks and the source code for enterprise applications, so their systems also need to be protected against compromise. In either environment improved security benefits the organization.

The topics presented here form what is sometimes known as a "hardening guide." They consist of explanations of security settings and other optional configuration and how those improve security, and recommendations for using them in accordance with the organization's security policies and posture, and the intended use of Enterprise Server.

Because security touches on every aspect of a system, and security concerns are intertwined and interact with one another in complex ways, some recommendations appear more than once, in different sections.

Micro Focus recommends all Enterprise Server administrators (including developers who run their own enterprise server instance) review these topics and implement the recommended configuration settings which are appropriate for their organization and deployment. In addition, Micro Focus also recommends reviewing the entire guide before making any complex changes to harden your system, since some decisions might render other recommendations irrelevant. For example, if you disable certain optional features, you do not need to spend time hardening them.

  • Scope
    The scope of this chapter.
  • Hardening the operating environment
    Describes changes to make to the operating environment to improve Enterprise Server security.
  • Hardening enterprise server region
    Recommendations for improving the security of an enterprise server region.
  • Using and hardening ESF
    Discusses the use of the External Security Facility (ESF) and how to harden it.
  • Using and hardening TLS
    Enterprise Server provides TLS, also known as SSL, for communications security.
  • Using and hardening the supplied configuration
    Modifying the configuration supplied with Enterprise Server to improve security.
Parent topic: Micro Focus Enterprise Test Server 10.0


Scope

Securing Enterprise Server describes the various security-related aspects of Enterprise Server and how these can be used to "harden" an Enterprise Server installation. By explaining the available security features, options and their effects when configured, it enables sensible decisions about enterprise server instance security. It also includes recommendations to help administrators achieve a security posture suitable for modern production environments.

The intended audience is enterprise server instance administrators, including developers who run enterprise server instances for development and test purposes, who want to ensure that their Enterprise Server installation:

  • Is only accessible to authenticated users, and those users only have access to their authorized resources.
  • Secures sensitive information, using encrypted communications and other features.
  • Does not enable unused features, in order to provide a minimal attack surface.

The features and configuration options discussed here are also described in the appropriate reference sections of the production documentation. This guide is intended to provide a single resource which can serve as a guide to ensure systems are configured appropriately from a security perspective. It also includes a checklist so administrators can consult a single topic to review which security features they have enabled. References to topics in your product Help are provided where relevant.

Some security aspects and guidelines for the operating systems hosting Enterprise Server are also reviewed.

What is not covered

This guide does not cover the following areas:

  • Enterprise Server for .NET.
  • Security configuration of some secondary enterprise server instance components, such as XDB.
  • Legacy features which should be disabled, such as the Micro Focus Directory Server Web user interface.
  • Securing development tools or the application development process (other than securing enterprise server instances used for development).
  • Samples, field-developed solutions (FDSs), third-party add-ons, and other components not part of the base Enterprise Server product.

Also, while the security of customer applications hosted under Enterprise Server is discussed briefly, that is a complex area which cannot be covered in any depth in this guide. Micro Focus recommends customers devote appropriate resources to industry best practices for producing secure software, including using a Secure Development Lifecycle, training employees in secure development techniques, and using tools to detect potential vulnerabilities (such as Micro Focus Fortify).

Parent topic: Securing Enterprise Server


Hardening the operating environment

Various configuration changes can be made in the operating system and filesystem to improve Enterprise Server security. These changes have a considerable effect on security and should be made to development, test, and production systems if possible.

Some of the changes described in this chapter improve the resistance of Enterprise Server to attack. Others reduce the potential damage of a compromised enterprise server instance.

The chapter contains some material which applies generally across operating systems, and other recommendations which are specific to an operating system.

Micro Focus recommends the Enterprise Server installation and hardening process be overseen by a system administrator with a good understanding of security considerations for the operating system being used.

  • Running with minimal privilege
    Applying the principle of least privilege to Enterprise Server.
  • Hardening filesystem permissions
    Reduce the damage potential of attacks by limiting access to files.
  • Additional operating-environment notes
    Additional notes on hardening the operating environment.
  • Hardening the operating environment: Summary
    A summary list of major recommendations for hardening the operating environment.
Parent topic: Securing Enterprise Server


Running with minimal privilege

The principle of least privilege is an important concept in security. It states that systems and each of their components should be granted only the privileges necessary to perform their intended functions. Here "privilege" means the capability to perform some action, such as executing a command or reading a file.

The principle of least privilege is an important security measure because it limits the damage that can be done by exploiting a vulnerability.

For the Windows operating systems on which Enterprise Server runs, the most important step to achieve a least-privilege configuration is to ensure that processes are not running under an administrative or "superuser" account.

  • Minimal privilege: Windows
    Guidelines for removing excessive privilege on Windows.
Parent topic: Hardening the operating environment


Minimal privilege: Windows

Under Windows there are two primary aspects of removing excess privilege: user accounts and security privileges. There are also some secondary aspects.

Do not run as an administrative user

Avoid running Enterprise Server processes under an administrative account. These include well-known accounts such as Administrator and LOCAL_SYSTEM, and other members of the Administrators group.

Micro Focus offers the following specific recommendations:

Windows services
Enterprise Server includes a number of Windows services. These are typically installed to run under the LOCAL_SYSTEM account, which has administrator-level access except for certain network resources. As discussed in the topic Reducing the attack surface, services which are not needed should be stopped and disabled. Other services should be reconfigured to run under distinct user accounts created just for this purpose, with only the minimal required permissions. The service account can be changed using the Services user interface.

It is particularly important to change the accounts for services with web interfaces such as ESCWA and (if the UI is not disabled) MFDS, since web interfaces are often the first point of attack.

If you use either ESCWA or MFDS to start an enterprise server region, all the region processes with run under the same account as MFDS. So if regions will be started using one of the web interfaces, it is particularly important to create a dedicated non-administrative account for this purpose and run MFDS under that account.

Note: Accounts created to run services must have the "Log on as a service" permission assigned to them using the Local Security Policy or Domain Security Policy, depending on whether the account is a local or domain one.
Note: The service setting "Allow service to interact with the desktop" is only available for services running as LOCAL_SYSTEM. Without this setting, the enterprise server region console window cannot be displayed on the desktop unless the region is started from the command line. However, the "Allow service to interact with the desktop" setting is a significant security vulnerability in itself, so this minor usability issue will have to be tolerated.
Running Enterprise Server processes from the command line
When processes are started from the command line, they inherit the account of the shell (Windows cmd.exe, Powershell, etc.) that they were started from. Avoid starting regions and running utilities from "Administrator command prompt" windows.
IDEs
Developers often run IDEs under administrator accounts. Avoid this if possible. However, most IDE operations related to Enterprise Server interact with already-running processes, so the account used by the IDE is not inherited for most of the processing within enterprise server instance.

Check for additional privileges

In Windows, user accounts can be assigned additional security privileges regardless of whether they are members of the Administrators group. Some of these privileges are "administrator equivalent": if a process holds the privilege, it can leverage it to gain administrator-level access. Other privileges can be exploited in ways which are not equivalent to full administrator access but are still dangerous.

The privileges assigned to an account can be viewed and changed using the Local Security Policy and Domain Security Policy user interfaces (and various scripting mechanisms, etc.). This is a standard task in Windows system administration.

Some privileges which are commonly assigned to user accounts and are particularly sensitive:

Back up files and directories
This allows a process to bypass file permissions to read files. It could be used to exfiltrate sensitive data, discover passwords, etc.
Create symbolic links
This could be abused to cause processes to load malicious versions of DLLs, for example.
Debug programs
This is equivalent to having administrator access, since it can be used to inject code into arbitrary processes and run it. It is not necessary to hold this privilege to debug programs running under your own account, so developer accounts should not routinely hold it.
Load and unload device drivers
The ability to load arbitrary device drivers is equivalent to having administrative access if the attacker can put a malicious device-driver module on the system.
Replace a process level token
In some circumstances (how this process interacts with Windows security is complex), this may allow an attacker to start a process under a different user account.
Restore files and directories
Ths allows a process to bypass file permissions to write files. It is equivalent to having administrator-level access, since an attacker can overwrite sensitive program files with arbitrary code.
Take ownership of files or other objects
This privilege is equivalent to having administrator-level access, since ownership implies full access to an object.

Secondary aspects of privilege on Windows

There are additional ways to prevent programs from taking undesirable actions on Windows. These are less critical than administrator access and security privileges, but organizations which are particularly security-conscious may want to review them.

Network file sharing
Windows File Sharing is account-specific. Remove unneeded persistent shares and mounts from the account(s) used for Enterprise Server processes.
Access to devices
Windows Group Policy can be used to restrict access to printers and other devices, in cases where it's not required.
Program path
Set the PATH environment variable to include only the necessary directories. Sometimes a vulnerability lets an attacker control the name of a program being executed, but not the full path to it; or lets an attacker place malware in a well-known directory which may be on the path unnecessarily.
Parent topic: Running with minimal privilege


Hardening filesystem permissions

As a system for running production applications, Enterprise Server will inevitably have access to some sensitive data. However, it is still worthwhile limiting the ability of Enterprise Server components and applications running in an enterprise server region to read and write data and system files which are not required for proper operation, and to prevent executing inappropriate programs. This can be achieved with careful use of filesystem permissions.

Comprehensively configuring filesystem permissions for security is difficult because filesystems are large and complex. Also, the operating systems under which Enterprise Server runs administer filesystem permissions by individual file and/or hierarchically, so determining which permissions to set where, and ensuring they are set consistently, might require considerable effort. Setting proper permissions for even some portions of the filesystem will reduce the attack surface and potential for exploitation.

Micro Focus recommends the following approach to hardening filesystem permissions:

  1. Run Enterprise Server programs under user accounts created specifically for that purpose. It is sometimes useful to have multiple user accounts so that privileges can be assigned differently for various components. For example, the Enterprise Server Common Web Administration (ESCWA) and MFDS components require additional access which is not appropriate for the processes running under an enterprise server region, so you may wish to create one user account for ESCWA and MFDS and another for regions.

    This is somewhat more difficult on UNIX when POSIX (traditional UNIX) file permissions are used, as those only allow three sets of permissions: one for the owner, one for the group, and one for all other users. Also, on UNIX, MFDS normally is started as root, and shortly after startup it will change its effective account to the Enterprise Server system user account. For these reasons, it is common on UNIX to have a single system user account which is used by all Enterprise Server processes.

  2. Determine which programs and data files Enterprise Server components require access to, and what level of access is required. For example, the MFDS repository files must be writable by MFDS, but can be read-only for enterprise server region.
  3. Where possible, group program files used by regions in a single directory tree, and data files used by regions in another directory tree, to make setting and checking permissions simpler.
  4. Grant the appropriate access to the filesystem objects identified in the previous steps to the user accounts created for use by Enterprise Server. See the topics listed below for more information.
  5. Deny access to other filesystem objects to the Enterprise Server user accounts.

Some specific items to attend to:

  • The MFDS repository-export function takes a path specified by the user. It is important that MFDS has write access to only a limited set of directories to prevent the abuse of this feature.
  • In some cases, the primary security task is not to restrict Enterprise Server access to a file, but to restrict other accounts' access to it. For example, the key files used with TLS should only be readable by Enterprise Server and administrators. See Using and hardening TLS for more information. Typically, data files used by applications running under Enterprise Server should not be readable or writable by programs running under other user accounts.

Additional administrator user accounts

As noted above, there will generally be one or more Enterprise Server system user accounts which ESCWA, MFDS, and enterprise server region processes run under. When administrators use ESCWA to perform administrative tasks, those will also be performed under the system user account, so only that account needs additional, privileged access to Enterprise Server filesystem objects.

In some organizations, however, some administrators or automated processes may perform administrative actions under different accounts, for example by running command-line utilities such as casstop or esfadmin. Those accounts will need additional access, typically the same access granted to the ssytem account, as described in Filesystem permissions: Windows or Filesystem permissions: UNIX.

WINDOWS To achieve this:

  1. Create an Enterprise Server administrators user group in Windows.
  2. Add the system user account(s) and all other administrative accounts to it.
  3. Use it, rather than the system account, when granting additional write access as described in Filesystem permissions: Windows.

UNIX POSIX file permissions limit the granularity of filesystem access. Here are some possible approaches to assigning filesystem permissions when there are multiple Enterprise Server administrative user accounts:

  • Have all administrators switch to the system account when performing Enterprise Server administration tasks, using a tool such as su.
  • Use Access Control Lists in addition to POSIX file permissions, to grant the additional access to a group which all administrators belong to. All the UNIX platforms currently supported by Enterprise Server support ACLs for the most commonly used filesystems, though the details vary among operating systems. Consult your OS documentatio nfor more information.
  • Create an Enterprise Server administrators group. Set the group ownership of files and directories to this group, rather than to an Enterprise Server users group as described in Filesystem permissions: UNIX. Follow the instructions in that topic but grant the elevated permissions to the group as well as the owner, and grant read-only access to "others" (all users) rather than to the group.
  • Filesystem permissions: Windows
    Setting filesystem permissions on Windows.
Parent topic: Hardening the operating environment


Filesystem permissions: Windows

Windows implements filesystem permissions using Access Control Lists (ACLs), which permit setting "allow" and "deny" rules for various types of access, for users and groups. It's generally best to avoid deny rules where feasible and use only allow rules to express the desired set of permissions.

ACLs can be set interactively by an administrator (or by a non-administrative user, for filesystem objects owned by that user) using Windows Explorer. However, as with other administrative tasks, we recommend this be scripted using Powershell or another scripting language so it can be saved and repeated if necessary.

If user accounts have been created for Enterprise Server processes, and application programs and data files have been organized into their own filesystem trees as recommended in Hardening filesystem permissions, then it should be straightforward to set the appropriate permissions for those accounts. Ensure those accounts are not members of groups with excess permissions (such as Administrators). Set inheritable ACLs granting the desired degree of access on the root directories of the trees containing programs and data files.

Parent topic: Hardening filesystem permissions


Additional operating-environment notes

Various guides to hardening steps specific to each operating system are available from OS manufacturers and other online sources. For production systems especially, Micro Focus recommends consulting such guides.

Parent topic: Hardening the operating environment


Hardening the operating environment: Summary

When hardening an Enterprise Server installation, review the following steps. Consult the topics in this document and related ones in your product Help for more information.

Run processes under user accounts created for that purpose
Create user accounts specifically for use by Enterprise Server processes, and run processes using those accounts.
Run processes with appropriate privileges
Configure the accounts used to run Enterprise Server processes with only the privileges required for Enterprise Server itself and the applications running under it.
Set filesystem permissions
Restrict file access for Enterprise Server and application processes to only the necessary programs and data files.

Restrict access to files used by Enterprise Server and applications so unauthorized users cannot read or modify them directly.

Parent topic: Hardening the operating environment


Hardening enterprise server region

Various configuration changes can improve the security of an enterprise server region. These are separate from hardening the environment in which Enterprise Server is running, and hardening the applications which are running under Enterprise Server; those are dealt with in other sections of this document.

These changes are organized into the following areas:

Reducing the attack surface
Disabling features that are not required for a particular instance, and restricting access to ones which are, makes the attack surface available to the attacker smaller. An attacker has fewer opportunities to find vulnerabilities in the system.
Enabling additional controls
The stock configuration for Enterprise Server External Security Facility does not enable all the supported security checks, in order to maintain backward compatibility. Enhanced security can be achieved by enabling additional security controls.
Removing or changing default credentials
The template enterprise server region, and associated components such as MFDS, have various default user accounts, some of which have corresponding passwords. Change these to prevent attackers from using them.
Restricting administrative access
Restrict which users can perform administrative tasks such as altering region configuration and defining CICS resources.

See the topic Restricting remote program execution and the chapter Using and hardening the supplied configuration for more information.

  • Reducing the attack surface
    Disable unnecessary features so they are not available to attackers.
  • Enabling additional controls
    Enable optional security controls to restrict access and eliminate vulnerabilities.
  • Removing or changing default credentials
    Eliminate well-known accounts or change their passwords to prevent attackers from using them.
  • Restricting administrative access
    Prevent non-administrative user accounts from performing administrative actions.
  • Restricting remote program execution
    Hardening Enterprise Server against executing arbitrary programs.
  • Additional region notes
    Additional notes regarding hardening enterprise server regions.
  • Hardening regions: Summary
    A summary list of major recommendations for hardening enterprise server regions.
Parent topic: Securing Enterprise Server


Reducing the attack surface

The security of an enterprise server region can be improved considerably by disabling unnecessary features. Recent releases of Enterprise Server disable some features, such as remote service deployment, by default, but more can be done, depending on the customer's requirements.

Disabling features that are enabled by default

When Enterprise Server is initially installed, and when a new enterprise server region is created, they will use a default configuration, also known as the out-of-the-box configuration. This configuration enables a number of features which are not required by all customers, for convenience and backward compatibility. Micro Focus recommends you disable features that are not required.

The features in question include:

  • On Windows, optional components and services the Enterprise Server installer adds and starts include:
    • Micro Focus EA Service Integration host for Enterprise Analyzer.
    • Services for Enterprise Server for .NET:
      • Micro Focus Event Monitor Service Shutdown Coordinator
      • Micro Focus SEE Administration Server
      • Micro Focus SEE Listener
      • Micro Focus SEE Monitor
      • Micro Focus SEE Service Bus Logon
    • Micro Focus XDB Server for the XDB database.

    For all of these, if the feature in question is not being used, the service should be stopped and disabled.

  • For MFDS:
    • The MFDS Web administration interface ("Enterprise Server Administration"). The Enterprise Server Common Web Administration (ESCWA) can be used instead. See the Security chapter in Enterprise Server Common Web Administration for more information.
    • The "UDP broadcast" option (Configure > Options > General). This feature is used by MFDS when it is asked to resolve the address of a Micro Focus CCI service, such as Fileshare, and it does not recognize the requested service name. If this option is enabled, MFDS will send a UDP broadcast search request for the service to its local subnet, asking if any MFDS instance on the subnet has information for that service. (UDP broadcasts do not traverse routers to other networks.) Most enterprise server instance installations do not require this functionality.
  • For regions:
    • Disable or delete unnecessary listeners. A newly-created enterprise server region will have a "Web" listener, which should already be disabled. This is used for COBOL Web Service and EJB deployment. Micro Focus recommends deleting this listener in production environments. A newly-created MSS enterprise server region might also have a "TN3270" listener, which should be disabled or deleted if it is not required.
  • Additionally, for MSS enterprise server regions:
    • The default CICS resource definition file contains a number of groups for demonstration purposes. Remove these, particularly from enterprise server region in production environments. Remove or disable other definitions which are not required.

Disabling optional features that are no longer needed

An Enterprise Server installation may have features enabled which are not enabled by default, either because it is, or was upgraded from, an older product release or because they were enabled after installation. See Hardening enterprise server instance for more information. If any of the following are enabled, they should be reviewed and, if not required, disabled:

  • For MFDS:
    • Access on external network interfaces. This is an MFDS configuration option which lets clients connect to MFDS from remote systems. If you are using Enterprise Server Common Web Administration (ESCWA), MFDS is running on the same system as the enterprise server region it defines, and no external clients need to make TCP connections to MFDS (for example, to use the -l option of the cassub command), then it is safer to restrict MFDS to loopback connections only.
  • For enterprise server regions:
    • If the enterprise server region's Configuration Information field contains an [ES-Environment] section, remove any unneeded entries. Take notice of any environment settings which are significant for the OS or COBOL RTS, such as PATH and COBPATH, and ensure their values are safe. For example, they should not contain any directories which an unprivileged user might be able to write to.
    • Disable tracing which is no longer required, as that can potentially reveal useful information to an attacker.
    • Disable dynamic debugging support if feasible, particularly for enterprise server regions in a production environment.
  • Additionally, for MSS enterprise server regions:
    • Remove any unnecessary directories from the CICS transaction, map, and file paths.
    • Disable EZ Socket support if it is not required.
    • Remove any unnecessary directories from the JES program path.
    • Remove any unused JES printer definitions.
    • Remove any unnecessary directories from the IMS TM MFS and application paths.
    • Disable PL/I support if it is not needed.
    • In the CICS resource definitions used by the region, disable or remove any definitions that are not required. Be aware that users might be able to bypass disabling of definitions if they have authority to install resource groups or perform other administrative actions, so it is safest for enterprise server regions in a production environment to use a CICS resource definition file that contains only the definitions needed by the production application set.
    • If the region is used for JES, remove unnecessary entries from the catalog.
    • In the IMS configuration (if any) used by the enterprise server region, ensure only the required definitions are present.
Parent topic: Hardening enterprise server region


Enabling additional controls

Additional security controls, beyond those enabled by product installation and configuring security with the default settings, can be enabled for greater enterprise server region security.

ESF resource classes

There are some optional resource classes which are not defined by the default security configuration shipped with Enterprise Server. Defining these classes and installing appropriate resource access control rules can significantly improve security.

This topic assumes that the External Security Facility (ESF) has been configured, and a Security Manager using the MLDAP ESM Module or VSAM ESM Module is being used for resource access control.

See your product Help for more information on how to specify additional resource classes in the External Security Manager.

PHYSFILE
The PHYSFILE resource class restricts what OS files can be used as JCL data sets.
Important: You must specify this class for any enterprise server region which uses JES. Otherwise, any user that can submit arbitrary JCL can operate on any file on the server system, with the permissions of the account under which the enterprise server region is running, simply by defining a data set appropriately using a catalog entry or PCDSN.

Under the PHYSFILE class, rules should allow one or more paths, with the appropriate level of access (typically at least one with full access for creating new data sets, possibly some with read-only access), and deny others using a rule with the name **.

Communications Server
The Communications Server class is used to restrict access to some administration features of the Communications Server process(es) associated with each enterprise server region. Restricting these features improves security primarily by reducing the information available to an attacker. See Resource Classes for Communications Server in your product Help for more information.
AdminAPI
This class can be used to restrict access to the External Security Facility's Admin API. If the Admin API is not being used to update security data, an appropriate rule set might be:
LIST*: allow:*:read
*: deny:*:all
This would permit only LIST functions, which are used internally by some Enterprise Server functions.

Security checks for CICS transactions

When a CICS transaction program is executing, the security checks made by the CICS subsystem are influenced by two settings in the CICS PCT entry for that transaction:

Resource Level Security (RLS)
This option controls whether access checks are made for the CICS resources (such as files, queues, and so forth) specified in EXEC CICS statements.
Command Security (Cmd)
This option controls whether access checks are made if the program attempts to use any of the CICS System APIs, such as EXEC CICS INQUIRE.

Enabling these options in the CICS transaction definitions improves security.

Parent topic: Hardening enterprise server region


Removing or changing default credentials

As installed, Enterprise Server includes various default user accounts, some of which have documented or obvious passwords. The sample LDAP security configuration contains more of these. Well-known credentials are a serious security risk, so region hardening should include removing or disabling these accounts, or at least changing the passwords.

The following discussion assumes ESF with LDAP-based security is being used by all enterprise server instance components.

MFDS default user accounts

MFDS initially installs a set of user accounts at various permissions levels. These accounts are named administrator, adddelete, modify, and schemaadmin. It also adds the SYSAD user if it does not already exist; it is also defined in the es_default_ldap*.ldf LDIF files used to populate the LDAP repository with CAS security data. All of these have passwords which match their usernames.

Micro Focus strongly recommends removing these accounts and creating only the MFDS user accounts required for your organization's use. Typically, this will be at least one account which is a member of the #AllUser and #DSAdmin groups; this would be the MFDS full-access administration account, equivalent to schemaadmin. Some organizations will also want MFDS accounts with fewer permissions. See your product Help for more information regarding MFDS default groups and permissions.

Alternatively, change the passwords for these accounts. Changing passwords is not as secure as disabling or deleting accounts which are not required, and replacing well-known account names with ones which are not known to attackers, but this still offers a significant security improvement.

MFDS internal accounts

MFDS also installs a set of accounts for use by other enterprise server instance components. These accounts are used by default by those components, and effectively represent an unsecured installation. They are mf_cs, used by Communications Processes; mf_dep, used for COBOL Web service and EJB deployment; and mf_mdsa, used by CAS.

The mf_cs and mf_mdsa accounts are only used when an enterprise server instance region is started without specifying a username and password. It is best to disable these accounts, and for extra security change their passwords as well, and always start regions using credentials.

The mf_dep account is used by the mfdepinst program, which installs COBOL Web services and EJBs to enterprise server regions from CAR files. mfdepinst needs to connect to MFDS and add service and package objects as part of the installation process; by default, it uses the mf_dep account. Different credentials can be specified in the .mfdeploy file or on the mfdepinst command line. Customers not using COBOL Web services or EJBs might disable this account or change its password if required, which will also prevent use of mfdepinst to create service and package objects unless suitable credentials are provided.

Note: Enterprise Server includes a file named cci-users.dat which contains definitions for the MFDS default accounts. This file is only used to create the MFDS Internal Security set of initial users. It can be ignored.

CAS default user accounts

Enterprise Server LDAP-based security is typically initialized using one of the es_default_ldap* LDIF files supplied with the product. Those files install a handful of sample user accounts: mfuser (with no password), SAFU (password "test"), SAFUIMS (password "test"), and SYSAD (password "SYSAD"). As with the default MFDS user accounts, these should be deleted or disabled, with customer-appropriate accounts created as necessary. SYSAD is intended as an administrative account and can be used as a template for creating other administrators.

If it is not practical to remove these accounts, change their passwords.

The mfuser account plays a special role. It is the default user for ESMAC, and for region startup and shutdown if credentials are not supplied when starting and stopping the region. Micro Focus strongly recommends setting a password for the mfuser account.

Additional steps are required to disable anonymous access to ESMAC. See Restricting administrative access for more information. Micro Focus strongly recommends disabling anonymous access to ESMAC.

CAS system accounts

CAS also installs and uses a number of system accounts, which are not intended for direct use by users. They are:

CICSUSER, IMSUSER, and JESUSER
These are the default accounts for the mainframe subsystem personalities. They are used for any security checks performed when no explicit user account is associated with the executing task. For example, CICSUSER applies when a user has not signed into CICS. By default, these accounts have no passwords; passwords should be set for them, so users cannot sign on using them. The accounts can also be renamed, using environment variables, such as ES_USR_DFLT_CICS. These are typically set in the [ES-Environment] section of the enterprise server region's Configuration Information field.
mfuser
Described in the previous section. Remove or disable this account, or assign it a password.
PLTPISUR
Used during PLT (enterprise server region startup/shutdown) processing. This has a password of "PLTPISUR"; it should be changed.
Parent topic: Hardening enterprise server region


Restricting administrative access

It is important to restrict administrative actions to those users who require that level of access. This is part of what is referred to as the Principle of Least Privilege: actors such as users and programs should be granted only the privileges necessary to perform their functions.

This is not only a matter of trust; it also protects the organization if a non-administrative account is compromised. Many successful attacks involve gaining access to an ordinary account and then elevating and pivoting to gain additional access.

Administrative functions which should be controlled include:

  • Administration UIs such as ESCWA, MFDS, and ESMAC. These can be restricted using resource access control rules. Ensure you disable anonymous access to ESMAC. See Removing or changing default credentials for more information.
  • Security data, which can potentially be altered using enterprise server instance utilities such as esfadmin, with third-party clients, or by manipulating data files directly. Configure security-data repositories such as LDAP servers with security controls and set appropriate permissions on the files they use.
  • CICS and IMS resource definitions. Set appropriate file permissions on the resource definition files such as dfhdrdat. For CICS, enable controls on the CICS system APIs. See Enabling additional controls for more information.
  • System utilities and transactions which perform administrative actions, such as CICS CINS. Those that run within an enterprise server region can be restricted using resource access control rules; those that run outside can have file permissions set.
  • Where feasible, administrative actions in the OS relevant to Enterprise Server should also be restricted. These include such actions as starting and stopping services on Windows, or killing processes on UNIX.

Restricting access to ESMAC

In addition to setting security controls for ESMAC, it is necessary to disable anonymous access to ESMAC, as mentioned in Removing or changing default credentials. In some older releases of Enterprise Server, this could be performed by assigning a password to the mfuser account. In current releases of Enterprise Server you must take additional steps.

To disable anonymous access to ESMAC:

  1. Assign a password to the mfuser user, or to whichever account is set as the default ESMAC user using the ES_USR_DFLT_ESMAC environment variable.
  2. Set the environment variable ES_ESM_DISABLE_DFLTUSER_ESMAC. See Configuring the Default ESMAC User in your product Help for more information. In addition or optionally, you can set the environment variable ES_DISABLE_DFLTUSR_SIGNON. See Security and Auditing Environment Variables in your product Help for more information.
    Note: There is a difference in the spelling of DFLTUSER and DFLTUSR between these two variables.
    These variables can be set in the global environment or in the Configuration Information field, under a [ES-Environment] configuration section for the enterprise server region. For example:
    [ES-Environment]
# Prevent anonymous access to ESMAC
ES_DISABLE_DFLTUSR_SIGNON=Y
ES_ESM_DISABLE_DFLTUSER_ESMAC=Y

    The function of these two settings is subtly different. For most purposes they have the same effect, but ES_ESM_DISABLE_DFLTUSER_ESMAC will also prevent signing on to ESMAC using the mfuser account, even with a password. It will also disable converting a blank username to "mfuser", and the use of the Default button on the ESMAC sign-on page. For maximum security, Micro Focus recommends setting both of these variables.

Parent topic: Hardening enterprise server region
Related information
ES_DISABLE_DFLTUSR_SIGNON
ES_ESM_DISABLE_DFLTUSER_ESMAC


Restricting remote program execution

One of the major goals for an attacker attempting to exploit a system is to gain the ability to execute arbitrary program code remotely. Unfortunately, as an application server, Enterprise Server is designed and intended to do precisely that: enable the remote execution of programs. So restricting which programs can be executed, and access to those programs, is a key aspect of hardening Enterprise Server.

There are two main contexts in which Enterprise Server executes arbitrary (customer-supplied) programs:

  1. Conventional COBOL applications might be exposed as Web services and Enterprise JavaBeans (EJBs) when an enterprise server region is used to support the COBOL service-oriented architecture.
  2. Under the Mainframe Subsystem Support (MSS) feature, programs written in COBOL, PL/I, Mainframe Assembler, and REXX, and scripts written in JCL can be executed by the Enterprise Server CICS, JES, and IMS subsystems.

In either context, there are three main avenues for hostile remote program execution:

  1. Hostile code is deployed as part of a legitimate application, through an authorized process for deploying applications to Enterprise Server. This might be done by an organization's employee (for example, a developer), or through a supply chain attack in which an attacker gains access to the application source code or the build or deployment pipeline. This document does not cover this category of threats in detail, but there are some notes below.
  2. An existing legitimate application is abused. This can be mitigated by improving application security, which is also out of scope for this document, and restricting illegitimate access to applications.
  3. An attacker is able to deploy a hostile application to an enterprise server region. This differs from a conventional supply chain attack in that the attacker is not subverting a legitimate application, but deploying an entirely new one. In some cases this can use an organization's approved deployment mechanism; in others, it might use an alternative mechanism.

Improving application security to protect against remote code execution

Application security can cover many aspects, but particular attention should address the following potential vulnerabilities:

  • Executing external programs using CALL "SYSTEM", pipe syntax with file I/O, and so forth.
  • Dynamic loading of program objects using the CALL statement, when the name of the program or path information might be controlled by an attacker. Watch for CALL statements using a data-item rather than a literal for the program name. Entry-point name mapping is also a potential vector. For CICS programs, watch for dangerous use of EXEC CICS LINK and EXEC CICS XCTL.

Restricting access to existing applications and programs

Ways to control access to applications hosted in an enterprise server instance include:

  • Application security features, such as requiring user sign-on and enforcing authorized access internally. This is outside the scope of this document.
  • Resource access control rules in the security configuration. This only applies to MSS applications; COBOL Web services and EJBs do not currently make use of external security. Resource classes that apply here include the TCICSTRN and MCICSPCT classes for CICS and the TIMS class for IMS. Unfortunately, there is no equivalent resource checks for JES, but access to job submission can be controlled using the JESINPUT class.
  • Communications security. Since remote program execution requires network communications, the vulnerability can be partly mitigated by restricting how attackers can connect to the region. This includes restricting which interfaces listeners use, using conversation filtering, and using TLS with client authentication. Communications can also be secured after a connection is made, for example, by requiring sign-on after connecting over TN3270.

Job submission to the JES engine is a particularly dangerous vulnerability for any enterprise server region which has JES enabled. The problem is that any user authorized to submit a job can run arbitrary programs, as long as they are found on the region's program path and have appropriate permissions for the system account under which Enterprise Server is running; and those programs can access any files on the system with the permissions of that account by using PCDSN syntax.

Features for restricting access to JCL submission are not entirely satisfactory. Micro Focus recommends the following:

  • Set the environment variable CASRDO44_NEWSUB=OFF. This will prevent submitting local JCL through ESCWA or ESMAC. These Web interfaces will only allow you to submit JCL by reference, that is JCL which already exists on the server system. This prevents one method of submitting arbitrary JCL. There is no practical way to prevent submitting arbitrary JCL remotely using cassub or similar.
  • Use rules of the form SUBMIT.region.jobname.userid in the JESJOBS class to restrict which users can submit which jobs.
  • Consider using JESINPUT or TSUINRDR to restrict job submission to only a single userid, then configure MFBSI to use that userid. This will force all job submission to occur through a scheduler, which could perform additional checks.
  • It would also be possible to use JESINPUT or TSUINRDR to disallow direct submission entirely, then submit JCL only through CICS or IMS (controlled by STCINRDR) and other JCL jobs (INTRDR). Then access to job submission could be controlled by CICS or IMS applications.

For CICS, prevent unauthorized users from adding CICS resource definitions, either through the administration user interfaces or by using CICS system APIs, as discussed in previous sections. This will mitigate against attackers executing existing programs by creating CICS transactions for them, or by specifying them as queue trigger programs, and so forth.

Disable or restrict access to the CRUN CICS transaction, which executes an arbitrary program.

Preventing the deployment of hostile applications

This vulnerability applies primarily to the COBOL Web service and EJB feature of Enterprise Server, and specifically to the remote-deployment feature. Remote deployment is convenient for developers, but should always be disabled in a production environment. It is an extremely dangerous vulnerability, because in the default configuration (once enabled) it lets anyone install any program under an enterprise server region.

If deployment is enabled, additional security measures can be configured for it. See Security Considerations for Service Interface Deployment in your product Help for more information.

Parent topic: Hardening enterprise server region


Additional region notes

Use ESF for security

As installed, enterprise server regions and other components do not use the External Security Facility (ESF). They should be configured to use ESF and a suitable External Security Manager (or managers). The MFDS Internal Security manager, which MFDS uses by default, is deprecated and should not be used in production. Similarly, the CAS Sign-on Table (SNT) security manager has limited features and is not recommended for production use. Most of the topics in this chapter assume ESF is being used. See Using and hardening ESF for more information.

Parent topic: Hardening enterprise server region


Hardening regions: Summary

When hardening an Enterprise Server installation, review the following steps. Consult the topics in this document and related ones in the your product Help for more information.

Disable unneeded features
Reduce the attack surface by disabling any features you are not using in Enterprise Server and your enterprise server regions.
Use ESF
Use the External Security Facility (ESF) with LDAP-based security for a comprehensive set of security controls. The legacy security mechanisms (MFDS Default Security and CAS SNT) are not sufficient.
Eliminate well-known credentials
Remove all of the default accounts, or change their passwords. Assign passwords to default and system accounts which do not have them in the sample configuration: mfuser, CICSUSER, IMSUSER, and JESUSER.
Enable additional controls
Enable additional security controls which are not enabled in the sample security configuration.
Restrict administrative access
Create resource access control rules to restrict what non-privileged users can do with the administrative user interfaces, utility programs, and APIs.
Restrict remote program execution
Apply various mitigation to make it more difficult for attackers to execute arbitrary code or abuse existing applications and programs.
Parent topic: Hardening enterprise server region


Using and hardening ESF

The External Security Facility (ESF) is the major security feature of Enterprise Server. One of the major stages of securing an Enterprise Server installation is enabling and configuring the ESF.

ESF uses one or more External Security Managers (ESMs), which are components outside Enterprise Server that help ESF make security decisions and hold security data such as information about users and resource access control rules. ESF communicates with ESMs using ESM Modules. The process of hardening ESF involves both ESF itself, through the security configurations used by various Enterprise Server components, and the security manager definitions which tell ESF how to connect to ESMs. Each security manager specifies an ESM Module, and the hardening process that is specific to that module.

  • Security Managers and security configurations
    Security Manager definitions and security configurations.
  • Additional ESF notes
    Additional notes about hardening ESF.
  • Hardening ESF: Summary
    A summary list of major recommendations for hardening the External Security Facility configuration for Enterprise Server.
Parent topic: Securing Enterprise Server


Security Managers and security configurations

Enabling the External Security Feature (ESF) for an Enterprise Server component, such as the Micro Focus Directory Server (MFDS), the Enterprise Server Common Web Administration (ESCWA) server, or an enterprise server instance (or "region"), involves specifying a security configuration. These various contexts in which a security configuration can be specified — enterprise server instance, MFDS, and ESCWA — are sometimes referred to as security domains.

In ESCWA, the security configuration for an enterprise server instance is specified on the Region Security Facility Configuration page or on the Default ES Configuration page, depending on whether it uses the default configuration. For configuring MFDS security in ESCWA there is a Directory Server Configuration page under the Security menu for the MFDS instance. ESCWA security itself is configured using the Security Settings page available via the spanner icon ( [image]) on the menu bar.

Each security configuration includes a list of Security Managers. A Security Manager defines an External Security Manager (ESM) to ESF. It includes the name of an ESM Module which provides the interface to the ESM, and typically connection information and processing options. In ESCWA, Security Managers are specified on the Security Managers page for an MFDS instance. Any number of Security Managers can be specified. When a security configuration lists multiple Security Managers, they are usually invoked in the order listed to process each security query (though some options affect which managers are used).

64/32-bit Security Managers

It is necessary to have the correct bitism for the security domain that is going to use the Security Manager. If the enterprise server region is a 64-bit region, it will require a 64-bit security manager. Similarly, the security manager used for MFDS must have the same bitism as MFDS.

If MFDS and the enterprise server region have different bitisms, they might not be able to use the same Security Manager. They can use the same external security manager (for example, LDAP repository) but two separate Security Manager definitions might be required. These would use essentially the same configuration details but any bitness-specific configuration items would differ.

For example, the MLDAP ESM Module has an optional provider configuration setting to specify an LDAP client library; this would need to name a library of the correct bitness. The details will depend on the platform and installation decisions made by the system administrator, but it might look like the following.

In the Security Manager, for 32-bit enterprise server regions and for MFDS (which is normally 32-bit, except on 64-bit-only platforms):

[LDAP]
provider=/usr/lib/libldap_r-2.4.so.2.7.1

In the Security Manager for 64-bit regions:

[LDAP]
provider=/usr/lib64/libldap_r-2.4.so.2.7.1

The difference in this case is in the location of the shared object, /usr/lib versus /usr/lib64.

Note: In recent Enterprise Server releases, the MLDAP ESM Module often does not need the provider setting, as it has improved logic for finding the commonly-used LDAP libraries in their normal installation locations.

The ESM Module must be the correct bitness for the Security Manager. If one of the standard ESM Modules provided with Enterprise Server is used, and it is specified in the Security Manager definition using just its base name (for example, mldap_esm) with no path or extension, then ESF will automatically select the module of the correct bitness. If the Security Manager specifies a path or extension for the module, only that specific file will be used, and you will need separate 32- and 64-bit Security Manager definitions.

Security Manager configuration

Hardening recommendations for Security Managers depend on the ESM Module used. See the following subtopics listed below for each standard ESM Module.

Security Configuration options

Each of the Security Configuration pages — Default ES Security, Security for a specific region, Directory Server Configuration, and the ESCWA Security Settings — provide options to configure ESF. The MFDS Directory Server Configuration and ESCWA Security Settings pages also have some options specific to those components.

ESF options relevant to hardening include:

Allow unknown users
This option should typically only be enabled for certain test situations. It allows anyone to sign on to the system using an unrecognized user ID and any password.
Allow unknown resources
Avoid this option where security is a concern; it permits the use of any unrecognized resource, which might, for example, let an attacker access system files through Enterprise Server applications. It is useful primarily for developers using their own test installations and while phasing in the initial set of security rules.
Verify against all Security Managers
Typically, user authentication (the Verify operation) is decided by the first Security Manager which returns a definite result — either allow or deny sign-on. When this option is enabled, all Security Managers are consulted until either one returns a deny result, or they have all returned allow or unknown (and at least one returned allow, unless "Allow unknown users" is also enabled). In effect, this option lets each Security Manager veto user authentication. It may be appropriate in some security configurations, particularly if a Security Manager has been configured specifically to reject certain users under certain circumstances, such as time of day.
Create audit events
Auditing can improve security by providing an audit trail for forensic analysis if a breach is discovered or suspected. Audit information can also be processed in real time or periodically to check for suspicious activity, or to monitor particularly sensitive resources. Note that enabling this option requires configuring the Micro Focus Audit API, and using a Security Information Event Manager (SIEM) such as syslogd or the Micro Focus Sentinel or ArcSight product to receive and process audit data.
Use all groups
While neither setting of this option is necessarily more secure, some organizations choose to disable it so they can give users particular roles based on their choice of sign-on group. For example, a user might have both an "application" role and an "administration" role, with different resource permissions in each, selected by which group is specified when signing on. Other organizations prefer to enable this option so the system behaves more like Windows or UNIX.
Cache TTL and limit
These options disable ESF caching (if either is set to zero) or enable it (if they are both non-zero). Depending on the organization's threat model and security posture, there may be a security benefit to disabling caching, to prevent ESF from using stale results when changes are made to the security information held by ESMs. For most organizations, some caching is desirable for improved performance. The organization should determine its tolerance for stale security results and set the Cache TTL appropriately. A setting of 60, for example, means no result more than a minute old will be returned by the cache. Also, the ESF Update mechanism can be used to flush the cache.
Configuration text: Group federation
The group federation mechanism can be enabled in the configuration text field using the following setting:
[Operation]
Federate=yes
Note: Section names and keywords are case-insensitive.
Group federation only applies if there are multiple Security Managers being used.

When group federation is enabled, all security managers for the security domain (enterprise server region, MFDS, or ESCWA) share a single list of user groups. Each security manager may add groups to the list, access control rules in one security manager may refer to groups defined in other security managers, and so on. When federation is explicitly disabled with Federate=no, each security manager has its own group list and understanding of which users belong to which groups. If no federation setting is specified, the security managers operate in backward-compatibility mode, which has semantics that are complicated and probably undesirable.

Micro Focus recommends enabling group federation unless the organization has a specific reason for requiring each Security Manager to keep separate group information.

Configuration text: Redundant mode
Redundant mode is an option for customers who are concerned about availability and can put all of their security information in a single security manager. In redundant mode, the security managers are not treated as separate sources for making security decisions. Instead, only the first security manager is used, unless it fails; then the second is used, and so on. So for redundant mode, all security managers must be equivalent in how they make security decisions, for consistency. Redundant mode also requires group federation.
Settings that apply to redundant mode are as follows:
[Operation]
redundant=yes
failover retry interval=time
The failover retry interval setting determines whether failed ESMs will be retried, and if so, how often. An appropriate value for this setting depends on the customer's requirements. See your product Help for more information.
Configuration text: Verify throttling
Verify throttling helps prevent brute-forcing user credentials by slowing down processing when too many Verify (authentication) requests are received by a process in a certain time interval. By default, this is triggered if more than 100 Verify requests are received in a second. The threshold can be changed, or throttling disabled entirely, using the [Operation] verify throttle threshhold setting. Micro Focus recommends leaving throttling enabled, although you might need to adjust the threshold if your workload triggers it.
Configuration text: ESF cache options
In addition to the cache size and TTL parameters discussed above, some additional cache options can be set in the configuration text:
[Cache]
requests=types of requests to cache
flush on change=yes|no
report interval=time in seconds
ignore=request fields to ignore in comparison
These are discussed in more detail in your product Help, but briefly:
  • requests sets which types of ESF requests can be cached. By default, authorization requests are cached, but authentication requests are not, so that each user authentication is processed by the ESMs.
  • If flush on change is enabled, then when the result of a request changes, any existing cached information for that request is removed. This is useful if authentication (Verify) caching is enabled and an ESM implements account lockout. See your product Help for more information.
  • The list of request fields in the ignore setting are ignored when comparing an incoming request with entries in the cache. This can improve cache performance if the fields in question are not considered security-sensitive by the customer. By default, the subsystem and facility fields are ignored.

Micro Focus recommends using the defaults caching options for maximum security, and changing them for performance if necessary. If Verify caching is enabled, Micro Focus recommends enabling flush-on-change.

Configuration text: Audit options
Options for auditing only apply if auditing is enabled. The audit options are:
password change success
This controls whether an audit event is generated for a successful password change.
category 3 events
This controls whether audit events are generated for calls to ESF, as well as the results of those calls. The category-3 events are largely redundant, so some customers prefer to suppress them.
selective
This enables selective auditing. In selective mode, audit events are controlled by additional LDAP attributes of users, groups, and resource access rules. Only the MLDAP ESM Module provides selective-audit capabilities. Selective auditing is useful if you only want audit events generated for ESF requests that apply to certain sensitive security objects. Using this requires additional administrative effort, to set the attributes appropriately for objects of interest.

Micro Focus has no specific recommendations regarding these options. Whether they are appropriate will depend on your requirements.

Configuration text: miscellaneous options
Other configuration text settings affect:
  • The ESF user exit (user exit)
  • The ESF Administration feature (allow-list)
  • Username mapping (map short names)
  • Update processing (update interval)
  • Trimming whitespace from character fields in requests (trim whitespace)
  • Passtokens (allow)

See your product Help for more information.

  • MLDAP ESM Module
    Hardening recommendations for Security Managers using the MLDAP ESM Module.
  • VSAM ESM Module
    Hardening recommendations for Security Managers using the VSAM ESM Module.
  • OS ESM Module
    Hardening recommendations for Security Managers using the OS ESM Module.
  • PAM ESM Module
    Hardening recommendations for Security Managers using the PAM ESM Module.
  • Other ESM Modules
    Hardening recommendations for Security Managers using less common and special-purpose ESM modules.
Parent topic: Using and hardening ESF


MLDAP ESM Module

For Security Managers using the MLDAP ESM Module, Micro Focus makes the following hardening recommendations:

Module
Set this to mldap_esm, with no path, and for Linux/UNIX installations, no bitness, threadedness, or file extension suffixes. ESF loads ESM Modules from the product installation directory automatically – it does not search the library load path. ESF will select the appropriate bitness and threadedness automatically.
Connection path
For optimal security, use LDAP-over-TLS by enabling TLS in your LDAP server and using the ldaps: scheme prefix in the value for this field. Depending on the LDAP client library (also known as "provider") in use, you might also have to configure the LDAP client to support TLS. For OpenLDAP, for example, you might need to edit a configuration file such as ldaprc to set the root-certificate file or path so that the OpenLDAP client can validate the server's certificate.
Authorized ID / Password
Micro Focus strongly recommends that you do not use the default credentials. For improved security, configure your LDAP server with an account which gives the appropriate level of access for Enterprise Server use. Typically, this is read-only access to groups and resource access rules, and write access to user objects if necessary for updating attributes such as passwords and last-login-time. Then set these fields to use that account.
Note: You can use the Micro Focus Vault Facility to store a secret for the Authorized ID and Password fields. These fields can be specified using the forms:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
Cache Limit / Cache TTL
From Enterprise Server 7.0, the MLDAP ESM Module can cache the results of some LDAP searches. This can significantly improve performance, but introduces the possibility of making security decisions with stale information. If the cache is enabled, set the TTL to meet the organization's tolerance for latency in recognizing changes to security information.
Note: The ESF Update mechanism will flush the MLDAP ESM Module's cache, reducing this exposure.

Configuration Information settings relevant to hardening

The MLDAP ESM Module supports a large number of options that can be added to the Configuration Information field. Many of these relate to LDAP repository configuration or other aspects which do not directly affect the security of Enterprise Server. Some options which might be useful when hardening an installation are discussed here.

Set login count / Set login time
Enables the module to update these attributes in the user record can provide useful information to administrators. The login-count attribute is also required for implementing account lockout, which is a useful security feature in many environments. This require giving Enterprise Server write access to user objects in LDAP, which is a risk. You will need to determine if that trade-off is appropriate to your organization.
Signon attempts
If Set login count is enabled, this setting can be used to lock accounts out after the specified number of failed signon attempts. This is generally considered good practice.
Note: This requires write access to the user object. Also, the MLDAP ESM Module does not currently support automatic unlocking after a period of time; the account must be manually unlocked by an administrator.
Check TLQ first / Maximum qualifiers for initial check
These options affect the processing of security rules, particularly for data sets. They can improve performance but could result in unexpected behavior and undesirable, if the organization uses rules which begin with wildcards.
Bind
On Windows, the negotiate and es-user options for this setting are somewhat more secure, particularly if LDAP-over-TLS is not used. These options are not currently supported on other platforms.
Password type
This setting only has an effect if Micro Focus password hashes are in effect, and only when users or administrators set passwords. Currently the best choice for this is MF-A2, which uses a salted Argon2 hash, a state-of-the-art type of password verifier. This is the default in current product releases.
Migrate passwords
Enabling this setting is useful if the customer is using Micro Focus password hashes, and has existing user objects that use password verifiers that are not of the MF-A2 type. In this case, Micro Focus recommends enabling this feature.
Password settings
A variety of settings under the [Password] section affect password processing and enables the administrator to harden password use. Most of these only apply when MF-hash passwords are used; otherwise the LDAP server and its interaction with the operating system determine the password-strengthening rules. With MF-hash passwords, Micro Focus recommends the following settings for hardening:
  • Configure Expiration to meet the organization's requirements. Note many security experts now believe regular password expiration is counterproductive.
  • The History setting can be used to prevent password reuse.
  • Set length requirements using Minimum length and Maximum length. Remember that Enterprise Server supports long passphrases in most interfaces, but some applications, such as older CICS applications, might not.
  • The Required and Complexity settings can be used to enforce password complexity. Often organizations have specific requirements for passwords which can be represented using the Required setting; otherwise, Micro Focus recommends setting Complexity to 2 or 3 if the minimum password length is less than 20 characters.
SecretFile
If ESF passtokens are used, for passing authentication between subsystems such as MFDS and ESCWA, or for DCAS, then Micro Focus strongly recommends using this option. The "secret file" can contain anything, as long as it has at least 128 bits of entropy; even 1 KB or so of ordinary text would suffice. The point of this setting is to avoid using either the built-in secret (which is available to anyone with a copy of the product) or a secret in the configuration (which is available to anyone who can view the configuration) to generate passtokens. Otherwise, a technically-skilled attacker could forge passtokens.
Note: there is no space between "Secret" and "File" in the name of this setting.
Trace settings
Tracing can useful in diagnosing issues, but might reveal sensitive data to an attacker who can obtain copies of log files. Micro Focus recommends that you disable tracing when it is not required.
Parent topic: Security Managers and security configurations


VSAM ESM Module

For Security Managers using the VSAM ESM Module, Micro Focus recommends the following hardening configuration modifications:

Module
Set this to vsam_esm, with no path, and for Linux/UNIX installations, no bitness, threadedness, or file extension suffixes. ESF loads ESM Modules from the product installation directory automatically – it does not search the library load path. ESF will select the appropriate bitness and threadedness automatically.
File ownership and permissions
It is important to secure the data files used by the VSAM ESM Module so attackers cannot subvert security by changing the security data. Access to reading and changing the data is determined by OS file permissions, not by ESF, with a couple of exceptions:
  • ESF can impose additional restrictions on changing the files using the ESF Admin API, by using rules in the AdminAPI resource class. For example, using the esfadmin utility or ESCWA.
  • ESF can impose additional restrictions on changing the files using JCL, using rules in the PHYSFILE resource class.
Predominantly, it is OS permissions which will protect the files. There are two common use cases:
  • Typical security: Here interactive users can change their own passwords, and administrators can alter security data using esfadmin or ESCWA. If a malicious program is run under Enterprise Server, it could alter security data. For this use case, set the file ownership to the user account that Enterprise Server processes run under, and give that account write access. If other users need to be able to write to the files — for example, interactive administrators need to be able to edit the files directly — create a user group containing those users and give that group write access to the file as well.
  • Enhanced security: The files cannot be changed by processes running under the ES system user account. Users will not be able to change their passwords and security data cannot be updated through ESCWA, but the security data is protected from any programs running under Enterprise Server. For this use case, make the files owned by a privileged user and deny write access to all other users, for example Administrator on Windows or root on UNIX.
Remember to set the same write permission on the directory containing the data files and all subdirectories. On Windows, you can use an inherited file ACL for this.
Default security: Changing generated passwords and removing them from the vault
On a fresh installation of 10.0 or later product release, a default security configuration is also installed. See The Default Enterprise Server Security Configuration for more information. That configuration includes two user accounts, SYSAD and readonly. Random passwords are generated for these users and written to the default vault of the Micro Focus Vault Facility.

If you are using the SYSAD account, Micro Focus recommends changing the password, which you can do using ESCWA, either when signing in or by editing the user entry in the security configuration. If you do not change the password, delete it from the vault using the following command:

mfsecretsadmin write -overwrite microfocus/temp/admin

The readonly account only grants read access, and is used automatically by some Enterprise Server components such as the Micro Focus Common Client and Host Access for the Cloud to retrieve data from MFDS, if no other credentials are configured for them. For that reason, you might want to leave those credentials in the vault. If you do not need them, however, you can delete them with the following command:

mfsecretsadmin write -overwrite microfocus/common/readonly
Predefined system user accounts
See User Accounts in the Default Enterprise Server Security Configuration and Removing or changing default credentials for more information. Disable or delete predefined accounts you do not need. For those that have passwords such as mf_cs and mf_dep, if you do not disable or remove them, change the passwords.
Parent topic: Security Managers and security configurations


OS ESM Module

For Security Managers using the OS ESM Module, Micro Focus recommends you apply the following hardening configuration settings:

Module
Set this to osesm, with no path. ESF loads ESM Modules from the product installation directory automatically – it does not search the library load path.

Configuration text settings relevant to hardening

The OS ESM Module only provides a handful of Configuration Information field settings. A few are relevant to hardening:

Enable / Default
These names are synonyms; they control the same setting. This setting enables the OS ESM Module to generate and accept passtokens. Unlike the MLDAP ESM Module, the OS ESM Module does not offer per-user control over passtokens, so if feasible do not use the OS ESM Module to provide passtokens.
Note: Only one Security Manager needs to support passtokens, and your organization can disable passtokens entirely if they are not required. Enabling surrogate passtokens by setting this option to any is a significant security vulnerability.
SecretFile
If ESF passtokens are used, for passing authentication between subsystems such as MFDS and ESCWA, or for DCAS, then Micro Focus strongly recommends using this option. The "secret file" may contain anything, as long as it has at least 128 bits of entropy; even 1 KB of ordinary text would suffice. The point of this setting is to avoid using either the built-in secret (which is available to anyone with a copy of the product) or a secret in the configuration (which is available to anyone who can view the configuration) to generate passtokens. Otherwise a technically-skilled attacker could forge passtokens.
Note: There is no space between "Secret" and "File" in the name of this setting.
Trace settings
Tracing is useful in diagnosing issues, but might reveal sensitive data to an attacker who can obtain copies of log files. Disable tracing when it is not needed.
Parent topic: Security Managers and security configurations


PAM ESM Module

The PAM ESM Module provides a Linux feature similar to what the OS ESM Module does for Windows, but since the mechanism it uses is different it also has different configuration requirements. For Security Managers using the OS ESM Module, Micro Focus makes the following hardening recommendations:

Module
Set this to pam_esm, with no path, and no bitness, threadedness, or file extension suffixes. ESF loads ESM Modules from the product installation directory automatically – it does not search the library load path. ESF will select the appropriate bitness and threadedness automatically.
Authorized user
The PAM ESM Module uses this as the service name passed to the Linux-PAM API. The PAM API uses the service name to identify a PAM configuration file (or stanza, if PAM is configured to use a single configuration file). The configuration file determines how PAM operates for the caller, so the information in this file is critical. Micro Focus recommends that you create a PAM configuration file specifically for the PAM ESM Module, preferably using the default name "microfocus-es", to avoid unexpected PAM configuration changes with OS updates and to simplify problem determination. You can copy a suitable existing PAM configuration file to create this configuration.
Note: Configuring PAM is outside the scope of this document.

Configuration text settings relevant to hardening

The PAM ESM Module only has a few configuration options which affect hardening:

Process groups
Enable this option if you want the PAM ESM Module to be able to add the user's PAM groups to the groups known to Enterprise Server. If the organization intends to create resource access rules which refer to those groups, enable this option; otherwise, disable it to reduce the processing performed by and attack surface of the PAM ESM Module.
Enable
This setting enables the PAM ESM Module to generate and accept passtokens. Unlike the MLDAP ESM Module, the PAM ESM Module does not offer per-user control over passtokens, so if feasible do not use the PAM ESM Module to provide passtokens.
Note: Only one Security Manager needs to support passtokens, you can disable passtokens entirely if you do not require them. Enabling surrogate passtokens by setting this option to any is a significant security vulnerability.
SecretFile
If ESF passtokens are used, for passing authentication between subsystems such as MFDS and ESMAC, or for DCAS, then Micro Focus strongly recommends using this option. The "secret file" can contain anything, as long as it has at least 128 bits or so of entropy; even 1 KB or so of ordinary text would suffice. The point of this setting is to avoid using either the built-in secret (which is available to anyone with a copy of the product) or a secret in the configuration (which is available to anyone who can view the configuration) to generate passtokens. Otherwise, a technically-skilled attacker could forge passtokens.
Note: There is no space between "Secret" and "File" in the name of this setting.
Trace settings
Tracing is useful in diagnosing issues, but might reveal sensitive data to an attacker who can obtain copies of log files. Disable tracing when it is not required.
Parent topic: Security Managers and security configurations


Other ESM Modules

Some additional ESM modules are available in the Enterprise Server product or as separate downloads. Here are some brief notes regarding these modules and hardening:

eTrust ESM Module
This module uses the CA eTrust product to make security decisions. For hardening, ensure all the Enterprise Server resource classes are defined in eTrust, then remove any DefaultAllow settings in the Security Manager configuration text.
Map ESM Module
The Map ESM Module is a special-purpose module which only performs name mapping, using a side file. If this module is used, set the permissions for the side file to restrict write access to system administrators.
Null ESM Module
The Null ESM Module normally allows all security requests, but can be configured to return different results for specific requests. Typically it is used for testing. There are no specific hardening recommendations, other than to note that since the Null ESM Module is configured using the Security Manager Configuration Information field, its security is limited by how access to Enterprise Server administration is restricted.
TSS ESM Module
This is a variant of the MLDAP ESM Module used with the CA Top Secret mainframe security product's LDAP server. This module has not been updated in some time, and further deployment of it is not recommended at this time.
Parent topic: Security Managers and security configurations


Additional ESF notes

Auditing

The ESF Auditing feature collects information about ESF events. Current Enterprise Server releases use the syslog protocol for audit events. The older Micro Focus Audit Manager is still supported but deprecated. For the highest level of security, enable auditing and send the audit events to a Security Event and Information Management (SIEM) system such as Micro Focus ArcSight or Sentinel, where it can be automatically analyzed and correlated with other security-relevant data.

Update

The ESF Update feature can be used to notify running processes of changes to security data in External Security Managers. The Update mechanism tells ESF to flush cached information and recompute stored results such as group membership. The ESCWA and MFDS administration user interface provide an Update All button to make basic update notifications, but Micro Focus recommends the use of the esfupdate command-line utility to submit update requests, as it provides more control of the request contents and destination.

Parent topic: Using and hardening ESF


Hardening ESF: Summary

When hardening an Enterprise Server installation, review the following steps. Consult the topics in this document and related ones in your product Help for more information:

Options which reduce security
Disable options which reduce security, such as Allow unknown users and Allow unknown resources.
Predictable behavior
It is best when security systems behave in a consistent and predictable way that is easy to understand. Where possible, avoid configurations which might produce unexpected results. If you use multiple Security Managers, enable group federation. Avoid options which introduce additional complexity such as check TLQ first; if you need to use them, avoid further configuration which might behave differently when those options are enabled. For example, with check TLQ first, the best practice is to not have any DATASET resource access rules which begin with a wildcard.
Strong passwords
If user authentication is being performed with the MLDAP ESM Module and Micro Focus password hashes, use the password-strength configuration options such as minimum length and complexity to require strong passwords. Consider whether password expiration and history (to prevent password reuse) are appropriate for you. Use the MF-A2 (Argon2) password hash type, and if your organization has older password hashes, enable password migration.

If Micro Focus password hashes are not used, password strength is determined by OS or third-party components which are outside the scope of this document.

Verify throttling
Enable the verify-throttling feature in the security configuration. Set its threshold to a value that your organization can tolerate. Generally the task latency in each SEP is high enough that at most a dozen or so signons might occur within the one-second window used by verify throttling.
Auditing
Consider enabling auditing in order to maintain an audit trail of security-related activity. This can be used for forensic analysis after a breach is suspected, and as a source of information for breach-detection systems.
Caching
Determine which is more important to the organization: performance and reliability, or immediate recognition of security changes. For the former, enable caching; for the latter, disable it, in both the security configuration and any Security Managers which use the MLDAP ESM Module.
Passtokens
ESF passtokens are a relatively strong mechanism, but disabling them offers security benefits. Passtokens are used for seamless transition between the MFDS and ESMAC user interfaces; use ESCWA instead to avoid this use case. They are also used for DCAS, but relatively few organizations use that feature.

If passtokens are used, use the SecretFile configuration option to set a site-specific or machine-specific secret for passtoken generation.

Secure LDAP
Use LDAP-over-TLS if possible.
Default credentials
As with all default credentials, the best security practice is to not use the default credentials for connecting to an LDAP server.
Account lockout
If Micro Focus users are used with the MLDAP ESM Module, enable the signon attempts setting for account lockout, to prevent guessing passwords.
Tracing
Avoid leaving tracing enabled, particularly in production systems, as it might provide attackers with useful information.
Parent topic: Using and hardening ESF


Using and hardening TLS

Secure communications are a cornerstone of system security. It is now widely acknowledged that even corporate private networks should not be trusted with sensitive data, which includes interactions among the components of distributed applications. TLS, when used correctly, provides confidentiality (attackers cannot read sensitive data), integrity (attackers cannot change data), and authentication (attackers cannot impersonate parts of the system) for network communications.

TLS can be enabled for many Enterprise Server components, including:

  • The listeners associated with an enterprise server instance. This includes the "control listener" associated with the Communications Process.
  • The ESCWA and MFDS administrative user interfaces and APIs. The ESMAC UI and API are secured by enabling TLS for all listeners of type Web Services and J2EE or SOAP and J2EE (legacy) in the enterprise server instance.
  • CICS Web Interface clients and servers.
  • Various utility programs which can connect to Enterprise Server over the network, such as the cassub utility.
  • COBOL Web Service proxy programs created by the Interface Mapping Toolkit (IMTK).
  • Fileshare.

The MLDAP ESM Module can also usually use TLS with its LDAP connection, though that is actually under the control of third-party software (the LDAP server and the LDAP provider library). Similarly, XA resources accessed over the network often support TLS connections.

Enabling TLS for these various components is covered by your product Help.
Note: TLS is very complex; Micro Focus strongly recommends that you have some technical knowledge of TLS and related technologies.

Here are some recommendations for hardening TLS:

Setting listener default TLS parameters

TLS options and parameters can be configured for each listener, but you can also set defaults for them in the mf-server.dat file. See To configure TLS default properties for listeners in your product Help for more information.

TLS protocol versions

The TLS (formerly SSL) protocol has gone through a number of protocol revisions.

The older SSLv2 and SSLv3 protocols are insecure and are not supported by Enterprise Server.

Currently TLS protocol versions are TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3. By default, Enterprise Server components support all four TLS versions, for interoperability and backward compatibility. TLSv1.0 and TLSv1.1 are insecure and deprecated, and are disabled by default beginning with release 8.0.

Unless there is a pressing need to interoperate with peers which only support old versions of TLS, Micro Focus recommend disabling TLSv1.0 and TLSv1.1 where possible. For listeners and other components which provide a TLS protocol configuration field this can be performed by setting the protocol list to -ALL+TLS1.2+TLS1.3. See Configuring a TLS Protocols List in your product Help for more information.

Cipher suites and parameters

As with the TLS protocols, the default set of cipher suites permitted by Enterprise Server is intended for interoperability, not hardening. For TLSv1.2, if it is not necessary to support older peer systems, Micro Focus recommends either of the following options:
  • Set the cipher suite list to ALL:@SECLEVEL=3. This will enable only the suites which meet "security level 3", which requires strong algorithms and Perfect Forward Secrecy.
  • Set the cipher suite list to -ALL:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:DHE-DSS-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256. This is a collection of best-in-class cipher suites for TLSv1.2. Add other suites if required for interoperability.

The DH minimum group size option determines how large ephemeral Diffie-Hellman keys must be. The default for this is 2048 bits, which should provide adequate security. This can be changed to 4096, but most clients will permit the use of Elliptic Curve Diffie-Hellman (ECDH), so this setting rarely applies.

There is no need to change the TLSv1.3 cipher suite list or the list of permitted elliptic curves for hardening purposes.

Honor server cipher list

This option should be enabled. It lets the server determine the preference order of cipher suites. This is important because servers are more strictly administered, and because an attacker in a privileged position might be able to tamper with the cipher-suite list offered by the client and downgrade the conversation to the weakest suite the server offers. This option will likely be enabled by default in a future product release.

  • Certificates and private keys
    Hardening advice for the certificates and private keys used with TLS.
  • Additional TLS notes
    Additional notes about hardening TLS.
  • Hardening TLS: Summary
    A summary list of major recommendations for hardening TLS (also known as SSL) configurations for Enterprise Server.
Parent topic: Securing Enterprise Server


Certificates and private keys

X.509 certificates and their corresponding private keys are central to TLS. If you are involved in Enterprise Server administration, it is important that you understand at least the basics of certificates and private keys.

There are official standards for certificates and keys. The major ones are described here. Many of these (the RFCs and the CA/BF Baseline Requirements) are freely available online. ITU standards such as X.509 typically must be purchased from a standards organization, but summaries and discussions can generally be found online to answer most questions.

X.509
This is the ITU standard for the digital certificates used with TLS. The current version is 3, and all modern systems should use X.509v3 certificates, which provide a number of important features for security and interoperability. X.509 draws on a number of other standards, such as X.400 (which defines the distinguished name syntax used for subject and issuer names in certificates); X.500 (online directories, the precursor of LDAP); and ASN.1 (data representation and encoding). Regarding the last, you might see references to certificates in DER encoding; this stands for Distinguished Encoding Representation, a serialization format for ASN.1. Sometimes you might see a file described as being in "DER format". This typically means the file is the raw binary DER, as opposed to the Base64-encoded DER found in PEM-formatted certificate files.
PEM
The Privacy-Enhanced Mail standards were an early specification for encrypted email. While PEM as an email system was eclipsed by PGP and S/MIME, the PEM file and data formats (including Base64 encoding) are often used with certificates and private keys. PEM is defined in various RFCs, and the PEM file format in particular was most recently updated by RFC 7468.
PKCS
The Public Key Cryptography Standards, PKCS#1 through PKCS#15, were published by RSA Security. For users and administrators working with TLS, the PKCS standards most commonly encountered are PKCS#7, sometimes used as a certificate file format (typically with a .p7 or .p7b extension); PKCS#8, a format for private-key files (.p8 or .p8b); PKCS#10, used for Certificate Signing Requests to a CA, among other things; and PKCS#12, a file format for holding multiple pieces of information. PKCS#12 is the standardized version of Microsoft's PFX format, and most .pfx files are actually PKCS#12. (The .p12 extension is also used.) PKCS#12 files can hold multiple certificates and keys, and can be partly or entirely encrypted, so they are often used to carry both a certificate (or certificate chain) and its associated private key.
PKIX
The Public Key Infrastructure (X.509) specification, RFC 5280 (as updated by its errata and some succeeding RFCs), is the Internet standard for using X.509 certificates with TCP/IP protocols, including TLS. PKIX imposes a number of requirements on the contents and use of certificates. Some of these are noted below.
CA/BF Baseline Requirements
The CA / Browser Forum is an industry group of representatives from commercial CAs and browser makers who meet to discuss and specify additional requirements for the use of TLS on the public Internet. The Baseline Requirements (at version 1.7.3 as of this writing) documents their standard. In principle, the Baseline Requirements do not apply to organizational CAs and TLS used within an organization, or between private parties; but since browsers typically enforce the requirements, even in private use some of them might need to be observed at least for HTTPS. Below we note some of the consequences of the Baseline Requirements for certificates.

Certificate Authorities

Do not use the DemoCA certificate authority shipped with Enterprise Server in production. DemoCA is not supported for production use. Use an organizational or commercial CA.

For organizational CAs, Microsoft Windows Server includes a CA role which can be used to create suitable certificates and to distribute the required root and intermediate certificates to Windows client systems using Group Policy. This is a straightforward choice for organizations using Windows extensively, though configuring it to create suitable certificates takes some research. For Linux and UNIX, there are various open-source CA packages available.

Certificate validation types

When certificates are issued by a CA, the identity of the party requesting the certificate can be validated in one of three ways:

Organization Validation (OV)
An OV certificate is issued either within an organization, so (in theory) the request is authenticated using organizational channels; or it is issued by a commercial CA based on an official statement from the requesting organization that offers some proof of identity and authorization.
Domain Validation (DV)
A DV certificate is generated, usually through an automated process, for a specific fully-qualified domain name, and the request is validated by checking for certain DNS entries in the domain. The theory of DV certificates is that if someone controls DNS for a domain, they effectively own that domain and so it is appropriate to grant them DV certificates for systems in it. This is the approach used by Let's Encrypt.
Extended Validation (EV)
An EV certificate implies additional steps were taken to validate the certificate request. Typically these include additional paperwork and confirmation by staff at the issuing CA. EV certificates are also substantially more expensive, and are controversial in the industry, with some commentators suggesting they add little additional security. Browsers used to indicate to users when a site offered an EV certificate, but Chrome at least has stopped doing so.

The type of certificate validation does not matter to any Enterprise Server component. There is probably no significant benefit to using EV certificates with Enterprise Server.

Certificate properties

If an organization is generating its own certificates, it is important to ensure they follow best practices for their contents and options. Even with an external CA, the Certificate Signing Request (CSR) or other material provided to the CA should be sure to specify the appropriate parameters. Micro Focus recommends:

Names
Server certificates, and other certificates which identify computers by their network names — such as hostnames, fully-qualified domain names (FQDNs), and IP addresses — should list those names in Subject Alternative Name (SAN) extensions. Certificates which identify other entities such as people and applications should use a Subject Distinguished Name (Subject DN) with appropriate components.

At one time certificates for computers put the hostname or FQDN in the Common Name (CN) component of the Subject DN, but PKIX and CA/BF Baseline Requirements now require the use of SANs, and conforming implementations are not permitted to use the CN when validating a certificate they receive from a peer. The use of CN in a Subject or Issuer name is deprecated by CA/BF.

When generating a certificate or CSR for a server, specify a SAN for each name you might use to contact the server. Often that means a SAN for both the FQDN and bare-hostname forms of the server's canonical name, and if the server has aliases that clients might use, SANs for those (in both FQDN and bare-hostname forms) as well. If the system has a fixed IP address and clients can contact it using that address directly rather than resolving a hostname, you might want to have a SAN for the address as well.

For example, assume an enterprise server instance running on a system named corpserv, in the domain corpdom.com. For convenience, the organization has given this system the alias esserv. It has been permanently assigned the IPv4 address 10.2.5.18 and the IPv6 address fd0f:14d7:e62c:1234::0005:0012. For such a server we might want to request a certificate with the following Subject Alternative Names:
  • DNS:corpserv
  • DNS:corpserv.corpdom.com
  • DNS:esserv
  • DNS:esserv.corpdom.com
  • IP:10.2.5.18
  • IP:fd0f:14d7:e62c:1234::0005:0012
The idea is to create a certificate which adequately and uniquely identifies this computer, but accommodates all the names that a client might reasonably use in trying to connect to it using TLS.
Note: Some clients, such as the Chrome browser, now require a SAN when validating a server certificate.
Wildcards
Micro Focus recommends against the use of wildcard certificates for use with Enterprise Server, because of the risks associated with losing control of the private key for such a certificate.
Algorithms and key sizes
Each certificate has a signing algorithm and a public key. The signing algorithm must be a modern, strong algorithm; for example, signing algorithms using the MD5 hash are no longer allowed by many implementations. Keys should be adequately strong. The CA/BF requirements currently specify a minimum of 2048 bits for an RSA key, for example.
Validity dates
Every certificate contains two validity date-and-time fields: a not-valid-before and a not-valid-after. Currently the CA/BF requirements limit the total validity period for entity (server, client, user, and so forth) certificates to 398 days. Some browsers and other peers might enforce this. Currently, Chrome ignores this requirement for certificates which are issued by organizational CAs, but best practice is probably to issue certificates good for slightly more than one year, and schedule renewing them annually.
Serial number
Every certificate issued by a CA should have a unique serial number. CA/BF requires the serial number be positive and have at least 64 bits, which is why serial numbers for certificates issued by commercial CAs are very long (for example, 09:4a:51:9b:32:a5:b4:00:38:14:c5:ef:29:bf:8d:48 for the current certificate for www.microfocus.com). Sufficiently recent CA software should be able to generate serial numbers of this form. Some browsers and other peers may insist on serial numbers that meet this requirement.
Basic constraints
All entity certificates (server certificates, and other certificates which are not CA root or intermediate certificates) should have the Basic Constraints extension with the CA flag set to false. This is optional under the standards but good practice.
Key usage and extended key usage
Best practice is to issue each certificate for as narrow a use case as is feasible, and to set these appropriately for that use case. For example, a server certificate should have its Key Usage set to Digital Signature and Key Encipherment, and its Extended Key Usage to TLS Web Server Authentication.

Under the CA/BF rules, key usage is optional and extended key usage is required.

CRL distribution points and authority information access
These extensions deal with certificate revocation information. Certificate revocation is a fraught practice with numerous problems, and neither of the available mechanisms (Certificate Revocation Lists or CRLs, and the Online Certificate Status Protocol or OCSP) work very well, so many organizational CAs do not implement or make use of revocation, and many applications skip revocation checks. Currently no Enterprise Server components make revocation checks.

However, revocation still has a role in the industry, and the CA/BF have certain requirements regarding it.

CA/BF baseline requirements make the CRL Distribution Points extension optional, so it can be omitted.

CA/BF baseline requirements make the Authority Information Access extension mandatory, and require that it include an OCSP responder URL. They also note that the AIA extension should include a URL for retrieving the root certificate of the certificate chain. Currently it seems all browsers will ignore violations of this requirement, at least for organizational CAs, but that could change.

Authority key identifier (AKID) and subject key identifier (SKID)
The AKID and SKID extensions uniquely identify the public key of the certificate (SKID) and the certificate that signed it (AKID). They make it easier for an application which is validating a certificate to construct the certificate chain back to a trust anchor (typically a root certificate). CA/BF requires the AKID extension; best practice is to provide both.
Certificate policies extension
CA/BF requires the Certificate Policies extension. Micro Focus is unaware of any browsers or other clients which currently enforce this requirement.

Key hygiene

Key hygiene refers to good practices with private keys. Private keys are highly sensitive data, even when they are only used for testing purposes.

Consider the following scenario:

  • An organization creates a key pair for a test system, and a certificate for the system, so they can test with TLS.
  • For convenience, they use their organizational CA to issue the certificate. This way browsers within the organization (which have the appropriate trust anchors) will trust this certificate.
  • An attacker penetrates the internal network, obtains the certificate (from the server), and obtains the private key (because it was not adequately protected).
  • The attacker sets up a hostile server, and uses DNS cache poisoning or another technique to redirect traffic to the hostile server.
  • Now the attacker can use social engineering or other techniques to trick employees into connecting to the hostile server and submitting sensitive data such as credentials. Because the certificate is signed by the organizational CA, the browsers will not show any warnings.

Currently, Enterprise Server only supports storing private keys in key files, so protecting the private key is a matter of protecting the contents of those files and the files themselves.

Micro Focus recommends using an encrypted key file. Most key file formats, including PEM, PKCS#8, and PKCS#12 support encrypting the key data. Encrypting the file means the attacker must guess (including by brute force) the passphrase needed to unlock the key, or get the passphrase from another source. That increases the attacker's work factor.

Set permissions on the key file restrictively. Ideally, as discussed in the topic on filesystem permissions, Enterprise Server should run under a dedicated user account, and only that account should have read access to the private-key file. This is particularly important if the key is not encrypted, but a good practice in any case.

Restrict access to the private key to only those employees who have a business requirement for it. Do not share it with Micro Focus. Micro Focus Support, Professional Services, or Pre-Sales might ask for copies of your certificates; providing those is safe. Do not include the private keys. Micro Focus might occasionally ask for information about the private key, such as the modulus of an RSA key, in order to confirm that a private key matches the public key in a certificate; providing that is safe. Micro Focus will not ask for the private key itself.

Private keys corresponding to CA root and intermediate certificates are particularly sensitive. Industry best practice is to never store the private key for a CA root on non-removable media; keep it only on removable media or in a Hardware Security Module (HSM) and attach it only in order to generate new root or intermediate certificates.

Managing keys and supplying passphrases

If a private key is compromised, all certificates which use that key pair must immediately be revoked. A new key pair should be generated and the certificates re-issued and replaced.

A given key pair can be used for more than one certificate. Each customer will have to determine whether they prefer to manage a larger set of keys, or risk having to revoke and re-issue more certificates if a key is compromised.

In the previous section, Micro Focus recommended encrypting keys in key files. The disadvantage of encrypting the key is that the passphrase to unlock the key must be supplied when the key is first used by a process. For Enterprise Server that typically means supplying it at region startup. MFDS, ESCWA, and other cases are discussed below.

Note: Currently Enterprise Server also requests a certificate passphrase. In practice certificates are almost never encrypted, and so this passphrase is usually empty, but it needs to be supplied. Certificate passphrases can be provided in the same manner as key passphrases. See your product Help for more information.

There are various ways of providing the key passphrase:

  • Enter it manually after the enterprise server region has started. When a TLS-enabled listener is asked to start but the keyfile passphrase is not supplied in any other manner, the listener is put into a "start pending" state. Then a web form, linked to by ESCWA and MFDS, can be used to enter the passphrases and complete startup. This avoids having the passphrase stored for an attacker to find, but means that server startup requires this manual step.
  • Put it in the mf-server.dat file. In this case it is important to set restrictive file permissions on mf-server.dat. Beginning with release 8.0, the mf-server.dat file can also be used to specify passphrases contained in the Enterprise Server Vault facility.
    Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This can be specified in the mf-server.dat file and takes the following form:
    mfsecret:configuration-name:secret-path

    or:

    mfsecret::secret-path

    or:

    mfsecret:secret-path
  • Use the ESCERTPAS user exit to supply the passphrase. ESCERTPAS is documented for supplying passphrases for the CICS Web Interface feature, but it can also be used for regular Enterprise Server listeners. An advantage of ESCERTPAS is that the exit can, in principle, do anything to get the passphrase. The sample exit program just hard-codes passphrases, but an implementation could retrieve them using some more-secure mechanism.

In future releases, Enterprise Server will likely support other passphrase and key storage options, such as the increased use of the Enterprise Server Vault facility, the Windows certificate and key store, and HSMs using the OpenSSL PKCS#11 interface.

For MFDS and ESCWA, the key passphrase is specified in the configuration or kept in the Vault Facility.

For clients using MFCC, key passphrases can be supplied programmatically, but few clients support this option. Instead, keys can be specified in mf-client.dat files, either directly or using the Vault.

Clients and servers that use CCI directly, such as Fileshare and the Mainframe Access client, can supply passphrases as part of the CCI machinename string.

See your product Help for more information.

Parent topic: Using and hardening TLS


Additional TLS notes

Symmetric (client) authentication

TLS includes the capability for the server to authenticate the client using a certificate. This is known as symmetric authentication or client authentication. Symmetric authentication is rarely used with public HTTPS websites, due to the complexities of issuing personal certificates to users, but is more common with various TLS applications within organizations.

While server certificates are expected to identify the server host machine, generally by its domain name, PKIX does not specify what a client certificate will identify. The possibilities include:

  • The client machine, just as a server certificate identifies a server machine.
  • The client application. That is, the certificate might be issued to the application itself, or a particular installation of the application. This is often seen with smartphone apps (though often with poor key-hygiene practices, such as private keys hard-coded in the app, due to the difficulties of provisioning and managing private keys for each app installation).
  • The user running the application. This is sometimes known as a "personal certificate".
  • Something else. Some systems maintain a mapping between arbitrary certificates and system identities. For example, the Enterprise Server CICS Web Interface and DCAS features can be configured to map arbitrary certificates to individual users.

If you want to use symmetric authentication with features such as CICS Web Interface, DCAS, or ELF (TN3270 Express Login Facility, which uses DCAS and TN3270 macros to sign users in automatically) you might want to consider expanding the use of symmetric authentication. For example, if you are issuing client certificates to users anyway, they could set other TLS-enabled listeners to require client certificates, making it more difficult for attackers to connect to those listeners.

Certificate chains

When you configure a certificate for a server or client, you can, and often should, specify not just the entity certificate (which identifies the server or client) but an entire certificate chain. A chain includes the entity certificate, the certificate which was used to sign it, the certificate which was used to sign that certificate, and so on.

Best practice for a CA is to sign entity certificates not with a root certificate but with an intermediate. CAs can have multiple intermediates, and multiple levels of intermediate (one intermediate signed by the root, then another intermediate signed by the first, which is then used to sign entity certificates). There are a number of reasons for this, mostly related to CA security and reducing the impact of a CA compromise.

Because clients might not always have all the intermediates available – they might only have the root as a trust anchor – applicable standards require the server send a chain including at least the entity certificate and any intermediates needed to reach the root.

Sending the root itself is optional. PKIX and the CA/BF Baseline Requirements do not address the question, except for PKIX noting that trust anchors (including roots) should be delivered using a trusted out-of-band mechanism. But this does not mean the server should not send the root regardless. RFC 6066 (TLS Extensions) and RFC 8446 (TLSv1.3) both say that the chain can omit the root. Clients must not automatically trust an unrecognized root, but could prompt the user; and having the root in the server's chain can be useful for problem determination. Including the root does increase the size of the TLS handshake – certificates can be a few kilobytes in size on the wire – so there is a small performance penalty.

With Enterprise Server, a listener can send a chain rather than a single certificate by including all the necessary certificates in a single file, and then configuring that as the certificate file. The PEM and PKCS#12 (or PFX) file formats can hold multiple certificates. For PEM, simply concatenate the certificate files into one file. For PKCS#12, a tool such as the OpenSSL utility can be used to construct a file containing multiple certificates.

Parent topic: Using and hardening TLS


Hardening TLS: Summary

When hardening an Enterprise Server installation, review the following steps. Consult the topics in this document and related ones in your product Help for more information:

Disable old TLS protocols
Disable TLSv1.0 and TLSv1.1.
Enable only strong cipher suites
Configure a list of strong cipher suites or set the security level to a high value. Use the Honor Server Cipher List option.
Use a proper CA
Do not use DemoCA in production; use a commercial or organizational CA.
Generate quality certificates
Create certificates which conform to industry best practices. For server certificates, include all the appropriate Subject Alternative Names. Use strong signing algorithms (avoid MD5 and SHA1) and sufficiently-large keys (for example, at least 2048 bits for RSA keys).
Protect private keys
Use key-file formats that encrypt the private key, and set restrictive file permissions. Do not share private keys with entities that do not need them. Determine what method of supplying the keyfile passphrase is most appropriate for your organization.
Note: You can use the Micro Focus Vault Facility to store a secret for the certificate and keyfile pass phrases. This can be specified in the mf-server.dat file and takes the following form:
mfsecret:configuration-name:secret-path

or:

mfsecret::secret-path

or:

mfsecret:secret-path
Parent topic: Using and hardening TLS


Using and hardening the supplied configuration

When it is initially installed, Enterprise Server comes with a configuration which contains various default settings and objects, and samples to demonstrate aspects of the product. This is known as the default, Installation Verification Procedure (IVP), or out-of-the-box configuration.

Because this configuration is not customized for an organization's needs and is designed to assist users in exploring the product's features, it is not very secure. This chapter discusses what changes can be made to the sample configuration to improve its security.

Some of these aspects are also covered in other chapters of this document. Micro Focus recommends following the instructions in the Removing or changing default credentials topic.

Organizations which already have an enterprise server instance configuration which is suitable for their applications may dispense with this chapter and simply use their existing configuration. Micro Focus recommends reviewing any existing configuration to remove facilities that are not required, such as listeners and CICS resources which are not needed by the applications running under Enterprise Server.

  • Removing unnecessary configuration objects
    Remove unnecessary information from the supplied configuration.
  • Hardening access-control rules
    The access-control rules defined by the supplied configuration can be customized for greater security.
Parent topic: Securing Enterprise Server


Removing unnecessary configuration objects

It is likely you will not use all of the features of Enterprise Server, and so you will not require many of the objects defined by the supplied configuration. These can be removed for greater security. Removing unnecessary configuration reduces the attack surface and decreases the amount of information available to attackers who can install the product and review the supplied configuration.

Servers, listeners, services, and handlers

You can use ESCWA to review these configuration objects and remove or disable them. Micro Focus recommends making a backup of the MFDS repository first using the export function.

Items to review include:

  • The ESDEMO sample server, and any servers created using the tutorials and demos included in the product, such as ESACCT (from the CICS tutorial) and ESSOAP (from the IMTK tutorial).
  • The Web listener in each server. The listener is used for the automated deployment of COBOL Web Services and EJBs, through the IDEs or the imtkmake utility. The Web listener and service deployment are potential security vulnerabilities. While recent Enterprise Server releases reduce the risk in the supplied configuration, Micro Focus recommends removing or disabling the listener on production systems (and using a scalable, reproducible, service-deployment process if necessary), and securing it on development systems. See Restricting remote program execution for more information.
  • Any other listeners which might not be needed by the enterprise server region. For example, non-MSS, and MSS enterprise server regions which are not used interactively, do not require a TN3270 listener. Some topics in the product Help suggest using a listener with the custom configuration type http-echo for testing; those listeners should be deleted or disabled when testing is complete.
  • The services in each server:
    • If automated service deployment is disabled (as recommended above), the Deployment service can be deleted or disabled.
    • Non-MSS enterprise server regions do not need the CICS and JES services.
    • Any services (and their associated packages) created from the tutorials and demos.
  • The handlers in each server:
    • MFRHSOAP and MFRHJSON can be disabled if the server is not being used for non-MSS COBOL Web Services. If it is only handling one type of service, SOAP or JSON, the other handler can be disabled.
    • MFRHJCL can be disabled for non-MSS, or MSS enterprise server regions which are not doing any JES processing.

    Do not disable the MFRHBINP handler, as this is used for various internal Enterprise Server functions.

CICS resource definitions

The CICS RDO file supplied with Enterprise Server contains numerous resource groups for optional features and demos. Micro Focus recommends you make a backup of this file (dfhdrdat) and remove any groups that are not required. Removing groups from your enterprise server region's startup list is only a partial mitigation because attackers might be able to install resources dynamically in a running enterprise server region.

Groups you should consider for removal include:

  • DFH$ACCT contains the CICS ACCT sample application.
  • DFH$APCT is a PL/I version of the ACCT sample.
  • DFH$IMQS contains a sample IBM MQ application.
  • DFH$IVP contains the resources for the Installation Verification Procedure (IVP), which is optional and no longer needed once you have confirmed Enterprise Server and CICS are working.
  • DFHCDDE, DFHCIPX, DFHNAMP, and DHFCNETB are vestigial support for old communications protocols which are no longer supported, and can be safely removed from all installations.
  • DFHCIVP contains definitions for testing CICS Distributed Program Link functionality.
  • DFHCTCP contains definitions for testing CICS inter-region communication (CTG / Universal Client) functionality.
  • DFHCWI contains a sample CICS Web Interface (CWI) application.
  • DFHELCG contains resources used with the Component Generator functionality.
  • DFHEZA contains resources required for the EZ Sockets functionality, and can be removed if you do not use this product feature.
  • DFHISC contains resources required for CICS Inter-System Communication, and can be removed if you do not use this feature.
  • DFHMQS contains resources required for IBM MQ connectivity, and can be removed if you do not use this feature.
  • IMSGRP contains sample resources for CICS-IMS interaction.
  • MCOASM contains a sample program using the Assembler support functionality.
  • MCOGROUP contains the CMAP transaction, a utility transaction to display CICS BMS maps, which is generally only useful to developers.

LDAP and VSAM security definitions

If you are using LDAP-based or file-based security through the External Security Facility (ESF) and the MLDAP ESM Module (mldap_esm) or VSAM ESM Module (vsam_esm), and you have imported (or plan to import) the sample security definitions from one of the LDIF or YAML files supplied with the product, such as es_default_ldap.ldf, then you will likely have many security definitions which are irrelevant or too permissive for your requirements. Micro Focus recommends you back up your security rules and remove or edit rules as appropriate, for example, by exporting them to an LDIF or YAML file.

If your security configuration has the Allow unknown resources option enabled, then be cautious about removing rules, as this may in effect grant additional permissions. In this case, instead of removing rules, change their Access Control Lists (ACL) to deny access to all users.

Note: The Allow unknown resources is not the default and Micro Focus strongly recommends against using it in a production environment.

Security definitions to consider for removal include:

  • As discussed in the Removing or changing default credentials topic, Micro Focus recommends removing definitions for the supplied user accounts, or at least changing their passwords. Supplied user accounts include CICSUSER, JESUSER, IMSUSER, mfuser, SYSAD, PLTPISUR, and SAFU. In particular, the default administrator account SYSAD and the test account SAFU should be removed or disabled, or have their passwords changed.
  • Any supplied user groups you are not using can be removed. For example, DEVGROUP and INTERCOM. You might want to replace the predefined SYSADM, OPERATOR, and ALLUSER groups with others that you specify for similar purposes.
  • The sample security definitions include rules for a number of sample applications and other resources which might have been removed, as discussed above. Removing the security rules for them is also recommended. These include, for example, the rules in the TCICSTRN class container for ACCT and other transactions beginning with "AC", and the rule in the FCICSFCT container for ACCTFIL. One way to identify these rules is to open the es_default_ldap.ldf file in a text editor and search for "sample" and "demo".
  • Some CICS system transactions might not be used by some installations, and the rules for them in the TCICSTRN class container can be removed or edited to prevent execution of those transactions. For example, there are rules for the IMS, CMAP, and CENV transactions, all of which might not be needed by your organization.
  • Certain system transactions are particularly risky from a security perspective and should be restricted to system administrators. These include the CENV, CPMT, CQIT, CRUN, and EZAC transactions. In addition, when practical restrict permissions to system transactions such as CFCR, CFLE, and CINS.
  • There are a number of rules for JES and IMS which can be removed if you are not using those features. For JES, these include the rules in classes beginning with "JES", such as JESJOBS and JESSPOOL. Micro Focus recommends keeping the rules in the SURROGAT and PHYSFILE classes. For IMS, these include the rules in the classes with names that end in "IMS" such as CIMS and TIMS.
Parent topic: Using and hardening the supplied configuration


Hardening access-control rules

Assuming you are using LDAP-based security with Enterprise Server through the External Security Facility (ESF) and the MLDAP ESM Module, or file-based security through the VSAM ESM Module, access to various resources — programs, data files, CICS queues, and so forth — from application programs running in Enterprise Server is controlled by resource rules stored in the LDAP repository. Similar rules restrict access to administration functions under ESCWA, system services invoked by command-line utilities such as casout, and so forth.

A set of sample rules is provided with Enterprise Server in the form of LDAP Data Interchange Format (LDIF) files such as es_default_ldap.ldf, and in YAML format as es_default_security.yaml, for use with the VSAM ESM Module. For LDAP, there are a number of LDIF files to accommodate variations in repository structure, LDAP object types, and syntax among LDAP servers and configurations. You can import these rules into your LDAP repositories or use them as a basis for creating your own security configuration. For file-based security, you can customize es_default_security.yaml to suit your needs.

Many of the rules are unnecessary, inappropriate, or too permissive for most production enterprise server instances. As discussed in Removing unnecessary configuration objects, Micro Focus recommends removing rules for sample applications and some unused features.

For the rules that remain, you should review and consider tightening the permissions. In some cases that might involve adding additional permissions to the rules for some resources so that a group of users can be granted access only to those resources, rather than membership in a generally privileged group such as SYSADM. For example, an organization might create a group with permission to use some CICS system transactions such as CINS, but not others such as CFLE; that could be achieved by adding an Access Control Entry (ACE) to the rule for CINS.

About access-control rules

With the MLDAP ESM Module and VSAM ESM Module, access to Enterprise Server resources is controlled by Access Control Lists (ACL) in determining rules. Rules are grouped into classes which correspond to particular types of resources: data files, programs, CICS transactions, administration commands, and so forth. Each rule has a name, which can contain wildcard characters.

When Enterprise Server needs to authorize a user for a particular operation (read, update, and so forth) on a particular resource, it queries ESF, passing the resource class and name, the user information, and the requested level of access. In ESF, the ESM Module will find all rules in the given class with names which match the resource name; because rule names can contain wildcards, there might be multiple matches. The module examines each of these rules from the closest match to the most general one, until it finds a rule with an ACL that applies to the user, explicitly or through group membership. That rule becomes the determining rule which grants or denies the action.

ACLs contain one or more Access Control Entries, or ACEs, each of which allows or denies a permission level or set of permissions to an actor, which is the name of a user or group, possibly specified with wildcards, so an ACE can apply to multiple users or groups. The interactions between user and group ACEs, and allow and deny ACEs, and the case where multiple ACEs apply to a given request, can be complex and are discussed at more length in the product documentation. Broadly speaking, more-specific ACEs override less-specific ones; user ACEs override group ACEs; and deny ACEs override allow ACEs. In most cases, the result of the ACE and ACL processing algorithm is what an administrator would expect, following the "principle of least surprise".

Access-control rules can be hardened by ensuring their ACLs do not grant excessive permission to any users. Sometimes this might involve changing the permissions granted by a part of the ACL; in other cases, it might be achieved by adding ACEs or changing them to refer to different actors (usually groups) created to give only certain users a type of access.

Group structure

For most organizations, few or no ACEs refer to individual users. Assigning permissions at the granularity of users does not scale and makes it difficult to reassign responsibilities. Aside from generic rules which refer to all users with a wildcard (for example, allow:*:none), most ACEs will refer to groups.

There are many ways to organize users into groups for the purpose of resource access control. Groups might represent user roles; projects, departments, or functional areas; or simply sets of resource-access assignments. Micro Focus does not recommend any particular interpretation of user groups. Keep in mind that a clear, well-documented group structure will make it easier to assign and audit permissions.

The MLDAP ESM Module has a number of options for group structure, including nested groups and features for using different types of group objects. The VSAM ESM Module also supports nested groups. See your product Help for more information.

Principle of least privilege

In security, the principle of least privilege states that actors, such as users, groups, and applications, should be given the minimum set of privileges they require. While this can be difficult to achieve completely, here are some guidelines to help administrators move toward this goal:

Use generic rules to deny access by default
A rule with the name ** and the ACL deny:*:all in a resource class will match all requests if there is not a more-specific rule, and deny access. This avoids any issues if an attacker is able to specify a resource name not covered by your specific rules.
Note: These rules will prevent the Allow unknown resources security option from taking effect, since no resources will be unknown. As a minimum, they will all be covered by the generic rule.
Organize resources in ways that make it easy to use wildcard rules
If your cataloged datasets follow a well-documented hierarchy of qualifiers, it is easier to create an accurate set of rules and validate them against your policies. For example, if everything below the top-level qualifier SYS. should only be writable by members of the SYSADM group, you can create a rule in the DATASET class named SYS.** with the ACL allow:SYSADM group:alter; deny:*:update and know that except where overridden by more-specific rules, that will implement the desired policy. In general, following naming conventions that are parallel to security policies where possible will reduce the number of rules that need to be created, maintained, and vetted.
Err on the side of restriction
It is better to make rules too restrictive and subsequently have to relax them, than to make them too permissive initially. Trying to remove permissions after users have adopted habits or applications have been deployed can cause many problems, and often excessive permissions never get revoked.
Strive for rules which are simple and clear
Another important concept in security is the principle of least surprise, this states that a system which is difficult to perceive, understand, and reason about is more likely to contain vulnerabilities. It is important that you are able to read the security rules and understand their intent. Try to avoid special-case rules and conflicting rules which require understanding how Security Managers prioritize and resolve conflicts.

As a rule of thumb, restrict access to resources and then grant it according to specific requirements. In addition to making the security configuration more secure, it will lead to documenting access requirements and their justifications.

General recommendations

Micro Focus recommends the following for hardening access-control rules:

  • Remove permissions for unused features, or restrict them to privileged users such as system administrators.
    Note: The sample rules provided with Enterprise Server include many sample and demonstration resources which should be removed, particularly from production environments.
  • Ensure features for tracing, debugging, querying system information, and so on, are restricted to users with a legitimate need for it. Depending on the resource, system type (for example, production or development), and other factors, that might mean only system administrators, or also operators or developers.
  • Make rule names and ACLs as general as possible to achieve a given security requirement.
  • Apply ACEs to groups, not individual users. Create groups that represent something meaningful for your organization.
  • Consider using advanced features if they address a security requirement. For example, the username-substitution feature of the MLDAP ESM Module lets you easily give each user access to their own dataset "namespace". When this feature is enabled, you can create two rules in the DATASET class like this:
    USERS.**
    deny:*:all
    USERS.${user}.**
    allow:*:alter
    Because the second rule only applies to a top-level dataset qualifier of USERS followed by the user's ID as a second qualifier, each user will only have access to their own datasets under the USERS area. For example, the user ALICE would have access to everything under USERS.ALICE.

Finally, Micro Focus recommends periodically reviewing access rules to determine whether any should be tightened or removed.

Parent topic: Using and hardening the supplied configuration


Mainframe Access

Enterprise Developer provides functionality that you can use to work with files and data located on the mainframe. This section describes the functionality.

Important: Mainframe Access is only available in the following products. It is available for testing of mainframe applications and not for production:
  • Enterprise Developer
  • Enterprise Test Server

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 Mainframe Access
  • Configuring Mainframe Access
  • Using Mainframe Access
Parent topic: Micro Focus Enterprise Test Server 10.0


About Mainframe Access

Important: Mainframe Access is only available in the following products. It is available for testing of mainframe applications and not for production:
  • Enterprise Developer
  • Enterprise Test Server

Mainframe Access includes the following components that enables 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.
  • MFA command line enables you to transfer files between mainframe and PC environments.
Parent topic: Mainframe Access


Configuring Mainframe Access

The information in this section covers configuring the mainframe access functionality.

  • Configuring the Environment
  • Configuring Server Access
  • Using z/OSMF
Parent topic: Mainframe Access


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
  • Configuring MFDAS for UNIX
Parent topic: Configuring Mainframe Access


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:

Environment variable Description
CCITIMEOUT Enables 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. For example, to set 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. For 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 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. For example:
SET MFAMAXHOTLINKS=4
MFAIMBEDDEDHEX Indicates that you require 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. For example:
SET MFAIMBEDDEDHEX=COBOL
MFA_INDEX_FORMAT Enables you to override the default index format on KSDS VSAM data sets. Set MFA_INDEX_FORMAT to the index format you want to use during the conversion. For example:
SET MFA_INDEX_FORMAT=IDXFORMAT(8)

Then run the MFA client program.

Note: This can be used for Drag and Drop, synchronization monitor and command-line tools.
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 MonitorMFDAS command line, in two different ways, depending upon your requirements:

  • The first method, the default, is to simply translate these hex values to ASCII, assuming that the workstation applications handle them properly.
  • The second method is more integrated with other Micro Focus applications, and might 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 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 might want to mix applications and techniques if required. 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 MFDAS for UNIX

To configure MFDAS to operate in a UNIX environment you must specify the server and interactions in the mfa_config.json configuration file. A template configuration file is supplied with the product and can be located at $COBDIR/etc/config/mfa/mfa_config.json (UNIX) or %ProgramData%\Micro Focus\Enterprise Developer\mfa\mfa_config.json (Windows).

Required configuration is as follows:

{
  "connection_config":
  {
    "host" : "MYMFAHOST",
    "port" : "2020",
    "timeout_seconds" : "60",
    "retry_count" : "2",
    "max_retry_time" : "120",
  }
}

Optional configuration enables you to specify more advanced options which can be added to the "connection_config" section.

To specify TLS client verification:

client_cert
Specifies the absolute path to the certificate file (.pem). If multiple certificates are used, separate the paths with a semicolon ';'.
client_key
Specifies the absolute path to the keyfile (.pem).
client_password
The password for the keyfile specify it here. If multiple keyfiles are used, separate the passwords with four colons '::::'.
ca_path
The location, on disk, of the server root certificate.
client_cert_type
The following certificate file types are supported DER, CER, PKCS #7, PKCS #8, PKCS #12, and PEM.
client_key_type
The following key file types are supported PKCS #8, PKCS #12, and PEM.
verify_host=ENABLE|DISABLE
When enabled, libcurl will verify that the certificate provided by the server has a Common Name (CN) field or a Subject Alternate Name (SAN) field which matches the hostname in the URL that the mfsecretshashicorp vault provider is connecting to.

The default value is ENABLE.

verify_peer=ENABLE|DISABLE
When enabled, the mfsecretshashicorp vault provider will verify the authenticity of the server's certificate against the Certification Authority's (CA) certificates supplied to the ca_path configuration option.

The default value is ENABLE.

cert_revoke_check=ENABLE|DISABLE
Specifies whether libcurl verifies the status of the server certificate using the "Certificate Status Request" TLS extension, that is OCSP stapling.

The default value is DISABLE.

Note: If this option is enabled but the server does not support the TLS extension the verification will fail.
cipher_list
Specifies the priority of cipher suites to be used. The cipher suite priority is formed using a combination of keywords and keyword modifiers for a space-separated string:
!
Exclude. Permanently exclude the cipher suite and ignore any subsequent attempt to add the cipher suite back in.
+
Add. Add the cipher suite to the end of the collection.
-
Delete. Delete the cipher suite from the existing collection.
By default, the following cipher suite list is used:
kEECDH+ECDSA kEECDH kEDH HIGH MEDIUM +3DES +SHA !RC4 !aNULL !eNULL !LOW !MD5 !EXP
tls13_cipher_suites
The list of cipher suites to be used with TLS1.3 separated by a colon ':'. For example:
TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
ssl_two_stage_connect=ENABLE|DISABLE
Specifies whether libcurl should enable the use of false start during the TLS handshake. False start is a mode where a TLS client will start sending application data before verifying the server's Finished message, this saves a round trip when performing a full handshake.

The default value is DISABLE.

tls_protocol
Specified the TLS protocol version to use which can be one of the following options:
  • TLSv1
  • SSLv2
  • SSlv3
  • TLSv1_0
  • TLSv1_1
  • TLSv1_2
  • TLSv1_3
  • MAX_DEFAULT
  • MAX_TLSv1_0
  • MAX_TLSv1_1
  • MAX_TLSv1_2
  • MAX_TLSv1_3
connection_debugging=true|false
Set to true to turn on verbose transport layer debugging.
Warning: Setting this to true will print out HTTP headers and bodies which could contain sensitive data, such as passwords.
Note: You should not be set this to true unless asked to do so by the Micro Focus support team.
mainframe_time_delta=time
This specifies the difference between mainframe time and your local machine time in milliseconds (ms).
tls_enable=ENABLE |DISABLE
Specifies whether libcurl targets an https endpoint (ENABLE) or http. If ca_path is set then tls_enable is treated as ENABLE.

The default value is DISABLE.

  • Configuring user credentials
Parent topic: Configuring the Environment
Related concepts
Using z/OSMF


Configuring user credentials

There are two methods you can use to specify user credentials for MFDAS in a UNIX environment:

Environment variables
You can specify your user credentials using environment variables. For example:
MFA_USERNAME=username
MFA_PASSWORD=password
Vault Facility

You can use the mfsecrets vault by specifying:

MFA_CREDENTIALS=mfsecret:vault_name:/path_to_vault/location

Where vault_name is the name of the vault to use from the mfsecrets.cfg file. If this is not specified then the default is used, for example:

MFA_CREDENTIALS=mfsecret:/path_to_vault/location

The credentials stored in the vault must be in the following format:

{
“version”:1,
“username”:”username”,
“password”:”password”
}

Micro Focus recommends that you use a vault location of microfocus/MFA/my_credentials. Where my_credentials is replaced with an identifier for that user.

See Vault Facility for more information.

Parent topic: Configuring MFDAS for UNIX


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 Mainframe Access


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


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


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:

    The Node Configuration Wizard

  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 information
Editing a Mainframe Node
Deleting a Mainframe Node


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


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


Using z/OSMF

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

MFA has limited functionality to use a z/OSMF server for basic source discovery and off load to the workstation.

Configuration:

To configure MFDAS or MFA Compare and Synchronization Monitor to operate with a z/OSMF server the following configuration is required:

  • Environment variable MFA_ZOSMF=true must be set in the process environment.
  • The z/OSMF server's host, port, and TLS information must be set in the mfa_config.json file.

See Configuring MFDAS for UNIX for more information.

MFA Compare and Synchronization Monitor requires the time delta specified in the mfa_config.json file. The time delta specifies the difference between mainframe time and your local machine time in milliseconds (ms). For example:

"mainframe_time_delta" : "-18000"

Commands available

MFDAS:
mfdas catdcb <data set> ALL
mfdas DIR PDS <data set> FULL
mfdas import <local dir> FROM PDS <data set> MEMBER <prefix|member name>
MFMON2:
mfmon2 [TEXT|BINARY] DOWNLOAD [PREFIX <prefix>] PDS <local dir> AGAINST <data set> [EXT=<extension>]
Parent topic: Configuring Mainframe Access
Related reference
Configuring MFDAS for UNIX


Using Mainframe Access

The information in this section describes how to use the mainframe access functionality.

  • 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.
  • Using the command-line interface
    The command-line interface, in which you can perform file-related interactions with the mainframe.
  • Remote Job Step Execution
  • Compare and Synchronization Monitor
  • SourceConnect: Mapping a PC Drive to Mainframe Data
  • Mainframe Access Data Connect Server
Parent topic: Mainframe Access


Drag and Drop

Enterprise Developer has the following variations of the Drag and Drop functionality:

  • Drag and Drop Error Messages
    Error messages relating to Drag and Drop are prefixed MFDAS.
Parent topic: Using Mainframe Access


Drag and Drop Error Messages

Refer to the table below for a list of possible error messages:

  • MFDAS01: Mainframe access problem.
  • MFDAS02: Cannot import multiple files to a single file.
  • MFDAS03: Cannot export multiple files to a single file.
  • MFDAS04: Module 'MFLSC' is missing or inaccessible.
  • MFDAS05: File had no length, or does not exist.
  • MFDAS06: Call to module 'DFCONV' failed. Unable to convert the VSAM/QSAM file.
  • MFDAS07: Value is not a valid number.
  • MFDAS08: For VSAM/QSAM files, extensions of PRO, DAT, or IDX are reserved.
  • MFDAS09: Rename to file failed.
  • MFDAS10: The allocation of failed with message number.
  • MFDAS11: The allocation of differs from the mainframe.
  • MFDAS12: One or more of the fields have not been properly entered.
  • MFDAS13: The PC file name cannot have more than 4 subdirectory levels.
  • MFDAS14: Mismatch between new and repeat passwords.
  • MFDAS15: Unable to make the directory.
  • MFDAS16: Unable to remove directory.
  • MFDAS17: Call to module 'PCIMS' failed. Unable to convert the IMS database.
  • MFDAS18: A catalog search criteria must be entered.
  • MFDAS19: A real workstation drive must be used.
  • MFDAS22: Call to module 'SQL-Wizard' failed. Unable to convert the XDB table.
  • MFDAS23: Cannot establish connection to the mainframe server.
  • MFDAS24: Network communication problems with blocks of size.
  • MFDAS25: CCI module was not found.
  • MFDAS26: Module is not a CCI module.
  • MFDAS27: Unable to delete file.
  • MFDAS28: Either recall this dataset or assign a type.
  • MFDAS29: Assign a type to this dataset.
  • MFDAS30: The workstation dataset is connected to the mainframe
  • MFDAS31: Copy of file failed.
  • MFDAS32: Paste of file failed.
  • MFDAS33: PCIMS is not available. Unable to convert the IMS database
Parent topic: Drag and Drop


MFDAS01: Mainframe access problem.

Return Code

1001

Description

A communication problem has been detected. Refer to the MFAERROR.LOG file for more information.

Parent topic: Drag and Drop Error Messages


MFDAS02: Cannot import multiple files to a single file.

Return Code

1002

Description

An illogical request has been made, in that the user is attempting to import more than one file into a single file.

Parent topic: Drag and Drop Error Messages


MFDAS03: Cannot export multiple files to a single file.

Return Code

1003

Description

An illogical request has been made, in that the user is attempting to export more than one file into a single file.

Parent topic: Drag and Drop Error Messages


MFDAS04: Module 'MFLSC' is missing or inaccessible.

Return Code

1004

Description

The required module MFLSC cannot be found. This is most likely an installation problem.

Parent topic: Drag and Drop Error Messages


MFDAS05: File had no length, or does not exist.

Return Code

1005

Description

The file had either a zero length, or had been deleted but the display was not refreshed.

Parent topic: Drag and Drop Error Messages


MFDAS06: Call to module 'DFCONV' failed. Unable to convert the VSAM/QSAM file.

Return Code

1006

Description

A bad return code was given by the converter program. Run the dfconv program on its own to determine the error.

Parent topic: Drag and Drop Error Messages


MFDAS07: Value is not a valid number.

Return Code

1007

Description

A non-numeric value was given when a numeric value was expected.

Parent topic: Drag and Drop Error Messages


MFDAS08: For VSAM/QSAM files, extensions of PRO, DAT, or IDX are reserved.

Return Code

1008

Description

You cannot use a restricted extension for a file transfer.

Parent topic: Drag and Drop Error Messages


MFDAS09: Rename to file failed.

Return Code

1009

Description

An error was returned when trying to rename a file.

Parent topic: Drag and Drop Error Messages


MFDAS10: The allocation of failed with message number.

Return Code

1010

Description

An error message has been returned from the COBOL development environment. See the product documentation for a description of the message.

Parent topic: Drag and Drop Error Messages


MFDAS11: The allocation of differs from the mainframe.

Return Code

1011

Description

The DCB information for the COBOL development environment dataset differs from that of the mainframe.

Parent topic: Drag and Drop Error Messages


MFDAS12: One or more of the fields have not been properly entered.

Return Code

1012

Description

Insufficient or incorrect information has been provided in the panel.

Parent topic: Drag and Drop Error Messages


MFDAS13: The PC file name cannot have more than 4 subdirectory levels.

Return Code

1013

Description

The COBOL development environment is unable to support more than 4 subdirectory levels.

Parent topic: Drag and Drop Error Messages


MFDAS14: Mismatch between new and repeat passwords.

Return Code

1014

Description

The new and repeat passwords given do not match.

Parent topic: Drag and Drop Error Messages


MFDAS15: Unable to make the directory.

Return Code

1015

Description

An error was returned when trying to create a directory.

Parent topic: Drag and Drop Error Messages


MFDAS16: Unable to remove directory.

Return Code

1016

Description

An error was returned when trying to remove a directory.

Parent topic: Drag and Drop Error Messages


MFDAS17: Call to module 'PCIMS' failed. Unable to convert the IMS database.

Return Code

1017

Description

A bad return code was given by the PCIMS program. Run the PCIMS program on its own to determine the error.

Parent topic: Drag and Drop Error Messages


MFDAS18: A catalog search criteria must be entered.

Return Code

1018

Description

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.

Parent topic: Drag and Drop Error Messages


MFDAS19: A real workstation drive must be used.

Return Code

1019

Description

The drive selected for the COBOL development environment dataset does not exist on this workstation.

Parent topic: Drag and Drop Error Messages


MFDAS22: Call to module 'SQL-Wizard' failed. Unable to convert the XDB table.

Return Code

1022

Description

A bad return code was given by the SQL wizard program. Run the SQL wizard program on its own to determine the error.

Parent topic: Drag and Drop Error Messages


MFDAS23: Cannot establish connection to the mainframe server.

Return Code

1023

Description

Unable to connect to the mainframe server.

Parent topic: Drag and Drop Error Messages


MFDAS24: Network communication problems with blocks of size.

Return Code

1024

Description

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.

Parent topic: Drag and Drop Error Messages


MFDAS25: CCI module was not found.

Return Code

1025

Description

The CCI communications file is not found.

Parent topic: Drag and Drop Error Messages


MFDAS26: Module is not a CCI module.

Return Code

1026

Description

The module specified is not a CCI communications file.

Parent topic: Drag and Drop Error Messages


MFDAS27: Unable to delete file.

Return Code

1027

Description

An error was returned when trying to delete a file.

Parent topic: Drag and Drop Error Messages


MFDAS28: Either recall this dataset or assign a type.

Return Code

1028

Description

This dataset is migrated. Either use the right-mouse context to recall it, or assign a specific type.

Parent topic: Drag and Drop Error Messages


MFDAS29: Assign a type to this dataset.

Return Code

1029

Description

Unknown DSORG for this dataset. You need to use the right-mouse context to assign a specific type.

Parent topic: Drag and Drop Error Messages


MFDAS30: The workstation dataset is connected to the mainframe

Return Code

1030

Description

This workstation dataset you are tying to access is redirection to a mainframe dataset.

Parent topic: Drag and Drop Error Messages


MFDAS31: Copy of file failed.

Return Code

1031

Description

Unable to copy from the Windows clipboard.

Parent topic: Drag and Drop Error Messages


MFDAS32: Paste of file failed.

Return Code

1032

Description

Unable to paste the file to the Windows clipboard.

Parent topic: Drag and Drop Error Messages


MFDAS33: PCIMS is not available. Unable to convert the IMS database

Return Code

1033

Description

The PCIMS.LBR routines could not be found, or a project was not open.

Parent topic: Drag and Drop Error Messages


Using the command-line interface

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

  • Changing Your Mainframe Password
  • Converting to ASCII
  • Displaying a Directory List
  • Exporting Data
  • Importing Data
  • Locating Data Sets
  • Retrieving Endevor Footprints
  • Retrieving Enqueue Information
  • Specifying Servers, Nodes and Ports
  • Submitting Files
  • Unlocking Resources
  • Using the Command Line Application Program Interface
  • MFDAS Syntax and Options
    Use the MFDAS command line utility to perform a range of file-related interactions with the mainframe.
  • User exit after a successful import
  • User exit after a successful export
  • MFDAS AWM API
  • MFDAS Phase Codes
Parent topic: Using Mainframe Access


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


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: 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 can optionally specify a control file containing one or more commands that enable MFDAS to run them as a batch. To do this, place the commands in a control file with 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 require only the members that begin with the specified characters to be displayed. This is equivalent to using the FILTER parameter of the specified characters followed by an asterisk (*).

The FILTER parameter can be used to specify a specific mainframe member name, or can included special filter characters to enable multiple members to be displayed based on the special filter characters that you specify. These special filter characters are:

*
Any characters can follow.
?
Any character in this position.
+
The character in this position must be non-blank.
-
The character in this position must be blank.
\
The character in this position must be non-numeric.
/
The character in this position must be numeric.

Example

The following are examples of the directory list command:

CAT

To list data sets based upon a catalog search criteria:

MFDAS CAT
catalogsearchcriteria

Below is an example of the command and its output:

mfdas cat MFI01.COMMS.TEST.SYNC.CNTL
MFI01.COMMS.TEST.SYNC.CNTL
MFI01.COMMS.TEST.SYNC.CNTL.REL
MFI01.COMMS.TEST.SYNC.CNTL.UNL
CATDCB

To list the extended attributes for data sets based upon a catalog search criteria:

MFDAS CATDCB
catalogsearchcriteria

Below is an example of the command and its output:

mfdas catdcb MFI01.COMMS.TEST.SYNC.CNTL
Name=MFI01.COMMS.TEST.SYNC.CNTL                  ,Volume=TEMP1G,DSORG=BPAM,RECFM=FB,BLKSIZE=3120,REC
L=80,Average RECL=0,Max RECL=0,Key Position=0,Key length=0,Reuse=48,Volume type=CYL,Last backup=????

Name=MFI01.COMMS.TEST.SYNC.CNTL.REL              ,Volume=TEMP0F,DSORG=QSAM,RECFM=FB,BLKSIZE=3120,REC
L=80,Average RECL=0,Max RECL=0,Key Position=0,Key length=0,Reuse=48,Volume type=CYL,Last backup=????

Name=MFI01.COMMS.TEST.SYNC.CNTL.UNL              ,Volume=TEMP1L,DSORG=QSAM,RECFM=FB,BLKSIZE=3120,REC
L=80,Average RECL=0,Max RECL=0,Key Position=0,Key length=0,Reuse=48,Volume type=CYL,Last backup=????
PDS

To list members of a partitioned data set:

MFDAS DIR PDS
pdsname [{PREFIX prefix | FILTER filter}]

Below is an example of the command and its output:

mfdas dir pds MFI01.COMMS.TEST.SYNC.CNTL filter m0001
M00010          CNTL    13/09/2008:17:23CSIJY1
M00011          CNTL    13/09/2006:40:28CSIJY1
M00012          CNTL    13/09/2006:40:34CSIJY1

Librarian

To list members of a Librarian data set:

MFDAS DIR LIB
libraryname [{PREFIX prefix | FILTER filter}]

Below is an example of the command and its output:

mfdas dir lib MFI01.COMMS.TEST.DATA.LIBR
MEM1            COB     16/01/1304:35:40MFITST
MEM2            DAT     16/01/1304:35:41MFITST
MEM3            DAT     16/01/1304:35:43MFITST
Panvalet

To list members of a Panvalet data set:

MFDAS DIR PAN
libraryname [{PREFIX prefix | FILTER filter}] [USERCODE <code>] [ALL]

Below is an example of the command and its output:

mfdas dir pan MFI01.COMMS.TEST.DATA.PANLIB all
A                DATA     16/01/13 04:35:56 MFITST   12            0 103 N TAE
AAA              DATA     16/01/13 04:35:59 MFITST   1             0 102 N TAE
AAB              DATA     16/01/13 04:36:00 MFITST   1             0 102 N TAE

Where the last column gives the 3-byte Panvalet status code which is a combination of the following:

P - Production | T - Test

A - Active | I - Inactive

E - Enable | D - Disable

Endevor

To list members of an Endevor data set:

MFDAS DIR END
ENV 'env' SYS 'sys' SUB 'sub'
[{PREFIX prefix | FILTER filter}]
[STG stage] [TYPE type] [ALL|FULL]

Below is an example of the command and its output:

mfdas dir end ENV SMPLPROD SYS FINANCE SUB ACCTPAY filter mem all
MEM1             COPY     16/01/07 04:32:55          FINANCE  ACCTPAY  P 0100
MEM2             COPY     16/01/07 07:39:40          FINANCE  ACCTPAY  P 0100
MEM3             COPY     15/11/25 04:09:39 MFITST   FINANCE  ACCTPAY  E 0100
Parent topic: Using the command-line interface


Exporting Data

You can export individual files, or a collection of files specified by a filter, to a partitioned data set, source code control system, or you can export entire QSAM data sets. You can optionally specify a control file containing one or more commands to enable MFDAS to run them as a batch. To do this, place the commands in a control file with 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 include special filter characters to enable 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. The valid special filter characters are:

*
Any characters can follow.
?
Any character in this position.

Example

The following are example export commands:

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


Importing Data

You can import individual members, or a collection of members specified by a filter, from the JES spool, a partitioned data set, 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 can optionally specify a control file containing one or more commands to enable MFDAS to run them as a batch. To do this, place the commands in a control file with 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 can be performed. 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 enable multiple imports to occur based on the special filter characters that you specify. These special filter characters are:

*
Any characters can follow.
?
Any character in this position.
+
The character in this position must be non-blank.
-
The character in this position must be blank.
\
The character in this position must be non-numeric.
/
The character in this position must be numeric.

Examples

The following are examples of import commands:

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. 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
  • Importing VSAM Files with Fixed Record Lengths
  • Creating a Log File
  • Performing a Bulk Import
  • Providing Your Own Security Exit to The Command Line Interface
  • Overwriting Existing Catalog Entries
  • Limiting the Number of VSAM Records to be Imported
  • 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


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


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


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


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/
Tip: By default, the physical file location will be folded into upper case. Use the following environment variable setting to preserve the case of the physical file location:
MFJ_STRICT_CASE=Y
Parent topic: Importing Data with Auto-catalog


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


Retrieving Enqueue Information

Retrieve detailed enqueue information from a PDS or a QSAM data set. The following example displays all current PDS locks:

MFDAS GETENQI PDS *

The result could look something like this:

Lock user=CABR12  ,Data set name=CABR12.ISPF.DOC                             ,Member name=AST
Lock user=CABR12  ,Data set name=CABR12.ISPF.DOC                             ,Member name=M00001

Which shows that user CABR12 has two members locked in the CABR12.ISPF.DOC PDS.

You can use the UNLOCK command to unlock these, but only if you are the owner, and you should only perform this if you are sure they are locked in error.

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. However, you can 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
This is the name of the server to use. The example below specifies a server called MVSSRV.
node
This is the URL or IP address to use. The example below specifies a URL of MVS.SERVER.COM.
portnum
This 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


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


Unlocking Resources

You can unlock a resource in a PDS or a QSAM data set as long as you are the owner of the lock. You should only perform this if you are sure that the resource is erroneously enqueued.

In the following example, member m00001 in the cabr12.ispf.doc PDS dataset is unlocked:

MFDAS UNLOCK PDS cabr12.ispf.doc MEMBER m00001

Use the GETENQI command to retrieve the current enqueue information.

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 DropMFDAS command line 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 Syntax and Options

Use the MFDAS command line utility to perform a range of file-related interactions with the mainframe.
Note: Slash parameters can appear anywhere, they are processed first and then removed:
  • /AMSLOG="<amslogPath>" - on AMS command if there was an IDCAMS command failure writes the SYSPRINT DD to the specified location. On TSO command writes SYSTSPRT DD to the specified location.
  • /CAT=Y
  • /CATLOC=<filename>
  • /CATLOG=<filename>
  • /CATOVERRIDE=<catalogpath>
  • /CODEPAGE=<codepage> See Supported codepages for more information.
  • /DATACODEPAGE=<codepage> See Supported codepages for more information.
  • /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

See User exit after a successful import and User exit after a successful export for more information.

Syntax:

MFDAS OPTION [/Parameter]

MFDAS supports the following options:

Parent topic: Using the command-line interface

ALLOCATE

MFDAS ALLOCATE PDS <dsname> CYL|TRK|BLK <number> LRECL <number>
BLKSIZE <number> RECFM FB|FBA|FBM|VB|VBA|VBM|F|FA|FM|FSA|FSM|U
DIR <number> [VOL <volser>]

MFDAS ALLOCATE SEQ CYL|TRK|BLK <number> LRECL <number>
BLKSIZE <number> RECFM FB|FBA|FBM|VB|VBA|VBM|F|FA|FM|FSA|FSM|U
[VOL <volser>]

MFDAS ALLOCATE PDS <dsname> EXT <extension>
MFDAS ALLOCATE USS <path> [PERM <permissions string>]
Note: The default value for PERM is 755. The umask applied to the process will be 000 and therefore any PERM specified will be the permissions applied to the process.

AMS

MFDAS AMS <cmd> /AMSLOG="<filename>"
MFDAS AMS FILE <filename> /AMSLOG="<filename>"

AWM

MFDAS AWM /AMSLOG="<filename>" "TAUZCIF <parms>"

BINDER

MFDAS BINDER <filename> PDS <dsname> MEMBER <mname> [XREF]

BROWSE

MFDAS BROWSE <filename> FROM PDS <dsname> MEMBER <mname>
MFDAS BROWSE <filename> FROM QSAM <dsname>

BUILD

MFDAS BUILD <filename> CHG <pkgname> MEMBER <mname> TYPE <memtype>

CANCEL | HOLD | RELEASE

MFDAS CANCEL|HOLD|RELEASE <jobid>

CAT

MFDAS CAT <catalogsearchfilter>

CATDCB

To list data sets based on a catalog search criteria:

MFDAS CATDCB <catalogsearchfilter> [ALL]
MFDAS CATDCB * JESDD JOB#

COMPRESS

MFDAS COMPRESS <dsname>

COPY

MFDAS COPY USS <path> TO <path> [CREATE <YES|NO>] [REPL <YES|NO>]

DELETE

MFDAS DELETE <dsname> [MEMBER <mname>]
MFDAS DELETE END ENV <env> SYS <sys> SUB <sub> MEMBER <mname>|FILTER <filter> [STG <stage>] [TYPE <memtype>] [CCID <change-control-id>]
[OVERRIDE SIGNOUT] [COMMENT <user-comment>]
MFDAS DELETE JES <jobid> [PURGE]
MFDAS DELETE USS <path>

DIR

MFDAS DIR END ENV <env> SYS <sys> SUB <sub> [PREFIX <prefix>|FILTER <filter>] [STG <stage>] [TYPE <memtype>] [ALL|FULL]
MFDAS DIR FOOT <dsname> [FILTER <mname>]
MFDAS DIR JESDD <jobid> [ALL] [INPUT]
MFDAS DIR LIB <dsname> [PREFIX <prefix>|FILTER <filter>] [TYPE <memtype>] [ALL]
MFDAS DIR PAN <dsname> [PREFIX <prefix>|FILTER <filter>] [TYPE <memtype>] [USERCODE <code>] [ALL]

To list the members of a partitioned data set:

MFDAS DIR PDS <dsname> [PREFIX <prefix>|FILTER <filter>] [ALL|FULL]
MFDAS DIR CHG <pkgname> [TYPE <memtype>] [PREFIX <prefix>]
MFDAS DIR USS <path>

EXPORT | CHECKIN

MFDAS EXPORT|CHECKIN [BINARY|TEXT] <filename>|<filter> TO END ENV <env> SYS <sys>
SUB <sub> MEMBER <mname> TYPE <memtype> [VVLL <nnnn>] [CCID <change-control-id>] [COMMENT <user-comment>]
[OVERRIDE] [SIGNOUT] [BYPASS GEN] [PGRP <processor-group>] [LOCK=YES|NO]
MFDAS EXPORT|CHECKIN [BINARY|TEXT] <filename>|<filter> TO LIB <dsname> MEMBER <mname>
MFDAS EXPORT|CHECKIN [BINARY|TEXT] <filename>|<filter> TO PAN <dsname> MEMBER <mname>
[USERCODE <code>]

To export a partitioned data set:

MFDAS EXPORT|CHECKIN [NOEMPTYCHECK] [LOCK] [RJSE [NOTRANSLATE]] [BINARY|TEXT] [NODFCONV] <filename>|<filter> TO PDS <dsname> MEMBER <mname> [OVERRIDESCLM]

To export to a QSAM data set:

MFDAS EXPORT|CHECKIN [LOCK] [BINARY|TEXT] <filename> TO QSAM <dsname>
MFDAS CHECKIN [BINARY|TEXT] <filename> TO CHG <pkgname> [TYPE <memtype>] [MEMBER <mname>] [OPTION <YYY>] [DESC <description>]
Y=Lock Y=Save Prior Y=Checkin Activate
MFDAS EXPORT <filename>|<filter> TO USS <path> [CREATE <YES|NO>] [APPEND <YES|NO>] [TRUNC <YES|NO>] [EXCL <YES|NO>] [PERM <permissions string>]

GETENQI

Retrieve detailed enqueue information from a PDS or a QSAM data set:

MFDAS GETENQI PDS *|<dsname> [MEMBER <mname>]
MFDAS GETENQI QSAM *|<dsname>

HELP

Get basic information about the MFDAS syntax at the command line:

MFDAS HELP

HISTORY | LISTCONC

MFDAS HISTORY|LISTCONC <filename> CHG <pkgname> MEMBER <mname> TYPE <memtype>
MFDAS HISTORY|LISTCONC <filename> END ENV <env> SYS <sys> SUB <sub> STG <stage> MEMBER <mname> TYPE <memtype> [VVLL <nnnn>]

IMPORT | CHECKOUT

To import from an unloaded DB/2 table with automatic data conversion and produce a workstation XDB format table.

MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM DB2 <dsname> <location> <authid>
<tablename>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM END ENV <env> SYS <sys> SUB <sub>
MEMBER <mname>|<filter> [STG <stage>] [TYPE <memtype>] [VVLL <nnnn>] [CCID <change-control-id>] [COMMENT <user-comment>]
[OVERRIDE SIGNOUT] [LOCK=YES]

To import from a VSAM ESDS, KSDS, or an 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 ESDS-FIXED, KSDS-FIXED, or RRDS-FIXED instead of ESDS, KSDS, or RRDS, respectively:

MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM ESDS|KSDS|RRDS[_FIXED] <dsname>
[NODFCONV]

To import from an unloaded IMS database with automatic data conversion and produce a workstation PCIMS format database.

MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM IMS <dsname> <databasename>
<segmentnamelocation> <segmentdatalocation>

To import from the mainframe JES2 or JES3 spool:

MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM JES <jobid> [EXECUTING] [INPUT]
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM JESDD <jes_ddname> JES <jobid> [EXECUTING] [INPUT]
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM LIB <dsname> MEMBER <mname>|<filter>
MFDAS IMPORT|CHECKOUT [BINARY|TEXT] <filename> FROM PAN <dsname> MEMBER <mname>|<filter>

To import from a partitioned data set:

MFDAS IMPORT|CHECKOUT [LOCK] [BINARY|TEXT] <filename> FROM PDS <dsname> MEMBER <mname>|<filter>

To import from a QSAM data set with automatic data conversion:

MFDAS IMPORT|CHECKOUT [LOCK] [BINARY|TEXT] <filename> FROM QSAM <dsname>
MFDAS IMPORT [BINARY|TEXT] <filename> FROM CHG <pkgname> [TYPE <memtype>] [MEMBER <mname>]
MFDAS CHECKOUT [BINARY|TEXT] <filename> FROM CHG <pkgname> [TYPE <memtype>] [MEMBER <mname>] [LEVEL <0|+|->]
[OPTION <YYYY>] Y=Lock Y=Overlay Prior Y=Save Prior Y=Suppress Notify
MFDAS IMPORT USS <path>

LIST

MFDAS LIST END ENV
MFDAS LIST END [SYS|SUB|STG|TYPE|PGRP] ENV <env> [SYS <sys>] [SUB <sub>] [STG <stage>] [TYPE <type>] [PGRP <pgrp>]

LOCATE

Check whether a data set exists on the mainframe.

MFDAS LOCATE <dsname>

A zero return code indicates that the data set exists, and a non-zero return code indicates that it does not exist.

MOVE

MFDAS MOVE END ENV <env> SYS <sys> SUB <sub> MEMBER <mname> [STG <stage>] [TYPE type] [TOUSER <userid>] [BYPASS GEN]
MFDAS MOVE [OVERRIDE SIGNOUT] [CCID <change-control-id>] [COMMENT <user-comment>]

PASSWORD

To change your mainframe password:

MFDAS PASSWORD <password>

RECALL

MFDAS RECALL <dsname>

RENAME

MFDAS RENAME <dsname> MEMBER <mname> NEWNAME <mname>
MFDAS RENAME <dsname> NEWNAME <dsname>
MFDAS RENAME USS <path> NEWNAME <path>

SETPERM

MFDAS SETPERM USS <path> PERM <permissions string>

SETUSER

MFDAS SETUSER <userid> <password>

STATUS

To get a job status:

MFDAS STATUS [LIST] <jobname>|<filter> [FILTER filter]

SUBMIT

To submit a JCL file for execution:

MFDAS SUBMIT <filename>|<filter>

TERMINATE

MFDAS TERMINATE

TRANSFER

MFDAS TRANSFER END ENV <env> SYS <sys> SUB <sub> MEMBER <mname> [STAGE <stage>] [TYPE <type>] [VVLL <nnnn>]
[TOENV <env>] [TOSYS <sys>] [TOSUB <sub>] [TOMEMBER <mname>] [TOSTAGE <stage>] [TOTYPE <type>]
[CCID <change-control-id>] [COMMENT <user-comment>] [OVERRIDE SIGNOUT] [LOCK=YES]

TSO

MFDAS TSO <TSO command>

UNLOCK

Unlocks a resource in a PDS or a QSAM data set as long as you are the owner of the lock. You should only perform this if you are sure that the resource is erroneously enqueued.
MFDAS UNLOCK PDS <dsname> MEMBER <mname>
MFDAS UNLOCK CHG <pkgname> [MEMBER <mname>] | [TYPE <memtype>]
MFDAS UNLOCK QSAM <dsname>
Note: Use the GETENQI command to retrieve the current enqueue information.

VERSION

MFDAS 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 16 byte area containing the mainframe member name used in the import

You may write your own user exit in COBOL if you desire. The name of the program must be MFDASIMP.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFDASIMP.
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-MEMBERNAME     PIC X(16).
PROCEDURE DIVISION USING P-WORKSTATION P-DATASETNAME
                         P-MEMBERNAME.
*> EXECUTE CODE HERE GOBACK.
Parent topic: Using the command-line interface


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 16 byte area containing the mainframe member name used in the export

You may write your own user exit in COBOL if you desire. The name of the program must be MFDASEXP.

IDENTIFICATION DIVISION.
PROGRAM-ID. MFDASEXP.
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-MEMBERNAME      PIC X(16).
PROCEDURE DIVISION USING P-WORKSTATION P-DATASETNAME
                         P-MEMBERNAME.
*> EXECUTE CODE HERE
   GOBACK.
Parent topic: Using the command-line interface


MFDAS AWM API

The MFDAS AWM API enables you to call AWM ISPF commands from an Enterprise Developer command prompt. AWM ISPF commands are REXX procedures, CLISTs, or load modules which are written according to the AWM ISPF tool interface definitions. AWM ISPF commands are called through the tool interface REXX procedure TAUZCIF.

Before you can use MFDAS AWM commands, you must connect to an MFA server connection on z/OS. This can be done by using the MFDASMX command. The MFDASMX command requires the connection properties (host name and port) and the user credentials (user ID and password). When the first AWM ISPF command is sent the credentials are requested once again.

An example call of an AWM ISPF command might looks like this:

MFDAS AWM /amslog="c:\temp\awm.log" "TAUZCIF INPARM(SOURCE;%;SMPLTEST;%;T;%;1;%;MFUID;%;BANKDEMO;%;COBOL;%;BBANK10P;%;0102) FORM(REXX) TOOL(TAUENEPR) EXITPARM(TEST) ENV(ONLINE)"

You should ensure that REXX procedures called via MFDAS AWM adheres to the conventions for modeling an ISPF tool. See Attaching ISPF Tools under the ISPF Function Package chapter for more information.

The AWM ISPF command used in the preceding example retrieves all properties of the Endevor element BBANK10P located in the system MFUID and sub system BANKDEMO. In Enterprise Developer you can determine the structure of an AWM ISPF command by executing the command under the corresponding attachment model. Start Enterprise Developer using the -debug option.

In the Eclipse Error Log, the command can be found under the tag:

!MESSAGE Sending TSO Command String:

The output of the AWM ISPF command can be found in the local log file specified with the MFDAS command, c:\temp\awm.log, as specified in the example above.

In this example, the awm.log file will contain the following information:

Input TAUENEPR: SOURCE;%;SMPLTEST;%;T;%;1;%;MFUID;%;BANKDEMO;%;COBOL;%;BBANK10P;%;0102
TAUTOUT: TOOL: TAUENEPR
TAUTOUT: RC: 0
TAUTOUT: INPARM: SOURCE;%;SMPLTEST;%;T;%;1;%;MFUID;%;BANKDEMO;%;COBOL;%;BBANK10P;%;0102
TAUTOUT: DATE: 18/10/10 03:01
TAUTOUT: OUTPARM: ELM2;%;CICS;%;0101;%;0102;%;FB;%;00080;%;cbl;%;T;%;NL;%;ZOS;%;Y;%;
TAUTOUT: ENDPARM:
TAUTOUT: UPDATE: ELM;%;SMPLTEST;%;T;%;1;%;TEST;%;MFUID;%;BANKDEMO;%;COBOL;%;BBANK10P;%;CICS;%;TEST;%;SAMPLECCID2;%;0101;%;0102;%;0
101;%;MFUID;%;MFUID;%;00004;%;00000;%;MFUID;%;20180921 01433098;%;MFUID;%;20181009 03540000;%;CICS;%;FB;%;00080;%;cbl;%;T;%;NL;
%;ZOS;%;Y;%;MFUID.TAUENTMP.OUTSRCM.COBOL(BBANK10P);%;

The relevant output information can be found after the TAUTOUT: OUTPARM: entry. If the command fails, the output in the log file might look like this:

REXX Procedure TAUENEPX not found
TAUTOUT: TOOL: TAUENEPX
TAUTOUT: RC: 99
TAUTOUT: INPARM: SOURCE;%;SMPLTEST;%;T;%;1;%;MFUID;%;BANKDEMO;%;COBOL;%;BBANK10P;%;0102
TAUTOUT: DATE: 18/10/10 03:05
TAUTOUT: OUTMSG: REXX Procedure TAUENEPX not found

Some AWM ISPF commands return a data set which contains the output data. In this case, the local log file will contain a line like this:

TAUTOUT: OUTPARM: MFUID.TAUCMTMP.VALLIST

You can use the MFDAS IMPORT command to retrieve this data set to your local file system, for example:

MFDAS IMPORT  TEXT "c:\temp\vallist.txt" FROM QSAM 'MFUID.TAUCMTMP.VALLIST'

If the AWM ISPF command is calling a REXX procedure which does not work as expected, it might be helpful to set the REXX trace to obtain more detailed information. The REXX trace can be set by calling the REXX procedure TAUZCDBG, for example:

MFDAS AWM "/amslog=c:\temp\awm.log" "TAUZCDBG TAUENEPR"

When executing the AWM ISPF command TAUENEPR again, the trace of the REXX procedure will be written to the local log file awm.log.

Parent topic: Using the command-line interface


MFDAS Phase Codes

The following lists the returned MFDAS phase code and its phase description:

1
NO SUBCHAIN EXISTS
2
ACTIVE IN CI IN AN FSS
3
AWAITING POSTSCAN
4
AWAITING POSTSCAN
5
AWAITING VOLUME FETCH
6
AWAITING SETUP
7
IN MDS SYSTEM SELECTION
8
AWAITING RESOURCES
9
AWAITING UNAVAILABLE VOL
10
AWAITING VOLUME MOUNTS
11
IN MDS SYSTEM VERIFY
12
ERROR IN MDS PROCESSING
13
AWAITING EXECUTION
14
EXECUTING
15
RESERVED
16
RESERVED
17
ON OUTPUT QUEUE
18
AWAITING MDS RESTART
19
MAIN AND MDS PROC DONE
20
ON HARDCOPY QUEUE
21
AWAITING OUTPUT SERVICE
22
AWAITING RSVD SERVICES
23
OUTPUT SERVICE COMPLETE
24
AWAITING MAIN SELECTION
25
ENDING FUNCTION RQ WAIT
26
ENDING FUNCTION RQ SKIP
27
MAXIMUM RQ INDEX VALUE
128
IN INPUT PROCESSING
129
AWAITING CONVERSION
130
CONVERTING
131
ACTIVE IN SETUP
132
ACTIVE IN SPIN
133
AWAITING OUTPUT
134
AWAITING PURGE
135
ON PURGE QUEUE
136
ON NJE SYSOUT RECEIVER
137
AWAITING NJE TRANSMIT
138
ON NJE JOB TRANSMITTER

See the IBM documentation for more information.

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 Mainframe Access


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


RJSE Error Messages

In rare cases, RJSE issues the error messages listed in Related Reference.

If you get any JCLCMnnnns messages, check the JCLCM Error Messages section.

Parent topic: Using RJSE
Related reference
JCLCM Error Messages
JCLCM0118E Unexpected error from function <value>
JCLCM0119E Previous JCLCM0118E message is for DD/DSN <value>.
JCLCM0121
JCLCM0122E Incorrect password caused SAF failure on the host.
JCLCM0123E Expired password caused SAF failure on the host.
JCLCM0124E Invalid user id caused SAF failure on the host.
JCLCM0125E <value> is not supported.
JCLCM0126E <value> is not yet supported.
JCLCM0127E Host dataset <value> unexpectedly created by alien job.
JCLCM0128E Host dataset <value> unexpectedly deleted by alien job.
JCLCM0129W LRECL of host RECFM F dataset <value> assumed to be 80.
JCLCM0130W LRECL of host RECFM V dataset <value> assumed to be 255.


Compare and Synchronization Monitor

Compare and Synchronization Monitor enables 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 Mainframe Access


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
GUID-8A6257AD-E737-4B06-8C93-9F4B5D86FE2D.html
Related information
BKMAMAFSCRS009.html


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.

  • Advanced filter details
  • Adding an advanced filter
  • Editing an advanced filter
  • Removing an advanced filter
Parent topic: Compare and Synchronization Monitor


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 a file called monrule.ini.

Rule Name
The name that the rule is 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 options configuration process.
Rule
A free format field containing the rule as a regular expression. This enables you to create complex rules. There is a short description of the syntax below.
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 are ordinary, unless preceded by '\'.

For example, 'f' is not a special character, so it is ordinary. 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.

For example, you 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. For 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. This means that 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 +. This means that 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. This means that 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 square brackets form the set. This means that [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, and so forth.

Character ranges can also be included in a character set, by writing two characters with a - (hyphen) between them. This means that [a-z] matches any lower-case letter. Ranges may be intermixed freely with individual characters, as in [a-z$%.], which matches any lowercase letter or $, % or period.

Note: 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. This means that ^foo matches a foo which occurs at the beginning of a line.

$
Similar to ^ but matches only at the end of a line. This means that 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 are ever 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 match.

This means that 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.

\( ... \)
Specifies 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. This means that \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 matches a file called NULLFILE and nothing else.
  • ^NUL[0-9][0-9].* matches files beginning with NUL, followed by two numeric characters in the range 0-9, followed by any number of characters.
  • .*3$ matches any file ending with the number 3.
  • ^A.*[0-3][1-2]$ matches 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\$) excludes invalid DOS file names.
    Note: You can 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 Mainframe Access
Parent topic: Advanced filters
Related concepts
Drag and Drop
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints
Related tasks
Adding an advanced filter
Editing an advanced filter
Removing an advanced filter


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
Related information
Advanced filter details


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
Related information
Advanced filter details


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
Related information
Advanced filter details


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---+
                    +-TYPE=mem-type-+ +-CCID=xxxx--+ +-Comment="xxxxx"-+ +-EXT=extension-+

>-.----------------.-.--------.---<<
  +-REGEXT_ALLOW=Y-+ +-HASH=Y-+
Note: The second AGAINST-data-set line is for Endevor only.

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 or Endevor resource 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=extension
The extension to give each synchronized member on the workstation.
Note:
  • If you do not specify "EXTENSION" or specify "EXTENSION=" it will result in files downloaded without an extension.
  • If you specify "EXTENSION=*" you will get an extension that matches the last part of the data set name. For example, if the source data set is a.b.c.d then the file extension will be .d.
  • Everything else results in the extension specified. For example, "EXTENSION=txt" will result in files downloaded with a .txt extension.
REGEXT_ALLOW=Y
Allows the prefix to be in the format of a regular expression.
HASH=Y
Toggles monitor to use a hash of contents instead of the timestamp to determine what to synchronize. This mode is slower and should only be used when timestamps are unavailable.

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.

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 [DIRECTORY] DELETES

Specifies whether the Compare and Synchronize Monitor will delete workstation files when it determines that the corresponding mainframe member has been deleted. This will delete files when using hash sync.

Parameters

DIRECTORY
If this parameter is specified then the direcotry is deleted if it does not contain files.
Note: This does not include the __last_syncmon_run file.

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
[BINARY]
direction [PREFIX filter]
dataset-type
drive:\directory\*.ext
AGAINST mainframe-parameters

Specifies which workstation directories (when MONITOR 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.

    Set dataset-type to VSAM-KSDS if you want to monitor Innovation Access Method (IAM) files.

  • VSAM-ESDS

    Entry (VSAM ESDS) data set.

  • VSAM-RRDS

    Relative (VSAM RRDS) data set.

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

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

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

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.

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 Mainframe Access


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


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


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


Mainframe Access Data Connect Server

Mainframe Access Data Connect Server is one of Micro Focus's File Handler utilities for connecting to the mainframe.

Note: If you have used Mainframe Express before, note that there is a new version of Data Connect Server supplied with Enterprise Developer. You need to use the new version to connect to the mainframe.

This topic provides instructions for how to properly configure Data Connect to access the mainframe and how to configure your Enterprise Test Server region in order to work with Data Connect.

Set up a connection to the mainframe

As a first step, you need to configure Data Connect to access the mainframe remotely from your machine. To do this:

  1. Start an Enterprise Developer or an Enterprise Test Server command prompt.
  2. Execute the following command at the command prompt:
    sccfx

    This starts the Server Access Configuration dialog box.

  3. Configure a node as follows:
    1. Click the Node tab and then click Add.
    2. Follow the Node Configuration wizard instructions and specify the following details:
      • A name for the node, such as MVS.
      • A Logical server name - the name of the mainframe machine you are connecting to.
      • Click the first option to specify a Name or IP address and a Port number.
    3. On the Node tab, click Edit next to the node you have just defined.
    4. Click Credentials and specify the following details:
      • The user name and password that you use to connect to the mainframe.
      • Check both Use to authenticate against all resources and Save to INI file.

        This creates a mfaclient.ini file in c:\users\USERNAME\AppData\Roaming\Micro Focus with contents similar to the following:

        [SERVERNAME;NODENAME]
blank|_password=false
userid=SOMEUSER
password=SOMEPASSWORD
  4. Data Connect works as part of Source Connect so you must add an appropriate configuration for Source Connect:
    1. Click the Source Connect tab.
    2. Click Add.
    3. Specify a drive letter, a search criteria and specify the node that you just created.

      You must specify a drive letter that is not already in use or will not be used on the machine for any other purposes.

  5. After configuring Data Connect, start the mfdaemon service:
    1. Click the MFDaemon tab.
    2. Click Start Daemon.

      This starts the daemon. Check the details on the MFDaemon tab to ensure that it shows the resources associated with the saved logon credentials. This must match the information that is specified on the Node tab. Ensure that the resources in this list exist.

      Note: MFDaemon and MFDS on the machine must run with the same user credentials. This must not be the SYSTEM user.
    3. Start the enterprise server instance using the cas command.
    4. Also start the MFDAEMON from the command prompt.

Configure the region

Finally, you need to enable your Enterprise Test Server region to work with Data Connect. In order to do this, you need to exclusively specify the following environment variables in the server's Configuration Information section:

  • MFASERV=ON
  • MF_RCCF=KEEPJOB
  • HOST_DISP=ON
  • HOST_NEW=ON

See Mainframe Access Environment Variables and JCL-specific Environment Variables for more information on these variables.

Parent topic: Using Mainframe Access


Using Enterprise Test Server with Containers

This section of the documentation contains information on how you can use Enterprise Test Server with containers so that you can work with your COBOL and PL/I applications in containers.

It contains general information on containers, information for using containers with COBOL applications, and detailed information about the container demonstrations that are supplied with Enterprise Test Server that guide you through all the steps involved in creating containers to work with COBOL and PL/I applications.

Note: A separate document, Best Practices for Moving Your COBOL Applications to Containers, is available that describes best practices that Micro Focus recommends you adopt when moving an existing COBOL application to run in a containerized environment. See Micro Focus: Best Practices for Moving Your COBOL Applications to Containers for more information.
  • Introduction to Containers
  • Benefits of Using Containers
  • Container Terminology
  • Getting Ready to Use Enterprise Test Server with Containers
  • Key Concepts When Using Containers for COBOL Application Deployment
  • Building Images for COBOL Applications
  • Container Demonstrations
Parent topic: Micro Focus Enterprise Test Server 10.0


Introduction to Containers

Containers provide an open platform for developing, deploying, and running applications. Containerization enables you to create a container that includes your application, any binaries or libraries that your application depends on, and any configuration details. The way which containerized applications operate is shown below.

Containerized applications architecture overview

As can be seen from this diagram, a container includes an application plus any binaries or libraries that the application requires in order for it to run. The container runs under the control of the container engine (such as Docker), which in turn runs on top of the operating system (which can be Windows 10, Windows Server 2016, or Linux depending on the container engine being used). Micro Focus recommends that you always follow your operating system vendor's best practices when working with containers.

Compare the containerized approach shown above with the diagram below that shows similar applications running in virtual machines rather than containers.

Virtual machines architecture overview

Note that a virtual machine includes a guest operating system whereas the corresponding container does not.

Parent topic: Using Enterprise Test Server with Containers
Related reference
http://www.microfocus.com/en-us/docs/links.asp?vc=docker_ovw
http://www.microfocus.com/en-us/docs/links.asp?vc=docker_docs
Related information
Benefits of Using Containers
Container Terminology
Getting Ready to Use Enterprise Test Server with Containers
Containers (Known Issues)


Benefits of Using Containers

Running applications in containers brings a number of benefits:

  • Portability

    Once you have tested your containerized application you can deploy it to any other system where a compatible container engine is running and you can be sure that your application will perform exactly as it did when you tested it.

  • Performance

    Although virtual machines are an alternative to containers, the fact that containers do not contain an operating system (whereas virtual machines do) means that containers have much smaller footprints than virtual machines, are faster to create, and quicker to start.

  • Agility

    The portability and performance benefits offered by containers can help you make your development process more agile and responsive. Enhancing your continuous integration and continuous delivery processes to take advantage of containers and technology such as Enterprise Developer Build Tools for Windows makes it easier for you to deliver the right software at the right time. Enterprise Developer Build Tools for Windows is a component of Enterprise Developer which provides all of the functionality of Enterprise Developer to enable you to compile, build, and test COBOL code but without the overhead of an IDE.

  • Isolation

    A container that contains one of your applications also includes the relevant versions of any supporting software that your application requires. If other containers contain applications that require different versions of the same supporting software, that isn't a problem because the different containers are totally independent of one other.

    This also means that as you move through the various stages of your development lifecycle, you can have total confidence that an image you create during development will perform exactly the same as it moves through testing and potentially to your users.

  • Scalability

    You can quickly create new containers if demand for your applications requires them. When using multiple containers you can take advantage of a range of container management options. See the container engine's documentation for more information on these options.

Note:
  • Although there are a number of advantages to using containers, not all applications are suitable for running in containers. In particular, it is generally accepted that applications with a graphical user interface are not suitable for using with containers. Micro Focus recommends that when evaluating potential use of containers you bear in mind the types of application that you will need to run.
  • Micro Focus recommends that you always follow your operating system vendor's best practices when working with containers.
Parent topic: Using Enterprise Test Server with Containers
Related information
Introduction to Containers
Container Terminology
Getting Ready to Use Enterprise Test Server with Containers


Container Terminology

This topic provides a very brief summary of the key terms you need to be familiar with when working with containers. For more information see The Docker Documentation site.

Container
A run-time instance of an image.

A container is usually completely isolated from the host environment, only able to access host files and ports if it has been configured to do so.

To run an image in a container you use the docker run command.

Container engine
Software that performs tasks such as accepting user requests, pulling images, and running containers.
Docker
A collection of products for creating and working with containers on both Linux and Windows.
Docker Hub
A cloud-based registry for working with Docker containers.

A key use for Docker Hub is hosting images, but it is also used for activities such as user authentication and the automation of image building. Anyone is free to publish images to Docker Hub. No checking or verification is carried out on individuals or organizations who submit images to Docker Hub.

Docker Store
A cloud-based resource that is similar to Docker Hub, but the images on Docker Store have been submitted by commercial entities who have been approved or certified by Docker.
Dockerfile
A text document containing the commands to build an image.

The commands you can specify in a Dockerfile range from the complex (such as specifying an existing image to use as a base) to the simple (such as copying files from one directory to another). For example, you can create a Dockerfile that uses the Ubuntu image as a base, but also installs the Apache web server, your application, and any required configuration options.

To build an image from a Dockerfile you use the docker build command.

Image
A standalone, executable package that be run in a container.

An image is a binary that includes all of the requirements for running a single container, as well as metadata describing its needs and capabilities.

An image includes everything that is needed to run an application, including the application's executable code, any software on which the application depends, and any required configuration settings. You can build your own images (using a Dockerfile) or use images that have been built by others and then made available in a registry.

To build an image from a Dockerfile you use the docker build command.

To run an image in a container you use the docker run command.

Image format
The defined structure used by a container engine. Many major tools and container engines use an image format defined by the Open Container Initiative (OCI). Prior to this, however, different container engines used their own formats, reducing the portability of containers.
Open Container Initiative (OCI)
A Linux Foundation project to develop open standards and specifications for container solutions. Examples of tools for working with OCI containers are podman, buildah, and skopeo.
Registry
A service that stores and provides access to images.
Parent topic: Using Enterprise Test Server with Containers
Related reference
http://www.microfocus.com/en-us/docs/links.asp?vc=docker_docs
Related information
Introduction to Containers
Benefits of Using Containers
Getting Ready to Use Enterprise Test Server with Containers


Getting Ready to Use Enterprise Test Server with Containers

This section presents information to help you install the relevant software so that you can use containers with Enterprise Test Server. Before installing any third-party software mentioned in this section, see Containers Known Issues and Restrictions for information that might be relevant to your use of containers.

Micro Focus recommends that you always follow your operating system vendor's best practices when working with containers.

  • Installing Docker on Windows
Parent topic: Using Enterprise Test Server with Containers
Related information
Introduction to Containers
Benefits of Using Containers
Container Terminology
Containers (Known Issues)


Installing Docker on Windows

There are two editions of the Docker engine - the Enterprise Edition (EE) and the Community Edition (CE).

Docker Desktop for Windows, which is designed to be used on Windows 10/11 includes the Community Edition (CE). If you do not wish or want to use Docker Desktop for Windows, the "Docker Engine" itself can be installed. Some community-based package installers such as Chocolately provide an easy installation.

If you are using a server-based operating system, then Windows Server 2016/2022 provides a PowerShell package installer that installs the Enterprise Edition (EE) of Docker.

Installing Docker on Windows 10

Full information on installing Docker is contained in the Docker Desktop page on the Docker site.

Note:
  • You must enable Hyper-V in order to use Docker on Windows 10.
  • Once you have installed Docker you need to configure it to use Windows containers (rather than Linux containers, which is the default). To do this, ensure that Docker is running then right-click the Docker icon in your system tray and click Switch to Windows containers.

Installing Docker on Windows Server 2016

To install Docker Enterprise Edition on Windows Server 2016 use the following PowerShell commands:

Install-Module DockerMsftProvider -Force
Install-Package Docker -ProviderName DockerMsftProvider -Force
Parent topic: Getting Ready to Use Enterprise Test Server with Containers
Related reference
http://www.microfocus.com/en-us/docs/links.asp?vc=docker_ce
http://www.microfocus.com/en-us/docs/links.asp?vc=hyperv-windows10
Related information
Containers (Known Issues)


Key Concepts When Using Containers for COBOL Application Deployment

This topic outlines the key concepts you need to be aware of before you start using Enterprise Test Server to deploy your COBOL applications in containers.

  • Create Different Images for Different Deployment Tasks
  • Overview of Creating Images to Use in the Deployment Process
  • Additional Information on Using Containers for COBOL Application Deployment
Parent topic: Using Enterprise Test Server with Containers
Related reference
http://www.microfocus.com/en-us/docs/links.asp?vc=docker_pipeline
Related information
Building Images for COBOL Applications
Building a Base Image Containing Enterprise Test Server
Building an Image Containing an Application to Run Under Enterprise Test Server
Container Demonstrations
The CICS Container Demonstration
The Container Demonstration for the Enterprise Test Server Base Image
Introduction to Containers


Create Different Images for Different Deployment Tasks

A key concept of using containers is the ability to create one image based on another and you should use this technique to build up a collection of images from which you can choose the most appropriate image for the job at hand. The following are examples of this approach:

  • If your applications require a particular version of Java you can add that to your image, ensuring that your applications always have the required files available. You can use a suffix of _java for an image to indicate that it includes Java.
  • Images that are targeted to 32-bit or 64-bit environments. You can include text such as x86 or x64 in the images' names to indicate whether they are for 32-bit or 64-bit environments respectively. For example, the image microfocus/entserver:win_10.0 could have platform-specific images named microfocus/entserver:win_10.0_x86 and microfocus/entserver:win_10.0_x64.
Parent topic: Key Concepts When Using Containers for COBOL Application Deployment


Overview of Creating Images to Use in the Deployment Process

The top-level approach to creating deployment images to work with COBOL applications is as follows:

  1. Create a base image containing Enterprise Test Server.

    As described in Create Different Images for Different Deployment Tasks, you might want to consider creating a small number of base images rather than just one.

  2. Ensure that you have available the executable files that are require to run the application.
  3. Create an application-specific image that uses one of the images created in step 1 as a base, but also contains the executable files for your COBOL applications that you want to run.

    Using this approach, the Dockerfile for the image must contain commands to copy the executable files that are required to run the application from the local machine to the image. Once you have created your application-specific image you can then run it in a container.

Parent topic: Key Concepts When Using Containers for COBOL Application Deployment


Additional Information on Using Containers for COBOL Application Deployment

All of the concepts that are outlined in this section are illustrated in the container demonstrations. These demonstrations are supplied with Enterprise Test Server and illustrate how to build a range of images to perform different tasks, from being used as a base image for running Enterprise Test Server to debugging a sample CICS application. See Container Demonstrations for a list of all of the supplied container demonstrations.

For more information see:

  • Building a Base Image Containing Enterprise Test Server for a description of how to create a base image that includes Enterprise Test Server.
  • Building an Image Containing an Application to Run Under Enterprise Test Server for a description of how to extend the Enterprise Test Server base image with applications of your own to run under Enterprise Test Server.
  • The Container Demonstration for the Enterprise Test Server Base Image for a look at the container demonstration files supplied with Enterprise Test Server that show how to create a base image for Enterprise Developer Build Tools for Windows.
  • The CICS Container Demonstration for a look at how the container demonstration files supplied with Enterprise Test Server extend the Enterprise Developer Build Tools for Windows base image with an application that you can debug, test, or run.
Parent topic: Key Concepts When Using Containers for COBOL Application Deployment
Related information
Container Demonstrations
Building a Base Image Containing Enterprise Test Server
Building an Image Containing an Application to Run Under Enterprise Test Server
The Container Demonstration for the Enterprise Test Server Base Image
The CICS Container Demonstration


Building Images for COBOL Applications

The section Key Concepts When Using Containers with COBOL Applications outlines the different ways in which you can use containers with your COBOL applications and introduces the recommendation of first creating base images for Enterprise Test Server, then using those base images to create additional images that also include your applications.

This section outlines the steps you need to perform when creating these images.

Once you are familiar with the steps described in this section you should look at the container demonstrations supplied with Enterprise Test Server. These demonstrations include all the files that are needed to create example images for use with Enterprise Test Server, and the section Container Demonstrations contains detailed descriptions of the files contained in some of the demonstrations.

After reading this section and Container Demonstrations you should be able to create your own images for use with your COBOL applications.

Note: A separate document, Best Practices for Moving Your COBOL Applications to Containers, is available that describes best practices that Micro Focus recommends you adopt when moving an existing COBOL application to run in a containerized environment. See Micro Focus: Best Practices for Moving Your COBOL Applications to Containers for more information.
  • Building a Base Image Containing Enterprise Test Server
  • Building an Image Containing an Application to Run Under Enterprise Test Server
Parent topic: Using Enterprise Test Server with Containers
Related information
Key Concepts When Using Containers for COBOL Application Deployment
Container Demonstrations


Building a Base Image Containing Enterprise Test Server

This topic outlines the steps that a Dockerfile must carry out to create a base image for Enterprise Test Server.

By far the easiest, and the recommended, way to create a base image for Enterprise Test Server is to use the container demonstration as described in The Container Demonstration for the Enterprise Test Server Base Image. If you do use the container demonstration, you do not need to perform any of the steps described in this topic because the container demonstration does them all for you. The information in this topic is provided if you choose to write your own Dockerfile to create an Enterprise Test Server base image.

Note: A separate document, Best Practices for Moving Your COBOL Applications to Containers, is available that describes best practices that Micro Focus recommends you adopt when moving an existing COBOL application to run in a containerized environment. See Micro Focus: Best Practices for Moving Your COBOL Applications to Containers for more information.

Once you have built your Enterprise Test Server base image you can then build additional images, based on the base image, that include your COBOL applications as well as Enterprise Test Server. For more information on creating those additional images see Building an Image Containing an Application to Run under Enterprise Test Server.

Note: Remember that Enterprise Developer is a development and test environment so not for use in production situations. If you want to run COBOL applications in containers in a production environment you must use containers that contain Enterprise Test Server.
  • Prerequisites
  • Building a base image

Prerequisites

Before building a base image for Enterprise Test Server you need to ensure that you have available the following:

  • The installable executable file for Enterprise Test Server. This is ets_100.exe and is supplied in the container demonstration for the Enterprise Test Server base image.
  • The appropriate license (.xml) file for Enterprise Test Server.

Building a base image

To build a base image that includes Enterprise Test Server your Dockerfile needs to perform the following steps:

  1. Specify a base image to work from. This will typically be microsoft/dotnet-framework.
  2. Define metadata for your image. This will make it easier to establish significant details of the image when you use the docker inspect command.
  3. Define any variables for filenames and folder locations.
    Note: If you will be using this image to run applications under Enterprise Server, you need to set the MFDS_EXTERNAL_ADDR environment variable to specify a resolvable external address string. This is to enable client browsers to resolve the URLs used by ESMAC and other utilities in Enterprise Server Administration.

    The value that you specify for this environment variable is used to replace the internal container address in the URL.

  4. Copy the installable executable file for Enterprise Test Server (ets_100.exe ) from your host machine to a temporary folder in the image's filesystem, then run it to install Enterprise Test Server.

    When running ets_100.exe you need to specify the following parameters:

    /q
    to run the installaton silently; that is non-interactively with no user interface, using defaults for any values that are not specified elsewhere on the command line.
    InstallFolder=installation-location
    to specify the name of the folder into which you want to install Enterprise Test Server. This a folder that you must have created on the image's filesystem.
    /l log-file-name
    to create a log file of the installation.
    accepteula=yes
    to indicate that you accept the terms of the Micro Focus End User License Agreement (EULA).
  5. Check the log file produced by the installation to ensure that the installation was successful.
  6. Perform any required clean-up. This includes tasks such as resetting variables and deleting temporary folders.
  7. Set the working directory to be the folder into which you installed Enterprise Test Server.
Note: Micro Focus recommends that in addition to having a Dockerfile that performs the above steps you have additional Dockerfiles to create platform-specific versions of the Enterprise Test Server base image. These additional Dockerfiles will be very simple, using the Enterprise Test Server base image as their base then running commands to ensure that the correct (32-bit or 64-bit) environment is set up.
Parent topic: Building Images for COBOL Applications
Related information
Building an Image Containing an Application to Run Under Enterprise Test Server
Running the Container Demonstration for the Enterprise Test Server Base Image
The Container Demonstration for the Enterprise Test Server Base Image


Building an Image Containing an Application to Run Under Enterprise Test Server

This topic outlines the steps that a Dockerfile must carry out to create an image that contains a COBOL application that can be run under .

The process defined in this topic is used by the supplied container demonstrations that create images for applications that you can use with . When you need to create an image to contain an application of yours, Micro Focus recommends that you base your Dockerfile on a container demonstration's Dockerfile (rather that write your Dockerfile from scratch) because that Dockerfile already performs the steps described in this topic. For more information on one of those container demonstrations, including information on all the files it contains, see The CICS Container Demonstration.

Note: A separate document, Best Practices for Moving Your COBOL Applications to Containers, is available that describes best practices that Micro Focus recommends you adopt when moving an existing COBOL application to run in a containerized environment. See Micro Focus: Best Practices for Moving Your COBOL Applications to Containers for more information.

Before you follow the steps in this topic you must have built a base image for Enterprise Test Server. For information on creating a base image for Enterprise Test Server see Building a Base Image Containing Enterprise Test Server.

Note: Remember that Enterprise Developer is a development and test environment so not for use in production situations. If you want to run COBOL applications in containers in a production environment you must use containers that contain Enterprise Test Server.

Before building an image containing an application to run under Enterprise Test Server you need to ensure that you have available the following:

  • A base image for Enterprise Test Server. If you have not yet built such an image, see Building a Base Image Containing Enterprise Test Server for information on how to build one.

To build an image that includes an application to run under Enterprise Test Server your Dockerfile needs to perform the following steps:

  1. Specify a base image to work from. This should be an image containing only Enterprise Test Server which was built for 32-bit or 64-bit as required and includes the additional build functionality, typically or .

    See Building a Base Image Containing Enterprise Test Server for more information.

  2. Define metadata for your image. This will make it easier to establish significant details of the image when you use the docker inspect command.
  3. Define any variables for filenames and folder locations.
    Note: If you will be using this image to run applications under Enterprise Server, you need to set the MFDS_EXTERNAL_ADDR environment variable to specify a resolvable external address string. This is to enable client browsers to resolve the URLs used by ESMAC and other utilities in Enterprise Server Administration.

    The value that you specify for this environment variable is used to replace the internal container address in the URL.

  4. Create a folder to hold the application files then copy the application files and the license file (.mflic) for Enterprise Test Server file into it.
  5. Use the MFLicenseAdmin.exe utility to install the license for Enterprise Test Server.
  6. Wait until Micro Focus Directory Server (MFDS) is running, then configure and start any required enterprise server regions. You should consider putting the commands to perform these operations in a separate script. The CICS container demonstration uses a script called DeployAndWait.ps1.
  7. Perform any required clean-up. This includes tasks such as resetting variables and deleting temporary folders.
  8. Specify the name of the executable to run when the image is run.
Note: When starting a container that includes an application to be run under Enterprise Test Server, to be able to manage the container's enterprise servers using Micro Focus Directory Server (MFDS) and Enterprise Server Monitor and Control (ESMAC) from a machine other than the host machine you must specify some additional parameters on the docker run command. The additional parameters are:
  • -p to map the container's port to a port on the host computer
  • -e to specify the MFDS_EXTERNAL_ADDR environment variable, which is used to specify the name of the host computer where the container is running.

For example, when running an image for the CICS container demonstration you should ensure the docker run command contains parameters such as the following:

-p 16001:86/udp -p16001:86/tcp -p 9000-9010:9000-9010 -e MFDS_EXTERNAL_ADDR=host-computer-name
Parent topic: Building Images for COBOL Applications
Related information
Building a Base Image Containing Enterprise Test Server
The CICS Container Demonstration


Container Demonstrations

Enterprise Test Server includes a number of container demonstrations that supplement the information in this documentation and illustrate how to create and work with COBOL applications in containers.

There are different sorts of demonstration:

  • The base image demonstration shows how to build Enterprise Test Server images to work with your COBOL applications. You can use the base image demonstration exactly as it is supplied to create base images that you can subsequently use with your applications, or you can modify it if needed.
  • Example application demonstrations make use of the images created by the base image demonstrations and extend them to show how to build, run and debug images containing example COBOL applications.

This section lists the container demonstrations that are supplied, and for some of the supplied demonstrations provides detailed information such as descriptions of the files that are included.

  • Supplied Container Demonstrations
  • Using the Container Demonstrations
  • The Container Demonstration for the Enterprise Test Server Base Image
  • The CICS Container Demonstration
Parent topic: Using Enterprise Test Server with Containers
Related reference
http://www.microfocus.com/en-us/docs/links.asp?vc=docker_best_practices
Related information
Key Concepts When Using Containers for COBOL Application Deployment
Building Images for COBOL Applications


Supplied Container Demonstrations

This topic lists the different container demonstrations that are supplied with Enterprise Test Server, specifies the folder they are contained in, and provides a brief summary of what they do.

Demonstration | Windows location | Summary
Base Image | EnterpriseTestServer | Creates a base image for Enterprise Test Server and two images configured for use with 32-bit or 64-bit applications.
CICS | Examples\CICS | Creates an image containing a sample CICS application that can be run or debugged.

For detailed information see The Container Demonstration for the Enterprise Test Server Base Image and The CICS Container Demonstration.

Parent topic: Container Demonstrations
Related information
Using the Container Demonstrations
The Container Demonstration for the Enterprise Test Server Base Image
The CICS Container Demonstration


Using the Container Demonstrations

Enterprise Test Server includes a number of container demonstrations that illustrate typical uses of containers with COBOL applications.

These container demonstrations include Dockerfiles and related batch/script files to simplify the process of running them, and this documentation contains descriptions of the files that comprise the container demonstrations. After running the container demonstrations and reading this documentation to help you familiarize yourself with how the demonstrations work you will have all the information you need to enable you to build and use images for use with your own COBOL applications.

The container demonstrations are supplied in the file ent_test_server_dockerfiles_100_windows.zip which is accessible from the same place that you accessed the Enterprise Test Server installation file. Unzip ent_test_server_dockerfiles_100_windows.zip into a folder of your choice to create a series of folders containing the container demonstrations.

Each container demonstration includes the following:

  • A readme.html file that summarizes what it does and explains how to use it.
  • A bld.bat file to run it. Execute bld.bat with no parameters for a summary of the parameters that you can specify. More information on the parameters you can specify is provided in Running the Container Demonstration for the Enterprise Test Server Base Image and Running the CICS Container Demonstration.

See Supplied Container Demonstrations for information on the containers demonstrations that are available.

Parent topic: Container Demonstrations
Related information
The Container Demonstration for the Enterprise Test Server Base Image
The CICS Container Demonstration
Running the Container Demonstration for the Enterprise Test Server Base Image
Creating the Image for and Running the CICS Container Demonstration
Supplied Container Demonstrations


The Container Demonstration for the Enterprise Test Server Base Image

This section of the documentation introduces the container demonstration for the Enterprise Test Server base image, shows how to run it, and summarizes the files it includes.

  • Introduction to the Container Demonstration for the Enterprise Test Server Base Image
  • Running the Container Demonstration for the Enterprise Test Server Base Image
  • Files in the Container Demonstration for the Enterprise Test Server Base Image
Parent topic: Container Demonstrations
Related information
Supplied Container Demonstrations
Using the Container Demonstrations
The CICS Container Demonstration
Building a Base Image Containing Enterprise Test Server


Introduction to the Container Demonstration for the Enterprise Test Server Base Image

The container demonstration for the Enterprise Test Server base image contains all the files that you need to build an image containing Enterprise Test Server. Once you have built this you can use it as the base image from which you can build images to contain your applications to use with Enterprise Test Server.

Parent topic: The Container Demonstration for the Enterprise Test Server Base Image
Related information
Running the Container Demonstration for the Enterprise Test Server Base Image
Files in the Container Demonstration for the Enterprise Test Server Base Image


Running the Container Demonstration for the Enterprise Test Server Base Image

The container demonstration to create the Enterprise Test Server base image includes a batch file (bld.bat) to make the process of running the demonstration as easy as possible. This topic lists and describes the parameters that you can specify when running bld.bat.

Note: The product installers for the ... for docker products, such as Visual COBOL Development Hub for Docker, are supplied as a .tar file. For example devhub_dockerfiles_8.0_platform.tar for the base release, and devhub_dockerfiles_8.0_platform_patchupdate01.tar for the patch update installer. (The patch update installers provide the basic product images, but do not include the Hello World or other container examples; these are only provided with the base release.)

To obtain the bld.sh installation script, installable executable, and other files mentioned below, extract the provided .tar file into an empty directory on the container host machine. The files for the base release will be in a DevHub directory within the .tar file; the files for a patch update will be in the main directory extracted from the .tar file.

When using bld.bat to create a base image for Enterprise Test Server you need to ensure that the relevant installation files and licenses are available in the same folder as bld.bat. These are:
  • The installable executable file for Enterprise Test Server. This is ets_100.exe and is supplied in the container demonstration for the Enterprise Test Server base image.
  • The appropriate license (.xml) file for Enterprise Test Server.

The command to execute the batch file to run the container demonstration for the Enterprise Test Server base image is as follows:

bld.bat { IacceptEULA [options] }

options enables you to specify a number of characteristics for the image, such as any odbc or java requirements, or auto-login credentials. For a full list of available options and their definitions, run ./bld.sh without specifying any other parameters.

Parent topic: The Container Demonstration for the Enterprise Test Server Base Image
Related information
Introduction to the Container Demonstration for the Enterprise Test Server Base Image
Files in the Container Demonstration for the Enterprise Test Server Base Image


Files in the Container Demonstration for the Enterprise Test Server Base Image

The files contained in the container demonstration for the Enterprise Test Server base image are as follows:

bld.bat | Batch file to automate the process of building Enterprise Test Server images. For full details on the parameters you can specify to bld.bat see Running the Container Demonstration for the Enterprise Test Server Base Image.
bld.env | Configuration file defining various environment variables that are used while building the images. The environment variables define details such as the names of installable files and strings to be used for different parts of the image names.
bld_hotfix_env.bat | Batch file called by bld.bat to include a Patch Update when building the base image for Enterprise Test Server.
bld_image_info.bat | Batch file called by bld.bat to display information about the version of Enterprise Test Server included in an image.
convsetx.ps1 | PowerShell script file used by Dockerfile.x86 and Dockerfile.x64 to configure the COBOL environment to make it specific to 32-bit or 64-bit applications.
Dockerfile | Dockerfile used to build the base microfocus/enttstserver:win_100 image. For a detailed look at the commands used in this file, see Dockerfiles in the Container Demonstration for the Enterprise Test Server Base Image.
Dockerfile.x64 | Dockerfile used to build the microfocus/enttstserver:win_100_x64 image based on the microfocus/enttstserver:win_100 image. This is a very simple Dockerfile that uses the convsetx.ps1 PowerShell script file to customize the COBOL environment for use with 64-bit applications.
Dockerfile.x86 | Similar to Dockerfile.x64 but builds the microfocus/enttstserver:win_100_x86 image for use with 32-bit COBOL applications.
ets_100.exe | The installable executable file for Enterprise Test Server.
palic.env | Configuration file used to specify the name of the license (.mflic or .xml) file for Enterprise Test Server.
prodver.env | Configuration file containing a setting that specifies the version of Enterprise Test Server that this container demonstration is supplied with.
README*.* | Files for HTML and plain text documents containing instructions on how to build the Enterprise Test Server base images.
Parent topic: The Container Demonstration for the Enterprise Test Server Base Image
Related information
Introduction to the Container Demonstration for the Enterprise Test Server Base Image
Running the Container Demonstration for the Enterprise Test Server Base Image


The CICS Container Demonstration

This section of the documentation introduces the CICS container demonstration, shows how to run it, and describes the files it includes.

  • Introduction to the CICS Container Demonstration
  • Creating the Image for and Running the CICS Container Demonstration
  • Files in the CICS Container Demonstration
Parent topic: Container Demonstrations
Related information
Supplied Container Demonstrations
Using the Container Demonstrations
The Container Demonstration for the Enterprise Test Server Base Image


Introduction to the CICS Container Demonstration

The CICS container demonstration for Enterprise Test Server builds on the Enterprise Test Server base image and adds the source files for a sample CICS application to illustrate how you can work with your COBOL applications in containers.

Parent topic: The CICS Container Demonstration
Related information
Creating the Image for and Running the CICS Container Demonstration
Files in the CICS Container Demonstration


Creating the Image for and Running the CICS Container Demonstration

Creating the image

On Windows, the CICS container demonstration includes a batch file (bld.bat) to make the process of creating the image for the demonstration as easy as possible. This topic lists and describes the parameters that you can specify when running bld.bat.

The command to execute the batch file to create the CICS containers image is as follows:

bld.bat IacceptEULA { {dn|x64|x86} [debug]  |
          package               |
          rmi }
bld.bat IacceptEULA [hotfix hotfix.exe] [verbose] [usemcr]
        [dotnetver a.b.c] [java^|openjdk] [javaversion nn]
        [showverinfo] [memlimit nnG] [nomemlimit] [installloc]

The parameters to use with bld.bat and are:

installloc
If not specified, the default path is used.
debug
Indicates that you want to debug the CICS application rather than simply execute it. Specifying debug causes Dockerfile.debug to be run rather than Dockerfile.
dn
Indicates that you want to run the CICS application in a .NET environment.
package
Indicates that you want to rebuild the COBOL application. Specifying package runs a series of MSBuild commands and Powershell scripts to recreate the CICS application.
x64
Indicates that the resulting created image is a 64-bit one.
x86
Indicates that the resulting created image is a 32-bit one.
rmi
Indicates that you want to remove any previously-created CICS container demonstration images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove any CICS container demonstration images.
IacceptEULA
Indicates that you accept the Micro Focus End User License Agreement (EULA). If you do not specify IacceptEULA, no image is created.
dryrun
Indicates that you do not want bld.sh to run any Docker commands. Use dryrun with the verbose parameter to display the Docker commands without running them.
esadminuser=admin-id
Specifies the ID to be used for the Enterprise Server admin user.
esadmgid=admin-gid
Specifies the group ID to use for the Enterprise Server admin user.
esadmuid=admin-uid
Specifies the user ID to use for the Enterprise Server admin user.
hotfix=tar-file-name
This option is only for installing a Patch Update version. Specify the name of the installable executable .tar file as mentioned above, without the extension. For example: hotfix=setup_visualcobol_devhub_for_docker_9.0_patchupdate03_312109_ platform_x64.
java
Indicates that you want the image to include Java support provided by Adoptium's OpenJDK. Use the javaversion parameter to specify the version of Java that you want support for.
javaversion=java-version
When specified in conjunction the java parameter, java-version can be 8, 10-18.
login
Indicates that you want to create a login image. Using this option results in image that you can use to log in to (using any details specified by the logingid, loginid, logingname and loginname parameters). Once logged in to this image you can execute shell or Enterprise Server commands.

This option is useful if you are not adding any application files to a base image but want to be able to use Enterprise Server commands from it.

When you specify login the tag of the image created is suffixed with "_login".

logingid=login-gid
Specifies the group ID to use for the user specified by the loginid parameter.
loginid=login-id
Specifies the user ID to use for the login image.
logingname=login-gname
Specifies the group name to use for the user specified by the loginid parameter.
loginname=login-name
Specifies the user name to use for the user specified by the loginid parameter.
nojava
Indicates that you do not want Java to be installed in the base image. You might want to use this parameter if your system already includes a number of different versions of Java and you don't want to introduce another version unnecessarily.
nologin
Indicates that you do not want to create a login image. You would typically want to use this option when creating an image that contains an application rather than just a base image for Enterprise Server. This is the default.
notools
Indicates that you do not want the image to contain the IP tools (such as ping and netcat) that are included in the image by default. Use this option if you do not need the tools and want to minimize the size of the image.
odbc|odbc-dev
Specifies that the odbc run-time library or the odbc developer tools library is installed. (UNIX/Linux platforms only.)
package
Indicates that you want to rebuild the COBOL application in this image.
settings
Causes the settings that will be used for various properties of the image to be displayed on-screen. Properties that are displayed include the names of the installable file and the license file for Enterprise Server, the details to be used for the Enterprise Server admin user, and the details to be used for the login image. Specifying settings does not cause an image to be created.
verbose
Causes Docker commands to be displayed on-screen as they are executed.

Build the application code

  1. Navigate to this example folder in the command window.
  2. To build the application code, enter:
    bld x64

Running the demonstration

You can run the image created by the CICS container demonstration with the docker run command. To manage the container's enterprise servers, you use the ESCWA interface.

To run the x86 acctdemo image:

docker run -p 16002:10086 -p 9040-9060:9040-9060 -p 9000-9010:9000-9010 -ti --network="nat" --rm microfocus/edbuildtools-acctdemo:win_8.0_x86

To run the x64 acctdemo image:

docker run -p 16002:10086 -p 9040-9060:9040-9060 -p 9000-9010:9000-9010 -ti --network="nat" --rm microfocus/edbuildtools-acctdemo:win_8.0_x64

To use the image:

  1. Locate the ip address of the container, this can be done using the following:
    docker inspect -f "{{ .NetworkSettings.Networks.nat.IPAddress}}" <container id>

    Where <container id> is the long number assigned to each container upon run. You can abbreviate it by entering just the first 4-5 characters of it.

  2. Set the ip address from the above and port 9004 (9040 for the x64 image) into the port in your terminal emulator.
  3. Connect to the port in your terminal emulator, and run ACCT transaction.
  4. From the host machine, you can also submit the provided JCL in ESCWA and check its output from the SPOOL page.
    To access ESCWA from a browser, load the following URL: http://localhost:16002, where the port parameter was specified when you ran the image:
    -p 16002:10086
Parent topic: The CICS Container Demonstration
Related information
Introduction to the CICS Container Demonstration
Files in the CICS Container Demonstration


Files in the CICS Container Demonstration

The files contained in the CICS container demonstration are as follows:

MSS folder | Folder containing source files for the CICS application.
bld.bat | Batch file to automate the process of building CICS container demonstration images. For full details on the parameters you can specify to bld.bat see Creating the Image for and Running the CICS Container Demonstration.
bld.env | Configuration file defining various environment variables that are used while building the images. The environment variables define details such as the names of installable files and strings to be used for different parts of the image names.
Dockerfile | Dockerfile used to build the CICS container demonstration image.
MSS.zip | .zip file containing source files for the CICS application.
MSS32_export.zip | .zip file containing Micro Focus Directory Server (MFDS) resource definitions for the CICS application for use in 32-bit environments.
MSS64_export.zip | .zip file containing MFDS resource definitions for the CICS application for use in 64-bit environments.
README*.* | Files for HTML and plain text documents containing instructions on how to build the CICS container demonstration images.
zipbld.ps1 | PowerShell script to recreate MSS.zip to contain the source files for the CICS application.
Parent topic: The CICS Container Demonstration
Related information
Introduction to the CICS Container Demonstration
Files in the Container Demonstration for the Enterprise Test Server Base Image
Creating the Image for and Running the CICS Container Demonstration


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
  • run Command
  • cobjrun Command
  • run Command Examples
Parent topic: Micro Focus Enterprise Test Server 10.0


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. Alternatively, to run the program from its current directory, use the ./program-name syntax.
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 Command

Restriction: This command is supported for native COBOL only.

To run dynamically loadable programs (that is, .int or .gnt files) use the following command:

run [(switch-params)] program-name [program-params]

where:

switch-params
One or more programmable and run-time switches that control events in a program at run time. On Windows platforms, enclose all switches in parentheses. Your application supplier will tell you which switches to specify.
program-name
The name of a dynamically loadable program.
program-params
One or more 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


cobjrun Command

The command to invoke the Java/COBOL application launcher in order to run Java bytecode. It can take one of two formats:

cobjrun [options] class [arguments]
cobjrun -jar [options] jarfile [arguments]

where the parameters are:

options
The options you would normally specify to your Java application launcher.
class
The name of the class to be invoked. If the Java/COBOL application launcher cannot find a Java class of this name, it tries to find a COBOL program of the same name. If a COBOL program is found, it is executed.
arguments
The arguments to pass to the main function.
-jar
Specifies that a program from a JAR file is to be executed.
jarfile
The name of the Java archive (.jar) file to be invoked.
Tip: You can also specify an arguments file (@<name-of-args-file>); for syntax usage within the file, see the Oracle documentation for more details of a Java command-line arguments file.
Important:
  • The Java/COBOL application launcher loads a specified class, and invokes the class's main method, where the method declaration must be in one of the following formats.
    If the class is a Java class:
    public static void main(String args[])
    If the class is a COBOL class:
    method-id main static.

procedure division using by value args as string occurs any.
  • If the Java application is contained in a .jar file, you need to add it to the classpath by using the -classpath (or -cp) option and specifying the fully qualified class-name
  • If you specify a .jar file that contains a manifest including a Main-Class attribute, you can use the -jar option to execute the application
  • When using cobjrun in a 64-bit AIX environment, you must specify the locations of shared libraries using the LIBPATH environment variable, for example
    export LIBPATH=/usr/java6_64/jre/lib/ppc64/j9vm:/usr/java6_64/jre/lib/ppc64:/usr/java6_64/jre/../lib/ppc64:
  • If you receive an Could not load JVM... error, check your environment settings, and also ensure your effective working mode (COBMODE) matches the version of Java shared libraries being called.
  • If the effective working mode is not set, you can directly invoke the correct environment by using either cobjrun32 or cobjrun64.
Parent topic: Running an Application from the Command Line


run Command Examples

The following examples illustrate how you could run a program using a number of options from the command line.

To run demo.int with numeric checking turned off:

run (-F) demo.int

To run demo.int in ANSI debug mode whilst disabling the display of trailing spaces:

run (+D+A1) demo.int
Parent topic: Running an Application from the Command Line


Run-time System Configuration

You can configure the COBOL run-time system environment to ensure it behaves appropriately for an application, regardless of the configuration used by other COBOL applications.

Run-time behavior can be controlled using environment variables, a run-time launch configuration file (Windows only), run-time tunables, and run-time switches.

  • Run-time Switches
  • Run-time Tunables
Parent topic: Micro Focus Enterprise Test Server 10.0
Related reference
Run-time Launch Configuration Files


Run-time Switches

You can control the behavior of a program by setting run-time switches. For example, there is a switch to hide trailing spaces in DISPLAY ... UPON CONSOLE statements, and a switch to direct error messages to a log file or the console. Most switches affect specific COBOL features.

Restriction: These switches are supported for native COBOL only.
  • Introduction to Switches
  • Setting Run-time Switches
  • Syntax for Setting Switches
  • List of General Run-time Switches
Parent topic: Run-time System Configuration
Related information
COBSW


Introduction to Switches

A switch is a parameter you pass to the run-time system to control the behavior of your program at run time. These switches fall into two categories:

Run-time switches
Run-time switches are acted on by the run-time system itself. Each consists of an upper-case or lower-case letter. These switches affect optional aspects of the behavior of certain COBOL features at run time.
Programmable switches
COBOL programmable switches are numbered from 0 to 8. Each can be set to "off" or "on" when your application is started. Their state can be read by your application at any time when it is running.

The switches must be defined using a condition name in the Special-Names paragraph. For example:

 special-names.
     switch-0 is job-origin on status is us-office
                            off status is uk-office
  ...
 procedure division.
     evaluate true
      when us-office...
      when uk-office...
  ...
Parent topic: Run-time Switches


Setting Run-time Switches

Restriction: These switches are supported for native COBOL only.

You can specify programmable and general run-time switches using the following methods:

Using environment variables
Use the environment variables COBSW and OOSW (for switches for object-oriented programs) to set or override the switch values when the application is started.
Note: We recommend that for switches affecting file handling, you do not use COBSW, but edit the file handler configuration file (extfh.cfg) instead.

The following command sets the programmable switches 1 and 4 on, and all the others (2, 3, 5-8) are off by default:

set COBSW=+1+4
On the command line
Specify switches on the command line when you start the application. Switch set here take precedence over those in the environment variable (COBSW).

In the following example, the command loads the program myprog with programmable switches 5 and 7 on and switch 2 off, and all the others (0, 1, 3, 4, 6 and 8) are off by default. Note that switch 7 is turned on, since the last setting of it (that is +7) is the one used.

myprog (-2+5-7+7)

or:

run (-2+5-7+7) myprog.gnt
Note: You must enclose the switches in parentheses.
The following command loads the program myprog with switch T on and switch O off:
myprog (+T-O)
Parent topic: Run-time Switches


Syntax for Setting Switches

To set switches on the command line, use the following command:

({ {+|-|/}s }...)

To set switches using COBSW use the following command:

SET COBSW={ {+|-|/}switch }...

where:

{ | } | Choose one of the items either side of the |.
{ }... | You can repeat this item.
switch | Either a programmable switch with a digit in the range 0 through 8, or a run-time switch with an upper-case or lower-case letter. A letter is equivalent to the same letter followed by the digit 0. For example B, B0, b, b0 all refer to the same switch.
+ | Sets the switch on.
- | Sets the switch off.

Notes

  • Switches can be separated by spaces (but this is not required); however, there must not be a space between the sign ("+" or "-") and its associated switch
  • Switches can be specified in any order, but each programmable or alphabetic switch must be preceded by a sign
  • Individual switches can be set more than once, but the last setting of any particular switch is the one accepted by the system
  • Switches remain set when COBOL subprograms are called
  • Switches set on the command line take precedence over those defined in the COBSW environment variable
  • Switches are case sensitive
Parent topic: Run-time Switches


List of General Run-time Switches

  • 0, 1, 2, 3, 4, 5, 6, 7 and 8 run-time switches
    Sets the corresponding COBOL switch when the program is entered.
  • A run-time switch
    Starts the debugger to debug an application which is either invoked using the cobrun command or dynamically loaded by a linked module.
  • A1 run-time switch
    Disables the display of trailing spaces by causing DISPLAY ... UPON CONSOLE statements to strip off any trailing spaces in the data item being displayed before outputting the data to the screen.
  • B, B1 run-time switches
    Causes the record pointer to be updated past any locked record encountered when using the READ NEXT statement.
  • C4 run-time switch
    Forces the screen in 43-line mode on an EGA or VGA monitor, or with the COBOL Text Window.
  • C5 run-time switch
    Forces the screen in 50-line mode on an EGA or VGA monitor, or with the COBOL Text Window.
  • D run-time switch
    Invokes the standard ANSI COBOL Debug module.
  • d run-time switch
    Specifies the amount of memory in bytes to be used for the run-time system dynamic paging buffers.
  • E run-time switch
    Enables the execution of intermediate code which contains S-level syntax-check errors.
  • F run-time switch
    Checks all numeric items for valid numeric data.
  • I2 run-time switch
    Redirects run-time system errors to STDERR.
  • K4 run-time switch
    Causes run-time system error messages to stay on the screen until a key is pressed.
  • L2 run-time switch
    Determines the character(s) to be used as the record terminator when reading a line sequential file.
  • N run-time switch
    Enables null insertion for all line sequential files in your program.
  • S5 run-time switch
    Enables redirectable console I/O.
  • T run-time switch
    Enables insertion of tab characters in all line sequential files.
  • List of Run-time Switches for OO Programs
  • Key to Run-time Switches
Parent topic: Run-time Switches


0, 1, 2, 3, 4, 5, 6, 7 and 8 run-time switches

Sets the corresponding COBOL switch when the program is entered.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | All off
Type: | General

Comments:

These switches enable the COBOL switches 0-8 that you defined in the Special-Names paragraph of your program. You can specify these switches in any order, but each individual switch must be preceded by a sign.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


A run-time switch

Starts the debugger to debug an application which is either invoked using the cobrun command or dynamically loaded by a linked module.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

If you want to debug an application created by the cob command directly, you can use the anim command. If you use anim there is no need to set this switch.

If this switch is on, the debugger checks the DISPLAY environment variable. If DISPLAY is set, it attempts to open a new X window at the location specified in the DISPLAY environment variable; otherwise it uses the current terminal.

Parent topic: List of General Run-time Switches


A1 run-time switch

Disables the display of trailing spaces by causing DISPLAY ... UPON CONSOLE statements to strip off any trailing spaces in the data item being displayed before outputting the data to the screen.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This switch provides compatibility with earlier COBOL systems from Micro Focus. When this switch is off, the trailing spaces are included in the display, as required by the ANSI COBOL Standard.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


B, B1 run-time switches

Causes the record pointer to be updated past any locked record encountered when using the READ NEXT statement.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | File handling

Comments:

Set the B switch for indexed sequential files open INPUT or I-O. Set the B1 switch for indexed sequential files open INPUT. Setting either of these switches permits a file to be sequentially read, even if another process has records locked in that file.

A file status of "locked record" is returned when a locked record is read when the B switch is set; a file status of "00" is returned when a locked record is read when the B1 switch is set.

Note: This switch also affects relative and record sequential files when your program is compiled with the CALLFH directive set.
Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


C4 run-time switch

Forces the screen in 43-line mode on an EGA or VGA monitor, or with the COBOL Text Window.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

The original screen mode is restored upon return to the operating system.

Setting this switch causes the components to start in 43-line mode.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


C5 run-time switch

Forces the screen in 50-line mode on an EGA or VGA monitor, or with the COBOL Text Window.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

The original screen mode is restored upon return to the operating system.

Setting this switch causes the components to start in 50-line mode.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


D run-time switch

Invokes the standard ANSI COBOL Debug module.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This switch must be set on the command line.

Example:

The following command loads the program Myprog with the standard ANSI COBOL Debug module invoked:

myprog (+D)
Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


d run-time switch

Specifies the amount of memory in bytes to be used for the run-time system dynamic paging buffers.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | -d245760 (240 K)
Type: | General

Comments:

Dynamic paging is used by programs such as the Compiler. By increasing the amount of memory you might be able to improve the performance of such programs. Once the amount of memory allocated for dynamic paging is exceeded, the run-time system pages any further requirements onto disk.

For example, when compiling a large COBOL program, the amount of memory for dynamic paging buffers might be exceeded due to the Compiler requiring a large amount of dictionary to store the symbol table it creates. When the dynamic paging buffer space is exhausted, the run-time system starts to page dynamic accesses to disk, which might have a performance overhead. By raising the amount of memory for dynamic buffering, paging to disk can be avoided (or at least reduced) and therefore better Compiler performance achieved.

Example:

To double the amount of memory (to 500k) the run-time system could use before paging to disk, you would set the COBSW environment variable as follows:

COBSW=-d500000
Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


E run-time switch

Enables the execution of intermediate code which contains S-level syntax-check errors.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

If you try to run intermediate code programs which contain S-level Compiler errors when this switch is set to off, you receive a run-time system error.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


F run-time switch

Checks all numeric items for valid numeric data.

Properties:

Default: | On
Type: | General

Comments:

If the data is not valid, run-time system error 163 ("Illegal character in numeric field") is produced. Setting this switch to off suppresses this checking.

This checking is only done on generated code created with the CHECKNUM Compiler directive, and on intermediate code.

The run-time system and generated code try to optimize many types of numeric operations. These operations can cause invalid results if the numeric operands do not contain valid numeric data. By default, the run-time system gives the run-time system error 163 when a numeric operation is tried with invalid numeric data.

Invalid data is handled differently by intermediate and native code. We recommend that you enable numeric field checking while you are developing your program.

If you receive run-time error 163, we recommend that you adjust your code so that no invalid data is used. You can locate the invalid numeric data in your code by setting the +F switch on and then animating your program until run-time system error 163 is detected.

If you are not able to correct your code, you might want to use one or more of the following Compiler directives to resolve invalid data in numeric fields:

  • HOSTNUMCOMPARE - controls the operation of comparisons between integer numeric data items of USAGE DISPLAY and alphanumeric literals or figurative constants.
  • HOSTNUMMOVE - causes the Compiler to switch off checking for illegal characters in numeric fields during the execution of certain MOVE statements. (Use with care.)
  • SIGN-FIXUP - provides limited emulation of mainframe compiler options NUMPROC(NOPFD) and NUMPROC(PFD) for MOVE and COMPARE statements if you also set HOSTNUMCOMPARE or HOSTNUMMOVE.
  • SPZERO - causes space characters in numeric data items of USAGE DISPLAY to be treated as zeros. Note that this directive is deprecated (in favor of SIGN-FIXUP).
Note: It is recommended to use both HOSTNUMMOVE or HOSTNUMCOMPARE with CHARSET(EBCDIC) to give maximum compatibility with IBM mainframe behavior. If CHARSET(ASCII) is used, then some compatibility may be lost due to character encoding differences.

Example:

working-storage section.
    01 item-a       pic 9.
procedure division.
    If item-a =  0.
        Display "zero"
    else
        display "nonzero"
    end-if.

The variable item-a is not initialized by a VALUE clause, and so contains a space character x"20". Running this program with the F switch set on causes the run-time system to check whether the numeric field contains a non-numeric value resulting in run-time error 163.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


I2 run-time switch

Redirects run-time system errors to STDERR.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | On
Type: | General

Comments:

The I2 switch is enabled only when used in conjunction with the +S5 switch.

If set off, run-time system error messages are sent to STDOUT (standard output). If set on, the error messages are sent to STDERR (standard error).

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


K4 run-time switch

Causes run-time system error messages to stay on the screen until a key is pressed.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This is useful in batch runs where you want to know if any program terminates with a run-time system error message, or in a system that displays menus, where run-time system error messages can sometimes be quickly overwritten.

Parent topic: List of General Run-time Switches


L2 run-time switch

Determines the character(s) to be used as the record terminator when reading a line sequential file.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | File handling

Comments:

When off (-L2), x"0A" is taken as the record terminator.

When on (+L2), x"0D0A" is taken as the record terminator. This provides compatibility with earlier versions of this system, correctly reading files written using a WRITE ... AFTER ADVANCING statement.

This switch only affects read operations and not write operations.

Use of the +L2 switch is in many respects unnecessary for the majority of applications. The File Handler is able to recognize line sequential delimiters for data files created, irrespective of the platform on which the files are processed. Using this method to change the delimiters will not result in the user record area ever containing x'0D' characters (unless escaped using the INSERTNULL option) because these are discarded as noise characters by the File Handler. This is in contrast to OCDS behavior.

Parent topic: List of General Run-time Switches
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


N run-time switch

Enables null insertion for all line sequential files in your program.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | On
Type: | File handling

Comments:

This switch is especially useful if the format of your files is incompatible with this COBOL system.

Setting this switch to on means that when a program writes records to a line sequential file with a record containing control characters (that is, all characters with ASCII codes less than or equal to x"1F"), the system adds a null character (x"00") before each control character. Similarly, on reading a record from a line sequential file, these null characters are stripped from the control characters.

Setting this switch affects only the physical storage of data in a line sequential file. Records written with one setting and read back with the same setting are returned in exactly the same way. However, if you try to read a file with one setting which was written with the other setting, the results are unpredictable.

Setting this switch off enables control characters to be written and read in the same way as other characters.

When the N switch is on:

  • Any character is allowed in the data record of a line sequential file.
  • Each record is examined before it is written. All characters whose value is less than or equal to x"1F" are written with a preceding null (x"00") to form two-byte pairs. On output to disk, trailing spaces are removed, and a record terminator of x"0D0A" is appended to terminate the record.
  • The file is read as records, some of which might contain two-byte pairs where the first byte is null. The records are terminated by a record terminator. The leading null of each two-byte pair is removed to give the final data record. Tabs (x"09") that do not form part of a two-byte pair are expanded.

The File Handler configuration option INSERTNULL takes precedence over the N run-time switch:

Note: Control characters depend on the operating system. Their hexadecimal values are always less than x"1F". CR (x"0D"), LF (x"0A"), TAB (x"09"), NUL (x"00"), and EOF (x"1A") are all recognized control characters on Windows.

When the N switch is off:

  • Data records in a line sequential file must contain only ASCII text characters (those with a value greater than x"1F").
  • Trailing spaces are removed on output to disk, and a record terminator of x"0D0A" is appended to terminate the record. Printer control characters might also be written to disk.
  • The file is read as data records with each record terminated by a record terminator. If the data contains either x"0D" or x"0A", results can be unpredictable. Tab characters (x"09") are expanded to spaces; otherwise the data record is returned intact.

Example:

The command:

a:myprog (-n)

loads the program Myprog from drive a:. It also specifies that, in line sequential files, all characters less than or equal to x"1F", except for Tab and the file control characters, are treated as data. Null is not inserted before data characters less than x"1F" on output.

Parent topic: List of General Run-time Switches
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


S5 run-time switch

Enables redirectable console I/O.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | General

Comments:

This function is achieved by the run-time system forcing all ACCEPT FROM/DISPLAY UPON CONSOLE statements to be executed such that I/O to and from the screen and keyboard can be redirected by using the > and < operators on the operating system command line.

Parent topic: List of General Run-time Switches
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview
Run-time Switches for OO Programs
Key to Run-time Switches
I2 run-time switch


T run-time switch

Enables insertion of tab characters in all line sequential files.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | File handling

Comments:

This switch is especially useful if the format of your files is incompatible with this COBOL system.

On output to disk, multiple spaces before a tab stop position are written as one tab character. The T switch does not affect any trailing spaces as these are not part of the line sequential record, and they are removed on output. Tab positions are every 8 character positions (for example, 9, 17, 25) and cannot be changed.

On input, tab characters are always expanded to spaces to the next position, regardless of the setting of the T switch.

With this switch set to off, all spaces in a line sequential file are written to disk as space characters.

Parent topic: List of General Run-time Switches
Related information
List of Run-time Switches for OO Programs
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


List of Run-time Switches for OO Programs

Restriction: These switches are supported for native COBOL only.

To set OO run-time switches, use the environment variable OOSW. For example, the following turns on the f and d switches:

set oosw=+f+d
  • d OO run-time switch
    Enables debugging by preventing reuse of object handles from finalized objects.
  • f OO run-time switch
    Enables you to name the message trace file.
  • g1 OO run-time switch
    Sets a guard page before Object-Storage sections
  • g2 OO run-time switch
    Sets a guard page after Object-Storage sections.
  • l OO run-time switch
    Sets the Class Library to be preloaded by the run-time system.
  • t OO run-time switch
    Generate a trace file showing every message sent by your application.
Parent topic: List of General Run-time Switches


d OO run-time switch

Enables debugging by preventing reuse of object handles from finalized objects.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

In normal operation, each time an object is finalized its object handle is available for reuse by the run-time system and can be assigned when a new object is created. Setting +d prevents the run-time system from reallocating object handles.

Do not use this switch for production applications – the run-time system can eventually run out of memory to allocate new handles.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


f OO run-time switch

Enables you to name the message trace file.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

The format of the switch is:

ftrace.log

where trace.log is the name of the message trace file. The default trace filename is trace.log.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


g1 OO run-time switch

Sets a guard page before Object-Storage sections
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

You can't set +g1+g2.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


g2 OO run-time switch

Sets a guard page after Object-Storage sections.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

You can't set +g1+g2.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


l OO run-time switch

Sets the Class Library to be preloaded by the run-time system.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | On
Type: | OO

Comments:

The format of this switch is:

lclass

where class is the name of the class that you want pre-loaded.

Set this switch off to disable loading of the Class Library. You should do this if you want to debug the class library.

If you have your own class library in a .lbr file, you can load that instead of the Micro Focus Class Library. Set:

+lfilename

where filename is the name of the .dll file.

You can load more than one class library with the +l switch; separate the names with semicolons (;). For example:

+lclass1;class2

Do not leave any spaces between the names.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


t OO run-time switch

Generate a trace file showing every message sent by your application.
Restriction: These switches are supported for native COBOL only.

Properties:

Default: | Off
Type: | OO

Comments:

The trace file is named trace.log by default. You can specify a name for the file with the f switch.

The trace file shows you the messages sent by your application and is useful for debugging. Do not set this switch when running production applications – trace slows down execution, and the log file grows in size continuously while the application runs.

Parent topic: List of Run-time Switches for OO Programs
Related information
Setting Run-time Switches
Run-time Switches
Run-time Configuration Tunables - Overview


Key to Run-time Switches

Restriction: These switches are supported for native COBOL only.

The following information is shown for each switch:

Function:

The function that the switch performs.

Properties:

Default: The default setting of the switch.
Type: Indicates how you set the switch. The type can be:
  • General. Set on the command line or using the environment variable COBSW.
  • OO. Set using the environment variable OOSW.
  • File handling. Set in the file handler configuration file extfh.cfg

Comments:

Additional information about the switch.

Parent topic: List of General Run-time Switches


Run-time Tunables

You can use run-time tunables to control the behavior of a program. Run-time tunables are stored in a run-time configuration file.

  • Run-time Configuration Tunables - Overview
  • Format of a Configuration File for Native COBOL
  • Format of a Configuration File for .NET COBOL
  • List of Run-time Tunables
Parent topic: Run-time System Configuration


Run-time Configuration Tunables - Overview

You normally configure your run-time system using a project's properties in the IDE. However, some run-time behavior cannot be configured using the IDE; this must be configured using run-time tunables, which are stored in a run-time configuration file.

When your run-time system or linked executable starts up, it attempts to read the run-time configuration file. The run-time configuration file specifies values for the run-time tunables.

If a setting specified in the IDE conflicts with a setting in the configuration file, the setting specified in the IDE takes precedence.

If you use the Interface Mapping Toolkit to generate COBOL services for execution in Enterprise Server, you can specify settings for some tunables for the application container, a version of the run-time system used in Enterprise Server. If a setting specified by the Interface Mapping Toolkit conflicts with a setting in the configuration file, the setting specified in the Interface Mapping Toolkit always takes precedence.

The run-time configuration file is shared by all users of the run-time system.

For native COBOL, you create or edit a text-based run-time configuration file with a text editor, and then specify the location and name of the run-time configuration file using the COBCONFIG environment variable. The format of the text file is described in the sections Format of a Configuration File for Native COBOL and List of Run-time Tunables.

Examples

For example, if you want to use a configuration file called myconf.cfg , you set COBCONFIG as follows.

set COBCONFIG=e:\mydir\myconf.cfg

For .NET COBOL, you add a configuration file (such as an application.configuration file or web.configuration file) in Visual Studio. There is no need to use an environment variable to specify its location, because the file is part of the application managed at run-time.

The use of a configuration file is optional - no error is issued if it does not exist.

Parent topic: Run-time Tunables
Related information
COBCONFIG


Format of a Configuration File for Native COBOL

Set run-time tunables and environment variables in the configuration file using the following syntax:

Tunables

The format of each tunable is:
set tunable_name=value
For example:
set cobconfig_error_report=TRUE

Environment Variables

The format of each environment variable is:

setenv variable_name value

For example:

setenv COBSW +2+5+6

The following rules must also be observed:

  • Each run-time tunable or environment variable appears on a new line.
  • Blank lines are ignored.
  • A comment line starts with a # character. The maximum number of characters permitted in a comment line is 80, including any new-line or carriage return characters that might be placed at the end of the line by some editors.
    Tip: As the configuration file is processed at run time, we advise that you limit the number of comments, in order to keep time taken to process the configuration file to a minimum.
  • Each space in the definition can be replaced with tabs or more than one space.
  • For tunables, the value is validated according to the type and values allowed, and the value of the cobconfig_error_report tunable in effect. Where value is numeric, a leading zero indicates that the value should be treated as octal (that is, base 8). For example, 07 (octal) is 7 (decimal), while 010 (octal) is 8 (decimal); however, 08 (octal) and 09 (octal) are invalid octal values. Hexadecimal values can also be set by using numeric values that begin with 0x.
Parent topic: Run-time Tunables
Related reference
cobconfig_error_report


Format of a Configuration File for .NET COBOL

When a required option to configure the run-time behavior is not available in the IDE, use a .config file to set a run-time tunable in your .NET COBOL applications.

In Visual Studio, add the correct .config file for the type of application you are using; for example:
  • Add an application configuration file (exe.config) for a console application.
  • Add a web configuration file (web.config) for an ASP.NET application.
Note: You do not need to configure the COBCONFIG_ environment variable to point to this file, because the file is part of the application managed at run-time.

When you add the configuration to your .NET COBOL application, the Tunables section group is already declared. Add the section details, using the section details in bold below as an example.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <configSections>
  <sectionGroup name="MicroFocus.COBOL.Application">
   <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
   <section name="Environment" type="System.Configuration.NameValueSectionHandler" />
   <sectionGroup name="Interop">
    <section name="PreLoad" type="System.Configuration.NameValueSectionHandler" />
   </sectionGroup>
  </sectionGroup>

  <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></Switches>
 <Environment></Environment>
 <Interop> <PreLoad> </PreLoad> </Interop>
</MicroFocus.COBOL.Application>

 <MicroFocus.COBOL.Runtime>
  <Tunables>
   <add key="printer_redirection" value="true" />
   <add key="printer_defaults" value="size=20;font=Courier New" />
  </Tunables>
  <Switches></Switches>
 </MicroFocus.COBOL.Runtime>
</configuration>
Parent topic: Run-time Tunables


List of Run-time Tunables

  • acu_external_data
    Allows access to the ACUCOBOL-GT-specific external data items from a .NET COBOL application.
  • ansi_input_mode
    Specifies whether the run-time system uses ANSI or OEM character sets when inputting keystrokes from a console or Application Output window.
  • arguments_are_initial
    Affects the COBOL command line arguments returned from the syntax ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE.
  • cobconfig_error_report
    Specifies whether any errors detected during the processing of the configuration file are reported.
  • command_line_accept
    Specifies whether the first ACCEPT or READ from STDIN takes the input from the command line.
  • command_line_arguments_unquoted
    Provides command line argument handling that returns quoted spaces to the application; this is to ensure compatibility with product versions 2.3.2 and earlier.
  • command_line_linkage
    Enables you to call a program and pass the command line to the main program as a parameter to be accessed via the Linkage Section.
  • core_filename
    Specifies the name of the file that is generated when the core_on_error tunable is set to 3.
  • core_on_error
    Specifies in what circumstances a core file is produced.
  • current_day
    Specifies the day of the month required to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
  • current_hour
    Specifies the hour of the day that is to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
  • current_minute
    Specifies the minute of the hour that is to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
  • current_month
    Specifies the month of the year required to be returned when you use the ACCEPT identifier FROM DATE syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.
  • current_second
    Specifies the second of the minute that is to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
  • current_year
    Specifies the year required to be returned when you use the ACCEPT identifier FROM DATE syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.
  • datewarp_dynamic
    Specifies whether the day, month, and year values specified by the current_day, current_month, and current_year tunables return static or "rolling" values.
  • dbcs_text_enable_clip
    Specifies whether the font is clipped to the font height supplied by Microsoft Text APIs rather than overwriting pixels beyond the font height when running in a GUI window (runw).
  • debug_on_error
    Specifies whether to enable just-in-time debugging.
  • debugger_command
    Specifies the command to start the debugger when just-in-time debugging is enabled
  • default_cancel_mode
    Specifies whether logical or physical cancels are used.
  • device_name_detection
    Specifies whether programs can use filenames that are normally reserved for device-names.
  • entry_point_mapper
    Specifies whether entry point mapper support is to be enabled.
  • entry_point_mapper_alias_exists_error
    Specifies whether the Entry Point Mapping facility causes a run-time system error COBRT198 ("Load failure") when a program with the same name as an alias definition is found on disk, or whether the aliasing occurs without loading the program with the same name from disk.
  • entry_point_mapper_disable_auto_aliasing
    Specifies whether the Entry Point Mapping facility should not emulate the alias function of an IBM mainframe linkage editor, which redirects the system to execute a program accessed via an alias name, and instead cause the COBRT173 Called program file not found in drive/directory run-time system error.
  • entry_point_mapper_invalid_path_error
    Specifies whether the Entry Point Mapping facility should cause the COBRT013 File not found run-time system error when the ENTRYNAMEMAP environment variable refers to invalid/non-existent filename and directory paths.
  • entry_point_mapper_search_order
    Specifies whether to use entry point mapping to look for programs before or after searching for the programs on disk.
  • environment_mapper
    Specifies whether the External File Mapper is enabled. The External File Mapper allows you to assign values to environment variables in a file. If the External File Mapper is enabled the system searches for the file mfextmap.dat.
  • error_on_duplicate_entry_point
    Controls whether an RTS 119 error is generated when an attempt is made to load a program containing a duplicate entry-point.
  • filename_escape_char
    Specifies the escape character used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE.
  • filename_quote_char
    Specifies the quotation character used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE.
  • lock_mode
    Selects the locking implementation to be used.
  • mainframe_floating_point
    Specifies whether mainframe floating-point emulation is required.
  • memory_free_check_size
    Specifies the number of freed memory blocks that are to be monitored for subsequent corruption.
  • memory_strategy
    Sets a memory management strategy.
  • mfpm_access_cancelled_data
    Specifies whether the Working-Storage Sections of AMODE programs that have been canceled continue to be addressable.
  • mfpm_external_data31
    Specifies whether external data items are registered with Mainframe Pointer Manager (MFPM) above or below the 16 Mb line.
  • mfpm_logging
    Specifies whether Mainframe Pointer Manager (MFPM) events are to be traced.
  • no_mfredir
    Enables you to reduce the time the run-time system takes to initialize if your project or application does not execute remote programs.
  • os_error_log
    Specifies whether an event is written to the Windows Application Event log whenever run-time system error COBRT199 occurs.
  • printer_defaults
    Sets certain default printer settings when printer redirection has been enabled.
  • printer_raw_redirection
    Redirects WRITE statements through the Windows print spooler as RAW data types.
  • printer_redirection
    Redirects WRITE statements through the Windows print spooler.
  • profile_behavior
    Specifies the behavior of the Profiler with regard to the counting of time spent in called programs.
  • reduce_java_signals
    Specifies the options that are passed to a JVM when mixing Java and COBOL.
  • remote_64bit_access
    Specifies whether 64-bit file access is permitted for unknown remote file systems.
  • screen_cols
    Specifies the initial width of the Application Output window or console.
  • screen_lines
    Specifies the initial height of the Application Output window or console.
  • shared_memory_segment_size
    Specifies the initial size of the shared memory block allocated by the run-time system.
  • signal_regime
    Specifies whether or not the COBOL Run-Time System is to post its own signal handlers.
  • subsystem_cancel_mode
    Specifies whether logical or physical cancels are used for CBL_SUBSYSTEM cancels.
  • timewarp_dynamic
    Specifies whether the hours, minutes, and seconds values specified by the current_hour, current_minute, and current_second tunables return static or "rolling" values.
Parent topic: Run-time Tunables


acu_external_data

Allows access to the ACUCOBOL-GT-specific external data items from a .NET COBOL application.
Restriction: The following tunable is for .NET COBOL only.

Syntax:

>>-----acu-external-data=----.-TRUE-.-------><
                               +-FALSE+

Parameters:

TRUE | Allow access to the ACU external data items supported by the Vision file handler from a .NET COBOL application.
FALSE | Access to ACU external data items is not enabled in a .NET COBOL application.

Properties:

Default: | FALSE
IDE equivalent: |

Comments:

To configure this tunable for .NET COBOL, add a reference to a .config file in Visual Studio. Refer to Format of a Configuration File for .NET COBOL for details of the required syntax.

.

Parent topic: List of Run-time Tunables


ansi_input_mode

Specifies whether the run-time system uses ANSI or OEM character sets when inputting keystrokes from a console or Application Output window.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set ansi_input_mode=----.-TRUE-.---------><
                               +-FALSE+

Parameters:

TRUE | Use the ANSI character set to input keystrokes
FALSE | Use the OEM character set to input keystrokes

Properties:

Default: | FALSE
IDE equivalent: |

Comments:

Using ANSI enables characters such as the Euro symbol, which does not exist in the OEM character set, to be input and displayed.

Parent topic: List of Run-time Tunables


arguments_are_initial

Affects the COBOL command line arguments returned from the syntax ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set arguments_are_initial=-.-TRUE-.-----------><
                                  +-FALSE+

Parameters:

TRUE | The COBOL command line arguments are the same as the initial ones passed to the run-unit by the operating system. When using a trigger, such as run , argument 0 is the trigger name and argument 1 is the name of the main COBOL program.
FALSE | The COBOL command line arguments do not contain any trigger name. Instead, argument 0 is always the name of the main COBOL program. When set to FALSE this tunable gives consistent results no matter how your application is packaged.

Properties:

Default: | FALSE
IDE equivalent: | For service interfaces: > Deployment Server > Enterprise Server Run-time Configuration > Command Line Handling > Return trigger executable name as argument zero

Comments:

See the Language Reference for more details of the ACCEPT ... FROM ARGUMENT-NUMBER and ACCEPT ... FROM ARGUMENT-VALUE syntax.

If you are using a system executable to start your application, argument 0 is always the name of the executable (which, by default, is also the name of the main COBOL program), irrespective of the setting of this tunable.

For example, the command line:

myapp arg1 arg2

always returns myapp as argument 0, whereas the command line:

run myapp arg1 arg2

returns myapp as argument 0 when this tunable is set to FALSE; when the tunable is set to TRUE the trigger name ( run ) is returned as argument 0 and myapp as argument 1.

Parent topic: List of Run-time Tunables


cobconfig_error_report

Specifies whether any errors detected during the processing of the configuration file are reported.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set cobconfig_error_report=----.-TRUE-.----><
                                      +-FALSE+

Parameters:

TRUE | Errors are reported and result in processing of the configuration file being terminated
FALSE | Errors are not reported

Properties:

Default: | TRUE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related information
Format of a Configuration File for Native COBOL


command_line_accept

Specifies whether the first ACCEPT or READ from STDIN takes the input from the command line.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set command_line_accept=---.-TRUE-.-------------><
                                  +-FALSE+

Parameters:

TRUE | The first ACCEPT or READ from STDIN takes the input from the command line.
FALSE | The first ACCEPT or READ from STDIN takes the input from the user. This provides direct ANSI conformance.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related reference
command_line_linkage


command_line_arguments_unquoted

Provides command line argument handling that returns quoted spaces to the application; this is to ensure compatibility with product versions 2.3.2 and earlier.
Restriction: This tunable is supported for .NET COBOL only.

Syntax:

>>-----set command_line_arguments_unquoted=-.-TRUE-.-----------><
                                            +-FALSE+

Parameters:

TRUE | When a command line argument contains spaces and is enclosed in quotation marks, the argument is returned to the application unquoted.
FALSE | When a command line argument contains spaces and is enclosed in quotation marks, the argument is returned to the application within quotation marks.

Properties:

Default: | FALSE
IDE equivalent: | None

Example

Assuming that myprog is an application that displays the arguments it accepts from the command line, the following shows the results with and without this tunable being in effect:

myprog "A B"
A B   *> returned when command_line_arguments_unquoted=TRUE
"A B" *> returned when command_line_arguments_unquoted=FALSE
Parent topic: List of Run-time Tunables


command_line_linkage

Enables you to call a program and pass the command line to the main program as a parameter to be accessed via the Linkage Section.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set command_line_linkage=---.-TRUE--.------><
                                   +-FALSE-+

Parameters:

TRUE | The command line can be accessed via the Linkage Section
FALSE | The command line cannot be accessed via the Linkage Section

Properties:

Default: | FALSE
IDE equivalent: |

Example:

When using this tunable, the command line will be passed to the main program using the following parameter structure:

Linkage section.
01 CommandLinePass.
  03 CommandLineLen   pic 9(4) comp.
  03 CommandLine      pic x(256).

CommandLineLen contains the length of the parameters being passed and CommandLine contains the actual arguments being passed.

Comments:

This run-time tunable is provided for backward compatibility only. It works only with linked executables.

There is also an equivalent Compiler directive that provides this functionality (COMMAND-LINE-LINKAGE). If both the tunable and the directive are set, the setting for the directive take precedence.

Parent topic: List of Run-time Tunables
Related reference
command_line_accept


core_filename

Specifies the name of the file that is generated when the core_on_error tunable is set to 3.
Restriction: The following applies to native code only.

Syntax:

>>-----set core_filename=---"path&filename"-----------><

Parameters:

path&filename The path and name of the file that will be produced when a core file is generated if you set the core_on_error tunable to the value 3. If filename contains a tunable string it is substituted as follows:
%%
Single %
%d
The date of when the program encountered the error, in the format yyyymmdd
%f
The basename of the program that encountered the error
%p
The process ID of the program that has encountered the error
%t
The time of when the program encountered the error, in the format hhmmss

Properties:

Default: | cblcore in the current working directory.
IDE equivalent: |

Example:

set core_filename="c:/temp/core/core.%p@%t_%d"

Produces a file named core.12345@165920_20080115, on the path c:/temp/core.

Comments:

On Windows platforms, to use the backslash in a path, you must precede it with the escape character, which is also a backslash; for example:

set core_filename="c:\\temp\\core\\core.%p@%t_%d"
Parent topic: List of Run-time Tunables


core_on_error

Specifies in what circumstances a core file is produced.
Restriction: The following applies to native code only.

Syntax:

>>-----set core_on_error=---.-0-.-----------><
                            +-1-+
                            +-2-+
                            +-3-+
                            +-129-+
                            +-130-+
                            +-131-+

Parameters:

0 | The run-time system never produces a core file on any exception or run-time system error. This is the default behavior of the run-time system.
1 | The run-time system produces a core file when any exception is received that would normally produce a core file on the host system; for example, a run-time system error COBRT114, and so on.
2 | The run-time system produces a core file when any run-time system error occurs. After writing out the core file the process terminates immediately.
3 | The run-time system produces a snap shot core file when any run-time system error occurs. After writing out the core file the process continues as normal; for example, to display an RTS error message.
129 | Same as core_on_error=1, except no message box is displayed after the core file is created.
130 | Same as core_on_error=2, except no message box is displayed after the core file is created.
131 | Same as core_on_error=3, except no message box is displayed after the core file is created.

Properties:

Default: | 0
IDE equivalent: |

Comments:

  • You can debug core files to determine the cause of the problem if you have the appropriate dictionary (.idy) files. When a core file is produced, using core_on_error=1 or core_on_error=2, the run-time system itself cannot clean up COBOL file buffers or free system resources. This could lead to data file corruption that might not have occurred if no core file was produced.
  • On Windows, if debug_on_error is also set, the setting of core_on_error is ignored.
Parent topic: List of Run-time Tunables
Related reference
debug_on_error
signal_regime


current_day

Specifies the day of the month required to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set current_day=---integer------><

Parameters:

integer A value in the range 1 through 31, representing the required day of the month. The value you specify is returned when you use the ACCEPT identifier FROM DATE syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.

Properties:

Default: | The current day specified by the system clock.
IDE equivalent: |

Comments:

If the datewarp_dynamic tunable is set to TRUE, the day value specified is treated as the day the clock is started, and changes each time the system clock passes midnight.

Parent topic: List of Run-time Tunables


current_hour

Specifies the hour of the day that is to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set current_hour=---integer-------------><

Parameters:

integer A value from 0 - 23 indicating the required hour of the day. The value you specify is returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions. It is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.

Properties:

Default: | The current hour as returned by the system clock.
IDE equivalent: |

Comments:

If the timewarp_dynamic tunable is set to TRUE, the hour value specified is treated as the hour at which the clock is started, and will change every 60 minutes.

Parent topic: List of Run-time Tunables


current_minute

Specifies the minute of the hour that is to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set current_minute=---integer-------------><

Parameters:

integer A value from 0 - 59 indicating the required minute of the hour. The value you specify is returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions. It is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.

Properties:

Default: | The current minute as returned by the system clock.
IDE equivalent: |

Comments:

If the timewarp_dynamic tunable is set to TRUE, the minute value specified is treated as the minute at which the clock is started, and will change every 60 seconds.

Parent topic: List of Run-time Tunables


current_month

Specifies the month of the year required to be returned when you use the ACCEPT identifier FROM DATE syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set current_month=---integer------><

Parameters:

integer A value in the range 1 through 12, representing the required month of the year. The value you specify is returned when you use the ACCEPT identifier FROM DATE syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.
Note: A leading 0 indicates to the system that the value should be treated as octal. As a result, month values of 08 and 09 generate an error. For the months of September and October, use 8 and 9 rather than 08 and 09.

Properties:

Default: | The current month specified by the system clock.
IDE equivalent: |

Comments:

If the datewarp_dynamic tunable is set to TRUE, the month value specified is treated as the month the clock is started, and changes when the system clock passes midnight on the last day of each month.

Parent topic: List of Run-time Tunables


current_second

Specifies the second of the minute that is to be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE, FORMATTED-CURRENT-DATE intrinsic functions. The specified second is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set current_second=---integer-------------><

Parameters:

integer A value from 0 - 59 indicating the required second of the minute. The value you specify is returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions. It is also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.

Properties:

Default: | The current second as returned by the system clock.
IDE equivalent: |

Comments:

If the timewarp_dynamic tunable is set to TRUE, the second value specified is treated as the second at which the clock is started, and will change as the system clock changes.

Parent topic: List of Run-time Tunables


current_year

Specifies the year required to be returned when you use the ACCEPT identifier FROM DATE syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set current_year=---integer------><

Parameters:

integer A value representing the required year. The value you specify is returned when you use the ACCEPT identifier FROM DATE or ACCEPT identifier FROM DAY syntax, or the CURRENT-DATE and FORMATTED-CURRENT-DATE intrinsic functions.

Properties:

Default: | The current year specified by the system clock.
IDE equivalent: |

Comments:

If the datewarp_dynamic tunable is set to TRUE, the year value specified is treated as the year the clock is started and changes each time midnight passes on December 31st.

Parent topic: List of Run-time Tunables


datewarp_dynamic

Specifies whether the day, month, and year values specified by the current_day, current_month, and current_year tunables return static or "rolling" values.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set datewarp_dynamic=---.-TRUE-.-------------><
                               +-FALSE+

Parameters:

TRUE | The day, month, and year values specified for the current_day, current_month and current_year tunables are treated as the clock start values and will "roll" once they have been set.
FALSE | The day, month, and year values specified for the current_day, current_month, and current_year tunables are static values that will always be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE or FORMATTED-CURRENT-DATE intrinsic functions. The static values are also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables


dbcs_text_enable_clip

Specifies whether the font is clipped to the font height supplied by Microsoft Text APIs rather than overwriting pixels beyond the font height when running in a GUI window (runw).
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set dbcs_text_enable_clip=---.-TRUE--.------><
                                    +-FALSE-+

Parameters:

TRUE | Ensures that the font is clipped to the font height supplied by Microsoft Text APIs
FALSE | Pixels can be overwritten beyond the font height

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

Some Microsoft DBCS fonts write to a height greater than the font height supplied, consequently could corrupt things such as the use of OVERLINE; therefore, enable this tunable to avoid this issue.

Parent topic: List of Run-time Tunables


debug_on_error

Specifies whether to enable just-in-time debugging.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set debug_on_error=---.-0-.-----------><
                             +-1-+

Parameters:

0 | Disables just-in-time debugging.
1 | Enables just-in-time debugging: the Debugger starts if a running program terminates with a run-time system error.

Properties:

Default: | 0
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related reference
core_on_error
signal_regime


debugger_command

Specifies the command to start the debugger when just-in-time debugging is enabled
Restriction: This tunable is supported for native COBOL on UNIX platforms only.

Syntax:

>>-----set debugger_command=--"debugger-.------------.-"--><
                                        + directives-+

Parameters:

debugger | The name of an available debugger, such as cobanim or anim.
directives | Any directives to immediately apply when the debugger runs, each separated by a space. (Directives are optional.)

Properties:

Default: | cobanim
IDE equivalent: | None

Example:

When JIT debugging is initiated, the following example runs the cobanim debugger, with the mixedlangdebug directive in effect.

set debugger_command="cobanim mixedlangdebug"
Parent topic: List of Run-time Tunables


default_cancel_mode

Specifies whether logical or physical cancels are used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set default_cancel_mode---.-0-.-----------><
                                 +-1-+
                                 +-2-+

Parameters:

0 | Physical cancels: any program canceled during run-time will be freed from memory, making more memory available.
1 | Compatibility mode. As Logical cancels mode, except that .dll files or shared objects are physically canceled. This option is present for compatibility with older products.
2 | Logical cancels: any program canceled during run-time will not be freed from memory. The program is available to be reused and hence the performance of CALL/CANCEL statements is greatly increased.

As far as your program is concerned, logical and physical cancels behave identically.

Properties:

Default: | 2
IDE equivalent: |
Parent topic: List of Run-time Tunables


device_name_detection

Specifies whether programs can use filenames that are normally reserved for device-names.
Note: Restriction:

These tunables are supported for native COBOL only.

Syntax:

>>-----set device_name_detection=---.-TRUE-.------><
                                    +-FALSE+

Parameters:

TRUE | The run-time system treats certain predefined names (such as ERR) as device-names.
FALSE | No predefined device-names are used by the run-time system.

Properties:

Default: | TRUE
IDE equivalent: | None

Comments:

When you set device_name_detection=TRUE, the run-time system treats the following as device-names, so they cannot be used as filenames in your programs:

  • :BB
  • :CE
  • :CI
  • :CO
  • :LP
  • AUX
  • COM<n>
  • CON
  • ERR
  • LPT
  • LPT<n>
  • LST
  • NUL
  • PRN
  • PUN
  • RDR
  • STDERR
  • STDIN
  • STDOUT
Parent topic: List of Run-time Tunables


entry_point_mapper

Specifies whether entry point mapper support is to be enabled.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set entry_point_mapper=---.-TRUE-.-------------><
                                 +-FALSE+

Parameters:

TRUE | Enable entry point mapper support.
FALSE | Disable entry point mapper support.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related information
ENTRYNAMEMAP


entry_point_mapper_alias_exists_error

Specifies whether the Entry Point Mapping facility causes a run-time system error COBRT198 ("Load failure") when a program with the same name as an alias definition is found on disk, or whether the aliasing occurs without loading the program with the same name from disk.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set entry_point_mapper_alias_exists_error=---.-TRUE-.-------------><
                                                    +-FALSE+

Parameters:

TRUE | Run-time system error COBRT198 occurs when a program with the same name as an alias definition occurs on disk.
FALSE | Aliasing occurs without loading the program with the same name from disk.

Properties:

Default: | TRUE
IDE equivalent: |

Comments:

This tunable is only relevant if the entry_point_mapper_search_order tunable is set to 1; that is, pre-disk searching is enabled.

Parent topic: List of Run-time Tunables


entry_point_mapper_disable_auto_aliasing

Specifies whether the Entry Point Mapping facility should not emulate the alias function of an IBM mainframe linkage editor, which redirects the system to execute a program accessed via an alias name, and instead cause the COBRT173 Called program file not found in drive/directory run-time system error.

Syntax:

>>---set entry_point_mapper_disable_auto_aliasing=--.-TRUE--.--------><
                                                    +-FALSE-+

Parameters:

TRUE | The Entry Point Mapping facility does not emulate the alias function of an IBM mainframe linkage editor; it produces a run-time system error COBRT173 Called program file not found in drive/directory instead.
FALSE | The Entry Point Mapping facility emulates the alias function of an IBM mainframe linkage editor, which redirects the system to execute a program accessed via an alias name.

Properties:

Default: | TRUE
IDE equivalent: |

Comments:

This tunable is only relevant if the entry_point_mapper tunable is set to true; that is, the Entry Point Mapping facility is enabled.

Parent topic: List of Run-time Tunables


entry_point_mapper_invalid_path_error

Specifies whether the Entry Point Mapping facility should cause the COBRT013 File not found run-time system error when the ENTRYNAMEMAP environment variable refers to invalid/non-existent filename and directory paths.

Syntax:

>>---set entry_point_mapper_invalid_path_error=--.-TRUE--.--------><
                                                    +-FALSE-+

Parameters:

TRUE | The Entry Point Mapping facility produces a run-time system error COBRT013 File not found when the ENTRYNAMEMAP environment variable refers to invalid/non-existent filename and directory paths.
FALSE | The Entry Point Mapping facility does not report an error when the ENTRYNAMEMAP environment variable refers to invalid/non-existent filename and directory paths.

Properties:

Default: | TRUE
IDE equivalent: |

Comments:

This tunable is only relevant if the entry_point_mapper tunable is set to true; that is, the Entry Point Mapping facility is enabled.

Parent topic: List of Run-time Tunables


entry_point_mapper_search_order

Specifies whether to use entry point mapping to look for programs before or after searching for the programs on disk.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set entry_point_mapper_search_order=---.-0-.-----------><
                                              +-1-+

Parameters:

0 | Programs are looked for on disk before using entry point mapping.
1 | Programs are looked for using entry point mapping before looking on disk.

Properties:

Default: | 0
IDE equivalent: |
Parent topic: List of Run-time Tunables


environment_mapper

Specifies whether the External File Mapper is enabled. The External File Mapper allows you to assign values to environment variables in a file. If the External File Mapper is enabled the system searches for the file mfextmap.dat.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set environment_mapper=---.-TRUE-.-------><
                                 +-FALSE+

Parameters:

TRUE | The External File Mapper is enabled
FALSE | The External File Mapper is not enabled.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables


error_on_duplicate_entry_point

Controls whether an RTS 119 error is generated when an attempt is made to load a program containing a duplicate entry-point.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set error_on_duplicate_entry_point =---.-TRUE-.------><
                                              +-FALSE+

Parameters:

TRUE | Force an RTS 119 error to be generated when loading a duplicate entry point.
FALSE | Silently ignore duplicate entry-points.

Properties:

Default: | FALSE
IDE equivalent: |

Example:

If program A is loaded and contains entry-point ENTA, and then program B is loaded which also contains entry-point ENTA, the RTS can either issue an RTS 119 error ("Symbol redefined") when it encounters ENTA in program B, or silently ignore it.

Parent topic: List of Run-time Tunables


filename_escape_char

Specifies the escape character used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set filename_escape_char=---"character"------><

or:

>>-----set filename_escape_char=---'character'------><

Parameters:

character The escape character to be used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE. The escape character is not treated as part of the filename but instead quotes the character immediately following the escape character (such as a space). It is necessary to quote filenames that have embedded spaces within them.

Properties:

Default: | \0 (null byte is used as an escape character)
IDE equivalent: |
Parent topic: List of Run-time Tunables


filename_quote_char

Specifies the quotation character used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE.
Note: Restriction:

These tunables are supported for native COBOL only.

Syntax:

>>-----set filename_quote_char=---"character"------><

or:

>>-----set filename_quote_char=---'character'------><

Parameters:

character The quotation character to be used when interpreting filenames provided to the run-time system in calls such as CBL_OPEN_FILE. Within a quoted filename, two adjacent quote characters are interpreted as a single quote when deriving the filename. It is necessary to quote filenames that have embedded spaces within them.

Properties:

Default: | " (the double quote character)
IDE equivalent: |
Parent topic: List of Run-time Tunables


lock_mode

Selects the locking implementation to be used.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set lock_mode=---.-0-.-----------><
                        +-1-+
                        +-2-+

Parameters:

0 | Uses the locking mechanism provided by Micro Focus COBOL V3.1 and earlier versions.
1 | Provides compatibility with DOS and OS/2 locking mechanisms.
2 | Provides interlanguage locking. This method causes record locks to lock the physical record.

Properties:

Default: | 1
IDE equivalent: |

Comments:

This tunable is only applicable if the File Handler configuration option FILEMAXSIZE is set to 4.

Parent topic: List of Run-time Tunables


mainframe_floating_point

Specifies whether mainframe floating-point emulation is required.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set mainframe_floating_point=---.-TRUE-.-------------><
                                       +-FALSE+

Parameters:

TRUE | Mainframe floating-point emulation is required.
FALSE | Mainframe floating-point emulation is not required.

Properties:

Default: | FALSE
IDE equivalent: |

Comments:

Specifying this tunable has the same effect as specifying the MAINFRAME_FLOATING_POINT environment variable. If both are specified, the setting of the MAINFRAME_FLOATING_POINT environment variable overrides the setting of the mainframe_floating_point tunable.

Parent topic: List of Run-time Tunables


memory_free_check_size

Specifies the number of freed memory blocks that are to be monitored for subsequent corruption.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set memory_free_check_size=---freed-memory-blocks------><

Parameters:

freed-memory-blocks A numeric value defining the number of freed memory blocks to monitor

Properties:

Default: | 100
IDE equivalent: |

Comments:

You should use this tunable in conjunction with the check freed memory and reuse freed memory strategies offered by the memory_strategy tunable.

Parent topic: List of Run-time Tunables
Related reference
memory_strategy
Related information
COBRT252 Memory corruption detected (Fatal)


memory_strategy

Sets a memory management strategy.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set memory_strategy-=-strategy-specification------><

Parameters:

strategy-specification A numeric value representing one or more of the following flags (see Comments for information about valid combinations):
0x00000001
Check bytes strategy: prepend and append check bytes to each memory allocation
0x00000002
Check freed memory strategy: monitor for subsequent corruption the last n memory blocks freed, where n is the current value set using the memory_free_check_size run-time tunable
0x00000004
Reuse strategy: allow freed memory being monitored for corruption to be used to satisfy allocation requests
0x00000008
Validate strategy: validate memory before and after executing a user application running in a container
0x00000010
Validate strategy: validate memory before and after executing request handler functions in a container
0x20000000
Validate strategy: validate memory on the entry to and the exit from each program
0x40000000
Compatibility strategy: maintain compatibility with previous versions of the run-time system
0x80000000
Validate strategy: validate memory each time an allocation or free operation occurs

Properties:

Default: | 0x00000001
IDE equivalent: |

Comments:

You can use this tunable to enable a process to be executed with one or more memory management strategies in place. For example, to specify that each memory allocation made by the run-time system is to have check bytes prepended and appended, and that each time an allocation or free operation takes place memory is to be validated, you would set the tunable as follows:

set memory_strategy=0x80000001

Only certain combinations of strategies are valid:

  • Check bytes, check freed memory, reuse and validate can be used together in any combination.
  • Compatibility can be used only with validate.

When the check bytes memory management strategy is in place, and the run-time system receives a request to free a memory block, the run-time system checks that the check bytes have not been corrupted, and then releases the memory. A corruption occurs when a program has written past the end of another memory block into the header of this one, or a program has written past the end of this memory block. If the run-time system detects a corruption, it issues run-time system error COBRT252 indicating the memory block address and type of memory that has been corrupted, for example:

Execution error: file 'MYFILE'
error code: 252, pc=0, call=1, seg=0
252 Memory corruption detected (addr=00376068, type=136/1)
Note: The type is used by the run-time system for internal diagnostic purposes.

When the check freed memory strategy is in place, and the run-time system receives a request to free a memory block, the run-time system does not release the memory, but instead:

  • Clears the contents of the memory block to a predefined check value
  • Stores a reference to the block. The run-time tunable memory_free_check_size defines how many blocks the run-time system handles. If the limit has been reached, the run-time system:
    1. Validates the contents of the memory pointed to by the oldest entry stored. If the validation fails (that is, the memory does not contain the expected check value), the run-time system issues run-time system error COBRT252.
    2. Frees the memory pointed to by the oldest entry stored.

You should use the check freed memory strategy with caution as it can lead to memory fragmentation and a significantly larger memory footprint for the process than would normally be expected.

You can use the reuse memory management strategy in conjunction with the check freed memory strategy to allow freed memory to be used to satisfy new allocation requests. When the reuse strategy is in effect and the run-time system needs to allocate a new block of memory, it first checks whether an area of freed memory will satisfy the allocation request. An allocation request will be satisfied from freed memory only if the size and type of the freed memory exactly match the size and type of the allocation request. When an allocation request is satisfied from freed memory, the run-time system first validates the contents of the freed memory. If the validation fails (that is, the memory does not contain the expected check value), the run-time system issues run-time system error COBRT252.

The compatibility memory strategy is provided to give compatibility with the memory management provided in earlier versions of the run-time system. If this strategy is specified, all other strategies except validation are ignored. This strategy does not perform any memory validation or tracking, and silently ignores any memory chaining errors it encounters if an attempt is made to free a memory block more than once.

The validation memory management strategy causes all memory allocations previously made by the run-time system using the check bytes memory management strategy and all freed memory to be validated each time the run-time system is requested to perform a memory allocate or free operation. Additionally, if the operating system allows it, an operating-system memory heap validation check is performed. You should use this strategy with caution since it will lead to a major performance degradation in those applications that perform a large number of memory allocate and free operations.

Parent topic: List of Run-time Tunables
Related reference
memory_free_check_size
Related information
ES_MEM_STRATEGY
COBRT252 Memory corruption detected (Fatal)


mfpm_access_cancelled_data

Specifies whether the Working-Storage Sections of AMODE programs that have been canceled continue to be addressable.
Restriction: This tunable is supported for native COBOL only.

Syntax:

>>-----set mfpm_access_cancelled_data=---.-TRUE-.-------------><
                                         +-FALSE+

Parameters:

TRUE | The Working-Storage Sections of AMODE programs are addressable after they have been canceled.
FALSE | The Working-Storage Sections of AMODE programs are not addressable after they have been canceled.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related reference
mfpm_external_data31
mfpm_logging


mfpm_external_data31

Specifies whether external data items are registered with Mainframe Pointer Manager (MFPM) above or below the 16 Mb line.

Syntax:

>>-----set mfpm_external_data31=---.-TRUE-.-------------><
                                   +-FALSE+

Parameters:

TRUE | External data items are registered with Mainframe Pointer Manager above the 16 Mb line, making them addressable to only AMODE(31) programs.
FALSE | External data items are registered with Mainframe Pointer Manager below the 16 Mb line, making them addressable to both AMODE(24) and AMODE(31) programs.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related reference
mfpm_access_cancelled_data
mfpm_logging


mfpm_logging

Specifies whether Mainframe Pointer Manager (MFPM) events are to be traced.
Restriction: This tunable is supported for native COBOL only.

Syntax:

>>-----set mfpm_logging(option)=---.-TRUE-.-------><
                                   +-FALSE+

Parameters:

option
0
Mainframe Pointer Manager events and address map are traced.
1
Mainframe Pointer Manager events are traced.
2
Mainframe Pointer Manager address map is traced.

Properties:

Default: | 0
IDE equivalent: | None

Comments:

Mainframe Pointer Manager logging is performed using the Consolidated Tracing Facility (CTF). Setting this tunable implicitly sets the mf.rts#mfpm Consolidated Tracing Facility property, and the Consolidated Tracing Facility trace level to "info" if not already set.

Parent topic: List of Run-time Tunables
Related reference
mfpm_access_cancelled_data
mfpm_external_data31


no_mfredir

Enables you to reduce the time the run-time system takes to initialize if your project or application does not execute remote programs.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set no_mfredir=---.-TRUE-.-------------><
                         +-FALSE+

Parameters:

TRUE | The run-time system initializes without searching for the optional module _MFREDIR.
FALSE | The run-time system searches for _MFREDIR when initializing.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

The _MFREDIR module is only required to enable remote program execution. As most applications do not require remote program execution, _MFREDIR rarely exists resulting in many unnecessary lookups being made in the folders on the application and system search paths.

Parent topic: List of Run-time Tunables


os_error_log

Specifies whether an event is written to the Windows Application Event log whenever run-time system error COBRT199 occurs.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set os_error_log=---.-TRUE-.-------------><
                           +-FALSE+

Parameters:

TRUE | An event is written to the Windows Application Event log whenever run-time system error COBRT199 occurs. This was the behavior in previous versions of this COBOL system.
FALSE | An event is not written to the Windows Application Event log whenever run-time system error COBRT199 occurs.

Properties:

Default: | FALSE
IDE equivalent: |

Comments:

Regardless of the setting of os_error_log, a Consolidated Tracing Facility warning event can be generated whenever run-time system error COBRT199 occurs. See the help for the COBRT199 message for information on configuring Consolidated Tracing Facility to enable this.

Parent topic: List of Run-time Tunables


printer_defaults

Sets certain default printer settings when printer redirection has been enabled.
Note: This tunable is supported for .NET COBOL only.

Set these details in a configuration file, in Visual Studio.

Syntax:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <configSections>

  <sectionGroup name="MicroFocus.COBOL.Runtime">
   <section name="Tunables" type="System.Configuration.NameValueSectionHandler" />
   <section name="Switches" type="System.Configuration.NameValueSectionHandler" />
  </sectionGroup>
</configSections>

 <MicroFocus.COBOL.Runtime>
  <Tunables>
   <add key="printer_redirection" value="true" />
   <add key="printer_defaults" value="size=20;font=Courier New;printer.name=\\svr-ptr\office-ptr" />
  </Tunables>
  <Switches></Switches>
 </MicroFocus.COBOL.Runtime>
</configuration>

Parameters:

font
Name of the font
size
Size of the font
title
A name for the spooler job
printer.name
The name of the printer, as recognised in Windows

Properties:

Default: | Not set
IDE equivalent: | None

Comments:

This tunable is dependent on printer redirection being on, which you can do by setting the printer_redirection tunable or by calling the PC_PRINTER_REDIRECTION_PROC routine.

Parent topic: List of Run-time Tunables


printer_raw_redirection

Redirects WRITE statements through the Windows print spooler as RAW data types.
Restriction: This tunable is supported for .NET COBOL only.

Syntax:

>>-----printer_raw_redirection=----.-TRUE-.-------><
                                   +-FALSE+

Parameters:

TRUE | Redirect WRITE statements to files defined with the ASSIGN TO PRINTER syntax through the Windows print spooler and process them as RAW data types.
FALSE | Output is sent through the printer driver or directly to the printer port; see printer_redirection.

Properties:

Default: | FALSE
IDE equivalent: | None

Comments:

This tunable is dependent on printer redirection being on, which you can do by setting the printer_redirection tunable or by calling the PC_PRINTER_REDIRECTION_PROC routine.

Parent topic: List of Run-time Tunables


printer_redirection

Redirects WRITE statements through the Windows print spooler.

The following details are for native COBOL only; for details of .NET COBOL, refer to the Comments section.

Syntax:

>>-----printer_redirection=----.-TRUE-.-------><
                               +-FALSE+

Parameters:

TRUE | Redirect WRITE statements to files defined with the ASSIGN TO PRINTER syntax through the Windows print spooler, rather than sending the output directly to the printer port.
FALSE | Output is sent directly to the printer port.

Properties:

Default: | FALSE
IDE equivalent: |

Comments:

To configure this tunable for .NET COBOL, add a reference to a .config file in Visual Studio. Refer to Format of a Configuration File for .NET COBOL for details of the required syntax.

You can also set printer redirection by calling the PC_PRINTER_REDIRECTION_PROC routine.

Parent topic: List of Run-time Tunables


profile_behavior

Specifies the behavior of the Profiler with regard to the counting of time spent in called programs.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set profile_behavior=--value-----------><

Parameters:

value is a value between 0 and 3, and represents the following:

Bit | Value | Description
0 | 0 | Time spent in a called program is counted both in the called program and in the calling program.
 | 1 | Time spent in a called program is counted only in the called program.
1 | 0 | Profiler records CPU time; that is, the user + system time.
 | 1 | Profiler records elapsed time; otherwise known as real time or wall-clock time.

Properties:

Default: | 0
IDE equivalent: |
Parent topic: List of Run-time Tunables
Related information
Time Spent in Called Programs


reduce_java_signals

Specifies the options that are passed to a JVM when mixing Java and COBOL.

Syntax:

>>---set-reduce_java_signals=--.-TRUE--.-------><
                               +-FALSE-+

Parameters:

TRUE
When mixing Java and COBOL, the Java VM is initialized with the -Xrs option. Also, on HP-UX platforms, the -Xusealtsigs option is set. These options prevent the Java run-time from catching the SIGHUP, SIGINT, SIGQUIT, SIGTERM signals, and additionally on HP-UX, the SIGPROF signal. See the Java documentation for more details on these options.
FALSE
When mixing Java and COBOL, default Java signal handling behavior is used.

Properties:

Default: | TRUE
IDE equivalent: | None

Comments:

This tunable is implicitly set to TRUE when using the -i run-time switch.

Parent topic: List of Run-time Tunables


remote_64bit_access

Specifies whether 64-bit file access is permitted for unknown remote file systems.

Syntax:

>>-----set remote_64bit_access=---.-TRUE-.-------------><
                                  +-FALSE+

Parameters:

TRUE | The run-time system assumes that any unknown remote file system supports 64-bit file access.
FALSE | The run-time system assumes that any unknown remote file system does not support 64-bit file access.

Properties:

Default: | FALSE
IDE equivalent: |

Comments:

When this tunable is set to FALSE, and 64-bit access is requested, a 181 return code or file status is produced. You request 64-bit access using the access-mode parameter in CBL_CREATE_FILE and CBL_OPEN_FILE, or by setting FILEMAXSIZE=8 in your File Handler configuration file.

Parent topic: List of Run-time Tunables


screen_cols

Specifies the initial width of the Application Output window or console.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set screen_cols=----integer--------------><

Parameters:

integer A value in the range 0 through 255 indicating the width of the Application Output window or console.

Properties:

Default: | For console windows, the current screen width as returned by the operating system; for the Application Output window, 80.
IDE equivalent: | None
Parent topic: List of Run-time Tunables


screen_lines

Specifies the initial height of the Application Output window or console.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set screen_lines=----integer------------><

Parameters:

integer A value in the range 0 through 255 indicating the height of the Application Output window or console.

Properties:

Default:
  • For console windows, the current screen height as returned by the operating system
  • 25 for the Application Output window
  • 43 if COBSW=C4 is set
  • 50 if COBSW=C5 is set
IDE equivalent: None
Parent topic: List of Run-time Tunables


shared_memory_segment_size

Specifies the initial size of the shared memory block allocated by the run-time system.
Restriction: This tunable is supported for native COBOL only.

Syntax:

>>-----set shared_memory_segment_size=---integer-----------><

Parameters:

integer Specifies the initial size of the shared memory block allocated by the run-time system, in bytes. The minimum value you can specify is 8192 (8KB).

Properties:

Default: | 65536 (64KB)
IDE equivalent: |

Comments:

The default amount of shared memory allocated by the run-time system is 65536 bytes, of which the run-time system reserves some of these bytes for internal use, so the actual default allocation is around 64000 bytes.

Use this tunable to override the default size, but be aware that any change in allocation is restricted by the operating system (and the run-time system requirement mentioned above).

Parent topic: List of Run-time Tunables


signal_regime

Specifies whether or not the COBOL Run-Time System is to post its own signal handlers.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set signal_regime(sig)=integer---------><

or

>>-----set signal_regime=1---------><

Parameters:

sig The number of the signal, between 1 and the maximum signal number on your operating system. See your operating system documentation for details on signal numbers.
integer The action the run-time system is to take for the signal sig. integer can take one of the following values:
0 - The signal handler for signal sig is used if needed
By default, the run-time system sets up signal handlers for all signals whose operating system default action would cause termination. The run-time system can thus catch these signals and tidy up (for example, close any open files to prevent file corruption) before exiting.
1 - The signal handler for signal sig is used only if a handler was not already posted for this signal
This is useful if the third-party software is invoked before your COBOL system and sets up a handler for signal sig. If this tunable is not set for this signal, the run-time system overwrites the third-party software's handler with its own; this leads to unpredictable behavior, such as run-time system error COBRT115 ("Unexpected signal") being produced.

If a handler was posted, the run-time system will not post any handlers for this signal and so any run-time system functionality which relies on this signal will not work.

2 - The signal handler for signal sig is not used
This is only of use if the third-party software is invoked after the run-time system and sets up a handler for signal sig. Use of this setting is strongly discouraged for any signal whose operating system default action is to cause termination; if this signal is received between the run-time system being invoked and the third-party software setting up its handler, the default action of the operating system occurs, and the process exits without the run-time system being able to tidy up. This could lead to problems such as file corruption.

Any run-time system functionality which relies on this signal will not work.

Properties:

Default: | 0 for all signals
IDE equivalent: |

Comments:

If you use the alternative syntax (set signal_regime=1), the signal regime for all signals is set to 1.

Parent topic: List of Run-time Tunables
Related reference
core_on_error
debug_on_error


subsystem_cancel_mode

Specifies whether logical or physical cancels are used for CBL_SUBSYSTEM cancels.
Restriction: These tunables are supported for native COBOL only.

Syntax:

>>-----set subsystem_cancel_mode=--.-0-.-----------><
                                   +-1-+
                                   +-2-+

Parameters:

0 | Physical cancels: any program canceled with a CBL_SUBSYSTEM cancel will be freed from memory, making more memory available.
1 | Compatibility mode. As Logical cancels mode, except that .dll files or shared objects are physically canceled. This option is present for compatibility with older products.
2 | Logical cancels: any program canceled with a CBL_SUBSYSTEM cancel will not be freed from memory. The programs are available to be reused and hence the performance of CALL/CANCEL statements is greatly increased.

Properties:

Default: | 0
IDE equivalent: |

Comments:

As far as your program is concerned, logical and physical cancels behave identically.

Parent topic: List of Run-time Tunables


timewarp_dynamic

Specifies whether the hours, minutes, and seconds values specified by the current_hour, current_minute, and current_second tunables return static or "rolling" values.
Note:
  • Micro Focus does not recommend use of this tunable in an Enterprise Server environment.

Syntax:

>>-----set timewarp_dynamic=---.-TRUE-.-------------><
                               +-FALSE+

Parameters:

TRUE | The hours, minutes, and seconds values specified for the current_hour, current_minute and current_second tunables are treated as clock start values and will "roll" once they have been set.
FALSE | The hours, minutes, and seconds values specified for the current_hour, current_minute and current_second tunables are static values that will always be returned when you use the ACCEPT identifier FROM TIME syntax, or the CURRENT-DATE or FORMATTED-CURRENT-DATE intrinsic functions. The static values are also used in the calculation for the SECONDS-PAST-MIDNIGHT intrinsic function.

Properties:

Default: | FALSE
IDE equivalent: |
Parent topic: List of Run-time Tunables


RTS Error Messages

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 Test Server 10.0


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.
  • COBRT051 (message text is intentionally blank)
    This message is produced as the result of the environment being set to produce RM/COBOL file status codes.
  • 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


COBRT051 (message text is intentionally blank)

If your program is set to return RM/COBOL file status codes, but does not use a file status, or does not have a Declaratives section acting upon your data file, file I/O errors are reported by the run-time system. The extended file status reported may initially seem incorrect, but due to differences in the file handling of the different COBOL systems, the second byte of the reported error code needs to be converted from binary to ASCII. For example, if an error of 9/051 is reported, convert 051 to its ASCII character equivalent, which is 3 (0x33 in hexadecimal); therefore, the true RM/COBOL file status is actually 93.

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)
  • COBRT091 Incompatible Run-Time System detected (<run-time-system> already loaded)(Fatal)
    An attempt has been made to load both a threaded and a non-threaded Run-Time System into the same process.
  • COBRT092 Initialisation of Run-Time System failed (Fatal)
    An error occurred during initialisation, or attempted re-initialisation, of the COBOL Run-Time System.
  • COBRT093 De-initialisation of Run-Time System failed (Fatal)
    An error occurred during, or after, de-initialisation of the COBOL Run-Time System.
  • 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)

The network connection to a remote file system has been lost. Please check you connectivity to the remote system.

Parent topic: COBRT081 - COBRT100


COBRT091 Incompatible Run-Time System detected (<run-time-system> already loaded)(Fatal)

An attempt has been made to load both a threaded and a non-threaded Run-Time System into the same process.

A Run-Time System is linked into a COBOL executable (created with cob -x) or a self-contained callable shared object (created with cob -y) when they are created and the type of Run-Time System is dependant on whether the cob -t flag is specified or not. The Run-Time System is loaded when a COBOL executable starts or a self-contained callable shared object is loaded into a running process. If the process already contains a Run-Time System, then they must match; that is, they are both threaded Run-Time Systems or both non-threaded Run-Time Systems.

Parent topic: COBRT081 - COBRT100


COBRT092 Initialisation of Run-Time System failed (Fatal)

An error occurred during initialisation, or attempted re-initialisation, of the COBOL Run-Time System.

The Run-Time System is initialised when either:

  • A COBOL executable (created with cob -x) starts.
  • A self-contained callable shared object (created with cob -y) is loaded into a non-COBOL executable.
Parent topic: COBRT081 - COBRT100


COBRT093 De-initialisation of Run-Time System failed (Fatal)

An error occurred during, or after, de-initialisation of the COBOL Run-Time System.

The COBOL Run-Time System is de-initialised when:

  • The cobtidy() API is called.
  • When the last self-contained callable object (created with cob -y) is unloaded from a non-COBOL executable.
  • When a COBOL executable (created with cob -x) terminates.
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)

An attempt has been made to pass a parameter BY VALUE which is too large. The parameter should be passed BY REFERENCE instead.

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:

The generated code could not run against the current run-time system, due it being produced using an old product. Please recompile your code using a more recent Compiler, preferably one that matches the version of the run-time system.

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.

OpenText Support for Micro Focus Products 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.

OpenText Support for Micro Focus Products 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.
  • COBRT131 coblongjmp() can not return from current context (Fatal)
    You have called coblongjmp() in a error procedure, exit procedure or signal handler.
  • COBRT132 Live Recorder initialization failed
    An attempt has been made to enable the Live Recorder, via the COB_LIVE_RECORD environment variable, but Live Recorder is not enabled on your system.
  • COBRT133 Size of declare local items including parameters exceeds limit
    During the production of intermediate code, the limit to store all local variables and active parameters has been exceeded.
  • 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.
  • 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

See the 9/124 status code in Fileshare Extended Status Codes for more details.

Parent topic: COBRT121 - COBRT140


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

See the 9/125 status code in Fileshare Extended Status Codes for more details.

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


COBRT131 coblongjmp() can not return from current context (Fatal)

You have called coblongjmp() in a error procedure, exit procedure or signal handler.

Resolution:

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

Parent topic: COBRT121 - COBRT140


COBRT132 Live Recorder initialization failed

An attempt has been made to enable the Live Recorder, via the COB_LIVE_RECORD environment variable, but Live Recorder is not enabled on your system.
You can either:
  • Unset the COB_LIVE_RECORD variable and continue without the Live Recorder functionality.
  • Purchase the Live Recorder from the Micro Focus Marketplace - https://marketplace.microfocus.com/
Parent topic: COBRT121 - COBRT140


COBRT133 Size of declare local items including parameters exceeds limit

During the production of intermediate code, the limit to store all local variables and active parameters has been exceeded.

You need to re-factor the section to operate within a 16KB limit.

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


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

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

One such situation that could have caused this error is when attempting 64-bit file access where it is not permitted; see FILEMAXSIZE for scenarios where such access should not be attempted. If 64-bit access is required for a remote file system, set the remote_64bit_access tunable.

Parent topic: COBRT181 - COBRT200
Related reference
remote_64bit_access


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


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.
  • 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.
  • 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.
  • COBRT230 SORT RETURN attempted after the at end condition was returned
    A RETURN statement was attempted after the end of file has been reached.
  • 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.
  • 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 insufficient memory .
  • 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


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


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


COBRT230 SORT RETURN attempted after the at end condition was returned

A RETURN statement was attempted after the end of file has been reached.

Resolution:

Correct by revising the execution flow affecting the RETURN statement.

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.

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 insufficient memory .

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 Referencefor 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 <class-name> (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 SIGTERM signal to a service execution process (SEP) running on an enterprise server. This may occur for 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.
  • COBRT255 CODESET cannot open double byte conversion table
    The CODESET mapping mechanism is unable to locate a table required for conversion.
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 <class-name> (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 SIGTERM signal to a service execution process (SEP) running on an enterprise server. This may occur for 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.

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.

Additional information on the type of memory and determined reason for corruption is also appended to the error message; for example:

addr=12345678, type=53, stomp=6 <run-in data>

Where addr is the memory address, type is the type of memory, and stomp is the stomp type. For a full list of meanings for memory type and stomp type, refer to the MEMORY section of mf.rts.Component Properties.

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
Related concepts
mf.rts Properties
Related reference
memory_strategy
memory_free_check_size


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


COBRT255 CODESET cannot open double byte conversion table

The CODESET mapping mechanism is unable to locate a table required for conversion.

Resolution:

The required tables are located in a number of files in the etc\codeset sub-directory of your installation directory. Check that these files exist, and if they do, check that your COBDIR environment variable is pointing to the correct location.

Parent topic: COBRT241 - COBRT260


Data Access

  • Database Access
  • Data Files
  • File Handling
  • Database File Handling and Enterprise Server Region Database Management
Parent topic: Micro Focus Enterprise Test Server 10.0


Database Access

Enterprise Test Server provides several options to accommodate database access from your runtime applications.

  • HCO for DB2 LUW
  • HCO for SQL Server (HCOSS)
  • OpenESQL
  • SQL Option for DB2
  • Mainframe Batch Database Tools (MBDT)
    Describes batch utilities that facilitate mainframe database migration.
Parent topic: Data Access


HCO for DB2 LUW

  • HCO Tools
  • Creating a DB2 LUW Database for HCO
    Describes the requirements for creating a DB2 LUW database to use with COBOL applications written using a mainframe COBOL dialect.
  • Supported country codes
    Enterprise Developer has built-in country support for EBCDIC <-> ASCII character set translations.
  • How to
  • Command Line Reference
Parent topic: Database Access
Related concepts
Additional Software Requirements
Related information
Features Added in Enterprise Test Server 2.3 Update 2


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 Tool
  • 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 Windows platforms 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 alternative 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 were to use any of the IBM tools to create the database, all data would be returned to your application in ANSI collating sequence. IBM does provide some examples of how to create databases with alternative collating sequences, but the EBCDIC to ANSI translation that IBM uses might be different from the translation used by Enterprise Developer. Therefore, we strongly recommend 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 Tool

Host Compatibility Option provides a tool to generate DDL for existing SQL tables or copybooks for tables in COBOL 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*/
/*-------------------------------------------------------*/
Scenario 6
In this scenario, generate the EMP_PHOTO table without a DECLARE TABLE section, generate all numeric variables as COMP-5 rather than COMP, and generate LOB variables as LOB SQL TYPEs rather than generating them as the default of LOB-LOCATOR.

The DECLARE TABLE part of copybook file would look something like this:

/*----------------------------------------------------------*/
/* MFHCODCL OPTIONS:                                        */
/*     DATABASE : SAMPLE                                    */
/*     SCHEMA   : TESTER                                    */
/*     PREFIX   : TABLE NAME                                */
/*----------------------------------------------------------*/
/* COBOL DECLARATION FOR TABLE                              */
/*----------------------------------------------------------*/
 01  DCLEMP-PHOTO.
     10 EMP-PHOTO-EMPNO                  PIC X(6).
     10 EMP-PHOTO-PHOTO-FORMAT.
        49 EMP-PHOTO-PHOTO-FORMAT-LEN    PIC S9(04)  COMP-5.
        49 EMP-PHOTO-PHOTO-FORMAT-TEXT   PIC X(10).
     10 EMP-PHOTO-PICTURE                SQL TYPE IS
                                         BLOB(100K).
/*----------------------------------------------------------*/
/* COBOL INDICATOR VARIABLES FOR TABLE                      */
/*----------------------------------------------------------*/
 01  DCLEMP-PHOTO-NULL.
     10 EMP-PHOTO-PICTURE-NULL           PIC S9(04)  COMP-5.
/*----------------------------------------------------------*/
/* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 3 */
/*----------------------------------------------------------*/
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 machines 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 machines.

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 Import Data tool from the HCO for DB2 LUW user interface, or using the mfhco import 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 dclgen 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


Creating a DB2 LUW Database for HCO

COBOL applications written using a mainframe COBOL dialect require that any DB2 LUW database accessed by such an application use an EBCDIC collating sequence. The HCO Create Database Tool enables you to create a compatible DB2 LUW database on a Windows platform for access from a COBOL application coded using a mainframe COBOL dialect.

Note: The HCO Create Database tool provides seamless integration with mainframe COBOL-dialect applications that use SBCS (single-byte character sets) only, regardless of the platform. To create a database to be accessed from an application that uses DBCS (double-byte character sets), see the IBM documentation that covers database creation and appropriate EBCDIC collating sequences.

The Create Database Tool is available from the HCO for DB2 LUW user interface, or using the mfhco create. See the mfhco create command and To create a database topics for additional details.

Set MFCODESET to a country code

Before using the Create Database tool to create a database, set the MFCODESET environment variable to an appropriate country code value listed on the Supported Country Codes topic. A correct setting of MFCODESET ensures that the database EBCDIC collating sequence matches the CHARSET EBCDIC behavior of your application. The correct code for a given country could vary depending on your platform and whether or the database requires Euro (€) character translation enablement.

Windows platforms
Create DB2 LUW databases on Windows platforms using code page 1252 for both Euro and non-Euro character translations. To determine the country code, use the first table listed on the Supported Country Codes topic.

Determine the code page

You can determine which code page was used to create an existing database by connecting to the database, starting a DB2 command prompt, and issuing a get db config command. See the IBM GET DATABASE CONFIGURATION command documentation for details.

The following is an example of get db config output showing a Database code page of 1252:

C:\Program Files\IBM\SQLLIB\BIN>db2 get db config
       Database Configuration for Database
 Database configuration release level                    = 0x1400
 Database release level                                  = 0x1400

 Database territory                                      = En_US
 Database code page                                      = 1252
 Database code set                                       = 1252
 Database country/region code                            = 1
 Database collating sequence                             = UNIQUE
 Alternate collating sequence              (ALT_COLLATE) =
 Number compatibility                                    = OFF
 Varchar2 compatibility                                  = OFF
Parent topic: HCO for DB2 LUW


How to

  • To start HCO tools
  • To create a database
  • To process SQL DDL statements
  • To create a DCLGEN
  • To bind files
  • To import data
  • To export data
  • To set HCO for DB2 LUW options
Parent topic: HCO for DB2 LUW


To start HCO tools

Windows 8, 8.1, and Windows Server 2012
  • From the Windows Start screen, click the HCO for DB2 LUW tile
Windows 10 and Later
  • From your Windows desktop, click Start > Enterprise Test Server > HCO for DB2 LUW
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 bind files

  1. From the HCO for DB2 LUW interface, click Bind Files.
  2. On the Bind tab, complete the fields. See the Bind 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 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

Important: Before executing the mfhco create command, be sure that the MFCODESET environment variable is set to the appropriate country code. See Creating a DB2 LUW Database for HCO for details.

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 | If specified, must be the default value MFD. This ensures that the environment variable MFCODESET is used.
logfilename | The name of the log file in which 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]
       [id=logon pass=password] [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.
logon | The logon ID for the database server.
pass | The password for the database server.
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}]
     null=nullindname [typeint={COMP | COMP5}] [typelob={LOCATOR | LOB | FILE}]
        [declare={Y | N }] [str=structurename] [id=logon pass=password]

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 | Name of the target database.
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.
nullindname | Specifies the null indicator name suffix. Default is NULL.
COMP | Specifies generation of numeric fields as COMP variables. Default.
COMP5 | Specifies generation of numeric fields as COMP-5 variables.
LOCATOR | Specifies generation of LOB variables as SQL TYPE LOB-LOCATOR. Default.
LOB | Specifies generation of LOB variables as SQL TYPE LOB(size).
FILE | Specifies generation of LOB variables as SQL TYPE LOB-FILE.
declare | Y - Generate DECLARE TABLE as part of the copybook. Default. N - Do not generate DECLARE TABLE as part of the copybook.
structurename | Specifies the name of the copybook structure.
logon | The logon ID for the database server.
pass | The password for the database server.

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]
            [id=logon pass=password] [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.
logon | The logon ID for the database server.
pass | The password for the database server.
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] [id=logon pass=password]

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".
logon | The logon ID for the database server.
pass | The password for the database server.

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 HCO for SQL Server (HCOSS) section in the Database Management Systems (DBMSs).topic.

  • HCOSS Toolset
  • Before Using HCO for SQL Server
    Describes the SQL Server database adjustments that are required each time you upgrade your version of Enterprise Test Server.
  • 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
HCO for SQL Server (Known Issues)
Additional Software Requirements
Before Using HCO for SQL Server
Related information
Features Added in Enterprise Test Server 2.3 Update 2


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.
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 SQL Name Mappings
View or change default SQL name mappings, or define additional SQL name mappings.
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
Application Database Support
Related tasks
To start HCO for SQL Server
To set HCOSS options
Related reference
Options


Before Using HCO for SQL Server

Describes the SQL Server database adjustments that are required each time you upgrade your version of Enterprise Test Server.

HCOSS mimics z/OS functions and other z/OS functionality by storing SQL Server stored procedures and tables in your SQL Server database(s).

To successfully use HCOSS, it is important that you update this information stored in your database(s) each time you upgrade your version of Enterprise Test Server, including new releases, updates, or hotfixes. Doing so ensures that HCOSS always executes optimally.

We provide three HCOSS scripts you can use to update your SQL Server database(s) after each upgrade. By default, all are located in your %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory:

InstallSYSIBM.sql
Creates metadata tables.
InstallBindProcs.sql
Creates SQL Server stored procedures required for binding and managing temporary table metadata.
InstallDigitsFunction.sql
Creates SQL Server stored procedures required to support DB2 z/OS functions.
To execute these scripts against any SQL Server database, you must have the following permissions to the database:
  • CREATE SCHEMA
  • CREATE PROCEDURE
  • EXECUTE PROCEDURE in the SYSIBM schema

We suggest that you choose from the following methods of script execution:

SQL Server Management Studio
Execute all three HCOSS scripts against each SQL Server database.
SQL Server sqlcmd utility
This option enables you to automate the process, running the three scripts consecutively. Use the following syntax at a command prompt:
sqlcmd -S myServer\instanceName -i "scriptDir\HCOSSscript.sql"

Where:

myServer | Name of a SQL Server database
instanceName | SQL Server instance name
scriptDir | Full path to the directory that contains the scripts
HCOSSscript | Name of an HCOSS script
DSN Bind Utility
While the DSN Bind utility does just what the other two options also do, you might find it easier to use as an alternative to executing the scripts yourself. We recommend this procedure:
  1. Start an Enterprise Test Server command prompt.
  2. Do one of the following:
    • If using Windows authentication, enter:
      DSN SYSTEM(connectionName)
    • If using SQL Server authentication:
      DSN SYSTEM(connectionName) ASUSER(LoginID.Password)

    Where connectionName is the name of a connection created with the HCOSS Manage Connections tool, and LoginID and Password are a SQL Server login ID and password respectively.

    DSN automatically executes the required scripts and updates the database. The command window shows its execution process.

  3. When a DSN command prompt appears, enter END.
Note: You must have the same SQL Server permissions when using the DSN Bind utility as are required to execute the scripts using one of the other methods.
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCO for SQL Server (HCOSS)
DSN Bind Utility


Using HCOSS with Windows User Account Control (UAC)

Restriction: This topic applies to the Windows Vista and 7 operating systems and later.

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.

ODBC Providers

For ODBC connectivity, we recommend that you always use the most recent supported version of the ODBC provider available when creating new connections. We also recommend that you upgrade existing connections to use the most recent provider when possible.

When creating a new SQL Server connection, HCOSS defaults the connection to the latest ODBC provider installed and supported on the system. For any SQL Server connection on the SQL Server Connection tab or Connection List tab, you can select from a drop-down list of installed and supported SQL Server ODBC providers. You can also set the ODBC provider for all SQL Server connections on the Connection List tab.

Important: ODBC provider selection for SQL Server connections applies to System or User connections. Azure connections do not use ODBC connections. The "SQL Server" ODBC provider from Microsoft is an older provider that ships with Microsoft Windows and lacks certain features available in many newer Microsoft ODBC providers. As such, it is not shown in Manage Connections ODBC drop-down selectors. Microsoft ODBC provider versions provide support for particular versions of SQL Server. To help you select an appropriate ODBC provider, System requirements, installation, and driver files page on the Microsoft Web site.

For information on supported ODBC drivers, see the HCO for SQL Server (HCOSS) topic under Additional Software Requirements.

OLE DBProviders

To aid in ensuring the fastest performance during HCOSS data transfer, the Manage Connections tool checks to determine if any of the following OLE DB providers are available on your system:

  • Microsoft OLE DB Provider for SQL Server
  • SQL Server Native Client 11.0
  • Microsoft OLE DB Driver for SQL Server

Manage Connections does not directly create SQL Server OLE DB connections. Instead, it uses the ADO.NET provider System.Data.SqlClient and the ODBC provider selected. The Transfer Data tool converts the connection string for SQL Server connections created in Manage Connections to work with these specific OLE DB providers automatically to achieve the fastest data transfer performance. You can also use newer or alternative OLE DB providers by creating those connections in the ADO.NET connection editor. You can select one of these as the target connection in the Transfer Data tool.

  • 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.
  • Allows setting the SQL Server ODBC provider on the SQL Server Connection tab or Connection List tab.
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
Offline Extract Schema Solution


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.
Note: Support for .NET Framework versions 3.0 and 3.5, and for the CLR v2 has been deprecated. The option 2 of the ILCLR directive has also been deprecated.
%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.
Note: Support for .NET Framework versions 3.0 and 3.5, and for the CLR v2 has been deprecated. The option 2 of the ILCLR directive has also been deprecated.
%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.
Note: Support for .NET Framework versions 3.0 and 3.5, and for the CLR v2 has been deprecated. The option 2 of the ILCLR directive has also been deprecated.
%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.
Note: Support for .NET Framework versions 3.0 and 3.5, and for the CLR v2 has been deprecated. The option 2 of the ILCLR directive has also been deprecated.
%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: For more information, see To start the ADO.NET Connection Editor as an administrator and To start the ODBC Data Source Administrator.
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
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.

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.

  • Schema Extraction Process
  • Offline Extract Schema Solution
  • Modifying Exporting and Importing Schema Extract Files
  • Extract Schema Security
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Deploying Native Applications
Related tasks
To extract DB2 schema objects
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


Schema Extraction Process

The Extract Schema tool retrieves information about various z/OS DB2 SQL objects, and then stores this information in an XML file for further processing with HCOSS.

The standard schema extraction method is to first connect to your z/OS DB2 database, and then retrieve the required information directly from the z/OS DB2 catalog.

You can optionally use the offline schema extract solution. With this approach, you first migrate the z/OS DB2 catalog information to SQL Server, and then use the Extract Schema tool connected to SQL Server. This eliminates the need to connect to z/OS DB2 directly. For details on this approach, see Offline Extract Schema Solution.

The Extract Schema tool 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
  • SYSPARMS

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:

Note: To extract CREATE VIEW statements with proper translation when using DB2 for z/OS version 10 and higher, you might need to set the Cast STATEMENT column to VARCHAR during SysViews extract Extract Schema option to True. See the To set HCOSS Options and Options topics for more information.
  • Connects to a DB2 database directly, or connects to a SQL Server database that contains z/OS DB2 catalog information migrated using the method outlined in Offline Extract Schema Solution.
  • Requests a list of available schemas
  • 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
  • Reports results
Parent topic: Extract Schema Tool
Related concepts
Offline Extract Schema Solution
Related tasks
To set HCOSS options
Related reference
Options


Offline Extract Schema Solution

The HCOSS Extract Schema tool, when used as an online tool, requires a direct connection to DB2 for z/OS. In some production environments, this direct access can have a negative effect on the speed of regular business transactions on production databases, or can sometimes upset database security policy. To get around this, we provide a solution for schema extraction that can be done off line.

You can use Mainframe Batch Database Tools (MBDT) along with z/OS DB2 DSNUTILB UNLOAD to eliminate the need for direct access to the z/OS DB2 catalog. With this approach, the contents of the DB2 tables are unloaded from the mainframe using methods that either minimize or have no effect on z/OS DB2 processing. Once DB2 catalog tables are unloaded, you can use MBDT to load this information into SQL Server. This enables the Extract Schema tool to access the catalog via SQL Server.

This offline Extract Schema approach expands the existing HCOSS Toolset by altering only the Extract Schema step in the process of HCOSS database migration. All other steps, from Assess Data Migration to Compare Data, remain unchanged.

Like the online Extract Schema tool, the HCOSS Offline Extract Schema tool supports multiple versions of DB2 for z/OS, starting with Version 9.

Note: z/OS DB2 9 is no longer supported by IBM.

Unlike the online Extract Schema tool, which is one-step process, the offline tool requires that you perform multiple steps:

  1. Unload DB2 catalog tables from mainframe DB2 using z/OS DB2 DSNUTILB UNLOAD
  2. Import and catalog the unloaded data sets in Enterprise Server
  3. Create the DB2 catalog tables in SQL Server
  4. Load the data sets to SQL Server catalog tables using MBDT DSNUTILB LOAD
  5. Create foreign key references for the SQL Server catalog tables
  6. Run the Extract Schema tool with a SQL Server ADO.NET DSN

The following sections provide details for each step:

Important: All files referenced here as provided by Micro Focus are located by default in your %ProgramFiles(x86)%\Micro Focus\Enterprise Test Server\etc\hcoss directory.
Step 1: Unload catalog tables from z/OS DB2
Use the DB2 for z/OS batch utility, DSNUTILB UNLOAD, to unload the DB2 catalog tables for consumption by the MBDT DSNUTILB LOAD tool.

The SYSIBM schema contains 17 DB2 catalog tables that must be unloaded. To expedite this, Micro Focus provides the UNLOAD.parm file that contains all recommended UNLOAD cards. While some of the UNLOAD cards in UNLOAD.parm select an entire table, some of them select only a subset of the columns of a particular table. For example:

UNLOAD EBCDIC CCSID(00037,00037,00000)
DATA FROM TABLE SYSIBM.SYSPARMS
( SCHEMA,
  NAME,
  PARMNAME,
  ROWTYPE,
  ORDINAL,
  TYPENAME,
  LENGTH,
  SCALE,
  SUBTYPE,
  CCSID,
  ENCODING_SCHEME)

The purpose of selecting a subset of columns for some tables is to reduce the amount of data to unload, yet still provide enough information for the HCOSS Extract Schema tool to work successfully.

Important: When unloading, be sure to save the generated LOAD cards. These LOAD cards are used in Step 4.
Note: If you are using z/OS DB2 version 9, you must use the documented UNLOAD card provided for SYSIBM.SYSVIEWS in UNLOAD.parm rather than the one provided for z/OS DB2 version 10 or later.
Step 2: Copy the unloaded DB2 data and catalog it in Enterprise Server
Using Mainframe Access MFDAS IMPORT command-line tool, copy the unloaded DB2 data to your local Windows machine, and then catalog the data in an enterprise server region.
Preparing to copy and unload
Before you can run MFDAS IMPORT, you must create an enterprise server region that is enabled for both Mainframe Subsystem Support and Job Entry Subsystem (JES).

MFDAS IMPORT enables you to both copy and catalog all in one step, but you must run the tool separately for each extracted table. Therefore, you might consider creating a single batch file containing an MFDAS IMPORT command for each table.

Executing MFDAS IMPORT
You must run MFDAS IMPORT from an Enterprise Server command prompt as an administrator. The method you use to do this varies depending on your operating system. See To start an Enterprise Server command prompt as an administrator for details.

At your Enterprise Server command prompt, run MFDAS IMPORT using the following syntax:

MFDAS IMPORT datFilePath\datFileName.dat
FROM QSAM mainframeDataSet /CATLOC=ESWorkArea\ESRegionName\catalog.dat

Where the variables are:

datFilePath
The path to a local directory on Windows where you want to store the file containing extracted unloaded data set data.
datFileName
The name of a data file to contain the extracted data.
mainframeDataSet
The name of the unloaded data set on the mainframe.
ESWorkArea
Your Enterprise Server WORKAREA folder, which by default is %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA.
ESRegionName
The name of your MSS- and JES-enabled enterprise server region.

For example, to copy and catalog the data set for SYSVIEWS, the command line might look like this:

MFDAS IMPORT C:\work\DB2CATALOG\SYSVIEWS.DAT FROM QSAM MFIXCH.UTILBTS.ULSYSVWS
/CATLOC=%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREAEXSCHEMA\catalog.dat
Step 3: Create the DB2 catalog tables in SQL Server
To expedite the creation of DB2 catalog tables in SQL Server, Enterprise Developer provides the CREATECATALOG.sql script file. This file contains the SQL Server CREATE TABLE statements required to migrate the IBM catalog tables to SQL Server.

We recommended that you execute CREATECATALOG.sql from SQL Server Management Studio. Before execution, be sure that the SYSIBM schema exists in the SQL Server database.

Step 4: Load the data sets into SQL Server catalog tables
The MBDT DSNUTILB LOAD tool loads the imported and cataloged Enterprise Server data sets into SQL Server tables. Use the LOAD cards generated by z/OS DB2 DSNUTILB UNLOAD in Step 2 with some minor changes as follows:
  • Replace the RESUME YES with the REPLACE YES option
  • Specify the EBCDIC option explicitly to override the MBDT default of ASCII.

The following is a JCL example of MBDT DSNUTILB LOAD into a table in SQL Server:

//LDSYSPRM JOB
//DSNUPROC EXEC PGM=TSTUTILB,PARM='HCOD,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//*COLSDISC DD   SYSOUT=*
//* DISCARDDN CHKSDISC DISCARDS 0
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=MFIXCH.UTILBTS.ULSYSPRM
//SYSIN    DD   *
LOAD DATA INDDN SYSREC LOG NO  REPLACE YES
 EBCDIC  CCSID(00037,00037,65534)
 INTO TABLE
 "SYSIBM".
 "SYSPARMS"
 WHEN(00001:00002) = X'0146'
 NUMRECS                 1274
 ( "SCHEMA"
  POSITION(  00003:00132) VARCHAR
 , "NAME"
  POSITION(  00133:00262) VARCHAR
 , "PARMNAME"
  POSITION(  00263:00392) VARCHAR
 , "ROWTYPE"
  POSITION(  00393:00393) CHAR(001)
 , "ORDINAL"
  POSITION(  00394:00395) SMALLINT
 , "TYPENAME"
  POSITION(  00396:00525) VARCHAR
 , "LENGTH"
  POSITION(  00526:00529) INTEGER
 , "SCALE"
  POSITION(  00530:00531) SMALLINT
 , "SUBTYPE"
  POSITION(  00532:00532) CHAR(001)
 , "CCSID"
  POSITION(  00533:00536) INTEGER
 , "ENCODING_SCHEME"
  POSITION(  00537:00537) CHAR(001)
 )
/*
//
//*
Step 5: Create Foreign Keys for SQL Server catalog tables
To expedite the process of creating foreign keys for SQL Server catalog tables, Enterprise Developer provides the CREATECATALOGFK.txt file. This file contains SQL Server ALTER TABLE statements that enable foreign keys to be used properly with SQL Server. We recommended that you execute CREATECATALOGFK.txt from SQL Server Management Studio.
Step 6: Run the HCOSS Extract Schema tool against SQL Server
Create an ADO.NET connection to SQL Server using the HCOSS Manage Connections tool or the ADO.NET Connection Editor. Then, run the HCOSS Extract Schema tool:
From the command line:
Use the MFExtractSchemaInfo command with the DB2 argument set to your ADO.NET connection name. Set all other arguments the same as you would when running against DB2 for z/OS. For example:
MFExtractSchemaInfo DB2=HCODEMO; OUT=SCH81010; SCHEMA=DSN81010; TYPELOG=FILE

For complete information on running the Extract Schema tool from the command line, see MFExtractSchemaInfo command.

From the Extract Schema tool UI:
Follow the instructions in the topic To extract DB2 schema objects with the following exception:
  • In step 2, instead of providing a DB2 connection, click SQL Server DSN.

    This turns off the Table Row Count and Both Estimate and Actual options. If the actual table row count is required, use the UI version of the Assess Data Migration tool.

Note: Neither an ADO.NET connection to DB2 for z/OS nor a Microsoft OLE DB2 Provider for DB2 are required.
Parent topic: Extract Schema Tool
Related concepts
ADO.NET Connection Editor
Manage Connections Tool
Schema Extraction Process
Related tasks
To extract DB2 schema objects
To start an Enterprise Test Server command prompt as an administrator
Related reference
MFExtractSchemaInfo command
Required DB2 Catalog Tables


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 OpenText Support for Micro Focus Products in troubleshooting migration issues.

Parent topic: Extract Schema Tool


Extract Schema 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.
Parent topic: Extract Schema Tool


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
  • Enables selection of a dependency mode you can set to determine parent and child objects to include in the transfer. Available from the HCOSS user interface only.
  • 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 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 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 DB2 isolation level, 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 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

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


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


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
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
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
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
    Important: The stored procedures in SYSIBM must execute with permission sufficient to update these tables.
  • 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
Before Using HCO for SQL Server
Application Database Support
Related tasks
To bind from the command line
To manually code a bind script file
Related reference
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: %ALLUSERSPROFILE%\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, %ALLUSERSPROFILE%\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 in standalone mode. If you need instructions, see To start 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 Test 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
Deploying Native Applications
Additional Software Requirements
Extract Schema Tool
Related tasks
To start HCO for SQL Server
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
  • Migrate Databases Tasks
  • Manage Packages and Plans Tasks
  • Bind Applications
Parent topic: HCO for SQL Server (HCOSS)


To start HCO for SQL Server

In standalone mode:
Windows 10 and Later
  • From your Windows desktop, click Start > Enterprise Test Server > HCO for SQL Server.
Important: 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 tasks
To set HCOSS options
Related reference
Options


To set HCOSS options

When running HCOSS tools in standalone mode
  1. From the HCO for SQL Server interface, click Options.
  2. Set options as needed.
    Tip: Context help for each setting appears at the bottom of the window.
  3. Click OK.
Parent topic: How to
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Schema Extraction Process
Related tasks
To start HCO for SQL Server
To extract DB2 schema objects
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.
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 System.Data.SqlClient for SQL Server connections, or Microsoft OLE DB Provider for DB2 for DB2 connections, the Import button is disabled and you cannot import the connection.
    • 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 other then OK or Unknown for at least one connection type. SQL Server connections indicate status for 32- or 64-bit ODBC and 32- or 64-bit CLR 2 or 4 ADO.NET connection types. DB2 connections show 32- and 64-bit CLR 2 and 4 ADO.NET connection types.
  4. Click Repair.
Parent topic: Manage Connections Tasks


Migrate Databases Tasks

  • To extract DB2 schema objects
  • 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 schema objects

  1. From the HCOSS Extract Schema tool, click the Schema Extract tab.
  2. Do one of the following:
    • If using a direct connection to z/OS DB2:
      1. In the Connection group, select DB2 DSN.
      2. From the 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.
    • If using the offline schema extract solution:
      1. In the Connection group, select SQL Server DSN.
      2. From the Connection drop-down list, select the SQL Server connection you created using the Manage Connections tool that points to the SQL Server database containing the schema objects that you want to extract.
        Note: For detailed information about using the offline extract schema solution, see Offline Extract Schema Solution.
  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.
      Note: This option is not available when using the offline extract schema solution.
  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
Offline Extract Schema Solution
Related tasks
To export and import DB2 schemas
To set HCOSS options
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
Options


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 schema objects


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 Dependency Handling drop-down list, select the mode:
    Default | Automatically include all parent objects of the selected object.
    Family tree Automatically include all parent objects of the selected table.

    Automatically include the child objects of each parent object.

    Repeat until no more parents and children are found.

    No dependency handling | Include the selected table only (do not include any parent or child objects).
  6. 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.

  7. To filter the list of available objects, use the fields in the Object Filtering and Selection group. Optional.
  8. 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: When Dependency Handling is set to either Default or Family tree, objects that are automatically added are indicated as inherited.
  9. Optionally, 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.
  10. 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.
    Warning: While the transfer is running, do not to switch to another HCOSS tool. This action could produce an undesirable result. If you must switch to another tool, click Cancel and wait for the transfer process to stop before switching.
  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
  • HCOSS Messages
  • Log Files
  • User Interface Reference
Parent topic: HCO for SQL Server (HCOSS)


Command Line Reference

  • MFConnection command
    Executes the HCOSS Manage Connections tool from the command line.
  • 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


MFConnection command

Syntax

{MFConnection32_v2 | MFConnection32_v4 | MFConnection64_v2 | MFConnection64_v4}
   DSNTYPE={SYSTEM | USER | AZURE};
   CLRVER={2 | 4};
   CTYPE={ODBC | ADONET};
   STYPE={DB2 | SQL};
   MODE={ADD | UPDATE | REMOVE | CHECK | EXIST};
   DSN=connectionName;
   PROVIDER=providerName;
   ADOSAVEP={TRUE | FALSE};
  [SERVER=serverName;]
  [DATABASE=databaseName;]
  [TC={YES | NO};]
  [IC=initialCatalog;]
  [NA=networkAddress;]
  [NP=networkPort;]
  [PC=packageCollection;]
  [CCSID=HostCCSID;]
  [USERID=userId;]
  [PASSWORD=password;]
  [CREPOS={TRUE | FALSE};]
   TYPELOG={CONSOLE | FILE | BOTH};
  [CTIMEOUT=timeOutInSeconds;]
  [LOGFILE=logFileName;]
  [FORCE={TRUE | FALSE};]
  [FMODE={TRUE | FALSE};]

Parameters:

DSNTYPE
Specifies the type of connection to associate with the DSN.
SYSTEM Connection information is specific to the system configuration found in the machine.config file and other relevant system configuration files.
Note: When using a SYSTEM connection and UAC, you must run MFConnection as an administrator.
USER Connection information is specific to the user logged onto Windows.
CLRVER
The Common Language Runtime (CLR) version of an ADO.NET connection. Valid values are 2 or 4. Value required but ignored if CTYPE=ODBC.
CTYPE
Specifies the type of connection. Valid values are ODBC or ADONET.
STYPE
Specifies the server type. Valid values are DB2 or SQL.
MODE
Specifies the action to perform on the connection.
ADD | Establish and catalog the connection.
UPDATE | Update the existing connection. Must also specify the FORCE parameter.
DELETE | Delete the connection.
CHECK | Check the status of the connection.
EXIST | Determine if the connection exists.
DSN
Specifies a name for the connection.
PROVIDER
The name of the provider.
Connection | Value
SQL Server ODBC | The full provider name, for example, ODBC Driver 17 for SQL Server.
SQL Server ADO.NET | System.Data.SqlClient
DB2 | DB2OLEDB
Note: Do not enclose the value in quotes.
ADOSAVEP
Save the ADO.NET connection password. Valid values are TRUE or FALSE. Value required but ignored if CTYPE=ODBC.
SERVER
Server name for the connection. Default is no value.
DATABASE
Database name for the connection. Default is no value.
TC
Trusted connection setting for the connection.
YES | Use Windows Authentication. Default.
NO | Connect by passing login credentials via the USERID and PASSWORD (if required by USERID) parameters.
IC
Initial catalog setting for the connection. Default is no value.
NA
Network address setting for the connection. Default is no value.
NP
Network port setting for the connection. Default is no value.
PC
Package collection setting for the connection. Default is no value.
CCSID
The host CCSID setting for the connection. Default is no value.
USERID
Specifies a user ID to pass to the database. Required for SQL Server connections when TC=NO. Otherwise optional, depending on your database requirements.
PASSWORD
Specifies the password for the user ID specified with the USERID parameter. Required for SQL Server connections when TC=NO and the specified user ID requires a password. Otherwise optional, depending on your database requirements.
CREPOS
Specifies whether or not to validate the connection.
TRUE Validates the connection as follows:
  • The parameters provided on the command line are sufficient to establish a valid connection
  • The parameters provided on the command line are cross referenced with connection details stored in the Windows registry (ODBC connections) and configuration files (ADO.NET connections)
FALSE Validates that the parameters provided on the command line are sufficient to establish a valid connection. Default.
TYPELOG
Sets the type of logging to perform. Valid values are:
  • CONSOLE
  • FILE
  • BOTH (Default)
CTIMEOUT
Sets a timeout value, in seconds, when testing a connection. Default is 5.
LOGFILE
When TYPELOG=FILE or TYPELOG=BOTH, specifies the log file name. The default value is HCOSS-log-file-path\Connections\CONMANtimestamp.log.
FORCE
Force overwrite of existing connection settings. Valid values are TRUE or FALSE. Default is FALSE.

Examples:

To add a system 32-bit ODBC SQL Server connection (CLRVER, ADOSAVEP values are ignored for ODBC connections):

 mfconnection32_v4 DSNTYPE=SYSTEM; CLRVER=2;
CTYPE=ODBC; STYPE=SQL; MODE=ADD; DSN=APP_DSN; PROVIDER=ODBC Driver
17 for SQL Server; ADOSAVEP=FALSE; SERVER=YOURSERVER;
DATABASE=YOURDB; TC=YES; TYPELOG=BOTH;

To add a system 32-bit ADO.NET SQL Server CLR 4 connection:

 mfconnection32_v4 DSNTYPE=SYSTEM; CLRVER=4;
CTYPE=ADONET; STYPE=SQL; MODE=ADD; DSN=APP_DSN;
PROVIDER=System.Data.SqlClient; ADOSAVEP=TRUE; SERVER=YOURSERVER;
DATABASE=YOURDB; TC=YES; TYPELOG=BOTH;

To add a system 32-bit ADO.NET DB2 CLR 4 connection:

 mfconnection32_v4 DSNTYPE=SYSTEM; CLRVER=4;
CTYPE=ADONET; STYPE=DB2; MODE=ADD; DSN=APP_DSN; PROVIDER=DB2OLEDB;
ADOSAVEP=TRUE; USERID=YOURUSERID; PASSWORD=YOURPASSWORD;
NA=YOURIPADDRESS; NP=YOURPORTNUMBER; IC=YOURINITIALCATALOG;
PC=YOURPACKAGECOLLECTION; CCSID=YOURHOSTCCSID;
TYPELOG=BOTH;
Parent topic: Command Line Reference


MFDataTransferCtlr command

Executes the HCOSS Transfer Data tool from the command line.

Syntax:

{MFDataTransferCtlr16 | MFDataTransferCtlr17 | MFDataTransferCtlr19}
  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};]
  [CQUERY="SELECT projectionList FROM tableName [searchCondition][optionalClauses]";]
  [ADJBUF={TRUE | FALSE};]
  [BUFROWS=n;]
  [CSIZE=n;]

Parameters:

MFDataTransferCtlr16
The name of the command for SQL Server 2016.
MFDataTransferCtlr17
The name of the command for SQL Server 2017.
MFDataTransferCtlr19
The name of the command for SQL Server 2019.
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.
CQUERY
Specifies a customized SELECT statement that retrieves data from the source table in which the projection list, optional search condition, and optional clauses can be tailored.
Note: When an expression replaces a column entry in the projection list, the column name has to be maintained by using the same name as the alias. For example, cast(Col1 as binary(8)) as Col1.
ADJBUF
Specifies the AutoAdjustBufferSize property of the DATAFLOW of the SSIS package. Default is FALSE.
BUFROWS
An integer that specifies a value for the DefaultBufferMaxRows property of the DATAFLOW of the SSIS package. Default is 1000.
CSIZE
An integer that specifies a value for the FastLoadMaxInsertCommitSize custom property of the OLE DB Destination of the SSIS package. Default is 1000.

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 | SQLServerConnection;]
                    [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 or, when using the Offline Extract Schema Solution, the name of a cataloged SQL Server 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
Offline Extract Schema Solution
Related tasks
To extract DB2 schema objects
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 Test Server\bin directory.
  • Execute DSN.exe from a command prompt in the %ProgramFiles(x86)%\Micro Focus\Enterprise Test 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
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
Offline Extract Schema Solution
Related tasks
To extract DB2 schema objects
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 Function Mappings
    The default mappings HCOSS uses to convert DB2 aggregate and scalar functions to SQL Server equivalents.
  • Default Special Register Mappings
    The default mappings HCOSS uses to convert DB2 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 Function Mappings

The default mappings HCOSS uses to convert DB2 aggregate and scalar functions to SQL Server equivalents.

Note: In addition to these default mappings, you can also define customized mappings. See Customizing Functions and Special Registers for more information.

z/OS DB2 Aggregate Functions in HCOSS

All of the following aggregate functions are fully supported:

  • AVG
  • COUNT
  • COUNT_BIG
  • MAX
  • MIN
  • STDDEV or STDDEV_SAMP
  • SUM

z/OS DB2 Scalar Functions in HCOSS

HCOSS provides either full or partial support for the following z/OS DB2 scalar functions.

DB2 Function | Support | Implementation1 | Not supported
ABS | Full |  |
ACOS | Full |  |
ADD_MONTHS | Full | ESQL runtime |
ASCII | Full |  |
ASCII_CHR | Full | SQL Name Mapping |
ASIN | Full |  |
ATAN | Full |  |
BIGINT | Full | ESQL runtime |
BINARY | Full | ESQL runtime |
BLOB | Full | ESQL runtime |
CEILING | Full |  |
CHAR | Partial | ESQL runtime | The third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
CLOB | Partial | ESQL runtime | The third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
COALESCE | Full | ESQL runtime |
COMPARE_DECFLOAT | Full |  |
CONCAT | Full | SQL Name Mapping using dbo.CONCAT |
CONCAT_BINARY | Full | SQL Name Mapping using dbo.CONCAT_BINARY |
COS | Full |  |
DATE | Full | ESQL runtime |
DAY | Full | ESQL runtime |
DAYOFMONTH | Full | ESQL runtime |
DAYOFWEEK | Full | ESQL runtime |
DAYOFWEEK_ISO | Full | ESQL runtime |
DAYOFYEAR | Full | ESQL runtime |
DAYS | Full | ESQL runtime |
DBCLOB | Partial | ESQL runtime | The third parameter – CODEUNITS16, or CODEUNITS32
DECFLOAT2 | Partial | ESQL runtime | The second parameter – 16 or 34
DECIMAL or DEC | Partial | ESQL runtime | The optional fourth parameter – decimal character
DEGREES | Full |  |
DIFFERENCE | Full |  |
DIGITS | Full | SQL Name Mapping using dbo.digits |
DOUBLE_PRECISION or DOUBLE | Full | ESQL runtime |
EXP | Full |  |
EXTRACT | Full | ESQL runtime |
FLOAT | Full | ESQL runtime |
FLOOR | Full |  |
GRAPHIC | Partial | ESQL runtime | The third parameter – CODEUNITS16, or CODEUNITS32
HEX | Full | SQL Name Mapping using dbo.hex |
HOUR | Full | ESQL runtime |
IDENTITY_VAL_LOCAL | Full | ESQL runtime |
IFNULL | Full | SQL Name Mapping using COALESCE |
INTEGER or INT | Full | ESQL runtime |
LAST_DAY | Full | SQL Name Mapping using dbo.lastday |
JULIAN_DAY | Full | SQL Name Mapping using dbo.julianday |
LCASE | Full | SQL Name Mapping using LOWER |
LEFT | Partial | ESQL runtime | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
LENGTH | Full | SQL Name Mapping using DATALENGTH |
LN | Full | SQL Name Mapping using LOG |
LOCATE | Partial | ESQL runtime | The optional fourth parameter – CODEUNITS16, or CODEUNITS32
LOG10 | Full |  |
LOWER | Partial |  | The optional second and third parameters are not supported by SQL Server
LPAD | Full | SQL Name Mapping using dbo.LPAD |
LTRIM | Partial |  | The optional second parameter is not supported by SQL Server
MICROSECOND | Full | ESQL runtime |
MIDNIGHT_SECONDS | Full | ESQL runtime |
MINUTE | Full | ESQL runtime |
MOD | Full | ESQL runtime |
MONTH | Full | ESQL runtime |
NEXT_DAY | Full | SQL Name Mapping using dbo.nextday |
POSSTR | Full |  |
POWER | Full | ESQL runtime |
QUARTER | Full | ESQL runtime |
RADIANS | Full |  |
RAND | Full |  |
REAL | Full | ESQL runtime |
REPEAT | Full | SQL Name Mapping using REPLICATE |
REPLACE | Full |  |
RIGHT | Partial | ESQL runtime | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
ROUND | Partial |  | ROUND function in SQL Server does not automatically expand precision for the result if arithmetic overflow occurs. For example, SQL Server treats ROUND(873.726,-3) as error whereas DB2 yields 1000.000
RPAD | Full | SQL Name Mapping using dbo.RPAD |
RTRIM | Partial |  | The optional second parameter is not supported by SQL Server
SECOND | Partial | ESQL runtime | The optional second parameter
SIGN | Full |  |
SIN | Full |  |
SMALLINT | Full | ESQL runtime |
SOUNDEX | Full |  |
SPACE | Full |  |
SQRT | Full |  |
STRIP | Full | SQL Name Mapping using dbo.strip |
SUBSTR | Full | SQL Name Mapping using SUBSTRING |
SUBSTRING | Full | ESQL runtime | The optional fourth parameter – CODEUNITS16, CODEUNITS32, or OCTETS
TAN | Full |  |
TIME | Full | ESQL runtime |
TIMESTAMP | Full | ESQL runtime |
TIMESTAMP_ISO | Full | ESQL runtime |
TIMESTAMPDIFF | Full | ESQL runtime |
TRANSLATE | Full | SQL Name Mapping using dbo.translate |
TRUNCATE or TRUNC | Full | ESQL runtime |
UCASE | Partial | SQL Name Mapping using UPPER | The optional second and third parameters
UNICODE | Full |  |
UPPER | Partial |  | The optional second and third parameters
VALUE | Full | SQL Name Mapping using COALESCE |
VARBINARY | Full | ESQL runtime |
VARCHAR | Partial |  | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
VARGRAPHIC | Partial |  | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
WEEK | Full | ESQL runtime |
WEEK_ISO | Full | ESQL runtime |
XMLQUERY | Full | ESQL runtime |
YEAR | Full | ESQL runtime |
1 When blank, SQL Server and z/OS provide same functionality. 2 The value is converted to FLOAT.
Parent topic: DB2 to SQL Server Conversion Reference


Default Special Register Mappings

The default mappings HCOSS uses to convert DB2 special registers to SQL Server equivalents.

Note: In addition to these default mappings, you can also define customized mappings. See Customizing Functions and Special Registers for more information.

The following table shows supported DB2 special registers and their HCOSS default SQL Server equivalents.

DB2 Special Register | SQL Server Equivalent
CURRENT CLIENT_APPLNAME | APP_NAME()
CURRENT CLIENT_USERID | SYSTEM_USER
CURRENT CLIENT_WRKSTNNAME | HOST_NAME()
CURRENT DATE or CURRENT_DATE | CONVERT(date,SYSDATETIME())
CURRENT TIME or CURRENT_TIME | CONVERT(time(0), SYSDATETIME())
CURRENT TIMESTAMP or CURRENT_TIMESTAMP | CONVERT(datetime2(6), SYSDATETIME())
CURRENT LC_CTYPE or CURRENT_LC_TYPE | CONVERT(char(50), SERVERPROPERTY('collation'))
CURRENT LOCALE LC_CTYPE | CONVERT(char(50), SERVERPROPERTY('collation'))
CURRENT SCHEMA or CURRENT_SCHEMA | CONVERT(varchar(128), SCHEMA_NAME())
CURRENT SERVER | CONVERT(char(16), SERVERPROPERTY('servername'))
CURRENT SQLID | USER
SESSION_USER | USER
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


HCOSS 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: HCOSS 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: HCOSS 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: HCOSS Messages
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schema objects
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: HCOSS 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 - either System.Data.SqlClient for SQL Server connections or Microsoft OLE DB Provider for DB2 for DB2 connections.
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 DSN type | The connection DSN type parameter "DSNTYPE" 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 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 CLRVER | The connection CLR version parameter "CLRVER" 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: HCOSS 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: HCOSS 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 schema objects
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
  • 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.
ODBC Provider
The ODBC provider to be used for the SQL Server. You can select from a drop-down list of installed and supported SQL Server ODBC providers. The connection is updated to use the selected provider.
Status
The last known status of the connection:
Checking | HCOSS is checking the status of the connection
OK | Able to connect
error-message

Unable to make the connection using the supplied information. Each connection type provides detailed information as to why the connection test failed.

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 a status other than OK or Unknown for at least one connection type. SQL Server connections indicate status for 32- or 64-bit ODBC and 32- or 64-bit CLR 2 or 4 ADO.NET connection types. DB2 connections indicate status for 32- or 64-bit CLR 2 or 4 ADO.NET connection types 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.
Set
Displays a dialog box with a drop-down list of installed and supported ODBC providers for SQL Server. All SQL Server connections are updated to the use the selected provider. Affects System or User SQL Server connections.
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.
Parent topic: Manage Connections


DB2 Connection tab

OLE DB Provider
The OLE DB provider to use. The value is always Microsoft OLE DB Provider for DB2.
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.
Host CCSID
Type the DB2 CCSID value to use in program connection strings, or click Get Default to connect to the mainframe using the connection information provided on this tab, and obtain the default CCSID value and populate the field.
Get Default
Connect to the mainframe using the connection information provided on this tab, and obtain the default CCSID value to populate the Host CCSID field.
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 Provider
Provides a drop-down list of installed and supported SQL Server ODBC providers to select for the connection. Available 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
error-message | The connection is established but is not working properly. Each connection type provides detailed information as to why the connection test failed.
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 DSN
The DSN specified in the accompanying field is DB2.
SQL Server DSN
The DSN specified in the accompanying field is SQL Server.
Catalog Schema
The name of an IBM catalog schema to extract.
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 schema objects
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 schema objects


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 schema objects
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


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.
Dependency Handling
Enables you to select a dependency mode to use when creating a list:
Default
Automatically include all parent objects of the selected object.
Family tree
Automatically include all parent objects of the selected table.

Automatically include the child objects of each parent object.

Repeat until no more parents and children are found.

No dependency handling
Include the selected table only (do not include any parent or child objects).
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

DB2 Isolation Level
Enables you to customize the DB2 isolation level. The options are:
CS
Cursor Stability (default)
UR
Uncommitted Read
RS
Read Stability
RR
Repeatable Read
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 is 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

Assessment Tool Options

Tab size
Tab size used in COBOL source. Default is 4.

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.

Extract Schema Options

Cast STATEMENT column to VARCHAR during SysViews extract
True | Fixes view migration issues from z/OS DB2 version 10 and later.
False | Default.

HCOSS Connections

Automatically Test Connections
True | HCOSS automatically tests your established database connections and automatically updates their status.
False | You must update the status of each connection using the Refresh button in the Manage Connections tool. Default.
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 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 %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where genFileType is one of the following:
  • ApplicationAssessments
  • BindTasks
  • CompareTasks
  • DataAssessments
  • 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 %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where genFileType is one of the following:
  • ApplicationAssessments
  • BindTasks
  • CompareTasks
  • DataAssessments
  • 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. Default.
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.
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 %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where logFileType is one of the following:
  • ApplicationAssessments
  • BindTasks
  • CompareTasks
  • Connections
  • DataAssessments
  • DataTasks
  • DBRMTasks
  • 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

Type of HCO for SQL Server Startup
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)
Schema Extraction Process
Related tasks
To start HCO for SQL Server
To set HCOSS options
To extract DB2 schema objects


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. Start the ODBC Data Source Administrator. For instructions, see To start the ODBC Data Source Administrator.
  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.
  • To start the ODBC Data Source Administrator
Parent topic: OpenESQL


To start the ODBC Data Source Administrator

Windows 10 and Later
  • From your Windows desktop, click Start > Windows Administrative Tools > ODBC Data Sources (32-bit) or ODBC Data Sources (64-bit).
Parent topic: ODBC Data Source Administrator
Related tasks
To add a Data Source Name (DSN) for an ODBC driver


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 catalogs 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, 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. See the To start the ADO.NET Connection Editor as an administrator and To start the ADO.NET Connection Editor as a user topics for more information.
  • The ADO.NET Connection Editor works in combinations of 32- or 64-bit and framework 4.0, 4.5, 4.6, 4.7 and 4.8 . Whichever mode you work in, you must have the 32-bit framework 4.0, 4.5, 4.6, 4.7, or 4.8 version of the provider that you want to work with your connection.
  • Connection Terminology
  • Cataloging an ADO.NET or ODBC Connection
  • Exporting and Importing Connections
  • Example Connection Settings
  • How to
  • Reference
Parent topic: OpenESQL
Related concepts
Offline Extract Schema Solution


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 as a user
  • 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 as a user

In standalone mode:
  1. From your Windows desktop, click Start > Enterprise Test Server.
  2. Right-click ADO.NET Connection Editor.
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 catalogued ADO.NET, ODBC, and OleDb 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 System DSNs, or OLE DB Data Providers page.

  8. For .NET providers, continue to the next step. For ODBC and OLE DB providers, do one of the following:
    • For an ODBC system DSN, select a DSN on the ODBC Data Sources 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. 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.
  5. 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 Settings Menu icon menu as required. For a description of each option, see Settings menu.
  3. Click Export Connections on the toolbar. This starts the Export ADO.NET Connections wizard.
  4. Click Next.
  5. On the Connections list, select the data sources you want to export, or check Select all connections. To select more than one connection, hold the Ctrl or Shift key down as you make your selections.
  6. Click Next.
  7. 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.
  8. Click Next.
  9. 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 Import Connections on the toolbar. This starts the Import ADO.NET Connections wizard.
  3. Click Next.
  4. 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.
  5. Select the connections you want to import, or check Select all connections. To select more than one connection, hold the Ctrl or Shift key down as you make your selections.
  6. Click Next.
  7. 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.
Displays the Provider Information window, which shows available provider names and versions for .NET, OLE DB, and ODBC. Information can be filtered on Type, Framework, and Availability.
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 as a user
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
4.0, 4.5, 4.6, 4.7, and 4.8
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. See To start an Enterprise Developer command prompt for instructions.

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 (deprecated) represents .NET Framework versions 2.0, 3.0, or 3.5, and v4 represents .NET Framework 4.0.

Support for .NET Framework versions 3.0 and 3.5, and for the CLR v2 has been deprecated. The option 2 of the ILCLR directive has also been deprecated.

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


SQL Option for DB2

Note: Throughout this documentation, the terms XDB, SQL Option, and SQL Option for DB2 are equivalent.
  • SQL Option User Guide
    This collection of topics provides conceptual information about the main components of the SQL Option for DB2 feature.
  • SQL Option Server Administration Guide
    This collection of topics provides conceptual information about the architecture, configuration, and use of the XDB Server.
  • SQL Option Link Configuration Guide
    This collection of topics provides the information you need to configure SQL Option (XDB) Link to link your applications.
  • SQL Option Preprocesor Guide
    This collection of topics provides information on using the SQL Option Preprocessor to develop applications containing embedded SQL and test them against a full-featured, relational database system.
  • How to...
    Step-by-step instructions on how to use the main components of the SQL Option for DB2 feature.
  • Reference
    Topics that provide reference information on the use of commands and directives, and descriptions of each error message you might encounter when using the SQL Option for DB2 feature. This reference also includes topics that describe the user interface for each SQL Option for DB2 component.
Parent topic: Database Access


SQL Option User Guide

  • Introducing SQL Option for DB2
  • Bind Utility
  • Declaration Generator
  • Gateway Profile Utility (Link Profile)
  • JDBC
  • Migrate Utility
  • Options Utility
  • SQL Wizard
  • Stored Procedures
Parent topic: SQL Option for DB2


Introducing SQL Option for DB2

With SQL Option, you can compile and run programs that contain Embedded SQL statements from the IDE without requiring access to a mainframe or LAN-based database system.

SQL Option uses the same technology as the popular XDB database system. An XDB database behaves exactly like a mainframe DB2 database but it runs on the PC. A personal XDB Server is installed on your PC, providing you with a completely self-contained development and test environment for DB2 applications.

SQL Option allows the EBCDIC environment on the PC to be fully compatible with your mainframe's EBCDIC environment. See the section SQL Option NLS Environment for details.

If you are developing in a workgrouping environment, your system administrator can configure SQL Option so that you can access one or more shared, LAN-based XDB Servers in addition to your personal XDB Server. This two-tier configuration provides you with several further options for testing your application. For example, you can:

  • Maintain a complete copy or a subset of your mainframe test data on a shared XDB Server. Members of your workgroup can test against this directly or import the necessary tables into their personal XDB Server in situations where data needs to be isolated from other users.
  • Duplicate test data on the shared XDB Server and workgroup members' personal XDB Servers. The shared XDB Server can then be used for integration testing, with workgroup members performing development and unit tests against their personal XDB Servers.
  • Distribute data across a shared XDB Server and personal XDB Servers. For example, larger, more static tables can be left on the shared XDB Server, with smaller, more volatile tables being exported to the PC.

In addition, with appropriate configuration, you can access mainframe DB2 databases seamlessly with SQL Option's connectivity features. With this third tier configured, you have access to the full range of development and test options, giving you complete freedom to devise an effective workflow customized to your environment. For example, you can:

  • Use the mainframe DB2 test environment for all testing
  • Use the mainframe for integration testing, with workgroup members performing development and unit tests against either their personal XDB Servers or a shared XDB Server
  • Distribute test data across all three tiers, keeping very large tables on the mainframe and providing others on a shared XDB Server. Workgroup members can then download specific data to their personal XDB Server where necessary for isolation purposes.
  • SQL Option Tools
  • SQL Option NLS Environment
  • Using Existing XDB Data
  • SQL Option Demonstration Programs
  • Tips
Parent topic: SQL Option User Guide


SQL Option Tools

SQL Option for DB2 consists of an embedded SQL precompiler and a number of client, configuration, and server tools, and graphical data utilities:

  • XDB Server
  • SQLWizard
  • Migrate utility
  • Options utility
  • Bind utility
  • XDB Link
  • Gateway Profile utility
  • Declaration Generator utility
  • SQL Option Preprocessor

For information on starting an SQL Option tool, see To access SQL Option for DB2 tools.

Parent topic: Introducing SQL Option for DB2


SQL Option NLS Environment

SQL Option allows you to create XDB locations that emulate all the various mainframe EBCDIC code pages. When you access these locations with SQL Wizard or a COBOL program, your data in these locations appears identical to the data on the mainframe.

The five steps necessary to ensure complete compatibility with the mainframe and/or your COBOL development system are as follows:

  1. Decide which EBCDIC code page you want to emulate.

    Typically, you would use the mainframe's code page. (If you do not know what it is, you may be able to use XDB Link to find out.) If you do not have a mainframe, you can choose whichever code page you prefer.

  2. Create a local EBCDIC location for this code page.

    Use SQL Wizard's Create Location dialog box. Pick the EBCDIC code page you want in the Sort Sequence box.

  3. Ensure that your project's national language support (NLS) setting is the same as your EBCDIC location.

    When you compile a COBOL program with Enterprise Developer, it can be associated with a particular EBCDIC code page.

  4. If you have XDB Link, configure it to access the mainframe.

    Use the Gateway Profile utility to define your DB/2 locations to the PC software, then specify the single Workstation Code Page as 911 (in the local Workstation Configuration). Next, use SQL Wizard to access the DB/2 location on the mainframe. A file named cpg_info.txt is created in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bindirectory by default, identifying the EBCDIC code page of the DB/2 location on the mainframe. The following table defines this EBCDIC code page number:

    NLS Setting | Code Page Number
    31 Dutch | 37
    33 French | 297
    34 Spanish | 284
    39 Italian | 280
    43 Austrian German | 273
    44 English (UK) | 285
    45 Danish | 277
    46 Swedish | 278
    47 Norwegian | 277
    49 German | 273
    351 Portugese | 37
    358 Finnish | 278
    437 English (US) | 37
    500 International | 500
  5. Populate your local EBCDIC location with data from the mainframe.

    If you have XDB Link for the mainframe, there are two ways to do this: using Migrate or using SQL Wizard.

    • To use Migrate, all you need to do is point to the DB/2 location on your mainframe as the source location, and point to the local EBCDIC location as the destination location.
    • To use SQL Wizard, first export your mainframe's data in DSNTIAUL format, then import it into SQL Wizard. When you use the DSNTIAUL format, you need to specify a code page translation for both exports and imports: for exports, use the PC's ANSI code page to EBCDIC code page translation; for imports, use the reverse translation. For example, suppose you want to extract from a Swedish EBCDIC DB/2 location. For the export, you would pick the ANSI to EBCDIC translation 1252 - 278, for the import, 278 - 1252.

    If you don't have XDB Link for the mainframe, extract the data from the mainframe into a file with DSNTIAUL format, then import the data into your local EBCDIC location using SQL Wizard's import function, citing the appropriate EBCDIC to ANSI code page translation.

XDB EBCDIC databases are stored using the default OEM character set for your machine (typically, code page 437 in the United States, or code page 850 almost everywhere else). The names of database objects such as tables and indexes are also validated using this character set. You can optionally specify that database object-names should be validated using any of the following character sets if, for example, you want to use accented characters in the names:

MS-DOS Code Page | Character Set
437 | US Latin 1
850 | International Latin 1
857 | Turkish
863 | French Canada
865 | Nordic
860 | Portuguese

To specify that an XDB Server should use one of the supported code pages for name validation, you must add two lines to the xdb.ini file in %ProgramData%\Micro Focus\Enterprise Developer\mfsql\cfg:

[SERVER] XDBCP=codepage

where codepage is the three-digit number of the code page you require.

Where a location has been created as an EBCDIC location (for example, the default location, MAINTAIN), data is automatically converted to EBCDIC before it is passed to the client application. Conversion between ASCII data on the PC and EBCDIC data on the mainframe is handled by the DB2 Link gateway if you are using the Migrate utility. If you are using the data import and export facilities in SQL Wizard, you can control the conversion used by choosing the DSNTIAUL data format and selecting an appropriate code page conversion. See the topics Import/Export NSL Considerations for more information.

For information about EBCDIC conversions and the Data File Converter, see the topic Converting Data Files.

Parent topic: Introducing SQL Option for DB2


Using Existing XDB Data

If you already use XDB databases, you might be able to access them using SQL Option for DB2, providing that the locations in which they were created are compatible.

Parent topic: Introducing SQL Option for DB2


SQL Option Demonstration Programs

To help you get working with SQL Option as quickly as possible, we supply several demonstration programs located in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\sql\xdb folder. The following lists each demonstration program and summarizes the functionality demonstrated by each:

test1.cbl | OPEN, FETCH, CLOSE, DELETE, and EXECUTE IMMEDIATE statements
test2.cbl | Scrolling through records and entering Y or N at the prompt
test3.cbl | CREATE TABLE, ALTER TABLE, UPDATE, and CREATE INDEX statements
test4.cbl | Joining tables
test5.cbl | Using Dynamic SQL PREPARE and EXECUTE statements
test6.cbl | OPEN, FETCH, UPDATE, DELETE, and CLOSE statements
OO_Sample.app | Coding an OO application for use with the SQL Option
Parent topic: Introducing SQL Option for DB2


Tips

  • Use the Query Design window in SQL Wizard when you want to add new DML commands to your program but are not sure of the correct syntax. Create your query and run it until you are happy that results are correct. Then open the SQL window and copy the SQL statements into your program, between the EXEC SQL and the end-of-procedure statements.
  • If you are writing a program that needs to create a table and you have a test table with the correct structure, use SQL Wizard's Export capabilities to generate the DDL commands for your program.
  • If you create date columns in a test table using the WITH DEFAULT constraint, you can use the Date Warp feature of the IDE to change the system date on a row-by-row basis, without having to restart the XDB Server.
  • SQL Option automatically commits changes to a database when the end of a program procedure is reached with no errors. If an error occurs or if you stop debugging prior to reaching the end of a procedure, a rollback is performed instead. You do not need to use the LOGOFF directive when running a COBOL application.
Parent topic: Introducing SQL Option for DB2


Bind Utility

The Bind utility enables you to create static SQL packages in a remote DB2 location accessed using DRDA, providing that the target location is registered appropriately at the DB2 Link gateway and that your AuthID has Bind authority at the target location.

The Bind Utility generates a static package in DB2 from the contents of a local database request module (DBRM). A package is a single, bound DBRM containing optimized access paths to data. A DBRM contains all the information needed to create a package in a remote database.

Every application that runs against DB2 (including XDB Link) must have an application package to support the execution of statically-bound and dynamic SQL contained in the program. You must create a default package for XDB Link for each DB2 location with which you want to use the Link. See the Link Configuration Guide for more information.

Use the Bind Utility if you are configuring the XDB Link and you are ready to create a default DBRM and package for the Link, or you used the Static Bind Administrator to generate a DBRM and package for your application and you would like to modify or drop the package.

Note:

You do not need to bind your application if you use the default SQL precompiler settings, as these enable Embedded SQL statements in your programs to be run dynamically against the remote system. Running Embedded SQL dynamically is useful in situations where you want to access remote DB2 data but do not want to keep rebinding your application as it changes; for example, while debugging the application. You can optionally change the precompiler settings to produce static SQL database request modules to bind the application for deployment purposes. For more information on the precompiler options, see the topic XDB Directive Options.

A package at a location is identified by a collection identifier, a program identifier, a version label and a consistency token. Typically, you would use the collection identifier as a way of grouping the packages used in a single application consisting of one or more programs. The precompiler creates a program identifier for a package from the root of the program filename. You can specify a version label or accept the default value (01). You do not have to specify a version label, because the current package can be identified from its consistency token, generated from a timestamp at the start of precompilation. Note that each time you recompile a DB2 application, the timestamp changes and you must rebind the application to the DB2 host location if you are using static SQL packages. An alternative approach to avoid having to rebind your application each time you compile it is to debug against data stored in an EBCDIC location on your personal XDB Server. You can then test it against mainframe data when you have achieved a satisfactory level of stability.

The Bind utility enables you to specify a number of options for an application, including a version number and the isolation level of the application. These options can be stored in a file for future use.

Parent topic: SQL Option User Guide


Declaration Generator

The Declaration Generator automates the process of creating copybooks to declare host variables. You specify the table for which you want to generate a copybook and the Declaration Generator creates a copybook with data declarations that match the data names and types used in the XDB system. The Declaration Generator can be used interactively or in batch mode and can create a separate copybook for each table or one copybook containing declarations for many tables.

You can use the Declaration Generator to declare a table in C, COBOL or PL/I. For each language, the Declaration Generator creates a complete SQL DECLARE statement and the appropriate record definition (COBOL) or structure (C and PL/I). Depending upon the language, the following file types are created:

Language | Declaration File
COBOL | Copybook file (.cpy file)
C | Header file (.h file)
PL/I | Include file (.inc file)

You can run the Declaration Generator interactively (from a dialog box) or in batch mode (from the command line). Batch mode is useful for generating declarations for many tables at one time.

Regardless of whether you run the Declaration Generator interactively or in batch mode, you must specify the following:

  • The name of the table for which you want to generate a declaration file. Unless you specify otherwise, the name of the table is used as the name of the structure (C and PL/I) or record (COBOL).
  • The programming language in which you want the declaration written.
  • The name of the file to which the declaration statements will be written. The Declaration Generator automatically affixes the correct extension to the file name depending upon the programming language you select. If you specify a file that already exists, you can replace it or append the new statements to it.

You can specify language-dependent options. For example, when you create a COBOL declaration, you can select the computation type for whole-number fields; when you create a C declaration, you can select upper or lowercase element names.

To access DB2 data from an application program, you need to create host variables that are common data items between the SQL statements in your query and in your program. A data item declaration in the program must have the same name as that used in your SQL statement and must conform to the relevant DB2 data type for the column concerned.

  • Examples
Parent topic: SQL Option User Guide


Examples

  • Example COBOL Declaration
  • Example C Structure
  • Example Transaction Statement
Parent topic: Declaration Generator


Example COBOL Declaration

The following shows the result of a COBOL declaration. In this example, level 2 was assigned to the record definition.

01 DCLEMPLOYEE.
  2 E-NO PIC S9(4) COMP.
  2 LNAME PIC X(10).
  2 FNAME PIC X(10).
  2 STREET PIC X(20).
  2 CITY PIC X(15).
  2 ST PIC X(2).
  2 ZIP PIC X(5).
  2 DEPT PIC X(4).
  2 PAYRATE PIC S9(13)V9(2) COMP-3.
  2 COM PIC SV9(2) COMP-3.
Parent topic: Examples


Example C Structure

The following shows the result of a C declaration. In this example, the structure was declared without using the Declare The Structure option. Therefore, the structure describes a data type (called dcl_employee), but does not declare it as a variable. In this example, field prefixing has not been used.

struct dcl_employee
  {
  short e_no;
  char lname[11];
  char fname[11];
  char street[21];
  char city[16];
  char st[3];
  char zip[6];
  char dept[5];
  double payrate;
  double com;
  };
  short c_employee_ind[10];

Note that an array called c_employee_ind is also declared after the structure. This array is to be used to hold the null indicators for this table. (for example, c_employee_ind[0] can hold the indicator for e-no, c_employee_ind[1] the indicator for lname, c_employee_ind[2] the indicator for fname, and so forth).

Parent topic: Examples


Example Transaction Statement

The following example shows a simple transaction statement. In this example, the Declaration Generator reads the EMPLOYEE table and writes a declaration file called EMP_FILE.CPY. Because a language is not specified, COBOL is assumed.

employee emp_file.cpy

In a batch declaration file with multiple transactions, each transaction must be entered on a separate line, with no blank lines between them. The following example shows a .DGE file containing three transactions.

employee employee.cpy l=cobol s=dclempl p=sales u=real c=4 v=4
employee employee.h l=c s=c_employee p=sales u=real
orders orders.h l=c s=c_orders u=n/a a=upper d=decl

This example produces COBOL and C language output for the EMPLOYEE table. C output is also created for the ORDERS table.

Parent topic: Examples


Gateway Profile Utility (Link Profile)

Host (mainframe) teleprocessing applications are usually designed for standard terminal environments that access large enterprise data stores. These applications do not usually have the power and graphics capabilities of PCs. While host applications are limited in this way, PC applications are also usually limited to processing local data in development or limited-production modes.

With XDB Link, you can combine both environments in a distributed application running on the PC or host and have access to both host and PC relational databases.

XDB Link consists of 32-bit software components based on IBM's Distributed Relational Database Architecture (DRDA), which specifies a standard way for different relational databases on different operating systems to communicate over a network. XDB Link runs on Windows servers, with a copy of the XDB Server relational database management system and a copy of a communication subsystem:

These communication subsystems provide APPC and TCP/IP protocol support.

XDB Link uses client/server architecture that allows networked PCs access to host data using IBM's DRDA.

PCs have access to host data through XDB Link AR (Application Requester). The Application Requester allows remote DBMS platforms to broadcast requests for RDBMS access across the Systems Network Architecture (SNA) network.

  • Link AR
  • XDB Link AR Architecture
  • XDB Link AR Security
  • XDB Link Installation and Configuration
  • Gateway Profile Utility
  • Host Option for TCP/IP
  • Code Mappings
  • Troubleshooting XDB Link Issues
Parent topic: SQL Option User Guide


Link AR

XDB Link AR allows your PC applications to quickly and easily access different types of host data, bringing the power of PC processing and graphical user interfaces to enterprise-wide data applications. XDB Link AR gives you access to host data for both development and production PC applications.

PC production application support is provided by remote static bind access from the PC to create static SQL packages on the host. Code page translation between PC and host platforms is provided in XDB Link.

When using the optional XDB Link host option for MVS in conjunction with XDB Link AR, additional SQL and non-SQL host data can be accessed through the use of remote procedures and the Customer Information Control System (CICS). XDB Host option also provides TCP/IP access from the PC.

Parent topic: Gateway Profile Utility (Link Profile)


XDB Link AR Architecture

XDB Link AR consists of two main components: the Gateway on the PC and the optional host component on the mainframe. XDB Link AR also enables SQL applications in a PC LAN environment to access host-based relational databases without providing special application code for network traversal or data type conversion.

Parent topic: Gateway Profile Utility (Link Profile)


XDB Link AR Security

Security for XDB Link AR is handled by the XDB Server and your existing mainframe security scheme. The user is required to provide user ID and password before accessing local or remote data.

If Global Security is turned on and the location includes the XDB Server, then the security scheme is controlled by the existing scheme on the host. Otherwise, when using XDB Server, you must set up user IDs and passwords that match the user IDs and passwords on the remote DBMS. For example, if you have a user ID of 'DAVIDH' for DB2, you should also create a user ID of 'DAVIDH' for XDB Server. This is easily accomplished with the User Administration function of SQLWizard.

If you are using the host option of XDB Link AR, you can set up additional security on the mainframe. The host programs can be secured by external security managers, such as RACF or Top Secret, and can be maintained from the PC through XDB Link AR using the PEM utility. This process is described in the Link Configuration Guide.

Parent topic: Gateway Profile Utility (Link Profile)


XDB Link Installation and Configuration

XDB Link provides a very powerful and easy-to-use method for cooperative processing to access both PC and mainframe data. XDB Link can be used in a variety of ways, depending upon corporate requirements. Listed below are the basic steps to get your application up and running with XDB Link. For more detailed instructions, see the Link Configuration Guide.

To install the client, some sort of client application is required. The client application can be another Micro Focus product, or, it could be an application developed using a Micro Focus interface.

The XDB Server software must be installed, configured, and started. It is the mechanism for transferring information to and from the mainframe, as well as maintaining XDB Server databases. This step assumes that the SNA or TCP/IP communications utility for your operating system has been installed on the XDB Server machine (such as NetWare SAA server). The Gateway installation and configuration procedure is outlined in the Link Configuration Guide

In addition (if not using Global Security), you must use SQLWizard to create user IDs to match those used on the mainframe. See the SQLWizard documentation for specific procedures.

If the host option was purchased, it must be installed and configured. This option is necessary if you want TCP/IP access to DB2 or if you want to use TCP/IP. See the Link Configuration Guide for details on installing the host software.

The host option does not need to be installed for DRDA access to remote locations.

Before the XDB Server can access mainframe locations, you must provide certain information about these locations. This information is registered in the communication database. Use the Gateway Profile utility to register mainframe locations that you want to access.

Use the Bind utility to create default database request modules (DBRM) for each of your DRDA locations. Bind this DBRM on each remote DRDA location you want to access via XDB Link AR. The package created when the DBRM is bound is used by all applications when accessing DRDA data via XDB Link AR.

Embed SQL statements in COBOL, use a Micro Focus application programming interface, or build your ODBC application. Create a program that has remote procedure calls.

Run the program you have created or run an XDB Server database management utility.

Be sure to read the instructions for installing and configuring XDB Link AR before attempting to access remote data.

Parent topic: Gateway Profile Utility (Link Profile)


Gateway Profile Utility

Before clients can access data from remote locations, you must use the Gateway Profile Utility to:

  • Define remote locations to the XDB Link so that client applications can access data in those locations
  • Configure the settings the XDB Link needs to translate data correctly and control client conversations

After the initial configuration, you can use the Gateway Profile Utility to modify existing settings or define additional remote locations.

The XDB Link may be installed:

  • On an XDB Server machine as part of a gateway configuration

    or

  • On an client machine as part of a direct-connect configuration

If you are configuring the Link on an XDB Server machine as part of a gateway configuration, see the topic Configuring XDB Link with the Gateway Profile Utility before you run the Gateway Profile Utility.

To display the main window of the Gateway Profile Utility, double-click the Gateway Profile Utility icon.

Parent topic: Gateway Profile Utility (Link Profile)
Related information
Configuring XDB Link with the Gateway Profile Utility
Configuring the Link for a Gateway Server


Host Option for TCP/IP

With the XDB Link Host Option for TCP/IP (or Host Option for TCP/IP) installed, the XDB Link can use the TCP/IP protocol to access DB2 data on the host. The XDB Link becomes a TCP/IP multi-user, multi-threaded server that processes DRDA-compliant requests for access to DB2 over a TCP/IP network.

The Host Option for TCP/IP consists of:

  • Scheduler Subsystem
  • LU 6.2 Communications Subsystem
  • TCP/IP Communications Subsystem
  • Administrative Subsystem
  • Trace Facility
  • Scheduler Subsystem
  • LU 6.2 Communications Subsystem
  • TCP/IP Communications Subsystem
  • Administrative Subsystem
  • Trace Facility
  • Issuing Commands to the Host Option for TCP/IP
  • Access List Message
Parent topic: Gateway Profile Utility (Link Profile)


Scheduler Subsystem

The scheduler subsystem is the main task of the Host Option for TCP/IP. It initializes subtasks and creates an environment based on system parameters in the parameter file. It also initializes the access list.

Parent topic: Host Option for TCP/IP


LU 6.2 Communications Subsystem

The LU 6.2 communications subsystem opens the Host Option for TCP/IP and initializes control blocks to interface with ACF/VTAM. When a client requests a connection to the remote DB2 location, it initializes a PLU of the DB2 LU 6.2 block and allocates a conversation with client-supplied information such as user ID, password and DB2 APPLID LU name.

This subsystem fills all necessary Function Management Header (FMH5) file information including LUWID. It transfers DDM flow to the remote DB2 location and receives messages from DB2. In case of an LU 6.2 communication error, the LU 6.2 communications subsystem formats an error packet and schedules a transmission request to the TCP/IP subtask.

Parent topic: Host Option for TCP/IP


TCP/IP Communications Subsystem

This task handles all TCP/IP traffic to and from clients. It accepts client connection requests and validates requester's IP addresses based on the access list. It creates multitasking subtasks to communicate with multiple clients.

How to...

Parent topic: Host Option for TCP/IP


Administrative Subsystem

The administrative subsystem manages the task and displays:

  • Conversation status.
  • PLU status.
  • Information about an XDB Link-started task through WTOR operator console commands.
Parent topic: Host Option for TCP/IP


Trace Facility

The trace facility cuts GTF trace records for diagnostic purposes and to establish audit trails. A system administrator assigns the GTF event ID in the started task parameter.

Parent topic: Host Option for TCP/IP


Issuing Commands to the Host Option for TCP/IP

There are several administrative commands that can be issued to control the Host Option for TCP/IP and to check its status. These commands are entered as replies to the following WTOR (Write To Operator with Reply) message prompt (which is displayed on the system console when you start the Host Option for TCP/IP):

@08 Enter XDBLINK Command

All Host Option for TCP/IP commands are issued in the following format:

R nn,command

where:

nn is the reply number message related to the Host Option for TCP/IP, and

command is the name of the Host Option for TCP/IP command.

Parent topic: Host Option for TCP/IP


Access List Message

When the Host Option for TCP/IP is installed, a list of client IP addresses to be permitted or rejected is created (the Link Configuration Guide describes how to create this list). If the Host Option for TCP/IP receives a request from a client that is not in this list, a WTOR message is issued to the system console.

The operator can issue a PERMIT to accept the connection or REJECT to reject the connection. Issuing a PERMIT temporarily grants access to the requesting client.

The following example shows a WTOR message followed by both possible operator responses:

@08 Enter XDBLINK Action Command for IP: 204.177.148.64
R 8,PERMIT
R 8,REJECT
Parent topic: Host Option for TCP/IP


Code Mappings

  • SQLCODE (DB2 Mode)
  • SQLCODE (XDB Mode)
  • SQLERRD
  • SQLSTATE Values
  • SQLSTATE Values (sorted by DB2 Code)
  • SQLSTATE Values (sorted by SQLSTATE Code)
Parent topic: Gateway Profile Utility (Link Profile)


SQLCODE (DB2 Mode)

SQLCODE is an element of the SQLCA that stores a warning or return code from an SQL process. If you are running in DB2 mode, the value in SQLCODE is a DB2 warning or return code. To determine the appropriate error code, you must translate it into an XDB error message ID using the formula listed in the table below.

SQLCODE Value | Error Type | Formula | Msg File
-1 to -999 | Remote DBMS Error | Take absolute value and prefix with "L" | XDBMF.XRR
-1001 to -1650 | Database Engine Error | Take absolute value, subtract 1000, prefix with "X". | XDBRES.XRR
-1651 to -3000 | Network Error | Take absolute value, subtract 1650, prefix with "N". | XDBNET.XRR
-3001 to -29,999 | Not used. | -- | --
-30,000 to -30,100 | Distributed DBMS Communication Error | Take absolute value and prefix with "L". | XDBMF.XRR
Note:

Error messages -1 through -999 and -30,000 through -30,100 that come back through XDB Link are native to the remote DBMS being accessed.

Parent topic: Code Mappings


SQLCODE (XDB Mode)

The following table describes the SQLCODE values when you are running in XDB mode.

SQLCODE is an element of SQLCA that stores the error code returned by an SQL process. If you are running in XDB mode, the value in SQLCODE is expressed as XDB error code. To determine the appropriate error code, you must translate it into an XDB error message ID using the formula listed in the table below.

SQLCODE Value | Error Type | Formula | Msg File
-1 to -650 | Remote DBMS Error | Take absolute value and prefix with "L". | XDBMF.XRR
-651 to -2000 | Database Engine Error | Take absolute value, subtract 1000, prefix with "X" | XDBRES.XRR
-2001 to -3000 | Network Error | Take absolute value, subtract 1650, prefix with "N" | XDBNET.XRR
-3001 to -3999 | Not used. | -- | --
-4000 to -4,100 | Distributed DBMS Communication Error | Take absolute value and prefix with "L". | XDBMF.XRR
Parent topic: Code Mappings


SQLERRD

The SQLERRD(1) element in SQLCA contains the XDB error code returned by an SQL process. If you are running in DB2 mode, the DB2-equivalent of this error code is contained in SQLCODE (See the topic SQLCODE (DB2 Mode)).

To determine the appropriate error code, you must translate it into an XDB error message ID using the formula listed in the table below.

SQLERRD(1) Value | Error Type | Formula | Msg File
-1 to -650 | Database Engine Error | Take absolute value and prefix with "X". | XDBRES.XRR
-651 to -2000 | Network Error | Take absolute value, subtract 650, prefix with "N". | XDBNET.XRR
-2001 to -3000 | Not Used | -- | --
-3001 to -3999 | Remote DBMS Error | Take absolute value, subtract 3000, prefix with "L". | XDBMF.XRR
-4000 to -4,100 | Distributed DBMS Communication | Take absolute value, add -26,000, and prefix with "L". | XDBMF.XRR
Parent topic: Code Mappings


SQLSTATE Values

The following table describes the ANSI equivalents to XDB mode and DB2 error codes. The ANSI error value is stored in the SQLSTATE element of SQLCA.

XDB mode SQLCODE | DB2 SQLCODE | ANSI SQLSTATE
+100 | N/A | 02000
0 | N/A | 00000
-2 | -198 | 37517
-4 | -405 | 53020
-6 | -102 | 54002
-7 | -10 | 37503
-9 | -206 | 52003
-11 | -401 | 53018
-12 | -401 | 53018
-16 | -501 | 24501
-18 | -803 | 23505
-19 | -101 | 54001
-20 | -84 | 37512
-23 | -302 | 22001
-26 | -129 | 54004
-28 | -159 | 52004
-32 | -913 | 40502
-35 | -913 | 40502
-40 | -803 | 23505
-43 | -402 | 53019
-44 | -685 | 58002
-46 | -602 | 54008
-47 | -107 | 54003
-48 | -601 | 52010
-50 | -614 | N/A
-51 | -603 | 22515
-54 | -117 | 53002
-55 | -121 | 52001
-56 | -601 | 52010
-57 | -117 | 53002
-58 | -408 | 53021
-59 | -404 | 22001
-61 | -680 | 54011
-66 | -125 | 53005
-71 | -412 | 53023
-72 | -112 | 37507
-73 | -122 | 53003
-75 | -122 | 53003
-76 | -913 | 40502
-79 | -150 | 56013
-80 | -127 | 56005
-82 | -421 | 53026
-83 | -415 | 53025
-86 | -407 | 23502
-87 | -107 | 54003
-88 | -107 | 54003
-91 | -551 | 42501
-103 | -119 | 53003
-104 | -607 | 53032
-106 | -155 | N/A
-108 | -153 | 56008
-118 | -601 | 52010
-119 | -107 | 54003
-124 | -607 | 53032
-125 | -514 | 26501
-127 | -414 | 53024
-130 | -618 | 53032
-138 | -156 | 53009
-140 | -160 | 53013
-141 | -161 | 23501
-144 | -652 | 23501
-146 | -616 | 23503
-153 | -913 | 40502
-154 | -913 | 40502
-155 | -913 | 40502
-156 | -911 | 40000
-157 | -913 | 40502
-158 | -913 | 40502
-159 | -913 | 40502
-160 | -913 | 40502
-174 | -601 | 52010
-177 | -107 | 54003
-179 | -604 | 37511
-185 | -126 | 53029
-188 | -305 | 22002
-212 | -104 | 37501
-214 | -502 | 24502
-215 | -501 | 24501
-227 | -531 | 23504
-228 | -532 | 23504
-229 | -530 | 23503
-231 | -510 | 53028
-244 | -118 | 56002
-246 | -534 | 21502
-247 | -181 | 22007
-277 | -551 | 42501
-278 | -553 | 42503
-279 | -107 | 54003
-280 | -204 | 52004
-281 | -601 | 52010
-284 | -637 | 37514
-287 | -513 | 56024
-288 | -512 | 56023
-289 | -644 | 37515
-290 | -620 | 53001
-291 | -199 | 37501
-305 | N/A | 22002
-343 | -925 | 56201
-344 | -926 | 40502
-803 | N/A | 23505
-811 | N/A | 21000
Parent topic: Code Mappings


SQLSTATE Values (sorted by DB2 Code)

The following table describes the ANSI equivalents to an XDB mode error codes. The ANSI error value is stored in the SQLSTATE element of the SQLCA.

DB2 SQLCODE | XDB mode SQLCODE | ANSI SQLSTATE
N/A | -811 | 21000
N/A | -803 | 23505
N/A | +100 | 02000
N/A | 0 | 00000
N/A | -305 | 22002
-10 | -7 | 37503
-84 | -20 | 37512
-101 | -19 | 54001
-102 | -6 | 54002
-104 | -212 | 37501
-107 | -47 | 54003
-107 | -87 | 54003
-107 | -88 | 54003
-107 | -119 | 54003
-107 | -177 | 54003
-107 | -279 | 54003
-112 | -72 | 37507
-117 | -54 | 53002
-117 | -57 | 53002
-118 | -244 | 56002
-119 | -103 | 53003
-121 | -55 | 52001
-122 | -73 | 53003
-122 | -75 | 53003
-125 | -66 | 53005
-126 | -185 | 53029
-127 | -80 | 56005
-129 | -26 | 54004
-150 | -79 | 56013
-153 | -108 | 56008
-155 | -106 | N/A
-156 | -138 | 53009
-159 | -28 | 52004
-160 | -140 | 53013
-161 | -141 | 23501
-181 | -247 | 22007
-198 | -2 | 37517
-199 | -291 | 37501
-204 | -280 | 52004
-206 | -9 | 52003
-302 | -23 | 22001
-305 | -188 | 22002
-401 | -11 | 53018
-401 | -12 | 53018
-402 | -43 | 53019
-404 | -59 | 22001
-405 | -4 | 53020
-407 | -86 | 23502
-408 | -58 | 53021
-412 | -71 | 53023
-414 | -127 | 53024
-415 | -83 | 53025
-421 | -82 | 53026
-501 | -16 | 24501
-501 | -215 | 24501
-502 | -214 | 24502
-510 | -231 | 53028
-512 | -288 | 56023
-513 | -287 | 56024
-514 | -125 | 26501
-530 | -229 | 23503
-531 | -227 | 23504
-532 | -228 | 23504
-534 | -246 | 21502
-551 | -91 | 42501
-551 | -277 | 42501
-553 | -278 | 42503
-601 | -48 | 52010
-601 | -56 | 52010
-601 | -118 | 52010
-601 | -174 | 52010
-601 | -281 | 52010
-602 | -46 | 54008
-603 | -51 | 22515
-604 | -179 | 37511
-607 | -104 | 53032
-607 | -124 | 53032
-614 | -50 | N/A
-616 | -146 | 23503
-637 | -284 | 37514
-644 | -289 | 37515
-652 | -144 | 23501
-680 | -61 | 54011
-685 | -44 | 58002
-803 | -18 | 23505
-803 | -40 | 23505
-911 | -156 | 40000
-913 | -32 | 40502
-913 | -35 | 40502
-913 | -76 | 40502
-913 | -153 | 40502
-913 | -154 | 40502
-913 | -155 | 40502
-913 | -157 | 40502
-913 | -158 | 40502
-913 | -159 | 40502
-913 | -160 | 40502
-925 | -343 | 56201
-926 | -344 | 40502
Parent topic: Code Mappings


SQLSTATE Values (sorted by SQLSTATE Code)

The following table describes the ANSI equivalents to an XDB mode error codes. The ANSI error value is stored in the SQLSTATE element of the SQLCA.

ANSI SQLSTATE | XDB mode SQLCODE | DB2 SQLCODE
N/A | -50 | -614
N/A | -106 | -155
00000 | 0 | N/A
02000 | +100 | N/A
21000 | -811 | N/A
21502 | -246 | -534
22001 | -23 | -302
22001 | -59 | -404
22002 | -188 | -305
22002 | -305 | N/A
22007 | -247 | -181
22515 | -51 | -603
23501 | -141 | -161
23501 | -144 | -652
23502 | -86 | -407
23503 | -229 | -530
23503 | -146 | -616
23504 | -227 | -531
23504 | -228 | -532
23505 | -18 | -803
23505 | -40 | -803
23505 | -803 | N/A
24501 | -16 | -501
24501 | -215 | -501
24502 | -214 | -502
26501 | -125 | -514
37501 | -291 | -199
37501 | -212 | -104
37503 | -7 | -10
37507 | -72 | -112
37511 | -179 | -604
37512 | -20 | -84
37514 | -284 | -637
37515 | -289 | -644
37517 | -2 | -198
40000 | -156 | -911
40502 | -32 | -913
40502 | -35 | -913
40502 | -76 | -913
40502 | -153 | -913
40502 | -154 | -913
40502 | -155 | -913
40502 | -157 | -913
40502 | -158 | -913
40502 | -159 | -913
40502 | -160 | -913
40502 | -344 | -926
42501 | -277 | -551
42501 | -91 | -551
42503 | -278 | -553
52001 | -55 | -121
52003 | -9 | -206
52004 | -28 | -159
52004 | -280 | -204
52010 | -48 | -601
52010 | -56 | -601
52010 | -118 | -601
52010 | -174 | -601
52010 | -281 | -601
53001 | -290 | -620
53002 | -54 | -117
53002 | -57 | -117
53002 | -54 | -117
53002 | -57 | -117
53003 | -73 | -122
53003 | -75 | -122
53003 | -103 | -119
53005 | -66 | -125
53009 | -138 | -156
53013 | -140 | -160
53018 | -11 | -401
53018 | -12 | -401
53019 | -43 | -402
53020 | -4 | -405
53021 | -58 | -408
53023 | -71 | -412
53024 | -127 | -414
53025 | -83 | -415
53026 | -82 | -421
53028 | -231 | -510
53029 | -185 | -126
53032 | -104 | -607
53032 | -124 | -607
53032 | -130 | -618
54001 | -19 | -101
54002 | -6 | -102
54003 | -47 | -107
54003 | -87 | -107
54003 | -88 | -107
54003 | -119 | -107
54003 | -177 | -107
54003 | -279 | -107
54004 | -26 | -129
54008 | -46 | -602
54011 | -61 | -680
56002 | -244 | -118
56005 | -80 | -127
56008 | -108 | -153
56013 | -79 | -150
56023 | -288 | -512
56024 | -287 | -513
56201 | -343 | -925
58002 | -44 | -685
Parent topic: Code Mappings


Troubleshooting XDB Link Issues

The following table gives a list of common problems and possible solutions.

Problem | Solution
A DOS system error is returned on startup of IBM LAN Requester. | Your Communications Manager, LAN feature profile is using a station address that is identical to another workstation's address. Change the station address to be unique within the LAN.
When booting the Communications Manager, LU 6.2 sessions are not allowed on the SNA gateway for a downstream Gateway. Only the 3270 session allocates on the SDLC/Token Ring Gateway. | Ensure you are using the correct CFG for Communications Manager and that it allows APPC. Ensure the CFG pointed to in config.sys for Communications Manager allows APPC.
The LAN Requester abends when selected from the Communications Manager main menu.

NetBIOS support is missing from config.sys and the Communications Manager CFG. Correct your Communications Manager CFG, access the LAN feature profiles section and configure the IEEE802 option (you may choose not to use Univ Admin Addresses and opt to create your own). Now you may reboot your machine and try to access the LAN Requester. If this fails to work, you must re-install Communications Manager. Remove the existing manager and re-install using the CFG file already modified above.
Import is taking a long time to transfer records. DB2 is slow. Timeout errors are occurring. Import was started without a commit interval being specified. Since no interval was specified, DB2 is filling up its buffer pool with a single unit of work. Run Import using the command:
xdbimpor /cnnn

where nnn is the commit interval. Try 50 to start.
Parent topic: Gateway Profile Utility (Link Profile)


JDBC

The Micro Focus Direct Flight JDBC driver provides JDBC support for XDB Server. See the chapter SQL Option for DB2 for more information on XDB Server.

You can use the Direct Flight driver to:

  • Establish a connection to an XDB Server
  • Send SQL statements to an XDB Server
  • Process results from an XDB Server
Note:

Before you can connect to an XDB Server you must load the Direct Flight driver. See the topic Loading the Direct Flight Driver for more information.

To use the Direct Flight driver you must have:

  • Java 2 Version 1.2 or higher installed
  • Access to an XDB Server
  • Loading the Direct Flight Driver
  • Connecting to an XDB Server
  • Calling COBOL Stored Procedures
Parent topic: SQL Option User Guide


Loading the Direct Flight Driver

You must load the Direct Flight driver before you can connect to an XDB Server. The simplest way to load the driver is to use the following code:

Class.forName ("mf.jdbc.DFDriver");

Where DFDriver is the name of the Micro Focus Direct Flight driver.

This creates an instance of the mf.jdbc.DFDriver class which represents the Direct Flight driver and registers the driver with your Java development environment Driver Manager.

The following code examples demonstrate two other methods for loading the driver:

In this example, the driver is loaded before calling the DriverManager.getConnection method:

Connection login(String sUser, String sPassword)
throws SQLException {

String sURL = “jdbc.mf://myhost”;
Driver driver = new mf.jdbc.DFDriver();

return DriverManager.getConnection(sURL, sUser, sPassword);

}

In this example, mf.jdbc.DFDriver is instantiated within the static code of the class that connects to the XDB Server:

Class MyClass {
      static {
              try {
                      Driver driver = new mf.jdbc.DFDriver();
              }
              catch  (Exception e)
              {
                      e.printStackTrace();
              }
      }
}
Parent topic: JDBC


Connecting to an XDB Server

Once you have loaded the Direct Flight driver, you can connect to an XDB Server. You do this by passing information to one of the three overloads for the DriverManager.getConnection method. See the section Overloads for the DriverManager.getConnection Method for more information. The following table shows you where different types of information can be passed to the overloads:

Information | Passed Where? | Required?
The name of an XDB Server (or a list of XDB Servers for fault tolerance) | Only in the URL | Required
An AuthID and password recognized by the XDB Server As explicit parameters for Overload 1 or as properties:
  • In the URL
  • In a Properties Object
Required
Additional property values (including a data profile)
  • In the URL
  • In a Properties Object
Optional

See the sections Direct Flight URL Syntax, Direct Flight Data Connection Properties and Defining a JDBC Data Profile for more information.

There is an order of precedence for property value definitions. The order is:

  1. A URL overrides all other definitions
  2. A Property Object overrides values defined in a data profile
  3. A data profile does not override any other definitions
Note:

If you have defined a data profile and set its canoverride property to "No," the property values defined in the data profile are not overridden by values in the URL or Properties Object. See the section Defining a JDBC Data Profile for more information.

  • Overloads for the DriverManager.getConnection Method
  • Direct Flight URL Syntax
  • Direct Flight Data Connection Properties
  • Defining a JDBC Data Profile
Parent topic: JDBC


Overloads for the DriverManager.getConnection Method

The DriverManager.getConnection method has three overloads. The URL syntax is the same for all three overloads. See the section Direct Flight URL Syntax for more information.

You connect to an XDB Server by calling one of these overloads in your Java applet or application. The overload you choose depends on the parameters that are supported by your Java development environment and on the data connection properties that you need to specify.

This section describes the three overloads for the DriverManager.getConnection method and their parameters.

  • Overload 1
    URL, AuthID and password.
  • Overload 2
    URL and Properties Object.
  • Overload 3
    URL only.
Parent topic: Connecting to an XDB Server
Related information
Direct Flight URL Syntax


Overload 1

Parameters:

URL | The XDB Server URL (String)
AuthID | The AuthID used to log on to the XDB Server (String)
Password | The password associated with the AuthID (String)
Connection Properties | Data connection properties defined in the URL itself or in a data profile

Comments:

Use Overload 1 if you:

  • Only have a few properties values to set
  • Have defined a data profile in which most of the values of the data connection properties are set
  • Do not want to define a Properties Object
  • Need to change from using the Direct Flight driver to other JDBC drivers in your code

Examples:

This example uses Overload 1 to define property values without instantiating a Properties Object:

void Connection login (String sUser, String sPassword) {

            String sURL =  “jdbc:mf://myhost?timeout=-1”;

            //Connect to the database
            return DriverManager.getConnection(sURL, sUser, sPassword);

}

This example uses Overload 1 to load property values from a data profile defined in the SYSXDB.SYSPROFILES table:

void Connection login (String sUser, String sPassword) {

            String sURL =  “jdbc:mf://myhost/myprofile”;

            //Connect to the database
            return DriverManager.getConnection(sURL, sUser, sPassword);

}
Parent topic: Overloads for the DriverManager.getConnection Method


Overload 2

Parameters:

URL | The XDB Server URL (String)
Connection Properties | The data connection properties defined in a single instance of a Properties Object

Comments:

Use Overload 2 if you have a Java development environment that supports Properties Objects and you have a number of properties that you want to set for each data connection.

In addition to specifying the property values in a Properties Object, you can:

  • Override property values in the URL itself
  • Use predefined property values by specifying the name of a data profile in your Properties Object

Example:

This example uses Overload 2 to set properties in a Properties Object and then pass the properties with the URL. Note that you must add the prefix mf. to every property name except user and password in a Properties Object.

void  Connection login (String sUser, String sPassword) {

            Properties props;
            String sURL = “ jdbc:mf://myhost”;

            //create a Properties Object
            props = new Properties();

            //load properties from a properties file
            props.load(new FileInputStream(“mydb.properties”));

            //set the numthreads property to 1
            props.put(“mf.numthreads”, “1”);

            // Set the user name and password
            props.put(“user”, sUser);
            props.put(“password”, sPassword);

            //connect to the database
            return DriverManager.getConnection(sURL, props);

}
Parent topic: Overloads for the DriverManager.getConnection Method


Overload 3

Parameters:

URL The XDB Server URL (String)

Comments:

If you need to, you can specify the AuthID and password for logging on to the XDB Server, as well as any other data connection properties, in the URL itself.

You can also include the name of a data profile in the URL.

Parent topic: Overloads for the DriverManager.getConnection Method


Direct Flight URL Syntax

The Direct Flight URL syntax is the same for all three overloads for the method. The URL is used to call the DriverManager.getConnection method. Your URL must use the following syntax:

jdbc:mf://server-list[/profile][@location][?property-list]

Where the parameters are:

server-list A comma-separated list of XDB Gateway Servers with the following format:
host1[:port1][,host2[:port2],...hostn[:portn]]

Where the parameters are:

server-list A comma-separated list of XDB Gateway Servers with the following format:
host1[:port1][,host2[:port2],...hostn[:portn]]

Where the parameters are:

profile | The name of a data profile defined in the SYSXDB.SYSPROFILES table. The default is the data profile specified in the data profile default property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
location | The name of the XDB location to which the applet or application connects. The default is the location specified in the data profile location property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
property-list An ampersand-separated list of property value pairs with the following format:
prop1=val1[[&prop2=val2]&...propn=valn]

Where the parameters are:

See the section Direct Flight Data Connection Properties for more information on the properties that you can set.

hostx | The DNS name, host name, or IP address of an XDB Server.
portx | The port number of the XDB Server on that machine. The default port for an XDB Server is 8898.
propx | The name of a data connection property.
valx | A valid value for the data connection property.
profile | The name of a data profile defined in the SYSXDB.SYSPROFILES table. The default is the data profile specified in the data profile default property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
location | The name of the XDB location to which the applet or application connects. The default is the location specified in the data profile location property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
property-list An ampersand-separated list of property value pairs with the following format:
prop1=val1[[&prop2=val2]&...propn=valn]

Where the parameters are:

See the section Direct Flight Data Connection Properties for more information on the properties that you can set.

Note:

You can add the prefix mf. to any property name in the URL except user and password.

Parent topic: Connecting to an XDB Server
Related information
Defining a JDBC Data Profile
Direct Flight Data Connection Properties


Direct Flight Data Connection Properties

This section describes the data connection properties that you can set in your Java applet or application. You can specify data connection properties in the URL or in a Properties Object. See the section Connecting to an XDB Server for more information.

  • user
    Sets the AuthID that an applet or application will use to log on to the XDB Server.
  • password
    Sets the password for the AuthID specified in the user property.
  • profile
    Sets the name of the data profile an applet or application will use to retrieve the values of data connection properties defined in the SYSXDB.SYSPROFILES table.
  • profile.location
    Sets the name of the location on the XDB Server where an applet or application will first log on.
  • profile.canoverride
    Determines whether the properties associated with profile can be overridden in the URL or in a Properties Object.
  • profile.default
    Determines whether the entry represents the default profile.
  • maxrows
    Sets the maximum number of rows the Direct Flight driver will return in response to a query.
  • maxfieldsize
    Sets the size of the largest data field the Direct Flight driver will return in response to a query.
  • numthreads
    Sets the number of threads for which the Direct Flight driver will optimize the data connection.
  • timeout
    Sets the number of milliseconds an applet or application will wait for a response from the XDB Server before causing an exception.
  • cache.numrecs
    Sets the maximum number of records that the Direct Flight driver will prefetch for read-only queries.
  • cache.size
    Sets the maximum number of bytes that the Direct Flight driver will prefetch for read-only queries.
  • cache.fetch.numrecs
    Sets the maximum number of records that the Direct Flight driver will fetch in one batch when prefetching records for read-only queries.
  • cache.fetch.size
    Sets the maximum number of bytes that the Direct Flight driver will fetch in one batch when prefetching records for read-only queries.
Parent topic: Connecting to an XDB Server
Related information
Connecting to an XDB Server


user

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Any valid AuthID with access to the data referenced in an applet or application
Default: | None

Comments:

You must specify a value for this property

Parent topic: Direct Flight Data Connection Properties


password

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | The current password for the AuthID specified in the user property. For AuthIDs that have no password, use an empty string as the value for this property.
Default: | None

Comments:

You must specify a value for this property

Parent topic: Direct Flight Data Connection Properties


profile

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Any data profile name with one or more property entries defined in the SYSXDB.SYSPROFILES table in the system location of an XDB Server
Default: | None

Comments:

This property is optional. You can connect to an XDB Server without defining any properties in a data profile.

Parent topic: Direct Flight Data Connection Properties


profile.location

Properties:

Where it can be set: | In the URL, in a Properties Object or in a data profile in the SYSXDB.SYSPROFILES table
Possible Values: | The name of any location on the XDB Server
Default: | SYSTEM

Comments:

Make sure that you specify the correct location as the value for this property. Note that the default location (SYSTEM) is not suitable for most applets and applications.

If you specify the value of this property in a data profile, do not prefix the property name with the name of the profile (profile).

Parent topic: Direct Flight Data Connection Properties


profile.canoverride

Properties:

Where it can be set: | Only in a data profile in the SYSXDB.SYSPROFILES table
Possible Values: | Yes or no
Default: | Yes

Comments:

You can prevent users setting data connection properties to inappropriate values when they enter the URL, by setting canoverride to "No". If you want to use the canoverride property for this purpose, make sure that all the profiles have canoverride set to "No." If even one profile has canoverride set to "Yes," users can specify that profile and set other data connection properties to any values they choose.

To create a single profile that cannot be overridden, set this property to "No" and make sure that the default property entry is also present.

Do not prefix the property name with the name of the profile (profile).

Parent topic: Direct Flight Data Connection Properties


profile.default

Properties:

Where it can be set: | Only in a data profile in the SYSXDB.SYSPROFILES table.
Possible Values: | Anything
Default: | The presence of this entry in the table makes its profile the default

Comments:

Make sure that only one data profile includes this property. Using multiple default profiles generates unpredictable results.

Do not prefix the property name with the name of the profile (profile).

Parent topic: Direct Flight Data Connection Properties


maxrows

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of rows) or 0 (all rows – no limit)
Default: | 0 (all rows – no limit)

Comments:

This property and its default value match the JDBC standard. You can reset this limit within the scope of a statement in your code. Each individual statement uses the initial limit specified by the value of this property.

Parent topic: Direct Flight Data Connection Properties


maxfieldsize

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of rows) or 0 (all rows – no limit)
Default: | 0 (all rows – no limit)

Comments:

This property and its default value match the JDBC standard. You can reset this limit within the scope of a statement in your code. Each individual statement uses the initial limit specified by the value of this property.

Parent topic: Direct Flight Data Connection Properties


numthreads

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of threads)
Default: | 4

Comments:

You should set this value to the number of threads you expect to access the XDB Server at the same time, for optimum performance.

If you set numthreads too high, your application will drain system resources. If you set numthreads too low, your application performance will drop.

Parent topic: Direct Flight Data Connection Properties


timeout

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of milliseconds) or -1 (disable timeout)
Default: | 5000

Comments:

This value represents the milliseconds between the time a packet is sent and the time a packet is received.

Parent topic: Direct Flight Data Connection Properties


cache.numrecs

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of records) or -1 (disable limit)
Default: | -1 (disabled)

Comments:

Do not disable both cache.numrecs and cache.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


cache.size

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of bytes) or -1 (disable limit)
Default: | 131072(128K)

Comments:

Do not disable both cache.numrecs and cache.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


cache.fetch.numrecs

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of records) or -1 (disable limit)
Default: | 100

Comments:

Do not disable both cache.fetch.numrecs and cache.fetch.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


cache.fetch.size

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of bytes) or -1 (disable limit)
Default: | 8196

Comments:

Do not disable both cache.fetch.numrecs and cache.fetch.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


Defining a JDBC Data Profile

A data profile is a set of property values defined in one location and referred to, as often as required, by a single profile name. Using property values from a data profile enables you to keep the URL short. This is convenient for development environments where you are required to retype the URL. If you are developing multiple applications, you can use data profiles to centralize your data configurations on one XDB Server and perform all of your maintenance in a single location.

Defining a data profile is optional. You can also set property values in the URL or in a Properties Object, depending on which overload for the DriverManager.getConnection method you use. See the section Overloads for the DriverManager.getConnection Method for more information.

You define a data profile by adding a set of entries to the SYSXDB.SYSPROFILES table in the SYSTEM location of your XDB Server. Each entry in the SYSXDB.SYSPROFILES table defines a profile property. The following data connection properties are available:

  • location
  • canoverride
  • default

You can use the SQL Wizard to alter the SYSXDB.SYSPROFILES table. For instructions on how to alter tables, see the topic Altering a Table in your SQL Wizard Online Reference. To define your data profile:

  1. Choose a name for the data profile. The maximum name length is 32 characters.

    Make sure that you enter the name consistently for each entry you add to the table. The profile name in the table must be the same as the one you specify in the URL when you call the getConnection method.

  2. Add an entry for the location property. Set its value to the name of the XDB Server location where your applet or application will first log on when it is executed.

    A minimal profile definition could consist of just a location entry. All other profile properties have default values.

  3. Add an entry for the canoverride property. Set its value to "No" if you do not want to be able to override the property associated with this profile.

    Ignore this property or set its value to "Yes" if you want to be able to override these values in the URL or in a Properties Object.

  4. Add an entry for the default property, if you want this data profile to be the default profile.

    You do not need to specify a value for the default property.

Note:

Do not add the prefix mf. to any of the properties defined in a data profile.

You can prevent a specific profile from being overridden by setting its canoverride property value to "No" and ensuring that the default property is also present. If you specify multiple profiles, make sure that all canoverride values are set to "No". For example:

Profile Name | Property name | Property Value
DEF | location | PASSTHRU
DEF | canoverrride | no
DEF | default | yes

If you add a second profile and leave its canoverride value set to "Yes" (the default), it will defeat the purpose of the first profile. In the following example, a user could specify the ALT profile and successfully override the data connection properties of the DEF profile in the URL:

Profile Name | Property name | Property Value
DEF | location | PASSTHRU
DEF | canoverrride | no
DEF | default | yes
ALT | location | ALTERNATE
ALT | canoverride | yes
Parent topic: Connecting to an XDB Server
Related information
Overloads for the DriverManager.getConnection Method


Calling COBOL Stored Procedures

Restriction: This topic applies to Windows environments (local development) only.

You can augment your Java code by calling stored procedures written in COBOL. You can execute stored procedures with the XDB Server running either in the blue screen character mode or as a service. For information on setting up stored procedures using XDB Server, see the section Stored Procedures in your SQL Reference.

The demonstration program mfExample3.java, located in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\mfsql\demo directory, demonstrates calling the COBOL stored procedure salraise.cbl. Consult the JDBCDEMO readme.txt file for detailed instructions on running the program.

Parent topic: JDBC


Migrate Utility

Migrate provides an easy, interactive way to copy one or more data tables between XDB Server locations or between an XDB Server location and a DB2 subsystem. You can use Migrate to quickly download a copy of a table from a mainframe for development and testing purposes. Or, you can use it to regularly copy up-to-date information from a production database on an XDB Server to a DB2 database on the mainframe.

Migrate simplifies the process of copying data from one location or database to another by eliminating intermediate file transfers and by eliminating the hand-editing of indexes and foreign keys. With Migrate, you can copy keys, indexes and tables in a single step. You can also quickly copy a subset of a table (certain columns or rows) by extracting data with a SELECT statement.

For complex migrations, you can use the Migrate utility's referential-integrity feature to detect data dependencies automatically and copy tables in the correct order. You can also produce a preliminary "impact analysis" report, which describes the effect of a migration before it is performed. If you copy certain tables regularly, you can save the specification in a .mig file. You can then run this file in batch mode, enabling you to perform a migration without respecifying it manually.

If your system administrator has configured the mainframe connectivity facilities of SQL Option, you can use the Migrate utility to import or export data between XDB locations, or between an XDB location and a DB2 subsystem.

  • Migration Paths Overview
  • To migrate between XDB Servers
  • To migrate between an XDB Server and a mainframe
  • Catalog Browser Overview
  • Schema Viewer Overview
  • Generating Reports
  • The Impact Analysis Report
  • The Post Execution Analysis Report
  • The Error File
Parent topic: SQL Option User Guide


Migration Paths Overview

Migrate lets you copy data between the following kinds of locations:

  • Mainframe to Mainframe
  • Mainframe to Server
  • Server to Mainframe
  • Server to Server
Parent topic: Migrate Utility


To migrate between XDB Servers

Migrate can copy data between any locations that are accessible to the server to which you are connected. To migrate tables between two XDB Servers, the server you log onto must have access to the other server via server-to-server communications. For information about establishing server-to-server connectivity, see your XDB Server Administration Guide.

Parent topic: Migrate Utility


To migrate between an XDB Server and a mainframe

To migrate tables between a mainframe and an XDB Server, XDB Link must be installed on at least one of the XDB Servers to which you have access. See the XDB Link documentation for information about setting up a mainframe location for remote access.

Parent topic: Migrate Utility


Catalog Browser Overview

The Catalog Browser graphically represents XDB Server database objects. In Migrate, you use the Catalog Browser to select the table(s) you want to copy, or to recall a query that you have created and saved with a data management tool such as SQLWizard.

The Catalog Browser shows you all of the locations that are known to the server to which you are connected (even locations that are on another server or on a mainframe). Database objects, such as locations, tables and indexes, are graphically represented in a hierarchical structure. Using the + and - buttons, you can expand and collapse the hierarchy to show just the elements you want to work with.

Note:

If you don't see the location that you want to migrate tables to or from, use Options to verify that you are connected to the correct server. If your server connection is correct, verify that the locations are listed in the server's SYSIBM.SYSLOCATIONS table. Your server must have access to both the source and target locations. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about setting up server-to-server communications.

Parent topic: Migrate Utility


Schema Viewer Overview

The Schema Viewer displays the schemas of tables selected for migration. If related tables are contained in the viewer, they are connected with arrowed lines.

You can add tables to the Schema Viewer by dragging them from the Catalog Browser (see The Catalog Browser). To remove a table from the Schema Viewer, select the table in the Schema Viewer, then choose the Remove command from the Object menu.

Parent topic: Migrate Utility


Generating Reports

Migrate can create selected reports during a migration. Reports are written to files that you specify in the Run dialog box. You can display a report by selecting it from the View menu. Once a report is open, you can print it using the Print command on the File menu.

Parent topic: Migrate Utility


The Impact Analysis Report

The Impact Analysis Report describes the schemas of the selected source and destination tables, and lists the options you have selected. You can use this report to review your specifications before you run a migration.

To create an Impact Analysis Report, select the Impact Analysis Report option in the Migrate Options dialog box before you run the migration. Type the name of the file to which you want the report written in the text-entry field next to the checkbox. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

Note:

When an Impact Analysis Report is selected, Migrate does not execute the migration. It simply describes what would happen if it were performed.

To view the report after it has been generated, select the Impact Analysis command on the View menu. Migrate automatically displays the last Impact Analysis file specified. To display a report other than the last one, specify the file with the Migrate command on the Options menu before you select the Impact Analysis command.

If you want to print the report once it is displayed, choose Print from the File menu.

The following is an example of an Impact Analysis Report.

                   IMPACT ANALYSIS REPORT

  Generated: 07/09/1996

                   Source               Destination
                   --------------       -------------
  Location:        SALES                SALES

    Table:
      Name:        CUSTOMERS            CUSTOMERS
      Authid:      DEV001               DEV001
      Database:
      Tablespace:

      Definition:
         Migrate:  Yes                  *
         Columns:  name(CHAR(20))       name(CHAR(20))
                   city(CHAR(20))       city(CHAR(20))
                   state(CHAR(2))       state(CHAR(2))

      Primary Key: CKEY                 CKEY
          Migrate: No
          Columns: NAME                 NAME

      Comments:
          Migrate: No
      Src Table Comment:
      Dst Table Comment:

      Synonyms:
          Migrate: No

      Privileges:
          Migrate: No
Parent topic: Migrate Utility


The Post Execution Analysis Report

The Post Execution Analysis Report provides a listing of the tables that were copied during a migration. It also reports the source and destination locations of those tables.

To create a Post Execution Analysis Report, select the Post Execution Report checkbox in the Run dialog box when you execute your migration. Type the name of the file to which you want the report written in the text-entry field next to the checkbox. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

Note:

You can specify the same filename for the Post Execution Analysis and the Error File to combine both reports into a single file.

To view the report after a migration has been executed, open the file using the Post Execution Analysis command on the View menu. Migrate automatically displays the last Post Execution file specified. To display a report other than the last one, specify the file with the Migrate command on the Options menu before you select the Post Execution Analysis command.

If you want to print the report once it is displayed, choose Print from the File menu.

The following is an example of a Post Execution Analysis Report.

                   POST EXECUTION REPORT

  Generated: 07/09/1996

                   Source              Destination
                   --------------      -------------
  Location:        SALES               TEST

    Table:
      Name:        CUSTOMERS           CUSTOMERS
      Authid:      DEV001              DEV001
      Database:
      Tablespace:

  Table created at 13:00:39 on 7/9/1996
  156 records inserted
Parent topic: Migrate Utility


The Error File

The Error File reports the number and type of errors detected while migrating your tables. An error file is created each time you select it in the Run dialog box; however, it will contain errors only if errors were generated by a migration.

To request an error file, select the Error File checkbox in the Run dialog box when you execute your migration. Type the name of the file to which you want the report written in the text-entry field next to the checkbox. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

Note:

You can specify the same filename for the Error File and the Post Execution Analysis to combine both reports into a single file.

To view the error file after a migration has been executed, open the file using the Error File command on the View menu. Migrate automatically displays the last Error File specified. To display a report other than the last one, specify the file with the Migrate command on the Options menu before you select the Error File command.

If you want to print the report once it is displayed, choose Print from the File menu.

Parent topic: Migrate Utility


Options Utility

Use the Options utility for configuring the SQL Option client-side software and its connectivity with XDB and DB2 database servers.

The settings that you can change fall into the following categories:

  • Connect

    For configuring the connection between a client application (for example, SQL Wizard or a program that you have developed) and the XDB or DB2 database that it uses.

  • Paths

    For specifying where SQL Wizard and other SQL Option files are to be found or written.

  • Format

    For specifying formats for dates, times and numeric fields.

  • Multi-user

    For specifying options for a multi-user XDB Server in a networked environment. For example, you can control isolation levels and autocommit.

  • Browser

    For specifying which database objects are shown in the Catalog Browser window.

  • Query

    For specifying default options for working with queries. For example, you can specify whether unqualified table-names can be used and whether Cartesian products are permitted. These options can be overridden for a particular query when you are editing the query.

  • Query run

    For specifying options for running queries with SQL Wizard. For example, you can control whether the result is displayed in table or form view and limit the number of rows returned.

  • SQL

    For specifying defaults for various SQL operational parameters, including compatibility and sort sequence. For example, you can set DB2 or SQL/DS compatibility and whether to use ASCII or EBCDIC sort sequences. You can also set the escape character and SysAuthID.

  • Security

    For specifying security options. You can switch on client security (required if you want to use an XDB Server that has security switched on), as well as controlling the enforcement criteria for user passwords.

The Options utility has a Summary page that enables you to obtain a list of all the current configuration settings. You cannot make changes to any of the options from the Summary tab but you can print it for reference purposes.

To access the Options utility from the main menu, > Configuration > Client Options.

The Options window is made up of several pages, each labeled with a tab. To view or change information on a particular page, click its tab.

The options that you select are stored in the xdb.ini file.

To ensure backward compatibility, the settings are also written to the config.xdb file. These files are usually found in your configuration directory. For more information about xdb.ini, see xdb.ini File Structure.

Note: If SQLWizard is running when you change your preferences using Options, you must exit from SQLWizard and restart it before the changes take effect.

Along the left edge of the window is a set of general-purpose buttons. Depending upon which tab you are working in, some or all of these buttons will be available to you.

OK | This button accepts the current configuration and writes the settings to the xdb.ini and CONFIG.XDB files, and any other configuration files used by your system. Exits Options.
Cancel | This button discards the changes made during the current session and exits Options.
Browse | This button becomes active when your cursor is in a field requiring a path, filename or location. Clicking Browse provides a dialog box for you to select a name.
Edit | This button is displayed when the current tab offers editable fields such as formats for days or months.
Help | This button displays a help window containing information about the current tab.
  • Picture Definitions Overview
  • US ASCII Table
  • xdb.ini File Structure
Parent topic: SQL Option User Guide
Related concepts
XDB xa_open string
Related information
xdb.ini File Structure


Picture Definitions Overview

The Options utility permits you to define input and display pictures to be used as the default masks for various types of columns.

Note that once a format has been defined for a data type or a variable, the system will not accept values that are not consistent with or are outside the range defined by the picture. For numeric fields, enter masks to handle the largest values you expect to enter and display.

  • Numeric Masks Overview
  • Numeric Picture Characters
  • Numeric Picture Examples
  • Date Pictures Overview
  • Date Picture Elements
  • Date Picture Examples
  • Time Pictures Overview
  • Time Picture Elements
  • Time Picture Examples
  • Character Strings Overview
  • Character Picture Examples
Parent topic: Options Utility


Numeric Masks Overview

All numeric masks (that is: smallint, int, float, decimal and money) are defined in the same way. The basic format for a numeric mask is:

mask [$='money'] [.='decimal'] [,='grouping']

where:

mask is a picture that defines the appearance of the variable when displayed on the screen or sent to the printer.

money is a money symbol (enclosed in single quotes) to be substituted for a dollar sign in numeric pictures. The money clause is optional. Money symbols can be up to five characters long. For example, to use the money symbol DM in place of a dollar sign, use:

$='DM'

decimal is a decimal point character (enclosed in single quotes) to be substituted for a period in numeric pictures. The decimal clause is optional. The grouping character and decimal point character cannot be the same. For example, to use a comma as the decimal point character, and a period as a grouping character, you would use:

.=',' ,='.'

grouping is a grouping character (enclosed in single quotes) to be substituted for a comma in numeric pictures. This clause is optional. The grouping character and decimal point character cannot be the same, as demonstrated in the example above.

Note that the optional money, decimal and grouping clauses are used only for numeric variables. If omitted, the default will be the money, decimal and grouping symbols specified through the Options utility. When defining decimal masks, keep in mind that precision refers to the total number of digits (before and after the decimal place) and scale is the number of digits to the right of the decimal point. For example decimal (10,4) allows six digits to the left of the decimal point, and four digits to the right of the decimal point.

To use a character that does not appear on your keyboard in your edit mask, use the facilities provided by your operating environment for entering extended characters. For example:

  • In DOS, hold down Alt key while entering the ASCII decimal code for the character on your numeric keypad. In US ASCII, the >= symbol is created by holding down Alt key while pressing 156. (For a list of decimal codes for US ASCII, see the US ASCII Table.)
  • In Windows, use the Character Map application from the Accessories window to select special characters.

Given the picture:

$$,$$$,$$9.99 $='>='

the value 23456.78 is displayed as >=23,456.78.

For additional information, see Numeric Picture Characters.

Parent topic: Picture Definitions Overview


Numeric Picture Characters

The following table describes the special characters that can be used when defining numeric pictures. Some numeric masks are illustrated in Numeric Picture Examples.

Picture | Result
+ | Indicates position of the minus or plus sign. Sign is placed as close to significant digits as possible. If z, 9, or $ appear after +, the sign will never be closer to the decimal place than the last + sign.
- | Same as + except signs are not displayed.
9 | Indicates a digit. Leading zeroes are displayed.
z | Indicates a digit. Leading zeros are replaced with blanks to allow alignment of decimal points and money symbols. (Lower case z only.)
. | Indicates the position of the decimal point. To use a different symbol for the decimal point (a comma, for example), use the period in the picture, but redefine the decimal point character by adding the .= decimal clause (for example: .=',').
, | Comma indicates relative position of grouping character. Grouping length is counted from the right, beginning with the first nonfractional digit. Only the grouping character closest to the decimal point is required. To use a different symbol for the grouping character (for example `.'), use the comma in the picture, but redefine the grouping character by adding the ,=grouping clause (for example: ,='.').
$ | Indicates the position of the money symbol. When several dollar signs appear together ($$,$$$.99 for example) the dollar sign will be shown next to the left-most digit (or decimal point) displayed. Using the example picture, the variable value 12.34 will therefore be displayed as $12.34. To use a different money symbol (>= for example), Use the dollar sign in the picture, but then redefine the money symbol by adding the $=money clause to the PICTURE command ($='>=' for example).
r | Indicates the number is to be rounded. If used, must appear at very end of the mask (zz,zz9.99+r for example).
Parent topic: Picture Definitions Overview


Numeric Picture Examples

The following table shows the effect of various numeric picture formats.

Picture | Input | Output
9999 | 123 | 0123
zzz.99 | 13.456 | 13.45
zz99 | 123 | 123
+999.99 | -13.4 | -013.40
++++.99 | -013.4 | -13.40
+zz99.9 | -13.456 | - 13.4
+++z9.9 | -130.456 | -130.4
zzz.9r | -13.456 | -13.5
+++.99r | 13.456 | 13.46
+999.99r | -13.456 | -013.46
$999.99 | 40 | $040.00
$$$$.99 | 40 | $40.00
$$$$.99+ | -40 | $40.00-
$$$$$,$$9.99 $='£' | 13.456 | £13.45
zzzzz,zz9 ,='.' | 12345 | 12.345
Parent topic: Picture Definitions Overview


Date Pictures Overview

A Date picture contains the components used to define date display pictures. You may order the Day, Month, Year and Weekday components any way you like (for example: dd/mm/yy, mm/dd/yy, yy/mm/dd). You can include characters to separate the components. Data must be entered according to the picture format, with a day and year component required.

The strings used for the mmm and mmmm month and www and wwww weekday pictures are defined on the Options utility's FORMAT tab. Separators can be any other characters, and will be displayed in the relative position they occupy in the mask. Commonly used separators are slash (/), hyphen (-), space ( ), and comma (,). In procedures, a date cannot consist of simply a month component.

For additional information, see Date Picture Elements.

Parent topic: Picture Definitions Overview


Date Picture Elements

The following table describes the elements that can be included in a Date Picture. Examples are shown in Date Picture Examples.

Clause | Picture | Result
Day | d | Integer between 1 and 31, corresponding to day of month. Does not display leading zeroes.
 | dd | Integer between 1 and 31, corresponding to day of month. Displays leading zeroes.
 | ddd | Integer between 1 and 365 (366 in a leap year), corresponding to number of days since first of the year. Does not display leading zeroes.
Month | m | Integer between 1 and 12, corresponding to a month. Note that this format does not display leading zeroes.
 | mm | Integer between 1 and 12, corresponding to a month. Displays leading zeroes.
 | mmm | A three character abbreviation for the month corresponding to stored month number (for example: JAN, FEB, MAR,...).
 | mmmm | Month corresponding to the stored month number (for example: January, February, March,...).
Year | yy | Displays last two digits of stored year.
 | yyyy | Displays the stored year.
Weekday | ww | An integer corresponding to the day of the week (Monday=1, Tuesday=2, etc.)
 | www | Three-character abbreviation for the day of the week (for example: MON, TUE, WED,...).
 | wwww | The day of the week a date falls on.
Parent topic: Picture Definitions Overview


Date Picture Examples

The following examples show various date pictures using the date August 31, 1995:

Date Picture | Displayed Date
m/d/yy | 8/31/95
mm/dd/yy | 08/31/95
mm/dd/yyyy | 08/31/1995
dd-mm-yy | 31-08-95
yyyy-mm-dd | 1995-08-31
mmm-dd-yyyy | AUG-31-1995
mmmm dd, yy | August 31, 1995
yyddd | 95242
dd | 31
wwww, mmmm dd | Monday, August 31
mmm 'yy | AUG '95
wwww | Monday
Parent topic: Picture Definitions Overview


Time Pictures Overview

A Time Picture contains the components used to define time pictures. You can use optional separators to separate the Hour, Minute and Second components.

Data must be entered according to the picture format, with an hour and minute component required. Midnight is 12:00:00 am for 12 hour clocks, and 24:00:00 for 24 hour clocks. One second after midnight is 12:00:01 am for 12 hour clocks, and 00:00:01 for 24 hour clocks.

Separators can be any other characters, and will be displayed in the relative position they occupy in the mask.

Commonly used separators are colon (:), hyphen (-), and period (.).

For 12 hour clocks, you can include the characters AM in your picture in the location you want AM or PM to appear. Use the case you want used in the display.

For a 24 hour clock, place the number 24 at the end of the picture. For a 12 hour clock, place the number 12 at the end of the picture. If you do not specify the clock type, a 24 hour clock is assumed, unless you have set the default time format to a 12 hour clock through the Options utility. Note that in procedures a time picture cannot consist of a minute component alone.

For additional information, see Time Picture Elements.

Parent topic: Picture Definitions Overview


Time Picture Elements

The following table describes elements of a Time picture. Examples are shown in Time Picture Examples.

Clause | Picture | Result
Hour | h | An integer between 0 and 24 (inclusive), corresponding to the hour of the day. Does not display leading zeroes
 | hh | An integer between 0 and 24 (inclusive), corresponding to the hour of the day. Displays leading zeroes.
Minute | m | An integer between 0 and 59 (inclusive), corresponding to a number of minutes. Does not display leading zeroes.
 | mm | An integer between 0 and 59 (inclusive), corresponding to a number of minutes. Displays leading zeroes.
Second | s | An integer between 0 and 59 (inclusive), corresponding to a number of seconds. Does not display leading zeroes.
 | ss | An integer between 0 and 59 (inclusive), corresponding to a number of seconds. Displays leading zeroes.
Parent topic: Picture Definitions Overview


Time Picture Examples

The following examples show some time format masks and the resulting output, using the time 15:08:25.

Clock Format | Time Picture | Displayed Time
12 hour clock | hh:mm:ss am 12 | 03:08:25 pm
 | hh.mm 12 | 03.08
 | AM h-m-s 12 | PM 3-8-25
24 hour clock | hh:mm:ss 24 | 15:08:25
 | hh.mm 24 | 15.08
 | h-m-s 24 | 15-8-25
Parent topic: Picture Definitions Overview


Character Strings Overview

Character pictures are defined using the special characters. Character Picture Examples, contains examples.

Picture | Result
x | Any character can be displayed or entered in this position. A positive integer n, in parentheses after the `x' indicates the string can be up to n characters long.
u | Alphabetic characters in this position are to be displayed in upper case. Adding a positive integer n, in parentheses after the `u' forces the next n characters to be displayed in upper case, and limits the length of the string to n characters.
l | Alphabetic characters in this position are to be displayed in lower case. Adding a positive integer n in parentheses after the `l' forces the next n characters to be displayed in lower case, and limits the length of the string to n characters.
9 | Indicates a digit from 0 to 9.
Parent topic: Picture Definitions Overview


Character Picture Examples

The following table contains examples of Character Pictures. All examples use the string "Example String 10" as input.

Picture | Displayed String
x(5) | Examp
x(16) | Example String 1
u(5) | EXAMP
u(17) | EXAMPLE STRING 10
l(5) | examp
l(17) | example string 10
u(2)x(15) | EXample string 10
u(2)x(13)99 | EXample string 10
Parent topic: Picture Definitions Overview


US ASCII Table

The following table shows the US ASCII character set and codes (in decimal).

Note that the first 32 ASCII codes usually are nonprintable; they have alternate meanings as special signal codes. The first 32 ASCII codes cannot be used for picture definitions.

ASCII | Char | ASCII | Char | ASCII | Char | ASCII | Char
0 | NUL | 32 | space | 64 | @ | 96 | `
1 | SOH | 33 | ! | 65 | A | 97 | a
2 | STX | 34 | " | 66 | B | 98 | b
3 | ETX | 35 | # | 67 | C | 99 | c
4 | EOT | 36 | $ | 68 | D | 100 | d
5 | ENQ | 37 | % | 69 | E | 101 | e
6 | ACK | 38 | & | 70 | F | 102 | f
7 | BEL | 39 | ' | 71 | G | 103 | g
8 | BS | 40 | ( | 72 | H | 104 | h
9 | HT | 41 | ) | 73 | I | 105 | i
10 | LF | 42 | * | 74 | J | 106 | j
11 | VT | 43 | + | 75 | K | 107 | k
12 | FF | 44 | , | 76 | L | 108 | l
13 | CR | 45 | - | 77 | M | 109 | m
14 | SO | 46 | . | 78 | N | 110 | n
15 | SI | 47 | / | 79 | O | 111 | o
16 | DLE | 48 | 0 | 80 | P | 112 | p
17 | DC1 | 49 | 1 | 81 | Q | 113 | q
18 | DC2 | 50 | 2 | 82 | R | 114 | r
19 | DC3 | 51 | 3 | 83 | S | 115 | s
20 | DC4 | 52 | 4 | 84 | T | 116 | t
21 | MAK | 53 | 5 | 85 | U | 117 | u
22 | SYN | 54 | 6 | 86 | V | 118 | v
23 | ETB | 55 | 7 | 87 | W | 119 | w
24 | CAN | 56 | 8 | 88 | X | 120 | x
25 | EM | 57 | 9 | 89 | Y | 121 | y
26 | SUB | 58 | : | 90 | Z | 122 | z
27 | ESC | 59 | ; | 91 | [ | 123 | {
28 | FS | 60 | < | 92 | \ | 124 | |
29 | GS | 61 | = | 93 | ] | 125 | }
30 | RS | 62 | > | 94 | ^ | 126 |
31 | US | 63 | ? | 95 | _ | 127 | 
Parent topic: Options Utility


xdb.ini File Structure

Sample xdb.ini File

Below is an example xdb.ini file. You will make most of the changes to this file through the Options utility. Do not change any of the sections that contain a warning not to change them. In most cases such changes will have no effect on the system. You must change such settings through the Options utility.

[CLIENT]
XDBCFG=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\
[SERVER]
XDBSERVE=XDBLOCAL
XSRVCFG=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg
[ConnectionDefaults]
AutoConnect=On
Protocol=Win32Local,NetBIOS,TCP/IP
ProtocolMap=64,1,8
Servers=XDBLOCAL
DefaultServerName=XDBLOCAL
NodeName=cXDBCLIENT
[ClientFormats]
DateFormat=ISO
DatePicture=yyyy-mm-dd
TimeFormat=ISO
TimePicture=hh.mm.ss 24
MoneyPicture=-$$$$$$$$$,$$9.99
DecimalPicture=-zzzzzzzzz,zz9.99
WeekdayPicture=WWW
FloatDecimalPlaces=2
TimeZone=0
ShortMonthNames=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec
LongMonthNames=January,February,March,April,May,June,July,August,September,October,November,December
ShortWeekNames=Mon,Tue,Wed,Thu,Fri,Sat,Sun
LongWeekNames=Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
[MultiUser]
IsolationLevel=Cursor Stability
TimeOutInterval=10
AutoCommit=On
BackwardLog=Off
ForwardLog=Off
[Preferences]
Confirm=NO
SortMode=US (Portuguese,Dutch) EBCDIC
SortSequence=EBCDIC
AbortCharacter=<27>
EscapeCharacter=`
CompatibilityMode=DB2
CobolLiterals=Default
DynamicSqlLiterals=Default
CommaDecimal=0
SQLPath=
[QueryRunOption]
MaxRecords=ALL
Execute=First Command
ResultView=Table
AllowEditing=Off
AutoCommit=On
NoLookForPrimaryKey=Off
ShowPositiveSqlcode=Off
HighlighNulls=Red
UseHex=Off
NoDispEmptyResult=Off
ReadOnlyAlert=Off
[QueryDefinition]
QueryUsing=3PartName
ProhibitCartesian=On
ShowTablename=Off
AutoJoinForeignKey=On
AutoJoinPrimaryKey=Off
AutoJoinLikeName=Off
[Browser]
ConfigType=-560
AutoRefresh=Off
AutoStartup=On
[SysAuthID]
SysIBM=SYSIBM
SysXdb=SYSXDB
[Security]
ClientSecurity=Off
PasswordEnforceLevel=1
[ClientPaths]
Executables=C:\Program Files (x86)\Micro Focus\Enterprise Developer\bin\
Application=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\
System=SYSTEM
Temporary=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\tmp\
Overflow=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\tmp\
[Connection XDBLOCAL]
Protocol=Win32Local
PrimaryAuthorizationID=TUTORIAL
CurrentLocation=SYSTEM

File Structure

The xdb.ini file contains values used by Micro Focus client applications (such as SQLWizard). It specifies which Server you will use, what protocol will be used, and other default values. You set set these values using Options before you start your client program.

All of the changes you will make to xdb.ini should be made through the Options utility, accessible from the Options icon in the Micro Focus group window. There are comments in xdb.ini indicating those sections that should not or cannot be edited by hand. Some of these items are actually duplicates of values found in other configuration files, maintained in xdb.ini to ensure backward compatibility with older products. Others have too many choices to be edited easily.

However, there are some parameters that must be edited by hand. xdb.ini is a text file that can be edited with any standard text editor.

Note: If xdb.ini is locked or in use by some other program (such as a text editor), SQLWizard (or your own client application program) will not operate correctly. In this case, when you start SQLWizard (or the clinet application), you will get an error that xdb.ini cannot be found. If you try to run queries, you will get no records back. To avoid this problem, make certain that xdb.ini is not being held open by some other program.

Each of the sections described below corresponds to an SQLWizard-related section of xdb.ini. There may be other sections in your xdb.ini file. These are used by other products, and are described in the related documentation.

For items that provide a choice of settings, the default is shown in bold.

[ConnectionDefaults]

The Connection Defaults section stores information about what to use as the default connection, and also about what protocols are available.

Servers=server1, server2

The Servers item lists all servers that you can access. When a new server becomes available, the server name is added to this list. Each server should have a corresponding [Connection server-name] section.

NodeName=client-name

This is the name by which your machine is known to all XDB Servers you use. This name should be unique among all machines that are trying to access any XDB Server or XDB Link on your network.

DefaultServerName=server-name

This is the name of the XDB Server you want to use.

AutoConnect=On|Off

If on, the Connect dialog box is not displayed when you start SQLWizard (unless security is also on). If off, the Connect dialog box will be displayed so that you can specify a Server, AuthID and Location when connecting.

Protocol=protocol1, protocol2
ProtocolMap=n1,n2

If you are running SQLWizard against an XDB Server Version 4 (or newer), you may need to add several values (separated by commas) to the Protocol and ProtocolMap parameters in the [ConnectionDefaults] section of your xdb.ini file. The xdb.ini file segment shown below adds TCP/IP and IPX/SPX protocol support to SQLWizard:

[ConnectionDefaults]
Protocol=local,netbios,tcpip,spx
ProtocolMap=32,1,8,4

The table below shows allowable values for the Protocol and ProtocolMap parameters:

Protocol | ProtocolMap
netbios | 1
namedpipes | 2
spx | 4
tcpip | 8
appc | 16
local | 32
win32local | 64
[ClientPaths]

The paths in this section of xdb.ini correspond to the paths that you set on the Paths tab of the Options utility. For more complete descriptions of these options, see Paths Tab.

Executables=default-directory

Path to the directory where executables are stored.

Application=application-path\

Path to the directory where the system should write or look for application files such as SQL scripts and import/export batch files.

Temporary=temporary-path\

Path to the directory where SQLWizard writes temporary files, such as temporary query result files.

Overflow=alternate-temporary-path

Not currently used. An alternative directory where SQLWizard can write temporary files.

System=system-location

The name of the system location.

[ClientFormats]

This section of xdb.ini corresponds to the items that you set on the Formats tab of the Options utility. For more complete descriptions of these options, see Format Tab.

DateFormat=USA|EUR|ISO|JIS|LOCAL

Indicates the default date format to be used when displaying or entering dates.

DatePicture=dd.mm.yyyy

Indicates the date picture to be used if DateFormat is set to LOCAL. See Date Pictures Overview for a description of the date picture format.

TimeFormat=USA|EUR|ISO|JIS|LOCAL

Indicates the time format to be used when displaying or entering dates.

TimePicture=hh.mm.ss 24

Indicates the time picture to be used if TimeFormat is set to LOCAL. See Time Pictures Overview for a description of the time picture format.

MoneyPicture=-$$$$$$$$$,$$9.99

The money picture to be used when displaying or entering monetary amounts. See Numeric Masks Overview for a description of the money picture format.

DecimalPicture=-zzzzzzzzz,zz9.99

The decimal picture to be used when displaying or entering decimal numbers. See Numeric Masks Overview for a description of the decimal picture format.

WeekdayPicture=WWW

The format to be used when displaying or entering weekdays. See the Date Picture Elements for the weekday picture format.

FloatDecimalPlaces=2

Number of decimal places to be displayed for float fields.

TimeZone=0

The timezone offset from Greenwich Mean time. This is used for time math.

ShortMonthNames=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec

The strings to be used for the MMM formatted month portion of the date format.

LongMonthNames=January,February,March,April,May,June,July,August,September,October,November,December

The strings to be used for the MMMM formatted month portion of the date format.

ShortWeekNames=Mon,Tue,Wed,Thu,Fri,Sat,Sun

The strings to be used for the WWW formatted weekday portion of the date format.

LongWeekNames=Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday

The strings to be used for the WWWW formatted weekday portion of the date format.

[MultiUser]

This section of xdb.ini corresponds to the items that you set on the Multiuser tab of the Options utility. For more complete descriptions of these options, refer to the Multiuser Tab.

IsolationLevel=Lock Current

Indicates the isolation level to be used by default.

AutoCommit=On|Off

Indicates whether AUTOCOMMIT should by default be turned on or off.

TimeOutInterval=n

Indicates (in seconds) how long to wait before retrying when a lock conflict occurs.

BackwardLog=On|Off

Indicates whether the Backward Log is on or off. Not used when accessing an XDB Server Version 5.0 or higher.

ForwardLog=On|Off

Indicates whether the forward log (used for recovery) is on or off. Ignored by remote XDB Servers (Win3.x).

[Preferences]

This section of xdb.ini corresponds to the items that you set on the SQL tab of the Options utility. For more complete descriptions of all of these options, refer to the SQL Tab.

Other xdb.ini items that correspond to items on the SQL tab are described later in the description of the [SysAuthID] section.

CompatibilityMode=DB2|XDB|ANSI

The SQL compatibility mode to be used. This option indicates which set of SQL rules will be enforced.

EscapeCharacter=`

The character used to precede a special character to turn it into a literal.

AbortCharacter=<27>

The character used to halt some operations. For future use.

SortSequence=Case Insensitive ASCII (A=a,...)

Specifies the sort sequence that is to be used as the default for creating a location.

[QueryRunOption]

This section of xdb.ini corresponds to the items that you set on the Query Run tab of the Options utility. For more complete descriptions of these options, refer to the Query Run Tab.

MaxRecords=ALL|n

Indicates if all records should be retrieved or only the first n records when a query is run.

Execute=All Command|First Command|Current
     Command

Indicates if only the first, the current, or all commands in the current query window should be executed. The ALL and FIRST options apply to the SQL Edit window and batch SQL scripts. The CURRENT option applies only to the SQL Edit window.

ResultView=Table|Form

Indicates whether the default Result view should be a RESULT TABLE or a RESULT FORM window.

AllowEditing=On|Off

Indicates whether the system should by default try to go into Edit Mode when displaying a query result. If off, you must switch to Edit Mode yourself.

NoLookForPrimaryKey=On|Off

Specifies whether, during an edit-mode query, SQLWizard automatically searches the SYSINDEX and SYSKEYS tables and adds unique key fields to the query, even if the user has not explicitly selected them. Such action allows SQLWizard to generate the appropriate WHERE clause should the user subsequently choose to update any of the extracted data.

On certain databases (such as large DB2 3.x locations without a shadow catalog), the search for unique key fields can result in extremely long query times.

If your database has been designed so that a unique key is always selected, this option can be turned on to eliminate the search for unique keys, thereby improving performance.

AutoCommit=On|Off

Indicates whether AUTOCOMMIT should be on or off.

[QueryDefinition]

This section of xdb.ini corresponds to the items that you set on the Query tab of the Options utility. For more complete descriptions of these options, refer to the Query Tab.

QueryUsing=3PartName|2PartName|1PartName

Indicates if table names should be qualified when they are inserted into queries or dragged to the SQL Edit window from the Catalog Browser.

ShowTablename=On|Off

Indicates whether the default for the Query Design window should be to show table names in the Query Conditions Grid. If on, table names are shown.

ProhibitCartesian=On|Off

Indicates whether the default for prohibiting Cartesian products should be on or off.

AutoJoinForeignKey=On|Off

Indicates if tables should be automatically joined on foreign key relationships.

AutoJoinPrimaryKey=On|Off

Indicates if tables should be automatically joined on primary keys and columns with like names in another table.

AutoJoinLikeName=On|Off

Indicates if tables should be automatically joined on like column names. Turn off with care!

[Browser]

This section of xdb.ini corresponds to the items that you set on the Browser tab of the Options utility. For more complete descriptions of these options, refer to the Browser Tab.

ConfigType=n

Modify this option only through Options.

AutoRefresh=Off|On

Not currently used. Always off

AutoStartup=On|Off

If on, the Catalog Browser is automatically loaded when SQLWizard is started (you may want to do this to make SQLWizard load faster). If off, you must access the Catalog Browser through the View menu.

[SysAuthID]

This section of xdb.ini corresponds to the items that you set in the SysAuthID section of the SQL tab of the Options utility. Other xdb.ini items that correspond to items on the SQL tab are described previously in the description of the [Preferences] section. If you receive errors when you try to connect to DB2, you should suspect that you do not have privileges on the system catalog tables or views with the AuthIDs currently set. For more complete descriptions of all of these options, refer to the SQL Tab.

SysIBM=SYSIBM

Specifies the AuthID to be used when issuing queries against system catalog tables owned by SYSIBM. Often you will only have privileges on a view on the system catalog tables. Usually the view is created using the same table name, but a different AuthID than the underlying table. When running against XDB Link to DB2, you will usually use SYSIBM=XDB instead of SYSIBM=SYSIBM.

SysXdb=SYSXDB

Specifies the AuthID to be used when issuing queries against system catalog tables owned by SYSXDB. Often you will only have privileges on a view on the system catalog tables. Usually the view is created using the same table name, but a different AuthID than the underlying table. When running against XDB Link to DB2, you will usually use SYSXDB=XDB instead of SYSXDB=SYSXDB.

[Security]

This section of xdb.ini corresponds to the Client Security items that you set on the Security tab of the Options utility. For a more complete description of this option, refer to the Security Tab. (Other items that may appear in this section are used to configure server security.)

ClientSecurity=On|Off

If on, you will have to provide a password to connect to the XDB Server. If off, you will not be asked for a password.

[Connection server-name]

There should be an instance of this section for every server listed in the Servers statement in the [Connection Defaults] section. The items specified here indicate how to make a connection to the named server. They are used in the Options Connect page.

Protocol=protocol

This is the protocol to be used when accessing the specified server. See the Connection Defaults section for a list of protocols.

PrimaryAuthorizationID=authid

This is the default user name that will be used when you connect to this server.

CurrentLocation=location-name

This is the name of the default location that will be provided when you connect to this server.

[Client]

This section contains client-side parameters.

XDBCFG=configuration-directory

This is the path of the configuration directory on the client.

ReceiveBufferSize=size

This is the size of the communications buffer on the client side. The default is approximately 60 Kb.

BulkFetch=0|1

If 1, the default, bulkfetch is on.

ANSICP=ANSI-code-page

The ANSI code page to use on the client-side.

OEMCP=OEM-code-page

The OEM code page to use on the client-side.

[Server]

This section contains server side parameters

XDBSERVE=server-name

This is the name of the default server.

XSRVCFG=configuration-directory

This is the path of the configuration directory on the server.

ReceiveBufferSize=size

This is the size of the communications buffer on the server side. The default is approximately 60 Kb.

[Trace]

This section specifies parameters that need to be set if you want to generate debugging information by turning on client/server traces.

RedirSndRcvTrace=redir-trace-path

This is the path of the client redirector rrace file, for example, c:\redir.trace.

RouterTrace=router-trace-path

This is the path of the router trace file, for example, c:\router.trace.

TraceType=type

This is usually set to 1, although Micro Focus Technical Support representatives might ask you to change this setting.

FileName=engine-trace-path

This is the path of the engine trace file, for example, c:\server.trace.

Flush=0|1

This determines whether or not the trace file is flushed to disk after each trace file entry. The default is 1, which causes the trace file to be flushed to disk after each entry.

ErrorLog=log-file-path

This is the path of the error log file, for example, c:\xmem.errors.

Parent topic: Options Utility


SQL Wizard

SQL Wizard is a graphical utility that makes it easy to create, maintain and query XDB and DB2 databases. You can use SQL Wizard to:

  • Manage system security and priorities
  • Manage locations, tables and queries
  • Create and run queries
  • Enter data directly into a table
  • Import and export data
  • Run batch scripts
  • Managing Locations, Tables and Queries
  • Create and Manage Database Objects
  • Explore Your Database
  • Add Data to Your Tables
  • Importing and Exporting Data
  • Get Answers to Your Questions
  • Examine Your Results, Change Your Mind
  • Transport Your Data
  • Perform Batch Processing
  • Manage Users, Passwords, and Priorities
  • Connect Dialog Box Overview
  • Introducing the Catalog Browser
  • Common Database Management Features
  • Queries
  • Query Results
  • Data Entry
  • Batch SQL Scripts Overview
  • Import
  • Import NLS Considerations
  • Using Batch Import
  • Export
  • Export NLS Considerations
  • Using Batch Export
  • User Administration
  • Security and Authority Overview
Parent topic: SQL Option User Guide


Managing Locations, Tables and Queries

SQL Wizard's Catalog Browser window provides an easy way to manage locations, tables and queries, including XDB Server system tables (providing your AuthID has suitable authority). You can open it by clicking any entry on the View menu of SQL Wizard or by clicking
Catalog Browser button
on the toolbar. The Catalog Browser has three tabs: Locations, Table and Query.

If you are a superuser, you can use the Locations tab to manage locations. A superuser can create, alter and drop locations, as well as set the currently active location. Other users can only view a list of available locations.

The Table tab displays the hierarchy of locations, AuthIDs, tables and columns. From this page you can create, open, alter and drop tables, as well as view table definitions and indexes, primary keys, foreign keys, views, aliases and synonyms. Note that only a superuser can edit system tables.

The Query tab displays all stored queries accessible to the current server under the Location, AuthID and Query hierarchy. From this page you can create, open, run and delete queries.

Parent topic: SQL Wizard


Create and Manage Database Objects

Using SQLWizard, you can create a new location (including the system catalog tables) with a touch of a button. You can also create a new table complete with indexes, keys, and foreign keys.

Advanced option dialog boxes generate the appropriate SQL commands for creating DB2 tables, indexes, and other objects.

Parent topic: SQL Wizard


Explore Your Database

The Catalog Browser provides instant access to SQLWizard's database management facilities. You can expand and collapse the levels to find the object or definition for which you are looking. Double click a table name to open the table. Drag a query to the workspace to edit it, or use the Create, Alter, and Drop buttons to manage database objects.

Parent topic: SQL Wizard


Add Data to Your Tables

Once you have created a table, you can enter data in several ways.

You can use the Import facility to read data from other file formats into a table.

You can open a table and type data directly into the rows displayed in a Result window.

You can run a program containing embedded SQL to insert data into the table. The Micro Focus application development products are available to assist you in creating programs using COBOL and C.

Parent topic: SQL Wizard


Importing and Exporting Data

SQL Option can import and export data in a variety of formats. You can specify import and export settings by clicking New > Import or New > Export on the File menu of SQL Wizard. You can optionally save these settings in an .imp or .exp file that you can subsequently run as a batch file for routine data conversions.

Use SQL Option's import capabilities to run programs against test data prepared in another file format. For example, you could export suitable test data held in a Microsoft Access database, or a Microsoft Excel or Lotus 1-2-3 spreadsheet, to delimited or fixed-field ASCII files. You could then import these files into XDB Server.

You can import data into an XDB database from any of the following sources:

  • Free ASCII files (Delimited)

    Imports data from delimited (free-format) ASCII files.

  • Fixed-format ASCII files (Columnar)

    Imports data from columnar (fixed-format) ASCII files.

  • DSNTIAUL

    Imports data downloaded from IBM's DB2 using IBM's DSNTIAUL facilities.

Use SQL Option's export capabilities to transfer data from an XDB database to a mainframe DB2 database if you do not have gateway connectivity, or to create the DDL commands required to create a table.

You can export data from an XDB database into any of the following targets:

  • Free ASCII files (Delimited)

    Exports data to delimited (free-format) ASCII files.

  • Fixed width ASCII files (Columnar)

    Exports data to columnar (fixed-format) ASCII files.

  • DSNTIAUL

    Exports data to DSNTIAUL files. DSNTIAUL files can be read into DB2 systems.

  • SQL statements

    Generates DDL commands that can be used to re-create a table, insert data into it and create indexes on the table. COMMENT, WHERE and SYNONYM statements can be included.

Parent topic: SQL Wizard


Get Answers to Your Questions

Once your tables are created and populated with data, you are ready to write queries that answer questions about your data. SQLWizard's Query Design facility assists both new and experienced users in writing SQL statements by providing interactive windows, online help, syntax checking, and access to database object information.

If you prefer, you can type and edit SQL statements yourself using the SQL Edit window. A key feature is the ability to execute SQL statements that contain host variables directly from SQLWizard. With support for cut/copy/paste (using the clipboard), you can copy SQL code directly from your host programs, paste it into an SQL Edit window, and test the SQL without having to execute the host program. Likewise, you can use SQLWizard's Query Design facility to create your queries, switch to the SQL Edit window, and copy/paste the SQL statement to your COBOL program.

Parent topic: SQL Wizard


Examine Your Results, Change Your Mind

Even after you run a query, you can make changes to it. For example:

  • You can rearrange the column order.
  • You can hide columns if you decide you don't need them.
  • You can lock one or more columns in place, so that you can keep an eye on them as you scroll through the other columns.
  • You can sort the retrieved result on any combination of columns.

You get this flexibility without having to continuously rewrite and rerun your queries.

Query Result windows support bi-directional scrolling, and can be viewed and edited in either form or tabular views. You can send the results to a printer, or output them to a file.

Parent topic: SQL Wizard


Transport Your Data

Import and Export facilities are integrated into SQLWizard. Using Import you can read data from other file formats into a new or an existing XDB Server table. Supported import formats include delimited and tabular ASCII files, DSNTIAUL files, and others.

Export allows you to extract entire or partial sets of data from XDB Server tables and write them to external file formats. You can also export to SQL commands (which results in batch SQL files containing appropriate CREATE and INSERT statements). The Export facility can export a subset of columns, reorder the columns, and apply WHERE criteria to selection of data.

Both interactive and batch modes are provided for Import and Export facilities.

Parent topic: SQL Wizard


Perform Batch Processing

SQLWizard supports batch processing of SQL statements, including SQL that contains host variables. You can use SQL Wizard to run the following kinds of batch scripts:

  • Prompted queries
  • SQL scripts, including DDL and DML
  • Import files
  • Export files

To run a batch script, click Run Batch on the File menu in SQL Wizard.

Several other SQL Option utilities can create batch files; you can also run these from the appropriate utility. For example:

  • Use the Migrate utility to create and run .mig files
  • Use the Declaration Generator to create and run .dge files

SQLWizard also offers batch export and import facilities.

Parent topic: SQL Wizard


Manage Users, Passwords, and Priorities

You can perform user administration functions from the Admin menu. You can assign AuthIDs and passwords to users, and establish groups of users who will share the same privilege sets.

Parent topic: SQL Wizard


Connect Dialog Box Overview

Use the Connect dialog box to specify the parameters needed to establish a connection between SQLWizard and an XDB Server. The information appearing in this dialog box reflects the entries in the Options utility.

  • Suppressing the Connect Dialog with Autoconnect
  • Using Security
Parent topic: SQL Wizard


Suppressing the Connect Dialog with Autoconnect

If security is off, you can turn on Autoconnect in the Options utility to prevent the Connect dialog box from displaying. When the dialog box is not displayed, the defaults you specified for the Server, Location, and AuthID in Options are used to establish the connection.

Parent topic: Connect Dialog Box Overview


Using Security

If you are connecting to a multi-user XDB Server on a LAN, or if you are using XDB Link to access DB2 or another database system, your XDB Server Administrator will most likely require you to run with Security on, and you will have to enter a password. (If you are running against an XDB Server that is running with its security feature on, then you must turn SQLWizard's security on.)

To turn SQLWizard's security on, enable the Client Security option on the Security tab in the Options utility. This option causes the Connect dialog box to appear when SQLWizard is loaded, allowing you to enter a password.

Parent topic: Connect Dialog Box Overview


Introducing the Catalog Browser

The Catalog Browser provides access to locations, tables, indexes, and other objects stored in your XDB Server databases. Buttons at each level of object access allow you to create, alter, drop, and open database objects, as well as run queries. Opening a table is as simple as locating the table's name and dragging it to the SQLWizard workspace, or clicking the Open button; much simpler than having to type SELECT * FROM tablename in an SQL Edit window.

Parent topic: SQL Wizard


Common Database Management Features

The information in this chapter explains how to create, alter, and drop various database objects. Several features are common to many of the windows that you use to perform these functions. These include:

  • SQL button
  • Comments (Remarks) field
  • Options button
  • Managing Locations
  • Managing Tables
  • Managing Indexes
  • Managing Table Relationships
  • Managing Synonyms
  • Managing Aliases
  • Comments (Remarks) Field
  • Options Button
Parent topic: SQL Wizard


Managing Locations

A location is a collection of tables, databases, and related objects organized in a specific structure. An XDB Server can have multiple locations, all managed by the same database server. Depending on the options you have installed, SQLWizard can also access locations managed by other XDB Servers, as well as DB2 and other DRDA systems. Through the use of a three-part naming convention and related security measures, you can access more than one location at a time, including remote locations.

Connecting to a location provides you direct access to that location, without having to qualify table names with a location name. You set your initial (default) location in the Options utility. You can choose a different location each time you start SQLWizard by selecting a location on the Connect dialog box. After SQLWizard is running, you can change your current location using the Set Location command from the Location menu.

SQLWizard displays the current location and current SQLID in the status bar at the lower right of the SQLWizard window. Whenever you create, alter, or access a data object, this location and SQLID is used to qualify the table names.

You will also see a SYSTEM location listed in the Catalog Browser dialog box. This location contains system administration and security information. Do not store your data objects in this location. It is reserved for system use. Keep your data in locations that you or your XDB Server Administrator create.

Note: An XDB Server location roughly corresponds to a DB2 subsystem. However, you cannot use the XDB Server location windows to manage a DB2 subsystem. These windows are intended only for use with XDB Server locations.
Parent topic: Common Database Management Features


Managing Tables

As a relational database management system, SQLWizard stores data in a collection of tables. A table is a named data object made up of columns and rows of data. The data in one or more columns can usually be used to uniquely identify the rows of a table. These identifying columns are known as the primary key columns. Tables can be related to each other based on the data in one or more columns of the related tables. Indexes can be built on the table to speed retrieval and enforce uniqueness among records.

Often a table is identified with a three-part naming convention, where the table name is preceded by the Location and AuthID. The three parts of the name are separated by periods. For example, the table name SYSTEM.SYSIBM.SYSTABLES identifies the SYSTABLES table as being in the SYSTEM location and owned by the SYSIBM AuthID.

Parent topic: Common Database Management Features


Managing Indexes

An index is a data structure that speeds retrieval or enforces certain constraints, such as uniqueness, on the records in a table. This data structure is separate from the table and can be deleted and recreated without affecting table data. There are three types of indexes:

  • Index

    An index is an organized set of pointers to the rows of a database. Each index is based on the values of data in one or more columns.

  • Unique Index

    A unique index prevents the table from containing two or more rows with the same value in the index key.

  • Primary Key Index (for Referential Integrity)

    A primary key is a column or set of columns used to uniquely identify a row. Primary keys are required for referential integrity relationships. A table may contain at most one primary key.

    You can specify a primary key when you create a new table or when you alter an existing table. You can alter or drop a primary key. The method for creating, altering, and dropping a primary key is the same as for an index. The only difference is that the Type option must be set to Primary Key.

    You must define all columns involved in a primary key either as NOT NULL or NOT NULL WITH DEFAULT. When you define a primary key for a table, the Column Definition Grid on the Create/Alter Table dialog box is modified automatically. Any column that was defined with nulls allowed (False in the Not Null column) is changed to NOT NULL (True in the Not Null column). You can change the value in the Column Definition Grid to w/Default if you wish.

Parent topic: Common Database Management Features


Managing Table Relationships

You can use SQLWizard to relate the information in one table to that in another table. But, to be able to match records, the foreign key in the dependent table must have a column or collection of columns that match primary key columns in a referenced table.

For example, consider the EMPLOYEE and DEPT tables. Each employee must work in a department that exists. If every existing department must have a row in the DEPT table, then a foreign key built on the Dept column of the Employee table references the primary key of the DEPT table, which is the DEPT column.

If you try to assign an employee to a department that does not exist, you will get an error. If you try to delete a department that has employees working in it, you will get an error. Depending on how you define the foreign key, SQLWizard could automatically delete the employees for you.

If you change the Department ID for a department, SQLWizard may cascade these changes to the employees in that department, or display an error message depending on how you define the foreign key.

Figure 1. *
Image showing the relationships between EMPLOYEE and DEPT

Referential integrity constraints ensure that data from one table that must match data in another table is not altered inadvertently. If you look at the Create Relationship dialog box you see three options that help you to enforce referential integrity between your tables. Restrict is the default.

Parent topic: Common Database Management Features


Managing Synonyms

A synonym is another name given to an existing table or view. Usually a synonym is used to define a more meaningful name for a particular application or for the use of a particular set of users. You can use a synonym to refer only to a table or view in the current location. Use an alias to provide an alternate name for an object that can be accessed by users from other locations.

Parent topic: Common Database Management Features


Managing Aliases

An alias is an alternate name for a table or view, similar to a synonym. When you assign an alias to a table, you specify in which locations users can use that alias. You can specify the current location as well as remote locations. This differs from a synonym, which provides an alternate name for a table only to users in the location where the table resides.

Parent topic: Common Database Management Features


Comments (Remarks) Field

Most database objects (locations, tables, indexes, etc.) may be described by entering comments in the system catalog. In SQLWizard, this is accomplished by entering the comment or description in the Comments field of the Create or Alter dialog box. Comments entered in this manner appear in the Catalog Browser dialog box when the Details option is checked.

Parent topic: Common Database Management Features


Options Button

The primary Create, Alter, and Drop dialog boxes provide access to dialog boxes that allow you to enter additional information. These options are used to describe the database object or to specify some of the less common attributes for the object. In many (but not all) cases, these additional items relate to compatibility with DB2 or other non-XDB Server databases with which SQLWizard may be used.

Options button
To access these additional items, click the Options button. Specify any options desired, then close the Table Options dialog box to return to the dialog box you were using.

Parent topic: Common Database Management Features


Queries

  • What is a Query
  • Why Use Queries
  • Creating and Running SQL Queries
  • How are Queries Written
  • Query Design Window Overview
  • Table Display Area
  • Entering Data Directly into a Table
  • Query Conditions Grid
  • SQL Edit Window Overview
  • Results That Cannot Be Edited
  • Query Options
  • Querying Multiple Tables
Parent topic: SQL Wizard


What is a Query

A query is a question about your data that allows you to retrieve specific information from your database. It is an instruction to the database system to search for a particular set of data that is of interest to you, and to present it in a useful format.

A query is written as an SQL SELECT statement, as in the following example of a fairly complex query that finds the number of customers in each city in New York or California that has at least one customer. The result is sorted by state and city.

SELECT   St, City, Count(C_no)
FROM     Customer
WHERE    St="CA"  OR  City="New York"
GROUP BY St, City
HAVING   count(*) > 0
ORDER BY St, City

The SELECT statement consists of several important clauses.

  • SELECT Clause

    Lists the columns to be retrieved from the table(s).

  • FROM Clause

    Lists the tables from which data is to be retrieved.

  • WHERE Clause

    Consists of a set of conditions that the rows of data must satisfy.

  • GROUP BY Clause

    Organizes data into subsets or groups based on the values in the grouped columns. It is frequently used to create summary rows containing totals, sums, counts, averages, minimum values, and maximum values.

  • HAVING Clause

    Defines conditions that summary rows of data must satisfy.

  • ORDER BY Clause

    Specifies the order in which the rows of data should be sorted.

Parent topic: Queries


Why Use Queries

These are some of the reasons for writing a query:

  • To view all of the data in a table.
  • To view a subset of the columns in a table.
  • To view a subset of the rows in a table.
  • To sort the rows of a table.
  • To view new columns based on data in existing columns.
  • To provide data to be used as the basis of a report, or for processing by some other program.
Parent topic: Queries


Creating and Running SQL Queries

You can create SQL queries either by entering SQL statements directly into an SQL window (click
SQL Window button
on the SQL Wizard toolbar), or by using a prompted query in the Query Design window (click
Query Design button
on the toolbar). You do not need to understand SQL to create a prompted query. The Query Design window is split into two areas:

  • A schema view that shows the tables involved in your query and any relationships between them. This area of the window is called the table display area.
  • A query-by-example view, which shows the columns resulting from your query with any filters that you have applied to them. This area of the window is called the query conditions grid.

When you create a prompted query, you first select the table and columns. Then you apply conditions and sort criteria to the columns to achieve the final result set. Further choices are available from the menus, including joins, the creation of computed columns and the use of built-in functions such as minimum, maximum and average.

As you create a prompted query, the equivalent SQL statements are built up by SQL Wizard. To see them, click
SQL button
. You can edit the SQL statements directly but the changes you make do not appear in the Query Design window. To go back to the Query Design window, click
Query Design Window button
. It's a good idea to save your prompted query before you try editing it in the SQL window. You can run your query and see the results at any time by clicking
Run button
.

Parent topic: Queries


How are Queries Written

Queries to XDB Server and other supported database systems are always written in the form of an SQL SELECT statement. When you use SQLWizard to create a query, you can type the SELECT command yourself in an SQL Edit window, or you can use a Query Design window to assist you in generating the statement.

SQLWizard's Query Design facility assists both new and experienced users in writing SQL statements by providing interactive screens, online help, syntax checking, and access to database object information.

Because of the advantages of the prompted method of writing queries, we will focus primarily on this method. However, the section on the SQL Edit window will provide you with the information you need to know if you would rather type queries yourself. In addition, some SQL statements, including some variations of the SELECT statement, cannot be created or executed from the Query Design window. You will need to use the SQL Edit window to create and run these statements. Often you can use a Query Design window to help you write significant portions of these types of SQL statements.

Parent topic: Queries


Query Design Window Overview

As you use SQLWizard's prompted query facility to generate an SQL statement, you will become familiar with the Query Design window. You can have more than one copy of the Query Design window open at any given time. If a Query Design window is the active window, it will come to the front of other document windows and be known as the current query or active window.

The Query Design window consists of two sections:

  • The Table Display Area.
  • The Query Conditions Grid.

These sections are separated by a splitter bar. By positioning your mouse over the splitter bar and holding down the right mouse button, you can drag the splitter bar up or down to resize the two sections.

Parent topic: Queries


Table Display Area

The upper section of the Query Design window is known as the Table Display Area. The tables you select are added to the Table Display Area and are shown in Column Selection Lists. It is in this way that you can choose specific columns in a table for your query while in Query Design mode. The name of each table selected appears in the title bar of each Column Selection List. If there is a join relationship between two tables, you will see a line connecting the tables.

Parent topic: Queries


Entering Data Directly into a Table

SQL Wizard provides both a spreadsheet-like table view and a form view that enable you to enter and edit data directly. Use the table view to see many records at once and the form view to see one record at a time.

You must have appropriate access privileges to edit tables. Only a superuser can edit system tables. Ordinary users can edit tables created using either their own AuthID or a GroupID to which they belong. They can also edit tables to which they have specifically been given access using the GRANT statement. In all cases, you must select Allow Editing on the Record menu before editing is enabled.

You can open or create a table at any time from the Catalog Browser. See the topic Managing Locations, Tables and Queries for more information. The Table view opens automatically to show the result of a query.

Parent topic: Queries


Query Conditions Grid

The lower section of the Query Design window is known as the Query Conditions Grid. This is the area where you can Query-by-Example (QBE). Each column in your query appears as a column in the Query Conditions Grid. The rows of the grid allow you to type in conditions that the data in the columns must meet, as well as sort conditions, and other instructions for performing your query.

Parent topic: Queries


SQL Edit Window Overview

While there are many advantages to using the prompted query facility to generate your SELECT statements, there will be many times that you will need to type in SQL statements, or paste SQL statements from the clipboard. Using the SQL Edit window, you can write and execute any type of SQL statement.

You can also include multiple SQL statements in an SQL Edit window and execute each in turn, or skip through them one at a time, or run just the currently selected command.

Although many of the menu items and toolbar buttons used by the Query Design window are disabled in the SQL Edit window, you will run and save queries in the same way, regardless of which window you use.

Parent topic: Queries


Results That Cannot Be Edited

SQLWizard allows you to use the Result window to insert, update, and delete records after you run a query. However, some query results cannot be updated. For example, the query result for a query that includes a join, an ORDER BY clause, a GROUP BY clause, computed columns, or UNIONS is not updatable.

If you use the Query Design window to create a query that cannot be updated, the Allow Editing command on the Query menu is disabled before you run the query. In addition, the Allow Editing command on the Record menu in the Result window is disabled after you run the query.

Parent topic: Queries


Query Options

Query options are divided into two types: Query Design options, and Query Run options.

Query Design Options

These options control how your Query Design window appears, and how SQL is generated.

Define Query
3-Part Names | If checked, uses fully qualified table names in queries. If you get X28 errors, you should try checking this box.
2-Part Names | If checked, qualifies names with AuthID.
Unqualified Names | If checked, does not qualify names.
Show Table Names
If checked, adds a row to the Query Conditions Grid to show the name of the table from which a column comes.
Note:

Show Table Names button
Click the Show Table Names button to display the name of the table from which a column comes.

Auto Join Defaults
These options indicate the rules the system should use when automatically defining join conditions.
Join on Foreign Keys | If checked, automatically joins all columns involved in a foreign key relationship when the referenced and referencing tables appear in the Table Display Area of the Query Design window. This method of auto joining produces good results, since foreign keys are built on columns that are meant to be joinable.
Join on Primary Key With Like Names | If checked, automatically joins a primary key column with a column (or collection of columns) having the same name(s) in another table, provided both tables appear in the Table Display Area of the Query Design window. This method can result in some unintended joins if the primary key column name is a common name like CITY.
Join on Like Names | If checked, automatically joins a column with another column of the same name in another table, provided both tables appear in the Table Display Area of the Query Design window. This option should be used with care. It is frequently the case that columns that should not be joined have the same name as another column in a different table. If you use this option, you should carefully check each join that is generated automatically to make certain it is meaningful.
Prohibit Cartesian Products
If checked, looks for any queries that are executed from within this program to determine if they will yield Cartesian products.

Query Run Options

These options take effect when a query executes.

Execute
Only one of these options can be enabled at a time.
All Commands | If enabled, executes every command in the current SQL Edit window or .SQL script. If Step Mode is on, you have to use the Query menu Continue command to execute each step.
First Command | If enabled, executes only the first command in the SQL Edit window or .SQL script.
Current Command | If enabled, executes the command at the current cursor location if bounded by semicolons.
Default Result View
These options indicate if you want the default view for a result window to be a Result Table view (like a spreadsheet, showing multiple records at one time), or a Result Form view (shows one record at a time, with the fields arranged vertically). This option defines the default. You can switch to the other view at any time before or after a query is executed.
Edit Options
Allow Editing | If a query result can be edited, signals the system to go directly to edit mode. If a result cannot be edited, it has no effect and the Allow Editing option is grayed out.
AutoCommit | If a query result can be edited, indicates that the system should perform an automatic commit each time a record is updated, deleted, or inserted.
Max Records to Retrieve
You can limit run away queries by checking the First n Recordoption, and providing a reasonable value for n. Otherwise, every row has the potential of being retrieved. Note that SQLWizard tries to be intelligent when retrieving results. If you do not try to look at or otherwise access all of the rows in a result, it does not fetch all of them. However, if you perform a count, or if you print the result, or scroll to the bottom of the result, all rows will be retrieved, which could take some time depending on the query.
Parent topic: Queries


Querying Multiple Tables

Good database design usually results in a database with multiple tables related to each other by the values in certain columns. Even though the data is stored in separate tables, you will often want to see it in a single result. When you combine the data from two or more tables into a single result, you create a join.

Parent topic: Queries


Query Results

  • Introducing the Result Window
  • Result Window Views Overview
  • The Result Table View
  • The Result Form View
  • Current Record and Total Record Counts
Parent topic: SQL Wizard


Introducing the Result Window

The Result window displays when you successfully run a query or when you open a table using the Catalog Browser dialog box. Specifically, the Result window appears when you:

  • Run a query from the Query Design window using the Run command from the Query menu, or the Run button on the toolbar.
  • Run a query from the SQL Edit window using the Run command from the Query menu, or the Run button on the toolbar.
  • Execute a batch SQL script (.SQL file) Open or Run Batch commands from the File menu.
  • Open a table using the Catalog Browser dialog box.
Parent topic: Query Results


Result Window Views Overview

The Result window has two views: the Result Table view and the Result Form view. You can switch between these views by clicking the Result Table and Result Form buttons on the toolbar, or by using the Result Table and Result Form commands on the View menu.

Parent topic: Query Results


The Result Table View

The Result Table view displays the result of your query in a tabular grid-like format that shows multiple records at a time like a spreadsheet. Each row in the Result window corresponds to a row (or record) from the table. You may have to scroll horizontally to see all columns in the result, and scroll vertically to see all the rows in the result.

Note:

Result Table button
Click the Result Table button on the toolbar to place the Result window in Result Table view.

Parent topic: Query Results


The Result Form View

The Result Form view displays the results of your query one record at a time. The Result Form view shows each record (or as much as will fit in the window) with the fields arranged one above the other. If your records contain many fields or long fields, you may have to scroll horizontally to see all the fields of a given record.

Note:

Result Form button
Click the Result Form button to place the Result window in Result Form view.

Parent topic: Query Results


Current Record and Total Record Counts

While in the Result window, SQLWizard retrieves enough records to show a complete page in the window. Each time you scroll or page to display more records, you are commanding SQLWizard to retrieve the additional records. There are two major advantages to this approach:

  • Results are displayed more quickly.
  • Many records can be viewed simultaneously.
Note:

You can limit the total number of records that a query can retrieve by setting the Max Rows To Retrieve option in the Current Query Options dialog box or through the Options utility.

Notice that as you move the cursor to different records in a result, SQLWizard updates the RECORD n OF m message on the status bar at the bottom of the screen. The first number in this message is the current record number and the second is the total number of records in the query result. If the total number of records is unknown, you will see a ? in place of the record count. If you need to know the actual record count, you can request that the system perform a count by selecting the Count command on the Record menu.

To find the total record count for the result:

  1. Open the Record menu.
  2. Click the Count command.

    SQLWizard displays the current record number (relative to the retrieved set of records) and the total number of records in the result on the status bar.

    Note:

    Performing a count causes the SQLWizard to retrieve all of the records in the result. For some results, such as joins on large tables, this could take quite some time. This is why SQLWizard does not automatically perform a count for you.

Parent topic: Query Results


Data Entry

  • Using the Result Window for Data Entry Overview
  • Transaction Processing
  • Working in Autocommit Mode
  • Using Commit and Rollback
Parent topic: SQL Wizard


Using the Result Window for Data Entry Overview

SQLWizard allows you to use the Result window to insert, update, and delete records. To enter data, you must enable the Allow Editing option either before you run the query or after the result is displayed.

Parent topic: Data Entry


Transaction Processing

A transaction is an atomic unit of work, meaning that all of the steps in a transaction must be performed completely, all must be undone completely. SQLWizard supports the concept of a transaction by allowing you to commit or rollback all edits made to the result since the last commit or rollback.

Note: If accessing an XDB Server version 4.x or lower, you must turn on the Backward Log using the Options utility. If the Backward Log is not on, rollback commands will have no effect.
Parent topic: Data Entry


Working in Autocommit Mode

When SQLWizard is installed on your machine, the default setting for data entry transaction processing is Autocommit On. In this mode, all changes made to a record are committed as soon as you move to the next record. This means that you do not have to remember to commit periodically, and it frees any locks that might be held on records you are editing, so that other users have access to the data. However, it means that you have little chance to rollback changes.

For this reason, SQLWizard provides two undo commands. The Undo command in the Edit menu restores changes to the current field. The Undo command in the Record menu re-reads the current record from the database. Since the record changes were never written to the database, there is no need to perform a rollback. However, you cannot use the Undo command once you have left the modified record.

Parent topic: Data Entry


Using Commit and Rollback

If you turn Autocommit mode off, the Rollback and Commit commands in the Record menu are enabled. You can now make changes to several records, and then decide whether to commit (accept) or rollback (undo) all of these changes. Choose the appropriate command from the Record menu.

Note:

If accessing an XDB Server version 4.x or lower, you must turn on the Backward Log using the Options utility. If the Backward Log is not on, rollback commands will have no effect.

Parent topic: Data Entry


Batch SQL Scripts Overview

A batch script is a set of SQL statements that have been stored in a text file. A script is usually created by saving the contents of the SQL Edit window to an .SQL file. Once the script has been saved, it can be replayed at any time using the SQLWizard's Run Batch command. It can also be executed directly from your system's command line.

Any operation that can be performed interactively can be performed from a script-- you can create tables, insert and delete records, view query results, and more. A batch script is particularly useful to automate tasks that are run on a regular basis. Once you have created a script, it can be used over and over.

Parent topic: SQL Wizard


Import

  • Introducing Import
  • Using Other Import Features
  • Importing a File Overview
  • Source File Information
  • XDB Server Table Information
  • Import File Formats Overview
Parent topic: SQL Wizard


Introducing Import

SQLWizard Import allows you to insert data from various file formats into new or existing XDB Server tables or views. You can view the source file to be imported, set options for recording import process errors, have the system calculate a new table definition from your source file, and set up and run Batch Import commands.

Batch import is particularly useful if you repeatedly import data with the same or similar table definition. Each time you open an Import window and provide import specifications and then save the specifications to a file, you create a Batch Import file. Before using Batch Import, you should be familiar with interactive import for the file type you are importing.

The following is a list of file formats supported by SQLWizard. Depending on the format you select, you may need to specify a number of options before activating the import.

  • Free ASCII Files (Delimited)

    Imports data from delimited (free-format) ASCII files into XDB Server tables.

  • Fixed-format ASCII Files (Columnar)

    Imports data from columnar (fixed-format) ASCII files into XDB Server tables.

  • DSNTIAUL

    Imports data downloaded from IBM's DB2 using IBM's DSNTIAUL facilities.

Parent topic: Import


Using Other Import Features

Other features available with Import allow you to clear all import specifications from an Import window, specify error handling options, and view the contents of your source file or Batch Import file.

Parent topic: Import


Importing a File Overview

The Import window is separated into two sections. The Source File Information section is where you specify the file you want to import, specify the format of the file, and define other format-specific requirements. The XDB Server Table Information section is where you specify the destination XDB Server table. You can import data to an existing table (with options to append or replace data) or create a new table to hold the imported data.

Parent topic: Import


Source File Information

This section of the Import window is where you specify the name of the file from which you will import data, as well as the format of that file and any other parameters required for the selected format.

File Name | Enter the drive, path, and name of the file whose data you want to import.
Format | Use the drop-down list to select the format of the file you are importing. SQLWizard can import data from free- or fixed-format ASCII files, and DSNTIAUL files.
Other Source File Parameters | Depending on the format of the file being imported, additional parameters may be required.
Parent topic: Import


XDB Server Table Information

This section of the Import window is where you specify the name of the XDB Server Table that is to receive your imported data. You can import data into an existing XDB Server table, or create a new table and define its table definition structure right on the Import window.

Table
Enter the name of the XDB Server table that will receive your data.

To import data to an existing XDB Server table, use the Browse button to select a table. Check the Replace Data checkbox if you want the imported data to replace existing data in the table. To append the imported data to the existing data in the table, be sure the Replace Data checkbox is unchecked.

To use the imported data to create a new XDB Server table, check the Create Table checkbox and specify the items in the Table Definition Grid at the bottom of the window.

Create Table
Check this box when you want to use the imported data to create a new XDB Server table.
Replace Data
Check this box when importing data to an existing XDB Server table and you want to replace the existing data. When this option is checked, all data in the existing table is deleted and is replaced in its entirety with the new data coming from the file you are importing.
Table Definition Grid
When importing to an existing XDB Server table, this area of the screen shows the table structure.

When creating a new XDB Server table to hold your imported data, SQLWizard provides a suggested table definition. You can make changes as desired.

Name (Column Name)
If you do not specify column names when importing to a new table, Import attempts to read the field names from the source file (if the Heading checkbox is marked or the format indicates that field names are in the first record). Otherwise, the import program provides default names (Field1, Field2, ... Fieldn).
Type (Field Type)
When importing data to a new XDB Server table, you must specify field types. You do not necessarily need to use the same data types as in the source file. For example, you can redefine a NUMERIC field to be a CHARACTER field, but you should not redefine a CHARACTER field that contains non-numeric data as SMALLINT, INTEGER, OR FLOAT.
Length (Field Length)
If you choose to specify field lengths, you can specify the lengths of CHARACTER, VARCHAR, GRAPHIC, VARGRAPHIC, CHAR FOR BIT DATA, and VARCHAR FOR BIT DATA fields. You must also specify the precision and scale for DECIMAL fields (default is 5,0). Other field lengths refer to storage length and are provided automatically.
Null (Null Values)
Specify the null permission of the field. Indicate Yes if nulls are allowed, No if nulls are not allowed, and DEF if nulls should be converted to the default value for the field. The DEF option is the same as NOT NULL WITH DEFAULT.
Pic
Indicate if you want to use the mask specified on the Format tab in Options when importing MONEY, DECIMAL, DATE, and TIME fields:
  • Yes: Use the Options mask.
  • No: Do not use the Options mask. Instead, use the following default format masks:
    Type | Default Picture
    Time | hh:mm:ss
    Date | mm/dd/yyyy
    Decimal | <sign><digits>[.<digits>][E[+-]<digits>]
    Money | <sign><digits>[.<digits>][E[+-]<digits>]
    where:

    <sign> includes any combination of + - $ >=

    <digits> are 0 through 9; also comma (,) if to the left of the decimal place.
Src Off (Source Offset)
For importing fixed-format ASCII files. Should indicate the starting column number for each field in the source file. The system suggests offsets based on the white space found in the heading row of the source file.
Src Len (Source Length)
For importing fixed-format ASCII files. Should indicate the length of each data field. You might have to edit the Src Len column to correctly describe the source file.

When importing a fixed-format ASCII file to a new table, you must specify field lengths or use the HEADING= and SPACES= statements in your batch file. If the import program finds HEADING=Y and SPACES=1 or more, it will be able to determine the field lengths.

Parent topic: Import


Import File Formats Overview

This topic contains detailed information about each file format that you can import to an XDB Server table. These include:

  • Delimited (free-format) ASCII files
  • Columnar (fixed-format) ASCII files
  • DSNTIAUL files
  • Delimited (Free-Format) ASCII Files
  • Columnar (Fixed-format) ASCII Files
  • DSNTIAUL Files
  • Summary of Import Parameters by File Format
Parent topic: Import


Delimited (Free-Format) ASCII Files

Use this format to import data from delimited, free-format ASCII files. ASCII format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII output files. There are two ASCII file formats:

  • Delimited, free-format ASCII Files allow variable field lengths-- each field is separated by a field delimiter.
  • Columnar, fixed-format ASCII Files have fixed field lengths-- data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

The new XDB Server table definition suggested by SQLWizard when it examines a free-format ASCII file depends entirely on the data found in the file. You can examine the file yourself by using the Source File command from the View menu. If needed, you can change the suggested table definition in the table display area on the Import window.

When you use the Browse button to choose a file to import, SQLWizard defaults the file listing to the *.fre extension. The file you are importing can have a different extension.

The default field delimiter assumed for free-format ASCII files is an @ symbol. You can change this on the Import window or you can change the default by using the Defaults command from the Import menu.

The following table shows you the delimited ASCII format options:

Field Delimiter You must specify the field delimiter that is used to indicate where each field ends. The field delimiter differs from the record delimiter. The field delimiter is entered as a keyboard character or as an ASCII decimal code for a character. Decimal codes must be enclosed in angled brackets. For example, if the source file uses a # as the field delimiter, enter the character # or the string <35>. To use the < or > character as a delimiter, you must enter the ASCII decimal codes <60> or <62>, respectively.

If you don't know what the field delimiter is, use the Source File command from the View menu to display the source file. Optionally, you can use an ASCII text editor to examine the contents of the source file. If the field delimiter contains nonvisible ASCII characters, you might have to use a hex editor to examine the contents of the file.

If you specify a field delimiter that is not found in the file, you will not be allowed to continue. If your data uses a delimiter character that also appears in the data values, the system might try to create a table with too many fields. You can use a delimiter that is found in the data values only if the data values are surrounded by double quotes.

If you use a double quote character as the delimiter, the fields cannot also be enclosed in quotes. Do not use a comma as the delimiter if your data contains numeric values having commas as a grouping character.
Record Delimiter | The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. If your file uses a different end-of-record delimiter, you can change this setting. For example, you can import a file using the record delimiter <005><010>.
Values In Quotes If field values in your data contain quotes, click the Quotes checkbox to select it. Otherwise, be sure the Quotes checkbox is deselected. If data values contain quotes, you cannot use a quote as the field or record delimiter.

If fields are enclosed in quotes (either double- or single-), any delimiter character found within a pair of quotes is treated as part of the string. For example, if you are using a comma as a delimiter, and your source file contains the string "Washington, DC 20021", the entire string will be treated as one field, even though it contains the delimiter character. There must be a matching quote character for every quote character in the file. If your fields are enclosed in quotes, do not use quotes as a delimiter.

The system suggests a character data type for any columns of data enclosed in quotes; you can change the data type on the Field Definitions Grid at the bottom of the Import window.
Heading

If the first row of the file you are importing contains field names, click the Heading checkbox to select it. This tells Import to use those names as the column names in the table you are creating. If record data begins in the first row, then uncheck the Heading checkbox to turn off inclusion of a heading row.
Insert Nulls As Defaults | Select this checkbox if you would like to insert the columns' default values in place of NULLs in the source file for those defined WITH DEFAULT.
Parent topic: Import File Formats Overview


Columnar (Fixed-format) ASCII Files

Use this format to import data from columnar, fixed-format ASCII files. This format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII output files. There are two ASCII file formats:

  • Delimited, free-format ASCII Files allow variable field lengths-- each field is separated by a field delimiter.
  • Columnar, fixed-format ASCII Files have fixed field lengths-- data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

The new XDB Server table definition suggested by SQLWizard when it examines a free-format ASCII file depends on the data found in the file and the parameters you enter on the Import window. You can examine the file by using the Source File command from the View menu. If needed, you can change the suggested table definition in the table display area on the Import window. You must specify the following:

  • Spaces
  • Heading
  • Offset
  • Source Length

When you use the Browse button to choose a file to import, SQLWizard defaults the file listing to the *.fix extension. The file you are importing can have a different extension.

The following table shows you the fixed-format ASCII format options:

Spaces |  | The Import utility requires that you confirm the number of blank spaces between columns. This is done by providing a number in the Spaces entry field on the Import window.
Heading |  | If the first row of the file you are importing contains field names, click the Heading checkbox to select it. This tells Import to use those names as the column names in the table you are creating. If record data begins in the first row, then uncheck the Heading checkbox to turn off inclusion of a heading row.
Table Definition |  | When importing fixed-format ASCII files in interactive mode, SQLWizard suggests a table definition based on the contents of the data file. You must examine and modify the source file offsets and lengths in the suggested table definition before you import the file. This must be done for all fixed-format ASCII imports, even if you are importing to an existing XDB Server table.
 | Offsets | Each column of data in a fixed-format ASCII file begins at a fixed point. The Offsets parameter indicates the number of characters from the beginning of the record to the beginning of the column specified. The system examines the row containing the column names (if any) to determine the offset. If the column names appear in the first row and consist of a single word that is left-justified over the column, the system should find the correct offset for you. Otherwise you will have to examine the data to determine the offset, and enter it in the appropriate location in the Offset column of the Table Definition Grid. Use the Source File command from the View menu to display the source file. The ruler at the top of the window corresponds to the offset. Use the beginning column number as the offset for each column. For example, in the following file, the offset for the E_NO column is 1, the offset for the LNAME column is 11, etc.
 | Src Len (Source Length) | When importing fixed-format ASCII files, Source Length refers to the width of the column in the source file. This value is used to determine where a column of data ends. Even if the target XDB Server table already exists, you must supply the length of each column in the source file. SQLWizard suggests a length for fields based on the source file structure. You must check and correct the source length for all columns in the Table Definition Grid before attempting to import the table.
Parent topic: Import File Formats Overview


DSNTIAUL Files

Code Page Support

If any translation tables are defined in SYSIBM.SYSSTRINGS, they will appear on the Import window in the Codepage list box. The format in the list box is FROM n1 TO n2, where n1 is the number of the code page being translated from and n2 is the number of the code page being translated to.

When you select an item from the Codepage list box, Import loads the translation table for that conversion and uses it to convert character data during the import operation. You can specify which fields to convert by selecting Yes or No in the EBCDIC column of the Table Definition Grid. Normally, a conversion is performed for all applicable fields.

The format of the SYSIBM.SYSTRINGS table is as follows:

Column Name | Type | Length | Description
INCCSID | int | 2 | Code page number to translate From.
OUTCCSID | int | 2 | Code page number to translate To.
TRANSTYPE | CHAR | 2 | Not used by Import.
ERRORBYTE | CHAR | 1 | Not used by Import.
SUBBTYPE | CHAR | 1 | Not used by Import.
TRANSPROC | CHAR | 8 | Not used by Import.
IBMREQD | CHAR | 1 | Not used by Import.
TRANSTAB | VARCHAR for bit data | 256 | Translation table to convert from INCCSID code page to OUTCCSID code page.
Parent topic: Import File Formats Overview


Summary of Import Parameters by File Format

The following table shows which import parameters are required for each file format.

Import Parameters |  | Batch Keyword | Free ASCII | Fixed ASCII | DSNTIAUL
Source File Name |  | FILENAME | Required | Required | Required
Fld names in 1st row? |  | HEADING | Required | Required |
Field delimiter |  | FLD_DELIMITER | Required |  |
End of rec delimiter |  | REC_DELIMITER | Required |  |
Values in quotes? |  | QUOTE | Required |  |
How many fields? |  |  |  | Required |
Insert Null as blank? |  | INS_NULL | Required | Required | Required
XDB Server Table name |  | TABLE | Required | Required | Required
If table exists: |  |  |  |  |
 | Append or Replace | REPLACE |  | Required | Required | Required
If table does not exist: |  |  |  |  |
 | Name | FIELDS |  | Required | Required | Required
 | Type | TYPES |  | Required | Required | Required
 | Length | LENGTH |  | Required | Required | Required
 | Null? | NULL_PERM |  | Required | Required | Required
 | PIC? | USE_PIC |  | Required | Required | Required
Source Offset |  | OFFSETS |  | Required |
Source Length |  | SRC_LENS |  | Required |
Source File type |  | FORMAT | Required | Required | Required
Convert EBCDIC values to ASCII |  | EBCDIC_TO_ASCII |  |  | Required
Code Page |  | EBCDIC_CODEPAGE |  |  | Required
 |  | ASCII_CODEPAGE |  |  |
Insert Mode |  | INSERT_MODE | Required | Required | Required
Commit Interval |  | COMMIT_INTERVAL | Required | Required | Required
Log Errors |  | ERR_LOG_FILE | Required | Required | Required
On Error |  | ON_ERROR | Required | Required | Required
Parent topic: Import File Formats Overview


Import NLS Considerations

You need to be aware of character set conversion issues when importing data, especially if:

  • Your data contains diacritical (accented) or other characters that lie outside the first half of the ASCII character set
  • Your data was created using a variety of EBCDIC code pages

If you are importing EBCDIC data using SQL Wizard, we recommend using the DSNTIAUL data format as this enables you to specify an appropriate EBCDIC to ANSI or ANSI to EBCDIC conversion.

You specify the appropriate conversion by picking an entry in the code page window. For example, to import a Spanish EBCDIC table, you would pick the EBCDIC to ANSI translation 284 - 1252.

Parent topic: SQL Wizard


Using Batch Import

When you enter import specifications and use the Save As command from the File menu, you are saving the contents of the Import window. The saved file is a Batch Import file containing one import transaction. It has an .imp file name extension. A Batch Import file can also be created using any ASCII text editor. You can preview how an import specification would look as a batch file by clicking on Batch Import Commands from the View menu.

Batch Import is particularly useful when you have a number of similar files to import, or when you import the same files on a regular basis. Once you have created a Batch Import file, you may use it over and over, with or without modification.

Parent topic: SQL Wizard


Export

  • Introducing Export
  • Using Other Export Features
  • Exporting a Table Overview
  • Saving and Reusing Export Specifications Overview
  • Export File Formats Overview
Parent topic: SQL Wizard


Introducing Export

SQLWizard Export allows you to transfer the contents of any XDB Server table or view into a file in any of the supported file formats. You can export the columns of an existing table in any order or export a subset of the columns. In addition, you can specify a WHERE condition to export only selected data from the original table. Features are available to log the export process, set your own defaults for various export options, and set up and run Batch Export commands.

Batch export is particularly useful if you repeatedly export data from the same tables. Each time you open an Export window and provide export specifications and then save the specifications to a file, you create a Batch Export file. Before using Batch Export, you should be familiar with interactive export for the type of file to which you are exporting.

The following is a list of file formats supported by SQLWizard. Depending on the format you select, you may need to specify a number of options before activating the export.

  • Free ASCII Files (Delimited)

    Exports data from XDB Server tables to delimited (free-format) ASCII files.

  • Fixed Width ASCII Files (Columnar)

    Exports data from XDB Server tables to columnar (fixed-format) ASCII files.

  • DSNTIAUL

    Exports data from XDB Server tables to DSNTIAUL files. DSNTIAUL files can be read into DB2 systems.

  • SQL Statements

    Generates SQL commands that can be used to re-create a table, insert data into it, and create indexes on the table. COMMENT, WHERE, and SYNONYM statements can be included.

Note: XDB Server indexes are specific to the XDB Server environment and are not relevant to any other environment. Index information is environment-specific and depends on the operating system. Therefore, SQLWizard Export will not export the indexes when it exports a table. However, if exporting to SQL statements, you can generate the SQL CREATE INDEX command that will re-create an index on an XDB Server or DB2 system.
Parent topic: Export


Using Other Export Features

Other features available with Export allow you to clear all export specifications from an Export window, specify error handling options, and view the contents of your target file or batch import or Batch Export files.

Parent topic: Export


Exporting a Table Overview

The Export window is divided into two sections. The Target File Information section is where you specify the file that will receive your exported data. The Source Table Information section is where you specify the table whose data you will be exporting. There are two versions of the Source Table Information section. You choose which one to use by selecting Design Mode or SQL Mode from the View menu, or by specifying your preference in the Export Default Settings dialog box.

Parent topic: Export


Saving and Reusing Export Specifications Overview

Export specifications can be saved and reused. Saving a specification as it appears on an Export window creates a Batch Export file containing one export transaction. The saved file can be redisplayed and run in an Export window, or can be run using the Batch Export facility. Using an editor, you can copy and paste to combine the contents of multiple batch files to run them as one job.

Parent topic: Export


Export File Formats Overview

This topic contains detailed information about each file format to which you can export XDB Server data. These include:

  • Delimited (Free Format) ASCII files
  • Columnar (fixed-format) ASCII files
  • DSNTIAUL files
  • SQL statements
  • Delimited (Free Format) ASCII Files
  • Columnar (Fixed-Format) ASCII Files
  • DSNTIAUL Files
  • SQL Statements Overview
Parent topic: Export


Delimited (Free Format) ASCII Files

Use this format to export data from an XDB Server table or view to a free-format ASCII file. ASCII format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII files. There are two ASCII file formats:

  • Delimited Free Format ASCII Files allow variable field lengths - each field is separated by a field delimiter.
  • Fixed-format ASCII Files have fixed field lengths - data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

When you use the Browse button to choose a target file, Export will search for the selected file format. Free format is indicated by the file name extension .fre.

You must specify a field delimiter to indicate where each field ends. The field delimiter differs from the record delimiter. The field delimiter can be typed as keyboard characters or as ASCII decimal codes enclosed in angle brackets. For example, to use a colon for a field delimiter, enter the character : or the string <58>. To use an angle bracket character ( < or > ) as a delimiter, you must enter the ASCII decimal codes <60> or <62>, respectively.

When specifying a delimiter, take care not to use a character found in your data, or in the default masks for the data types in the exported table. For example, do not use a comma as the delimiter if your data contains numeric or money values grouped with a comma. The default delimiter is an @ symbol.

Record Delimiter | Enter a character to be used as the end-of-record delimiter. The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. You can specify a different record delimiter to handle other file structures. For example, you could specify the field delimiter as <008><010> and the record delimiter as <005><010>.
Quotes | Select the Quotes checkbox if you want character fields in your target file to be enclosed in quotes. When character fields are enclosed in quotes (either double- or single-), any delimiter character found within the quotes is treated as part of the string. For example, if you are using a comma as a delimiter, and your source file contains the string "Washington, DC 20021", the entire string will be treated as one field even though it contains the delimiter character. Note: If your fields are enclosed in quotes, do not use quotes as a delimiter.
Heading | Select this option if you want to insert the column names in the first row of the target file. If you do not want columns names to appear in the first row, deselect the Heading checkbox.
Parent topic: Export File Formats Overview


Columnar (Fixed-Format) ASCII Files

Use this format to export data from an XDB Server table or view to a fixed-format ASCII file. This format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII files. There are two ASCII file formats:

  • Free Format ASCII Files allow variable field lengths-- each field is separated by a field delimiter.
  • Fixed-format ASCII Files have fixed field lengths-- data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

Because every record fits into a standard form, field delimiters are not required for this format. However, you do need to specify number of space characters to be entered between columns and whether or not a header row should be exported.

When you use the Browse button to choose a target file, export will search for the selected file format. Fixed-format is indicated by the file name extension .fix.

The following table shows you the columnar fixed-format ASCII format options:

Spaces | Enter a number to indicate how many space characters should be inserted between columns of data in the exported file.
Heading | Select this option if you want to insert the column names in the first row of the target file. If you do not want columns names to appear in the first row, deselect the Heading checkbox.
Parent topic: Export File Formats Overview


DSNTIAUL Files

Use this format to export data from an XDB Server table or view into the DSNTIAUL file format. DSNTIAUL is a mainframe format (File UNLOAD Utility) that is used with DB2.

When you use the Browse button to choose a target file, export will search for the selected file format. DSNTIAUL format is indicated by the file name extension .dsn.

In DSNTIAUL files, all data is consecutive (no delimiters), and padded for the full length of the field, making it more like a columnar (fixed-format) ASCII file. If nulls are allowed, a one-byte trailer after each field indicates null status:

  • A zero (0) indicates NOT NULL.
  • An EBCDIC question mark (?) indicates NULL.

Data types are exported as follows:

  • Text fields are stored in EBCDIC format.
  • Date, Time, and Timestamp fields are stored as text.
  • Decimal and Money fields are stored in BCD format.
  • Smallint fields are stored in binary format. As the field is read, its byte order is automatically transformed from standard Intel format (where the least significant byte is first) into standard binary format (where the most significant byte is first).
  • Integer fields are stored in binary format. As the field is read, its byte order is automatically transformed from standard Intel format (where the least significant byte is first) into standard binary format (where the most significant byte is first).
  • Float fields are stored in binary format (different from PCs).
  • Varchar fields have a two-byte header containing the length of the text.

The DSNTIAUL file format directly depends on the null permissions of the exported table. Therefore the null permissions of the table you import into must match the table's null permissions from which you exported.

The DSNTIAUL format uses a page-oriented storage for each record in the table. The typical page size is approximately 4K bytes. When the table contains a long varchar field (which is 4056 bytes long), information in this field may be truncated. The size of the long varchar field is truncated to the page size minus the sum of the sizes of the other fields in the table.

Export to DSNTIAUL format can make use of Code Page Support. This allows you to export objects to DSNTIAUL in EBCDIC and retain object names containing foreign characters. By default, Export assumes character data is stored in the source tables using the American ASCII character set and converts it to the American ASCII character set before writing it to a target file. See "ASCII Table" for a listing of the decimal ASCII character sets.

You can have the Export utility translate character data containing characters from any international EBCDIC character set using the code page feature in Export. For the EBCDIC code page, use the default EBCDIC character set for your country. Code page support is provided by the INCCSID and OUTCCSID fields in the SYSIBM.SYSSTRINGS table at the SYSTEM location.

The following table shows the structure of the SYSIBM.SYSSTRINGS table.

Column Name | Type | Length | Description
INCCSID | int | 2 | Code page number to translate FROM.
OUTCCSID | int | 2 | Code page number to translate TO.
TRANSTYPE | CHAR | 2 | Not used by Export.
ERRORBYTE | CHAR | 1 | Not used by Export.
SUBBTYPE | CHAR | 1 | Not used by Export.
TRANSPROC | CHAR | 8 | Not used by Export.
IBMREQD | CHAR | 1 | Not used by Export.
TRANSTAB | VARCHAR for bit data | 256 | Translation table to convert from INCCSID code page to OUTCCSID code page (ASCII to EBCDIC)

When the Export utility uses code page options, the values entered for INCCSID and OUTCCSID are compared with values in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert XDB Server data in ASCII format to DSNTIAUL data in EBCDIC format.

Parent topic: Export File Formats Overview


SQL Statements Overview

Use this option to generate a file containing standard SQL CREATE, INSERT, INDEX, SYNONYM, CHECK, and COMMENT ON commands that will allow a table or view and the data it contains to be re-created in another SQL environment. This option generates a standard Batch SQL file that can be used directly by SQLWizard's Batch SQL or other SQL DBMS applications. You can run an exported SQL file on a mainframe DB2 system as a means of copying tables and data from XDB Server to DB2.

The standard SQL commands you can create with this Export format are:

  • CREATE TABLE
  • CREATE INDEX
  • CREATE SYNONYM
  • COMMENT ON
  • INSERT
  • ALTER TABLE...CHECK.

When you use the Browse button to choose a target file, export will search for the selected file format. The SQL Statement format is indicated by the file name extension .SQL.

Specify what types of SQL statements you would like to have generated from the source table or view by clicking on the desired SQL statement checkboxes. The table below describes each option.

SQL Option | Generated SQL Statements
CREATE | Generates a CREATE TABLE or CREATE VIEW statement that will re-create the table or view when the exported SQL file is run in Batch SQL.
INSERT | Generates INSERT INTO statement(s) that will insert the source table data into the re-created table or view when the exported file is run in Batch SQL.
INDEX | Generates CREATE INDEX statement(s) that will create index(es) for the recreated table when the exported file is run in Batch SQL.
SYNONYM | If synonyms exist for the source table (or view) or for any columns in the source table, this option generates CREATE SYNONYM statement(s) that will create the same synonyms when the exported file is run in Batch SQL.
CHECK | If exporting a table, this option generates an ALTER TABLE command with the CHECK option. You can modify the statement to define the conditions for the check constraint. If exporting a view that was originally created using the WITH CHECK OPTION, the WITH CHECK OPTION is included in the CREATE VIEW statement generated by this utility.
COMMENT | Generates COMMENT ON statement(s) for the table and for each column.
SQL Statement Option | Description
DB2 Options for CREATE TABLE | Enter DB2 options if you are planning to run your exported SQL file on a mainframe DB2 system. Click the Create (Create Table) checkbox to select it, and then click the DB2 button to the right of it to specify mainframe options for the IN DATABASE clause to be generated. These options make the SQL statements more compatible with your target environment.
DB2 Options for CREATE INDEX | Enter DB2 options if you are planning to run your exported SQL file on a mainframe DB2 system. Click the Index checkbox and then click the DB2 button to the right of it to specify DB2 Create Index options. These options make the SQL statements more compatible with your target environment.
Parent topic: Export File Formats Overview


Export NLS Considerations

You need to be aware of character set conversion issues when exporting data, especially if:

  • Your data contains diacritical (accented) or other characters that lie outside the first half of the ASCII character set
  • Your data was created using a variety of EBCDIC code pages

If you are exporting EBCDIC data using SQL Wizard, we recommend using the DSNTIAUL data format as this enables you to specify an appropriate EBCDIC to ANSI or ANSI to EBCDIC conversion.

You specify the appropriate conversion by picking an entry in the code page window. For example, suppose you want to export a Swedish EBCDIC table. During the export, you would pick the ANSI to EBCDIC translation 1252 - 278.

Parent topic: SQL Wizard


Using Batch Export

When you enter export specifications and use the Save As command from the File menu, you are to saving the contents of the Export window. The saved file is a Batch Export file containing one export transaction. It has a .exp file name extension. A Batch Export file also can be created using any ASCII text editor. You can preview how an export specification would look as a batch file by clicking on Batch Export Commands from the View menu.

Batch Export is particularly useful when you have a number of similar tables to export, or when you export the same table(s) on a regular basis. Once you have created a Batch Export file you can use it over and over, with or without modification.

Parent topic: SQL Wizard


User Administration

  • Introducing Administrative Features
  • Managing Users and XDB Server Access Overview
  • Managing Groups Overview
  • Setting XDB Server Priorities
Parent topic: SQL Wizard


Introducing Administrative Features

This topic provides information on setting up AuthIDs, Groups, and Privileges. In addition, access to the XDB Server can be limited using the Governor features.

The AuthID is used for identification and security purposes when you access an XDB Server, utilities, and database objects. Passwords provide additional access security. Groups enable XDB Server Administrators to easily grant privileges to subsets of the user population who have similar needs. The Governor is used to invoke special access limitations.

System security can be complex. A complete discussion of the inter-relationships of the various security options is provided in "Security and Authority." You should be familiar with that information before setting up system security, AuthIDs, groups, authorities, and privileges.

Information you enter using the Admin menu commands is transformed into standard SQL UPDATE, INSERT, and DELETE statements that are sent to the XDB Server for execution against the appropriate system tables. Other security measures can be activated through the use of the SQL GRANT and REVOKE commands.

Parent topic: User Administration


Managing Users and XDB Server Access Overview

The Users command on the Admin menu allows an XDB Server Administrator (super user) to add, view, and modify AuthID specifications for all users of the currently connected XDB Server, including whether a password is required at connect time and the type of user (user or super user). The XDB Server Administrator can also assign a selected user to one or more groups, thus providing an easier means of granting database privileges to subsets of the user population who have similar needs. In addition, XDB Server Administrators can remove users (temporarily or permanently), assign priorities to users for XDB Server access, and provide a SecondaryID. (SecondaryIDs provide an alternate means of assigning privileges to groups of users.

When the Users command is selected from the Admin menu, the Add/Modify User dialog box is displayed. This is where you will add, delete, and update AuthIDs.

Parent topic: User Administration


Managing Groups Overview

A group allows an XDB Server Administrator to control location, database, and table level privileges using a GroupID. An XDB Server Administrator can define groups and assign them to users using the Groups dialog box. Using the SQL GRANT command, database and table privileges are then assigned to the GroupID rather than to each individual user who needs access to those database objects. This method gives the same privilege set to each user in the group. If a user belongs to multiple groups, that user has the privileges of all those groups.

Once a group has been created, it appears in the Group Membership list on the Add/Modify User dialog box. This provides an alternate means of assigning a user to a group.

Note: In some cases it might be better to give users a common Secondary ID.
Parent topic: User Administration


Setting XDB Server Priorities

Priorities are a set of usage restrictions imposed on an AuthID. Setting priorities gives an XDB Server Administrator the ability to define XDB Server usage priorities for peak hour processing, or to restrict users who do particularly intensive queries to off-peak hours.

You control a user's access to an XDB Server by defining a priority (a set of usage restrictions) and then assigning the priority to the user's AuthID. An AuthID that exceeds any of the limits of it's assigned priority is disconnected from the XDB Server.

Note:

If you are not running against an XDB Server version that supports priorities, or if the XDB Server has the Governor feature turned off, the Priorities command is grayed out on the Admin menu.

A new or changed priority does not take effect until the XDB Server is shut down and restarted.

Priorities are defined through the Define Priority dialog box. Priorities can be defined to limit users by number of API calls, amount of time in the XDB Server SQL engine, amount of time processing calls, amount of idle time and/or the number of fetches. You can also set the times of the day when these limits are in effect.

All the limits set for a priority are checked by the Governor on the XDB Server. Using the Server Configuration utility, you set the MAXIMUM GOVERNOR CYCLE TIME to define how often the governor checks whether a user has exceeded priority limits. To turn off the XDB Server Governor, set this cycle time to zero. Because the frequency with which the governor checks the user's limit status is not infinitely small, it is possible for the limits to be slightly exceeded before the governor takes action. For more information about the Governor features of the XDB Server, see the description of the Maximum Governor Cycle Time option in the section Governor Cycle Timein the chapter Server Configuration Utility in your SQL Option Server Administration Guide.

Parent topic: User Administration


Security and Authority Overview

XDB Servers provide a full featured security system, including the ability to define Primary Authorization IDs (AuthIDs), SecondaryIDs, and groups for users, the ability to grant and revoke privileges for users and groups at system, database, table, and column levels, and a choice of using a four- to eight-character password mask (with conditions).

  • Security System Concepts
  • Managing System Security and Priorities
  • System Level Access Control
  • Password Enforcement Level
  • XDBACF Database
  • AuthID Types
  • Current SQLID
  • AuthID Ownership and Usage Rules
  • Effect of AuthIDs on Object Names and Usage
  • Granted Authorities and Privileges
  • Predefined XDB Server Authorities for GRANT and REVOKE
  • The DSNDB06 Database
  • Granting and Revoking Privileges
Parent topic: SQL Wizard


Security System Concepts

XDB Servers are shipped with security turned off to allow you unlimited access to the system. You can continue to operate without security indefinitely, if desired, even in a multi-user environment.

If you do plan to use the XDB Server security features, starting with security off gives you a flexible development environment. You can create locations, databases, and other objects, and set up the required AuthIDs (user names), passwords, groups, and privilege sets you will need for controlling user access before you turn on security.

In a multi-user environment, if security is on at the server, all users must have security on at their individual workstations. If security is off at the server, individual users can have security on, if desired, to protect against unauthorized access at the workstation.

After security is turned on, each user or process must log in with a valid AuthID. If the AuthID has a password defined and required, the password must be entered as well.

To turn server security off, a user must have a valid AuthID with appropriate privileges to be able to access the Security Option in the XDB Server Configuration utility or the Options window as appropriate.

One special AuthID, INSTALL, is created when you install the XDB Server. The INSTALL user is an XDB Server super user. If you do not turn on security, you will not need to be concerned with this special AuthID or its password.

Note:

As long as security remains off and you do not create additional AuthIDs, all objects you create will belong to the Primary AuthID indicated in your Profile (that AuthID becomes the qualifying name in the three-part object name:location-name.authid.object-name). When you install XDB Server, the default AuthID in Options is TUTORIAL. You might wish to change this AuthID if you plan to turn security on and add more users to your system at a later date.

You can change the AuthID that is used for object creator names by any of the following methods:

  • Change each client's Primary AuthID by entering the value into the AUTHID field of the Options dialog box's Connect tab.
  • Issue the SET CURRENT SQLID command before you create the object.
  • Explicitly specify a valid AuthID when you create the object (by specifying a two- or three-part name in the CREATE statement (if specifying a three-part name, the location part of the name must be the current location).

Alternatively, you can create several AuthIDs and grant a different privilege set to each, using these AuthIDs for different purposes. You can also create a group, which allows you to grant the same privilege set to several or many AuthIDs.

When security is on, the super user is a special user. A super user is the only one who can:

  • Create and drop locations.
  • Edit (update) system tables.
  • Assign super-user privileges to another AuthID.

The Admin menu commands are used to assign super-user privileges. The SQL Grant and Revoke commands cannot be used for assigning super-user privileges.

On a multi-user system (or any system where security is an issue), you should assign a password to the INSTALL SUPER USER AuthID. You might wish to set up a few additional AuthIDs with super-user privileges before you turn on security. This allows you to have several other trusted users as a backup to the XDB Server Administrator.

Parent topic: Security and Authority Overview


Managing System Security and Priorities

SQL Option is provided with the security and administration features you would expect of a database system. Depending on how you intend to use it, however, you might not need to enable the security features. For this reason, your personal XDB Server and its client tools and utilities are initally installed with security switched off.

Security is controlled separately at the server and at the client. If you switch security on for an XDB Server, it can only be accessed by clients that also have security switched on. (In this context, a client is one of the XDB configuration tools or graphical data utilities. The client applications that you develop are expected to handle authorization in the usual way by means of CONNECT statements). If you are developing a DB2 application that handles passwords, you may want to work with a test environment that has security switched on to enable user authentication.

Use the Admin menu of SQL Wizard to manage system security. You can control security at three levels:

  • All users
  • Named groups of users
  • Individual users

When security is switched off for an XDB Server, all users are effectively superusers because:

  • No passwords are required
  • All users share a common AuthID, specified on the Connect tab of the Options utility
  • All users have access to both client and server utilities

Server security status is set using the Server Configuration utility (accessible by clicking SQL For DB2 > XDB Server on the Options menu). Once security has been enabled, users must log on with a valid AuthID and, if required, password. The user's actual AuthID replaces the shared one, which means that a user cannot access a database unless they have been granted the appropriate access privileges by the database owner using GRANT and REVOKE statements.

An AuthID that has been assigned superuser status can change user, group and priority settings that affect all databases on an XDB Server. Initially an AuthID called INSTALL is set as the superuser. If you log on with this AuthID, you can create further superusers as required by clicking Users on the Admin menu and giving each user the appropriate status.

Ordinary users can use the Admin menu only to change their password. Ordinary users who want to change access privileges for specific databases and tables that they own should click New > SQL on the File menu and use the SQL statements GRANT and REVOKE to change access privileges. The AuthID of the creator of a table is deemed to be its owner.

As well as managing system security, a superuser can assign priorities to individual users or groups of users. Priorities control how much processing resource is available to the user or group, depending on criteria set by the superuser.

Note:

When you install SQL Option, the default AuthID is set to TUTORIAL. This AuthID has user privileges and is not authorized to access system tables. This means that, if you switch security on for your personal XDB Server, you cannot use this AuthID to log on to the client utilities.

You should log on using the default superuser AuthID, INSTALL. You can then either set the TUTORIAL AuthID to have superuser status or you can grant it suitable authority on system tables, as appropriate. The INSTALL superuser AuthID has no password assigned initially: you should allocate one to it as soon as possible after switching XDB Server security on.

Parent topic: Security and Authority Overview


System Level Access Control

System level access control refers to that part of the security system that controls the login process, passwords, the assignment of users to groups, and the definition of SecondaryIDs.

Parent topic: Security and Authority Overview


Password Enforcement Level

Before setting up initial passwords for users (or before users change their passwords), the XDB Server Administrator (super user) should select a password enforcement level from the options provided in the Options utility. Use the copy of this utility that resides on the XDB Server machine.

Password level options are:

  • Level 1 - Password must be four or more characters.
  • Level 2 - Password must be six or more characters and include at least one digit (numeric).
  • Level 3 - Password must be six or more characters, include at least one digit (numeric), and must include the two randomly generated characters that appear in the prompt message on the User Control screen.

Users can change their passwords by using the CHANGE PASSWORD command from the ADMIN menu.

Note:

If you are using XDB-Link, your XDB Server AuthID and password are passed to the mainframe as a login UserID and password. To successfully access a DB2 location, your XDB Server AuthID and password must be valid on the mainframe system.

Depending on your security needs, you might wish to establish two AuthID/Password accounts on XDB Server, one for times when you are working only on XDB Server locations and one for times when you plan to access a DB2 location.

If you are using a version 2.40 or 2.41 utility or tool with XDB Server Version 3.x (or higher) and XDB Link, other considerations may apply for DB2 access. See the SQL Option Link User's Guide for more information.

Parent topic: Security and Authority Overview


XDBACF Database

The system location for each XDB Server contains a database called XDBACF (XDB Access Control Facility). This database contains information you enter for each user and group via the Admin menu commands. Information in the XDBACF database applies to all users and all locations on the server.

The XDBACF database contains the following tables and columns. For the specific format of each of these tables, see the topic List Of System Tables.

SYSXDB.SYSACFUSERS Contains a list of all users, including the following information for each user:
  • AuthID
  • SecondaryID
  • Password
  • DateOP (date of password)
  • TimeOP (time of password)
  • AccessAuthority
  • RequirePassword
  • UserType
  • Remarks
Note:

If you are a super user, do not edit or update a user's PASSWORD or TIMEOP information in this table. Use the Admin menu commands instead.

SYSXDB.SYSACFGROUPS Contains a list of all GroupIDs that have been defined. Columns in this table are:
  • GroupAuthID
  • Remarks
SYSXDB.SYSACFMEMBERS Contains a list of AuthIDs and the GroupIDs that each is authorized to use. Each user (Primary AuthID) can have several entries, one entry for each GroupID that the person is authorized to use. Columns in this table are:
  • UserAuthID
  • GroupAuthID
SYSXDB.SYSGOVERNOR Contains information on the type of activities that can be performed by certain users during certain periods. Columns in this table are:
  • EndFreeTime
  • MaxFetches
  • MaxIdleTime
  • MaxNumApiCalls
  • MaxTimeEngine
  • MaxTimePerApi
  • Priority
  • StartFreeTime
SYSXDB.SYSUSERPRIORITY Contains information about priorities that have been assigned to users.
Parent topic: Security and Authority Overview
Related information
System Table Overview


AuthID Types

Primary AuthIDs, GroupIDs, and SecondaryIDs can be used in combination when setting up system security. These IDs are defined as follows:

  • Primary AuthID
  • Group or GroupID
  • SecondaryID (optional)
  • Current SQLID
  • Primary AuthID
  • Group or GroupID
  • SecondaryID (optional)
Parent topic: Security and Authority Overview


Primary AuthID

This is the primary identifier for all users of an XDB Server. A Primary AuthID can be assigned to a process or program that requires access to XDB Server data.

  • Used for logging in to an XDB Server.
  • Appears as an identifier on server screens that are used to monitor activity of users.
  • Used as the default for the AuthID portion of a database object's three-part name when the user creates the object. A different ID will become the default if the SET CURRENT SQLID command is issued or if a SecondaryID is defined.
  • Determines privileges when a user attempts to access a database object. If a different ID is in effect (from issuance of a SET CURRENT SQLID command), that ID's privileges are available also. If the Primary AuthID belongs to a group, the privileges granted to the GroupID also are available to the user of the Primary AuthID. If a SecondaryID is defined, the Primary AuthID's privileges are not valid, but rather the SecondaryID's privileges take effect (along with its groups, if any).
Parent topic: AuthID Types


Group or GroupID

This is a special identifier that can be assigned to one or more Primary AuthIDs. The privileges granted to the GroupID are available to every Primary AuthID to which the GroupID is assigned. In addition, each Primary AuthID can have multiple GroupIDs assigned to it, thus gaining the privileges of all of those groups combined. Other privileges can be granted to the Primary AuthID, providing the user with the assigned group privileges plus the privileges assigned specifically to the Primary AuthID.

Note:

If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.

Parent topic: AuthID Types


SecondaryID (optional)

If defined, this AuthID replaces the Primary AuthID as soon as the user logs in to the XDB Server. The user (or process) is given the privileges that have been granted to the SecondaryID. If the Primary AuthID had privileges granted to it, those privileges would be ignored. When a user with a SecondaryID creates an object, the AuthID portion of the object's name is the SecondaryID. All other users who use the same SecondaryID will have all privileges on that object.

Note:
  • The XDB Server SecondaryID is not the same as the DB2 Secondary Authorization ID. The IBM method of defining multiple Secondary Authorization IDs and assigning them to Primary AuthIDs in RACF (Resource Access Control Facility) is similar to XDB Server's group concept.
  • If you use an object creator's AuthID as a SecondaryID for other users, those other users will all have all privileges on the object. A user with a SecondaryID is seen by the system as being the SecondaryID, and therefore has all privileges on all objects that carry that AuthID as the second part of the object name. Privileges cannot be revoked from the creator of an object, or from a user who's Current SQLID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on the privileges of an object's creator/owner.
Parent topic: AuthID Types


Current SQLID

The Current SQLID is a special register that keeps track of which AuthID is in effect for a given client session. A user with SYSADM or super-user authority can issue the SET CURRENT SQLID command to change the SQLID to any valid AuthID. If a user has a SecondaryID, the Current SQLID changes from the Primary AuthID to the SecondaryID at the start of the client session.

Parent topic: Security and Authority Overview


AuthID Ownership and Usage Rules

When security is on, the Primary AuthID and Password are used when each user (or process) logs in to the XDB Server. The system then checks the SYSXDB.SYSACFUSERS table for the existence of a SecondaryID. If present, the user (or process) assumes the identity of the SecondaryID and is accorded all privileges that have been defined for the SecondaryID. If no SecondaryID exists for the user, then privileges are based on what has been granted for the Primary AuthID and the group(s) to which it belongs.

Multiple users can be assigned the same SecondaryID. In effect, this provides an alternate method for granting a particular set of privileges to a group of users without having to define those privileges for each user individually. The privileges are granted to the SecondaryID (essentially just another AuthID). However, the preferred method for assigning the same privilege set to many users is to use the XDB Server Group, which is similar to the DB2 concept of assigning multiple secondary authorization IDs to a primary authorization in IBM's RACF (Resource Access Control Facility).

Note:

If several users have the same SecondaryID, all the objects they create will be owned by the SecondaryID and not by the individual users. All users having that same SecondaryID will have all privileges on those objects. The GRANT and REVOKE commands have no effect on privileges of an object's creator/owner, which in this case includes all users with the SecondaryID that is also the AuthID portion of the object's name. All of these users are seen by the system as being the owner of the object.

Parent topic: Security and Authority Overview


Effect of AuthIDs on Object Names and Usage

The following table illustrates how various GroupID and SecondaryID assignments can affect the naming of and access to database objects.

Primary AuthID | Secondary ID | Group Name | Creates Table...1 | Owner | Authorized Users
TECHPUBS | -- | -- | Created as a Primary AuthID. Privileges are assigned. Used as a SecondaryID for one or more Primary AuthIDs.
-- | -- | WRITER | Created as a group. Privileges are assigned to the group. GroupIDs are assigned to Primary AuthIDs.
ERIC | -- | -- | ERIC.TABLE1 | ERIC | ERIC
DEBBIE | -- | -- | DEBBIE.TABLE1 | DEBBIE | DEBBIE
DAVID | -- | WRITERS | DAVID.TABLE1 | DAVID | DAVID and, if access is granted to WRITERS, also ARLENE.
ARLENE | -- | WRITERS | ARLENE.TABLE1 | ARLENE | ARLENE and, if access is granted to WRITERS, also DAVID.
ROCHELLE | TECHPUBS | -- | TECHPUBS.TABLE1 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and, if access is granted to WRITERS, also DAVID, ARLENE.
STEVE | TECHPUBS | -- | TECHPUBS.TABLE2 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and, if access is granted to WRITERS, also DAVID, ARLENE.
PABLO | TECHPUBS | WRITERS (ignored)2 | TECHPUBS.TABLE3 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)
BRUCE | TECHPUBS | WRITERS (ignored)2 | TECHPUBS.TABLE4 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)

1All scenarios described here assume that the user does NOT specify an AuthID when creating the object and the user has NOT changed his Current SQLID.

2Pablo and Bruce do NOT have privileges defined for the group WRITERS because as soon as they log in, they both become TECHPUBS, and TECHPUBS is not assigned to the group WRITERS in this example.

As shown in the table above, the AuthID portion of the name assigned to a database object when it is created, and the users who have access to that object depend on how AuthIDs, GroupIDs, and SecondaryIDs are defined. The object naming and usage rules are as follows:

  • If a user belongs to a group and creates an object, the AuthID portion of the object name will be the user's own Current SQLID, and not the GroupID. This allows more than one user to create objects of the same name within the same location. For example:

    If user DAVID (who is in the WRITERS group) creates a table called STAFF in the location called BOOKS, the table's three-part name would be BOOKS.DAVID.STAFF. If user ARLENE (who is also assigned to the WRITERS group) attempts to create a table called STAFF, the table's three-part name would be BOOKS.ARLENE.STAFF. Since the three-part names of the two tables are unique, each user can have a table of the same one-part name within a location.

    Note:
    • If a user has no Secondary ID and has not otherwise changed his Current SQLID, the Current SQLID is the user's Primary AuthID.
    • If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.
  • If a GRANT command gives privileges to a GroupID, all users who are members of that group will have those privileges.
  • If a user belongs to multiple-groups, the user has privileges that have been granted to all the groups.
  • If a user has a SecondaryID and creates an object, the AuthID portion of the object name will be the SecondaryID (assuming that the user has not changed his Current SQLID, which by default takes the value of the SecondaryID). Two users with the same SecondaryID cannot create objects of the same name within a location. For example:

    If user ROCHELLE (who has a SecondaryID of TECHPUBS) creates a table called STAFF in the location called BOOKS, the table's three-part name would be BOOKS.TECHPUBS.STAFF. If user STEVE (who also has TECHPUBS as his SecondaryID) attempts to create a table called STAFF, the table's three-part name would also be BOOKS.TECHPUBS.STAFF. This is not allowed.

  • Any object whose name has a SecondaryID as the AuthID qualifier can be accessed by any user who has that same SecondaryID as his Current SQLID. GRANT and REVOKE commands have no effect on these users' access to the objects because these users are all seen by the system as being the owner of the object. All users who have the SecondaryID that is the owner of the object will have all privileges on the object.

    Users ROCHELLE, STEVE, PABLO, and BRUCE all have all privileges on TECHPUBS.TABLE1, TECHPUBS.TABLE2, TECHPUBS.TABLE3, and TECHPUBS.TABLE4. GRANT and REVOKE commands for these users and tables will have no effect.

    If an object has a different owner, then granting privileges to the SecondaryID will give those privileges to all users who have that SecondaryID as their Current SQLIDs.

  • If a user has a SecondaryID (as his Current SQLID) and belongs to a group and creates an object, the AuthID portion of the object name will be the SecondaryID. Other users in the group do not have access to the object, because privileges on the object have not been granted to the group. The object is owned by the SecondaryID. Only users with the same SecondaryID (as their Current SQLIDs) can access the object. (However, the original user who created the object of this example can access other objects to which the group has been granted privileges.)
Parent topic: Security and Authority Overview


Granted Authorities and Privileges

When security is on, databases and tables are protected from being accessed and manipulated unless the user's Current SQLID is either the owner of the object or has been granted specific privileges in the location where the object resides. Privileges can be granted to a Primary AuthID, a GroupID or a SecondaryID.

An AuthID can also be granted an authority, which is a pre-defined set of privileges. Notice that the Authorities are suggestive of different levels of responsibility. These responsibilities might or might not suit your needs.

Privileges (and authorities) can be granted at the location level (SYSADM or SYSCTRL), database level (DBADM, DBCTRL or DBMAINT), or by table or column within a table. AuthIDs must be granted privileges within each location they are authorized to use. Privileges in one location do not carry over to another location.

Note: If using XDB-Link to access a DB2 location from an XDB Server, you must have appropriate authorities granted on DB2 for the objects you will be using in that mainframe location. Authorities and privileges granted on XDB Server (including INSTALL and SYSADM) are not used by the mainframe system.
Parent topic: Security and Authority Overview


Predefined XDB Server Authorities for GRANT and REVOKE

To assign privileges to a given AuthID in two or more locations, the XDB Server Administrator (super user) can set up groups. Each GroupID is then assigned privileges for one location. The groups that represent the locations for which the user is to be allowed privileges are then assigned to the user's AuthID.

To allow a user to have unlimited privileges throughout the system (all locations), the user's Primary AuthID must be given super-user privileges.

Note:

Only a super user can create locations, drop locations, edit (update) system tables, and assign super-user status to another user. Super-user privileges can be assigned with the ADMIN menu commands, or by editing the USERTYPE column in the user's record in the SYSXDB.SYSACFUSERS table.

Users cannot grant privileges to themselves and cannot revoke privileges from themselves. Likewise, GRANT and REVOKE commands have no effect on users whose AuthIDs (or SecondaryIDs or GroupIDs) are the same as the AuthID portion of an object's name.

Parent topic: Security and Authority Overview


The DSNDB06 Database

The DSNDB06 database, which is a system catalog database provided in each location, contains the specific authorities and privileges that you define for each AuthID, SecondaryID or GroupID with the SQL GRANT and REVOKE commands. This information is stored in the following security-related tables:

  • SYSIBM.SYSDBAUTH (Database Authorization)
  • SYSIBM.SYSUSERAUTH (User Authorization)
  • SYSIBM.SYSTABAUTH (Table Authorization)
  • SYSIBM.SYSCOLAUTH (Column Authorization)
Parent topic: Security and Authority Overview


Granting and Revoking Privileges

After the XDB Server Administrator (super user) has set up the AuthIDs, SecondaryIDs and groups, the privileges and authority for each can be defined. This is accomplished with the SQL GRANT and REVOKE commands. You can set up the granted privileges before or after turning on security. However, any grants you issue when security is off will not take effect until you turn security on.

Note: Be sure you are operating in the location for which you want to define privileges. Each location has its own DSNDB06 database for maintaining authorization information. (To change locations, use the SET LOCATION TO command or change your default location on the Options dialog box.)
Parent topic: Security and Authority Overview


Stored Procedures

A stored procedure is a compiled program that can execute SQL statements. Stored procedures are stored at a local or remote XDB Server. Local XDB Server applications or remote DRDA applications can use the SQL statement CALL to invoke a stored procedure.

Design the application to use stored procedures if the application program operates in a client/server environment, and if either of the following two problems apply:

  • The application accesses host variables for which you want to guarantee security and integrity.
  • The application executes a series of SQL statements, creating many network send and receive operations, which significantly increase CPU and elapsed time costs.

Use of stored procedures removes SQL applications from the workstation, which prevents workstation users from manipulating the contents of sensitive SQL statements and host variables. The use of stored procedures also allows you to combine many of your application's SQL statements into a single message to the DB2 subsystem or XDB Server, reducing network traffic to a single send and receive operation for a series of SQL statements.

Note: If you are running your stored procedure on DB2 MVS, through the XDB Link product, then see your IBM DB2 documentation for other steps necessary to run the stored procedure.

To get a stored procedure up and running:

  1. Code and prepare a stored procedure. See Writing and Preparing Stored Procedures for instructions.
  2. 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.
  3. Define your stored procedure to the XDB Server by issuing a CREATE PROCEDURE command, which will place a row in the appropriate SYSIBM table(s). See Defining Stored Procedures under SQL Option for additional details.
  4. Compile and define a LOADLIB entry for your stored procedure. The LOADLIB entry tells the XDB Server where your stored procedure is. See Compiling Stored Procedures under SQL Option for additional details.
  5. Access mainframe tables using stored procedures under SQL Option. The steps necessary to do this are in Accessing Mainframe Tables With Stored Procedures.
  6. Check the current Limitations with Stored Procedures under SQL Option if you experience problems.
  • How an Application Works With a Stored Procedure
  • What You Can Do in a Stored Procedure
  • Preparing Stored Procedures
  • Executing the SQL Statement CALL
  • Linkage Conventions
  • Using Indicator Variables to Speed Processing
  • Declaring Data Types for Passed Parameters
  • Defining Stored Procedures under SQL Option
  • Compiling Stored Procedures under SQL Option
  • Accessing Mainframe Tables with Stored Procedures under SQL Option
  • Limitations with Stored Procedures under SQL Option
  • Stored Procedure Test Tool
Parent topic: SQL Option User Guide


How an Application Works With a Stored Procedure

A typical stored procedure contains two or more SQL statements, and some manipulative or logical processing that you cannot include in an SQL statement. In this example, your application, CALLSTPR, runs on a workstation client and calls a stored procedure, STPROC1. The following process occurs:

  1. The workstation application establishes a connection to the XDB Server.
  2. The SQL statement CALL tells the XDB Server that the application is going to run the stored procedure, STPROC1. The calling application provides the necessary parameters.
  3. The XDB Server searches the catalog table SYSIBM. SYSROUTINES for rows associated with stored procedure STPROC1.
  4. The XDB 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 XDB Server:
    • Closes all cursors that the stored procedure opened that weren't defined as WITH RETURN. Cursors that were defined as WITH RETURN are closed by the XDB Server when a COMMIT WORK command is issued if the WITH HOLD attribute was not declared on the stored procedure generated cursor.
    • Discards all SQL statements that the stored procedure prepared.
    • Reclaims the working storage that the stored procedure used.

    The application can call more stored procedures or it can execute more SQL statements.

  8. Once control is returned to the program that invoked the stored procedure, the XDB Server will treat all the work generated by the stored procedure (and subsequently by the calling program) as a single transaction.
Parent topic: Stored Procedures


What You Can Do in a Stored Procedure

A stored procedure is similar to any other SQL application.

The following restrictions apply to stored procedures:

  • Both C and COBOL stored procedures must be dynamic link library (DLL) files. See the appropriate language documentation for further information.
  • The XDB Server returns an SQL error code when a location other than the current location is used in an alias or three part name.
  • Do not include these SQL statements in your stored procedure:
    • COMMIT
    • SET CURRENT SQLID

    When these statements are encountered, it places the thread in a must roll back state. When control returns to the calling program, it must do one of the following things:

    • Execute the ROLLBACK statement, so that it is free to execute other SQL statements after rollback is complete.
    • Terminate, causing an automatic rollback of the unit of work.
Parent topic: Stored Procedures


Preparing Stored Procedures

The following are tasks which must be completed before a stored procedure can be run on an XDB Server:

  1. Prepare the application according to your embedded SQL documentation for creating stored procedure DLLs.
  2. Define the stored procedure to the XDB Server. See Defining Stored Procedures under SQL Option.
  3. Place the stored procedure DLL on the XDB Server machine in a location accessible by the XDB Server. The XDB Server uses the appropriate operating system call for loading the stored procedure, and searches the directory cited by the StProcLoadLib entry in the XDB.INI's server section for that stored procedure.
Parent topic: Stored Procedures
Related information
Defining Stored Procedures under SQL Option
Stored Procedures


Executing the SQL Statement CALL

Use the CALL statement to execute each series of SQL statements in your application. For example, to call the stored procedure described in How an Application Works With a Stored Procedure, your application might use this statement:

EXEC SQL
  CALL STPROC1
    (:V1, :V2)
END-EXEC

If you use host variables in the CALL statement, you must declare them before using them.

  • 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 STPROC1 (:V1 :IV1, :V2 :IV2)
END-EXEC

    where :IV1 and :IV2 are indicator variables for the parameters.

  • To pass integer or character string constants or the null value to the stored procedure, code a statement like this:
    EXEC SQL
  CALL STPROC1 (2, NULL)
END-EXEC
  • To use a host variable for the name of the stored procedure, code a statement like this:
    EXEC SQL
  CALL :PROCNAME (:V1, :V2)
END-EXEC

    Assume that the stored procedure name is STPROC1. The host variable PROCNAME is a character variable of length 254 or less that contains the value STPROC1. You should use this technique if you do not know in advance the name of the stored procedure, but you do know the parameter list convention.

  • To pass your parameters in a single structure, rather than as separate host variables, code a statement like this:
    EXEC SQL
  CALL STPROC1 USING DESCRIPTOR :ADDVALS
END-EXEC

    where ADDVALS is the name of an SQLDA.

  • To use a host variable name for the stored procedure with an SQLDA, code a statement like this:
    EXEC SQL
  CALL :PROCNAME USING DESCRIPTOR :ADDVALS
END-EXEC

    This form gives you extra flexibility because you can use the same CALL statement to invoke different stored procedures with different parameter lists.

    Your client program must assign a stored procedure name to the host variable PROCNAME and load the SQLDA ADDVALS with the parameter information before making the SQL CALL statement.

Each of the above CALL statement examples uses an SQLDA. If you do not explicitly provide an SQLDA, the precompiler generates the SQLDA based on the variables in the parameter list.

You can execute the CALL statement only from an application program. You cannot use the CALL statement dynamically.

Parent topic: Stored Procedures


Linkage Conventions

When an application executes the CALL statement, the XDB Server builds a parameter list for the stored procedure, using the parameters and values provided in the statement. The XDB Server obtains information about parameters from the catalog table SYSIBM. SYSPARMS See Defining Stored Procedures under SQL Option for more information. Parameters are defined as one of these types in SYSIBM.ROUTINES:

IN | Input-only parameters, which provide values to the stored procedure
OUT | Output-only parameters, which return values from the stored procedure to the calling program
INOUT | Input/output parameters, which provide values to or return values from the stored procedure

If a stored procedure fails to set one or more of the output-only parameters, the XDB Server does not detect the error in the stored procedure. Instead, the XDB Server returns the output parameters to the calling program, with the values established on entry to the stored procedure.

The XDB Server supports the DB2SQL linkage convention, as cited in detail for the CREATE PROCEDURE command.

Parent topic: Stored Procedures
Related information
Defining Stored Procedures under SQL Option
Stored Procedures


Using Indicator Variables to Speed Processing

If any of your output parameters require a great deal of storage, it is wasteful to pass the entire storage areas to your stored procedure. You can use indicator variables 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. To accomplish this, declare an indicator variable for every large output parameter in your SQL statement CALL.

Note:

If you are using the SIMPLE 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 SIMPLE or SIMPLE WITH NULLS.

For example, suppose that a stored procedure, STPROC2 defined with the SIMPLE 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 COBOL 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    PIC S9(9) COMP
OUTCHAR  PIC X(5000)
IND    PIC S9(4) COMP
.
.
.
MOVE -1 TO IND
EXEC SQL CALL STPROC2(:INNUM, :OUTCHAR :IND);
Parent topic: Stored Procedures


Declaring Data Types for Passed Parameters

A stored procedure must declare each parameter passed to it. In addition, the TYPENAME column of the catalog table SYSIBM.SYSPARMS must contain a compatible SQL data type declaration for each parameter. For TYPENAME string and corresponding language declarations, see the SQL data types table in the appropriate precompiler manual.

Parent topic: Stored Procedures


Defining Stored Procedures under SQL Option

A stored procedure is unusable until it is defined - use the CREATE PROCEDURE command to do this. At the command's conclusion, a record is placed in the SYSIBM.SYSROUTINES This record is used by the XDB Server when the stored procedure is executed.

The following is an example of a CREATE PROCEDURE command:

  create procedure MYAUTHID.STPROC1 (
             in    in1    char(4),
             out  out1  char(4),
             out  out2   smallint
   )
   external name STPROC1
   parameter style general with nulls
   language cobol
   collid  MYCOLLID
   result sets 1
   commit on return no
   ;

The create procedure statement must uniquely identify a stored procedure. You cannot have more than one row in SYSIBM.SYSROUTINES with the same values for the PROCEDURE, AUTHID, and LUNAME columns because the combination of PROCEDURE, AUTHID, and LUNAME uniquely identifies a stored procedure. You also will provide specific application information, such as what language the stored procedure is written in, whether you are using result-sets, what parameters are passed, and how they are passed.

Parent topic: Stored Procedures
Related reference
CREATE PROCEDURE
Related information
SYSIBM.SYSROUTINES


Compiling Stored Procedures under SQL Option

To compile a stored procedure under SQL Option, carry out the following steps:

  1. The project used for stored procedure development should always be declared as "Uses SQL". To indicate that an existing project uses SQL, click Project Settings on the Project menu, then select Project uses SQL on the SQL tab.
  2. To use the ECM SQL preprocessor, check the Preproc tab of the Build Settings dialog box and ensure that EXEC SQL is checked. If additional directives are needed, for instance the PKGSET directive to emulate SET CURRENT PACKAGESET functionality, click the More button next to the EXEC SQL checkbox and specify the directives there.
  3. SQL Option requires a LOADLIB directory to be able to find .dll files that execute as stored procedures. When Enterprise Developer compiles programs, it typically places the .dll files in a LOADLIB directory under the project directory.
Parent topic: Stored Procedures


Accessing Mainframe Tables with Stored Procedures under SQL Option

You can set up a special location to access mainframe tables from a stored procedure. Since the stored procedure must run under the XDB engine, the current location must be an SQL Option location. Access to DB2 tables and views is provided by using aliases.

To activate this functionality, the STProcRemoteAccess variable must be set to one in the server section of the xdb.ini file in the %ProgramData%\Micro Focus\Enterprise Developer\mfsql\cfg directory. The following is an example of setting the STProcRemoteAccess variable:

[CLIENT]
XDBCFG=c:\mfuser\config\
[SERVER]
XDBSERVE=myserver
XSRVCFG=c:\mfuser\config
StProcLoadLib=c:\mfuser\projects\MyProject\LOADLIB;c:\mfuser\projects\MyProject2\LOADLIB
StProcAnimate=yes
STProcRemoteAccess=1
.
.
.

You can easily create aliases for mainframe tables using the CREATE ALIAS SQL command. If you can use a three-part name to select from a table on the mainframe, the CREATE ALIAS command can be used to alias that table.

For instance, if the following command returns rows:

select * from MFLOCATION.MYAUTHID.MYTABLE;

an alias can be created in the MYLOCAL location using the following command:

create alias MYAUTHID.MYTABLE for MFLOCATION.MYAUTHID.MYTABLE;

CREATE ALIAS statements can be generated using SQL SELECT statements and the remote locations metadata. For instance, the following query will generate CREATE ALIAS syntax for all tables in a DB2 location that don't have a creator of SYSIBM:

SELECT 'CREATE ALIAS '
                  CONCAT
                  STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
                  CONCAT
                  ' FOR '
                  CONCAT
                  STRIP(CURRENT SERVER, TRAILING, ' ') CONCAT '.' CONCAT
                  STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
                  CONCAT
                  ';'
FROM SYSIBM.SYSTABLES
WHERE CREATOR NOT IN ('SYSIBM')
ORDER BY 1
FOR FETCH ONLY;

If the above query is run under SPUFI, you must take care to set up the SPUFI defaults appropriately - you need to ensure that settings such as MAX SELECT LINES in SPUFI are set to enable all the rows to be returned. Using SPUFI, the output data set will have output that looks as follows:

---------+---------+---------+---------+---------+---------+---------+---------
CREATE ALIAS MYAUTHID.PROC_TEST_TAB_1 FOR CSIMVSDB2.MYAUTHID.PROC_TEST_TAB_1;
CREATE ALIAS MYAUTHID.PROC_TEST_TAB_2 FOR CSIMVSDB2.MYAUTHID.PROC_TEST_TAB_2;
CREATE ALIAS MYAUTHID.PROC_TEST_TAB_3 FOR CSIMVSDB2.MYAUTHID.PROC_TEST_TAB_3;

The query can be adjusted to retrieve the tables necessary by using sub-queries or joins to limit the data retrieved. The following is an example of generating CREATE ALIAS commands for all tables and views within a particular DB2 database. Note that this query will not retrieve tables in other databases that are referenced by the views.

SELECT 'CREATE ALIAS '
       CONCAT
       STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
       CONCAT
       ' FOR '
       CONCAT
       STRIP(CURRENT SERVER, TRAILING, ' ') CONCAT '.' CONCAT
       STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
       CONCAT
       '; -- ALIAS OF TABLE'
  FROM SYSIBM.SYSTABLES
 WHERE DBNAME = 'MYDB2DB'
   AND TYPE = 'T'
 UNION
SELECT 'CREATE ALIAS '
       CONCAT
       STRIP(SVDP.DCREATOR, TRAILING, ' ') CONCAT '.' CONCAT SVDP.DNAME
       CONCAT
       ' FOR '
       CONCAT
       STRIP(CURRENT SERVER, TRAILING, ' ') CONCAT '.' CONCAT
       STRIP(SVDP.DCREATOR, TRAILING, ' ') CONCAT '.' CONCAT SVDP.DNAME
       CONCAT
       '; -- ALIAS OF VIEW'
  FROM SYSIBM.SYSTABLES  STBL,
       SYSIBM.SYSVIEWDEP SVDP
 WHERE STBL.DBNAME = 'MYDB2DB'
   AND STBL.TYPE = 'T'
   AND STBL.CREATOR = SVDP.BCREATOR
   AND STBL.NAME  = SVDP.BNAME
 ORDER BY 1
   FOR FETCH ONLY
;

Because the stored procedure is running under the SQL Option engine and DB2 is being used only for the retrieval of data, certain operations must still be set up under the SQL Option engine. In particular, SET CURRENT PACKAGE SET commands must be set up under SQL Option. SET CURRENT PACKAGE SET commands will not be passed to the mainframe DB2 region since the identification of data entities must take place under the SQL Option engine. Additionally, SYNONYMS must be created on the SQL Option location if your DB2 processing uses SYNONYMS.

Parent topic: Stored Procedures


Limitations with Stored Procedures under SQL Option

You should be aware of the following limitations when working with stored procedures under SQL Option:

  • Stored procedures cannot be debugged when the XDB server is running as a service.
  • We recommend you do not use STOP RUN statements within a stored procedure. If you use STOP RUN instead of GOBACK you will receive a -471 sqlcode on the EXEC SQL CALL STATEMENT.

    Note that IBM also recommends against the use of STOP RUN statements in stored procedures. This is because in the DB2 subsystem, a STOP RUN terminates the Language Environment enclave, so the next time a DB2 stored procedure is called, the Language Environment enclave has to be rebuilt. This extra work being done by the DB2 region severely impacts the benefits of running the stored procedure as a DB2 subprogram.

  • Currently, the VALIDATE preprocessor directive will provide minimal assistance with stored procedure SQL statements (CALL, ASSOCIATE, ALLOCATE).
  • No support is provided for performing a PREPARE statement using ALLOCATE CURSOR or ASSOCIATE LOCATORS syntax. ALLOCATE CURSOR and ASSOCIATE LOCATORS statements must be embedded within the SQL language EXEC SQL ... END-EXEC delimiters. ALLOCATE CURSOR and ASSOCIATE LOCATORS statements cannot be dynamically prepared.
Parent topic: Stored Procedures


Stored Procedure Test Tool

The Stored Procedure Test tool (SP Test tool) makes the testing of stored procedures easier. It enables you to test various input values for a stored procedure, see the results, and optionally create test scripts without having to write COBOL code to invoke the stored procedure. However, if you want to invoke the stored procedure from a COBOL program, the tool also provides an option that enables you to generate such a program containing all of the required COBOL host variables.

The Stored Procedure Test tool also provides three wizards that enable you to generate both the SQL and the COBOL code for stored procedures, external table functions, and external scalar functions:

The SP Test tool accesses your stored procedures by connecting to the XDB server you specify, building a list of stored procedures and functions defined for that server.

  • Options
  • Testing a Stored Procedure
  • Test Scripts
  • Generating a COBOL Program
  • Command Line Interface
  • How to...
Parent topic: Stored Procedures
Related tasks
To start the Stored Procedure Test tool


Options

The SP tool comes configured to test your stored procedures using a set of default options. You can change the default options to customize the behavior of the SP Test tool. For example, you can set startup, execution and testing options, control the generation of COBOL code and certain files, specify a particular editor, specify directories, and set Wizard options.

You can set the following options to control the behavior of the SP Test tool. Default settings appear in a regular typeface. Non-default settings, directories and filenames appear bold. Read-only options are grayed-out.
Generate COBOL Code Generates a COBOL program that invokes:
  • The stored procedure
  • Result sets generated by the stored procedure
  • Host variables required to invoke the appropriate functions

Default: True

COBOL Specifies the directory where the SP Test tool stores the COBOL it generates, if any.

Default: %LOCALAPPDATA%

Input Saved Parameters Specifies the directory where the SP Test tool retrieves the XML file containing input parameters.

Default: %LOCALAPPDATA%

Output Saved Parameters Specifies the directory where the SP Test tool stores the XML file it generates containing output parameters.

Default: %LOCALAPPDATA%

Stored Procedures Specifies the debug directory for stored procedures. You must set this option before attempting to debug a stored procedure to prevent it from hanging during execution.

Default: %LOCALAPPDATA%.

Use Project Settings Specifies whether or not to apply the settings defined for the current project to the SP Test tool as well.

Default: False

Editor for Side Files Optionally provide the full path and executable filename of a non-Micro Focus editor you want to use to edit side files.

Default: Blank

Allow Output Side Files Enable the SP Test tool to save output results in a side file rather than viewing them on-screen. This is useful when large amounts of data are returned for a parameter.

Default: False

Alternate Entry Map Name Optionally specify the path to a directory that contains entry point map files.

Default: Blank

Timeout

The amount of time in milliseconds to process requests, such as REFRESH, before being prompted to continue waiting. To turn this option off, set the value to 0.

Default: 5000 (equivalent to 5 seconds)

Automatically Save Input File Save input files in XML format, automatically generating input filenames based on the value of the Format Input Filename field. This option is automatically set to False if you have set the Format Input Filename to No Default Format, and is automatically set to True when Format Input Filename is set to either Stored Procedure name + “_IN_” + current date or Stored Procedure name + “_IN_” + number.

Default: True

Encoding of Side Files Specify the type of encoding to use for side files. Available types are:
  • ASCII
  • EBCDIC
  • UNICODE
Note:

If you specify EBCDIC, the tool translates the value to ASCII using the Micro Focus codeset defined for your machine.

Default: ASCII

Format Input File Name Set a default filename format for generated XML input files, or specify no default filename format. The XDB Stored Procedure Test tool uses the specified format for input files when Automatically Save Input File is set to True. The options are:
  • Stored procedure name + “_IN_” + number
  • Stored procedure name + “_IN_” + current date
  • No default format

Default: Stored procedure name + “ _IN_” + number

Format Output File Name Set a default filename format for generated XML output files, or specify no default filename format. The options are:
  • Stored procedure name + number
  • Stored procedure name + current date
  • No default format

Default: Stored procedure name + number

Generate Output File Name Save output files in XML format, automatically generating ouput filenames based on the value of the Format Output Filename field. This option is automatically set to False if you have set the Format Output Filename to No Default Format, and is automatically set to True when Format Output Filename is set to either Stored Procedure name + current date or Stored Procedure name + number.

Default: True

Refresh List on Startup Build a new list of stored procedures and functions each time you invoke the XDB Stored Procedures Test tool, saved to a local XML file. For this option to work properly, you must have the XDB Server started before you invoke the tool.
Note: We recommend disabling this option in cases where the time required to rebuild the list is prohibitive, for example, when connecting to a mainframe DB2 server using XDB LINK. When disabled, the tool presents the list from your previous session. You can then refresh the list manually by clicking Refresh list of stored procedures.

Default: True

Test Coverage Config File Specify the configuration file to use when executing the stored procedure in test coverage mode. This is only applicable if you have set the Use Test Coverage option to True.

Default: Blank

Use Test Coverage Specify whether or not the tool executes stored procedures in test coverage mode.

Default: False

Test Script Generation Set the tool either to write the commands used to test a stored procedure to an ASCII command file, or to not save the commands. The options are:
  • Automatically save commands
  • Prompt before saving
  • Don't save commands

See the section Test Scripts for more information.

Default: Automatically save commands

Abend Options Specifies the behavior of the routine when it encounters a failure. The options are as follows:
  • Use Default Setting
  • STOP AFTER SYSTEM DEFAULT FAILURES
  • STOP AFTER nn FAILURES
  • CONTINUE AFTER FAILURE
Note: If you select STOP AFTER nn FAILURES, you must specify the number of failures (represnted by "nn") in the Abend field on the Wizard's Specify Options page.

Default: Use Default Setting1

ASU Time | Specifies the total amount of processor time, in CPU service units, that a single invocation of the routine can run. Default: 0
Commit on Return Specifies whether or not DB2 commits the transaction immediately upon return from the routine. The options are:
  • Use Default Setting
  • YES
  • NO

Default: Use Default Setting1

DBINFO Parameter Specifies whether or not additional status information is passed when the routine is invoked.
Note:

This parameter is used only when the Parameter Style option is set to SQL.

Default: False

DETERMINISTIC | Specifies whether or not the routine returns the same results each time it is called with the same IN and INOUT arguments. Default: False
Dynamic Result Sets | Specifies the maximum number of result sets that the routine can return. Default: 0
Execute on FINISH | Specifies whether or not the Wizard executes the generated routine when you click Finish. Default: False
Fenced | Specifies whether or not the routine runs in an external address space to prevent user programs from corrupting DB2 storage. Default: False
Parameter CCSID Specifies the encoding scheme for string parameters. The options are:
  • ASCII
  • EBCDIC
  • UNICODE

Default: EBCDIC

Parameter Style Specifies the linkage convention used to pass parameters to and return values from the routine. The options are:
  • GENERAL
  • GENERAL WITH NULLS
  • SQL

Default: GENERAL

Language Specifies the language used to interface with the routine. The options are:
  • COBOL
  • C
  • PLI
  • ASSEMBLER
  • REXX

Default: COBOL

Run-time options | Specifies the Language Environment run-time options for the routine. Default: none (blank)
Security Specifies how the routine interacts with an external security product to control access to non-SQL resources. The options are:
  • Use Default Setting
  • DB2
  • USER
  • DEFINER

Default: Use Default Setting1

SQL Statement Defaults Specifies which SQL statements, if any, can be executed in this routine or any routine that is called from this routine. The options are:
  • Modifies SQL Data
  • Reads SQL Data
  • Contains SQL
  • No SQL

Default: Modifies SQL Data

Stay Resident Specifies whether or not the routine's load module remains resident in memory when the routine ends.

Default: False

Use Default Special Register Specifies whether or not special registers are initialized to the default values.

Default: False

WLM Environment Specifies the name of the WLM (workload manager) environment in which the routine is to run when the DB2 stored procedure address space is WLM-established.

Default: Blank

1The default setting for this option depends on the type of code the Wizard is generating - stored procedure, external table function, or external scalar function. The default setting for each type of code is that which appears in the field corresponding to this option when you first invoke the Wizard's Specify Options page.

Note: You can override Wizard options on the Specify Options page of each wizard.
Parent topic: Stored Procedure Test Tool
Related concepts
Test Scripts
Related tasks
To set Stored Procedure Test tool options
To generate a stored procedure
To generate an external table function
To generate an external scalar function


Testing a Stored Procedure

Once you have started and configured the SP Test tool, you are ready to test your stored procedures. These are listed on the IDE by schema name in the tree view on the left under Stored Procedures. The procedure to test a stored procedure is as follows:

  1. Set input and output parameters
  2. Specify filenames for generated files
  3. Execute the stored procedure
  4. Read the results
  • Setting Input and Output Parameters
  • Specifying Filenames for Generated Files
  • Executing a Stored Procedure
  • Testing with Third-party Software
  • Reading Test Results
  • Displaying Saved Results
Parent topic: Stored Procedure Test Tool


Setting Input and Output Parameters

You can optionally provide a value for each input and/or output parameter associated with the stored procedure. All parameters defined in a stored procedure selected in the tree view appear on the Parms tab. Input parameters are identified by either a P (for input) or a B (for input/output) in the I/O column. Output parameters are identified by an O in the I/O column.

You assign a value to an input parameter using one of the following methods:

  • Type the value directly into the Value field
  • Type the value into the Edit Entry Value editor
  • Specify a side file (.dat file) to contain the value
  • Specify a special register that defines the value

If you want to store the value of an output parameter as the stored procedure executes, set the Allow Output Side Files option to True. This enables you to specify a side file or a special register to hold the value.

Note: If you want to specify an EBCDIC side file to contain the value but do not already have one available, you can create one.
Parent topic: Testing a Stored Procedure
Related tasks
To specify an input parameter value for a stored procedure
To edit an input parameter value for a stored procedure
To specify a side file for a parameter value
To specify a special register for a parameter value


Specifying Filenames for Generated Files

You can set your options to automatically generate filenames for XML input and output files, and to also automatically generate a filename for generated COBOL code using default file naming conventions. However, you can also specify your own filenames for these files from the Files tab.

Parent topic: Testing a Stored Procedure
Related tasks
To set Stored Procedure Test tool options
To specify input, output, and generated COBOL filenames


Executing a Stored Procedure

You must have specified a default filenaming convention for input and output files via the Options dialog box or have specified input and output filenames via the Files tab before your stored procedure will execute. If no filename or filenaming convention is specified, the SP Test tool calls the Files tab before executing the stored procedure, requiring you to specify the appropriate filenames at that time.

The results of the stored procedure execution are automatically displayed on the Results tab following execution.

Parent topic: Testing a Stored Procedure
Related concepts
Reading Test Results
Related tasks
To execute a stored procedure
To set Stored Procedure Test tool options


Testing with Third-party Software

You can use the SP Test tool to generate an ASCII or a hexadecimal text string command that can run your stored procedure in a third-party test tool. Before generating the command, be sure you have specified all of the appropriate input parameters.

Parent topic: Testing a Stored Procedure
Related tasks
To generate a test command


Reading Test Results

The Results tab shows you the following information:

Type or RS Name

Shows whether this is a parameter or a result set. Result set names correspond to the cursor name defined in the DECLARE CURSOR statement.

Data Name

The parameter name or the column name of the data in the result set.

Row Number

Parameters display a row number of 0; result sets display the row number fetched from the result set that corresponds to the cursor name defined in the DECLARE CURSOR statement.

Value

  • Input - the value of the input parameter
  • Output - the value of the output parameter
  • Input only side file - the value that was found in the side file
  • Input/Output or Output side file - the side file name
  • Special register - the name of the special register (not the value of the special register)
Note:

Reporting the name of the special register rather than its value makes it somewhat easier to do regression testing in that you get consistent results when using special registers such as CURRENT DATE.

Parent topic: Testing a Stored Procedure
Related concepts
Displaying Saved Results


Displaying Saved Results

In addition to viewing the results each time you test a stored procedure, you can also view the results of any previously run stored procedure using the Display Saved Results command. This command enables you to choose any saved XML output file for viewing on the Results tab or on one or more customized tabs. Each customized tab displays one result set, and the name of the tab is the same as the SQL cursor name used to produce the result set. All information on customized tabs is displayed in a familiar tabular format with column names in the data grid taken from the columns names used in the query that selected the data.

Parent topic: Testing a Stored Procedure
Related concepts
Reading Test Results
Related tasks
To display saved results from output XML


Test Scripts

You can save the commands that the SP Test tool uses to test a stored procedure as a script that you can execute without having to reset options, input and output parameters, or filenames. This enables you to easily retest your stored procedures.

Test scripts are saved as ASCII command files in the following format:

TEST_storedprocedurename.cmd

Test script files are stored in the same directory as is specified for the COBOL option on the Options dialog box.

Each script includes the input and output file names used when the stored procedure is executed. The following is an example test script named TEST_GETEMPD.cmd:

MFXDBRUNSP IN=G:\temp\xml\GETEMPD_IN_0001.xml; OT=G:\temp\xml\GETEMPD_OUT_0001.xml;
MFXDBRUNSP IN=G:\temp\xml\GETEMPD_IN_0002.xml; OT=G:\temp\xml\GETEMPD_OUT_0002.xml;

This script runs two commands, one using XML input file GETEMPD_IN_0001.xml and another using XML input file GETEMPD_IN_0002.xml. The “OT” token specifies an output XML file.

The SP Test tool automatically creates a script file for each stored procedure you execute if you set the Test Script Generation option to Automatically save commands or Prompt before saving.

You can edit a generated test script in any text editor. You can also write your own test scripts by creating a command file that invokes individual stored procedure test scripts. See the topic Command Line Interface for additional commands you can specify in a test script.

Parent topic: Stored Procedure Test Tool
Related concepts
Options
Command Line Interface
Related tasks
To set Stored Procedure Test tool options


Generating a COBOL Program

When you set the Generate COBOL Code option to True, the SP Test tool automatically generates a COBOL program that calls the stored procedure. This COBOL program reflects the extent to which code was executed when you ran the stored procedure. If an error occurs within the stored procedure, the generated program is incomplete.

You can view the generated program on the Code tab after the stored procedure executes. Parameter values are generated as host variable names unless you specified a special register. In that case the special register name is generated as part of the EXEC SQL CALL statement. For example:
EXEC SQL
  CALL GETEMPD2 (CURRENT TIMESTAMP - 255 DAYS, :GETEMPD2-RSLT)
END EXEC
Parent topic: Stored Procedure Test Tool
Related tasks
To set Stored Procedure Test tool options
To specify input, output, and generated COBOL filenames


Command Line Interface

You can run stored procedures generated by the SP Test tool from the command line using the following syntax:
inputfilename; OT=<outputfilename; CD=<COBOLfilename
Where inputfilename is the full path to and filename of the XML input file, outputfilename is the full path to and filename of the XML output file, and COBOLfilename is the name of the generated COBOL program file. To execute multiple commands separate each command with a semi-colon (;).
Parent topic: Stored Procedure Test Tool
Related concepts
Test Scripts
Related tasks
To display saved results from output XML
To specify input, output, and generated COBOL filenames


How to...

  • To start the Stored Procedure Test tool
  • To set Stored Procedure Test tool options
  • To edit the list of stored procedures displayed
  • To specify an input parameter value for a stored procedure
  • To edit an input parameter value for a stored procedure
  • To specify a side file for a parameter value
  • To specify a special register for a parameter value
  • To specify input, output, and generated COBOL filenames
  • To execute a stored procedure
  • To generate a stored procedure
  • To display saved results from output XML
  • To generate a test command
  • To generate an external table function
  • To generate an external scalar function
Parent topic: Stored Procedure Test Tool


To start the Stored Procedure Test tool

In standalone mode
Windows 10 and Later
  • From your Windows desktop, click Start > Enterprise Test Server > Data Tools > SQL Option for DB2 > Client > Stored Procedure Test tool.
Parent topic: How to...
Related concepts
Stored Procedure Test Tool


To set Stored Procedure Test tool options

  1. From the SP Test tool toolbar, click Options Options.
  2. Scroll to the option you want to set and click its corresponding field in the right-hand column.
  3. Change the value in this field using one of the following mechanisms, depending on which is available:
    • Type a value directly into the field
    • Browse to a path and/or filename by clicking Browse Browse
    • Select a value from the drop-down menu
Note: Default settings appear in a regular typeface. Non-default settings, directories and filenames appear bold. Read-only options are grayed-out.
Parent topic: How to...
Related concepts
Options
Test Scripts
Specifying Filenames for Generated Files
Executing a Stored Procedure
Reading Test Results
Generating a COBOL Program


To edit the list of stored procedures displayed

  1. From the SP Test tool, right-click anywhere on the tree view; then click Edit List of Stored Procedures Displayed.
  2. If you have checked Also remove from database, the SP Test tool invokes the File Name to Save Drop Commands dialog box. Here, you specifiy the name of a command file that the SP Test tool generates to drop the checked stored procedures from their XDB location(s). The SP Test tool executes this command file when you click Save.
  3. Check the box to the right of each stored procedure you want to remove from the list.
  4. If you want to remove the checked stored procedures from the repository as well as the displayed list, check Also remove from database (optional).
  5. Click Remove to remove the checked stored procedures.
Note: If you leave Also remove from database unchecked, stored procedures you have removed from the list reappear when you start the Stored Procedure Test tool again, or when you click Refresh list of stored procedures Refresh list of stored procedures.
Parent topic: How to...


To specify an input parameter value for a stored procedure

  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, click the Value column corresponding to the parameter whose value you want to specify.
  3. Type the value of the parameter.
  4. Tab to another column to ensure that the value is saved properly.
Note:
  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • You can also specify a value using the Edit Entry Value editor or by specifying a side file or special register.
  • Values typed directly into the Value field or into the Edit Entry Value editor are limited to the length of the parameter.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To edit an input parameter value for a stored procedure
To specify a side file for a parameter value
To specify a special register for a parameter value


To edit an input parameter value for a stored procedure

  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, right-click the Value column corresponding to the parameter whose value you want to edit, then click Edit value.
  3. In the Edit Entry Values editor, type the value of the parameter.
  4. Click OK.
  5. Tab to another column to ensure that the value is saved properly.
Note:
  • To view or enter the value in hexadecimal, check Display value in hexadecimal.
  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • You can also specify a value by entering it directly into the Value column or by specifying a side file or special register.
  • Values typed directly into the Value field or into the Edit Entry Value editor are limited to the length of the parameter.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To specify an input parameter value for a stored procedure
To specify a side file for a parameter value
To specify a special register for a parameter value


To specify a side file for a parameter value

  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, right-click the Value column corresponding to the parameter whose value you want to edit, then click Insert side file.
  3. Navigate to the side file (.dat file) you want to use, or type the full path and filename of the side file into the File name field, then click Open.
  4. On the SP Test tool IDE, tab to another column to ensure that the value is saved properly.
Note:
  • The side file specification appears in the Value column in the following format:

    <SF=path/filename>

    If you have set the Encoding of Side Files option to EBCDIC, <ENC=E> is appended to the end.

  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • For input parameters, you can also specify a value by entering it directly into the Value column, using the Edit Entry Values editor, or by specifying a special register.
  • You cannot specify a side file to store an output parameter value unless you have set the Allow Output Side Files option to True.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To specify an input parameter value for a stored procedure
To edit an input parameter value for a stored procedure
To specify a special register for a parameter value


To specify a special register for a parameter value

  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, right-click the Value column corresponding to the parameter whose value you want to edit, then click Insert special register.
  3. From the drop-down menu that appears, click the special register you want to use to store the parameter value.
  4. Click Insert special register again to paste the reference into the Value column.
Note:
  • The special register specification appears in the Value column in the following format:

    <SR=specialregistername>

    Do not manually modify the SR= portion of this specification. Doing so can cause the stored procedure to execute improperly.

    However, you can modify the specialregistername portion of the specification by typing over it. For example, if you selected the CURRENT DATE special register, you could modify it to be CURRENT DATE - 100 DAYS which is then used instead of CURRENT DATE. Be advised that modified special registers cannot be validated.

  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • For input parameters, you can also specify a value by entering it directly into the Value column, using the Edit Entry Values editor, or by specifying a side file.
  • You cannot specify a special register to store an output parameter value unless you have set the Allow Output Side Files option to True.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To specify an input parameter value for a stored procedure
To edit an input parameter value for a stored procedure
To specify a side file for a parameter value


To specify input, output, and generated COBOL filenames

  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Files tab in the appropriate field, type the full path to and filename of the file you want to specify, or click the field's corresponding Browse Browse button to navigate to and select an appropriate file.
Note:
  • The Files tab automatically appears when you run a stored procedure for which no input or output filenames have been specified either directly or by selecting filenaming conventions via the Options dialog box, enabling you to specify these filenames at that time.
  • If you have set your Options to automatically generate COBOL code but have not specified a filename on the Files tab, the Files tab appears automatically when you run the stored procedure, enabling you to specify the filename at that time.
Parent topic: How to...
Related concepts
Specifying Filenames for Generated Files
Generating a COBOL Program
Command Line Interface


To execute a stored procedure

  • From the SP Test tool, click a stored procedure on the tree view, then click Run Run.
Note:
  • The Files tab automatically appears when you run a stored procedure for which no input or output filenames have been specified either directly or by selecting filenaming conventions via the Options dialog box, enabling you to specify these filenames at that time.
  • If you have set your Options to automatically generate COBOL code but have not specified a filename on the Files tab, the Files tab appears automatically when you run the stored procedure, enabling you to specify the filename at that time.
  • If you have set the Prompt Save Script option to True, you are prompted after the stored procedure executes to save or not save the command in the test script. If the stored procedure encounters errors while executing you do not receive this prompt.
Parent topic: How to...
Related concepts
Executing a Stored Procedure
Reading Test Results


To generate a stored procedure

  1. Start the Stored Procedure Test tool.
  2. Click Create a new Stored Procedure Create new stored procedure.
  3. Complete each page of the Wizard. For help on a specific page and help on a specific field or control on a page, click Help.
Note: The Wizard writes one COBOL and one SQL file containing the generated code. The location of these files is specified in your SP Test tool Options, and the filenames are as follows:
  • SQL file - procedurename.sql
  • COBOL file - procedurename.cbl
Parent topic: How to...
Related concepts
Options
Related tasks
To generate an external table function
To generate an external scalar function


To display saved results from output XML

  1. From the SP Test tool tree view, right-click the Stored Procedure for which you want to display saved results; then click Display Saved Results.
  2. From the Select Results to be Displayed dialog box, click the XML output file that contains the results you want to display; then click Open.
  3. Click the customized tab for the result set you want to view.
  4. Use Next and Previous to browse through the results sets.
Parent topic: How to...
Related concepts
Displaying Saved Results
Command Line Interface


To generate a test command

  1. From the SP Test tool tree view, right-click the Stored Procedure for which you want to generate a test command; then click Generate Test Command.
  2. From the Generate Stored Procedure Test Command dialog box, highlight the generated command.
  3. Right-click the highlighted command and click copy or cut from the menu.
    Note: If you want a hexadecimal equivalent for the command, check Display value in hexadecimal before copying or cutting the command.
  4. Click OK to close the Generate Stored Procedure Test Command dialog box.
  5. To run the command, paste it into an appropriate place in the third-party test tool of your choice and run it according to the instructions for that test tool.
Parent topic: How to...
Related concepts
Testing with Third-party Software


To generate an external table function

  1. Start the Stored Procedure Test tool.
  2. Click Create a new (external) Table Function Create new table function.
  3. Complete each page of the Wizard. For help on a specific page and help on a specific field or control on a page, click Help.
Note: The Wizard writes one COBOL and one SQL file containing the generated code. The location of these files is specified in your SP Test tool Options, and the filenames are as follows:
  • SQL file - functionname.sql
  • COBOL file - functionname.cbl
Parent topic: How to...
Related concepts
Options
Related tasks
To generate a stored procedure
To generate an external scalar function


To generate an external scalar function

  1. Start the Stored Procedure Test tool.
  2. Click Create a new (external) Scalar Function Create new scalar function.
  3. Complete each page of the Wizard. For help on a specific page and help on a specific field or control on a page, click Help.
Note: The Wizard writes one COBOL and one SQL file containing the generated code. The location of these files is specified in your SP Test tool Options, and the filenames are as follows:
  • SQL file - functionname.sql
  • COBOL file - functionname.cbl
Parent topic: How to...
Related concepts
Options
Related tasks
To generate a stored procedure
To generate an external table function


SQL Option Server Administration Guide

The XDB Server, utilizing a high performance SQL engine, supports multiple locations and multiple databases within a location. The XDB Server, when combined with accompanying client software, provides a full-featured, client-server based database management system. The XDB Server and client software are available for a variety of operating platforms. In all cases, responsible parties need to understand the storage architecture and the various system and user configuration parameters.Note:If you want to access mainframe DB2 data directly, your system administrator must first install and configure a number of SQL connectivity components. Once this is done, your system administrator can advise you how to connect to mainframe data.

  • Client-Server Architecture
  • Advantages of Using SQL Option Server
  • Storage Architecture
  • Basic Tasks
  • Server Configuration Utility
  • Monitor Utility
  • Security and Authority
  • Server-to-server Connectivity
  • Multiserver Security
  • Backup and Recovery
  • Storage Requirements
  • Performance Tuning
  • Location Management
  • Environment Variables
  • Server Files
  • Troubleshooting
Parent topic: SQL Option for DB2


Client-Server Architecture

The XDB Server makes use of a client-server architecture, which allows an application to be split into front-end (client) and back-end (server) components. The front-end components correspond to the end user's view of the application. The back-end is the XDB Server, which performs the actual database processing functions.

The front-end and back-end can reside on the same machine or they can be installed on a back-end server machine, with front-end client sessions initiated from separate workstations.

Parent topic: SQL Option Server Administration Guide


Advantages of Using SQL Option Server

There are many advantages to using the XDB Server. A server allows people throughout the organization to share data and resources. With the database server located on a separate machine, more memory is available on client machines for other applications. The XDB Server also allows the transparent integration of clients and servers running different operating systems. The server's security system allows for a separation of responsibilities and access privileges, if desired.

Distributed processing and server-to-server connectivity are supported. This allows the user of a single-workstation XDB Server, for example, to access data from other XDB Servers.

Parent topic: SQL Option Server Administration Guide


Storage Architecture

The XDB Server uses a logical storage architecture modeled after the architecture used by IBM's DB2. This architecture allows you to use the same three-part naming conventions (location-name.authid.object-name) typically used on the mainframe.Because much of the physical storage architecture employed on the mainframe has no equivalent in PC environments, the physical storage between the environments differs significantly. However, the physical implementation of the XDB Server generally makes these differences transparent to the user.The XDB Server allows you to explicitly define where data is to be stored or to use the system-generated defaults. With either method, data is accessed by using the logical names of objects, not by referencing the physical storage locations. The XDB Server performs the mapping between physical and logical layers automatically.

  • Locations
  • Storage Groups (Stogroups)
  • Databases
  • Table Spaces, Tables, and Indexes
  • Summary and Example
Parent topic: SQL Option Server Administration Guide


Locations

At the highest level of the logical storage hierarchy is the location. You can have multiple locations defined and available under one copy of the XDB Server software. This differs slightly from the IBM DB2 concept of locations, but the naming convention of location-name.authid.object-name is the same on both platforms.

Note: Do not copy, alter, or move the files in locations. Doing so can corrupt the system location and jeopardize all the data managed by the XDB Server.
  • Mainframe DB2 Location (Subsystem) Structure. On a mainframe, each copy of DB2 software (subsystem) is assigned its own location name. There may be one or more databases (each containing multiple tables) within a location. Each database can have one or more table spaces and tables, with associated index spaces, indexes, views, and synonyms.

    A system catalog (a set of catalog tables) maintains information about each table and database and its components, including which tables belong to which databases and where objects are located on disk. There is one system catalog per copy of DB2 software (one catalog per location or subsystem).

  • XDB Location Structure. One XDB Server can manage one or more locations. A system location is provided by default. The "super" user (usually the database or system administrator) can create other locations.

    Like the mainframe, there may be one or more databases within a location. Each database can have one or more table spaces and tables, with associated indexes, views, and synonyms.

A system catalog database called DSNDB06 resides in each location to maintain information about the location and all tables and databases in that location, including which tables and indexes belong to which databases and where objects are located on disk. The system location also contains two other system-related databases: DSNDDF and XDBACF. The DSNDDF database contains tables such as SYSXDB.SYSLOCALS and SYSIBM.SYSLOCATIONS which together serve as an index to local and remote locations. The XDBACF database contains tables for system security.

Each location, including the system location, also contains a DSNDB04 database. This database is the default database for storing tables and other objects that a user creates without specifying a database name.

The mainframe system catalog tables have a two-part name, using SYSIBM as the AuthID qualifier (for example, SYSIBM.SYSDATABASES and SYSIBM.SYSTABLES). The XDB Server uses this same AuthID for all system tables that have a corresponding table on DB2. The XDB Server has additional system catalog tables that have no counterparts on mainframe DB2. These catalog tables are prefixed with the SYSXDB AuthID (except SYSIBM.SYSXDBMAP).

When you install the XDB Server, the system catalog databases in the SYSTEM location are stored in subdirectories under the SYSTEM subdirectory of your XDB Directory. (Your "XDB Directory" refers to the directory where you installed the XDB Server and related executable software.)

Note: Do not run DDL files in the SYSTEM location.

For example, if you install the XDB Server in c:\xdb\ , then the system databases will be placed in the following subdirectories:

  • c:\xdb\system\dsndb06\
  • c:\xdb\system\dsndb07\
  • c:\xdb\system\dsnddf\
  • c:\xdb\system\xdbacf\
  • c:\xdb\system\dsndb04\

Whenever you create a new location you must specify a Location Name (up to 16 characters long) according to the following guidelines:

  • You must place your data tables in locations other than the system location. (You can have one or more databases and/or tables per location.)
  • Two locations with the same name cannot exist simultaneously under the same XDB Server (or engine). An error message is presented if you attempt to create a location using an existing location name.
  • If Distributed Unit of Work (DUW) processing is anticipated, location names must be unique across the entire system, that is, across the multiple servers and/or geographic sites that will be included in remote processing activities. (See Distributed Processing for more information.)

In addition to specifying a location name when you create a new location, you must also specify a directory for it on disk, according to the conventions for your operating system. For example, you could use the command:

 CREATE LOCATION locat1 IN c:\xdb\locat1

When you issue this command, the XDB Server creates the directory on disk and adds information about the new location to the SYSXDB.SYSLOCALS and the SYSIBM.SYSLOCATIONS tables in the SYSTEM location. Other options are available on the CREATE LOCATION command to allow you to specify the sort sequence, forward log name and other items. You can edit the SYSXDB.SYSLOCALS table to change these parameters.

Note: In an XDB database, the sort sequence (EBCDIC, ASCII, etc.) is defined when the location is created. You can change the sort sequence of a location with the ALTER LOCATION command.

You can execute the following utility command any place you can issue SQL commands to specify the current location:

SET LOCATION TO location-name

Your default current location is maintained in your client configuration. See the setup and configuration documentation that came with your client application for details. If you want to use or create objects in a location other than your current location, use SET LOCATION TO prior to entering your other SQL statements. In embedded SQL, and to access remote locations, you must use the CONNECT command.

Note: Distributed Unit of Work (DUW) Processing is also available for accessing data in locations other than your own. See Distributed Processing for more information.
Parent topic: Storage Architecture


Storage Groups (Stogroups)

On a mainframe system, Storage Groups (Stogroups) provide a means of specifying the physical DASD volume where data will be stored. The XDB Server provides an analogous function by allowing you to associate a drive and pathname with a stogroup name.

You can define one or more stogroups in each location as needed. Later, when you create a database or table space in a location that has one or more stogroups defined, you can specify a stogroup to be used for storing the database or table(s). Thus, you can specifically define the physical location (on what volume-- disk drive and directory) of each database or table space.

Note: Use of stogroups is optional. Once you define a location directory, subdirectory paths for other objects are created automatically as needed when you create the objects (for example, CREATE DATABASE). The XDB System Catalog keeps track of where objects are stored for each location and database.

To use stogroups to their full advantage, you must create the path(s) on your operating system. Then use the CREATE STOGROUP command to specify the drive and path name to be associated with a stogroup name. Lastly, modify two columns in the SYSIBM.SYSVOLUMES table to define the path to the XDB Server. (It is also possible to define a stogroup without assigning a path in SYSIBM.SYSVOLUMES. This provides compatibility with mainframe DB2 in terms of maintaining the stogroup-related entries in system tables but allows the XDB Server database software to use its default path creation and naming routines.)

If you do not specify a path in SYSIBM.SYSVOLUMES and/or you do not specify stogroups for your table spaces, the XDB Server will create a subdirectory under the location name directory to store your database files when you create the database. A typical database path created by the XDB Server could be :\XDB\LOCAT1\DBNAME\ .

Note: The XDB SYSIBM.SYSVOLUMES table contains two columns that are not included in the analogous DB2 table. These columns are XDBPRIMEVOLPATH and XDBVOLPATH.

See the SQL Reference for detailed information regarding the storage structure and naming conventions that apply when creating various table and database objects, with and without stogroups.

Example

The following CREATE commands will create two storage groups (named STOR1 and STOR2) on two separate disk volumes (named MINE and YOURS). The UPDATE commands will then define the disk drive and directory for each of the named volumes.

CREATE STOGROUP stor1 VOLUMES (mine) VCAT xdb;
CREATE STOGROUP stor2 VOLUMES (yours) VCAT xdb;
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y",
        XdbVolPath = "d:\stor1\"
    WHERE Volid = "mine";
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y",
        XdbVolPath = "e:\stor2\"
    WHERE Volid = "yours";

Before you can create databases or table spaces in these stogroups, you must create the two directories (d:\stor1 and e:\stor2).

Note: The VCAT parameter is required only when running in DB2 compatible mode. It is checked for syntax only, and recorded in the appropriate system table.

To complete this example, you would use CREATE commands such as the following to specify storage locations for objects you create:

CREATE DATABASE xyz stogroup STOR1;

or

CREATE TABLESPACE abc IN xyz
    USING STOGROUP stor1;
Parent topic: Storage Architecture


Databases

A database object is a 1-to-8 character name assigned to a collection of tables and indexes. When creating a database (without specifying a stogroup) the XDB Server also creates a subdirectory on disk using the database name. The subdirectory is created under the directory of the current location. (For example: c:\xdb\locat1\dbname )

When you create a table, you can specify the name of the database with which you want it to be associated. If you are using table spaces, you specify the name of the database and table space. If you do not specify a database name, then the tables and other objects are stored in the DSNDB04 default database which is automatically included in each location.

If you have defined stogroups (see above), you can specify which stogroup should be the default stogroup for the database. The directory (path) defined for that stogroup will then be used to store the various database files (tables, indexes, etc.).

If you do not specify a stogroup for the database, the XDB Server uses the default stogroup (SYSDEFLT) which causes files for database objects to be stored under the ..\location-name\dbname\ structure described above. (It is also possible to specify a stogroup for each table space that you define for your tables and indexes, if you use table spaces.)

See the SQL Reference for detailed information regarding the storage structure and naming conventions that apply when creating various database objects with and without stogroups.

Parent topic: Storage Architecture


Table Spaces, Tables, and Indexes

On a mainframe system, table spaces and stogroups provide a means of organizing tables and indexes on specific disk storage devices. Generally, each table space and index is associated with a stogroup. A table can be created within a specific table space, which associates the table with the stogroup of the table space. When an index is created, it can be associated with a stogroup as well.

The XDB Server supports the table space/stogroup structure, and provides syntactical/semantic support for relating an index to a stogroup.

Note: Use of table spaces and stogroups is optional. If you choose to specify table spaces, you can do so with or without stogroups.

If you have defined stogroups in an XDB database, you can specify which stogroup should be used when you create a table space. For example:

CREATE TABLESPACE brspace
    IN databas1 USING STOGROUP stor1;

When you create tables and indexes in a database, use either or both of the following methods:

  • Allow the XDB Server to define table spaces and directory paths for the tables and indexes you create. For example:
    CREATE TABLE branch
    ( fld1 SMALLINT, fld2 CHAR 1 )
    IN databas1;
CREATE INDEX brindex ON branch(fld1);

    If the database has a stogroup defined, the XDB Server uses its path to store the table and index files.

    If the database does not have a stogroup defined, the XDB Server uses the SYSDEFLT stogroup routine which uses the ..\location-name\database-name\ path structure. In this situation, the XDB Server creates table and index files under the database-name subdirectory to store each table and index. For example:

    • c:\xdb\locat1\databas1\branch.tab
    • c:\xdb\locat1\databas1\brindex.idx
    • c:\xdb\locat1\databas1\brindex.ptr

    The table space name will be the first eight characters of the table or index name, as appropriate. If the eight character name would duplicate an existing table space name, the system creates a unique name for the table space.

  • Specify a pre-defined table space for a table. The index will be placed in the table space where its associated table resides. For example:
    CREATE TABLE branch
    ( fld1 SMALLINT, fld2 CHAR 1 )
    IN databas1.brspace;
CREATE INDEX brindex ON branch(fld1);

    In this case, all tables you create with the named table space will be stored under the stogroup directory that was defined for the table space. Indexes created on those tables will be stored in the same stogroup path.

    For example:

    • d:\stor1\branch.tab
    • d:\stor1\brindex.idx
    • d:\stor1\brindex.ptr
Note:

If your database is the default DSNDB04 database, you do not have to specify the database name in the above commands.

Any table you create without specifying a database name will be placed in DSNDB04 automatically.

To summarize, when you create a table, you usually specify the database in which you want it to be created. Optionally, if you created table spaces in the location, you can specify a table space name in which to store the data. The system catalog keeps track of which tables belong to each database and where they are located on disk.

When you create an index, you specify the table to which it applies. Again, the system catalog keeps track of which indexes belong to each database and table, and where they are located on disk.

See the SQL Reference for detailed information regarding the storage structure and naming conventions that apply when creating various database objects with and without stogroups.

Example

In this example, a database and two table spaces are created in the current location. The first table space does not specify a stogroup, and thus the default database subdirectory will be used to store tables for this table space ( c:\xdb\locat1\dbname\ ). The other table space will reside in one of the previously defined stogroup directories ( d:\stor1 ).

Notice that when tables are defined, they are qualified with an IN clause to specify to which database they belong (and optionally, which table space should be used to store the physical data). In this example, the first two tables use specific table spaces. The third table is defined without a table space. The index for the BRANCH table will reside in the same table space as the BRANCH table.

CREATE DATABASE databas1;
CREATE TABLESPACE brchspc IN databas1;
CREATE TABLESPACE acctspc IN databas1
    USING STOGROUP stor1;
CREATE TABLE branch (
           BRANCH_ID   INTEGER,
           BRANCH_BAL  DECIMAL(15,2) )
    IN databas1.brchspc;
CREATE INDEX BIDX ON BRANCH(BRANCH_ID);
CREATE TABLE account (
           ACCT_ID     INTEGER,
           BRANCH_ID   INTEGER,
           ACCT_BAL    DECIMAL(15,2) )
    IN databas1.acctspc;
CREATE TABLE history (
           ACCT_ID     INTEGER,
           BRANCH_ID   INTEGER,
           ACCT_BAL    DECIMAL(15,2) )
    IN databas1;
Parent topic: Storage Architecture


Summary and Example

The XDB Server fully supports the naming conventions and data storage structures that are available on a mainframe DB2 subsystem. Features include the following structures and objects:

  • Locations
  • Storage Groups
  • Databases
  • Table Spaces
  • Tables
  • Indexes

Example

The following is a scenario for creating a new location with two databases. Each database has a table space defined. One table in each database is created in a table space. The other table in each database is created without a table space.

Use the SQL Wizard to execute these commands. See the SQLWizard User's Guide or on-line help for information.

CREATE LOCATION testxdb
    IN c:\xdb\testxdb\;
SET LOCATION TO testxdb;
CREATE DATABASE testdb1;CREATE DATABASE testdb2;CREATE TABLESPACE ts4db1 IN testdb1;
CREATE TABLESPACE ts4db2 IN testdb2;
CREATE TABLE table1 (Field1 integer, Field2 integer)
    IN DATABASE testdb1;
CREATE TABLE table2 (Field3 integer, Field4 integer)
    IN testdb1.ts4db1;
CREATE TABLE tableA (FieldA integer, FieldB integer)
    IN DATABASE testdb2;
CREATE TABLE tableB (FieldC integer, FieldD integer)
    IN testdb2.ts4db2;
CREATE INDEX inx ON table1 (Field1);
Parent topic: Storage Architecture


Basic Tasks

  • Starting an XDB Server
  • Shutting Down an XDB Server
  • Client Sessions and Multiple Logins
  • Administrative (Authority) Levels
  • Administrative Tasks
Parent topic: SQL Option Server Administration Guide


Starting an XDB Server

A personal XDB Server is installed on your machine when you install SQL Option for DB2. This local copy of XDB Server is the default server. It must be running before you can debug or run client applications against a local XDB database. The personal XDB Server can be installed as a Windows Service that is started automatically.

You can also run the XDB Server Blue Screen mode.

After installing and configuring the XDB Server and at least one client, you are ready to run your XDB Server.

When the XDB Server completes its initialization, users can access the locations controlled by the XDB Server immediately. See the topic Shutting Down an XDB Server for information about shutting down an XDB Server.

Parent topic: Basic Tasks
Related information
Shutting Down an XDB Server
To start the XDB Server in blue screen mode


Shutting Down an XDB Server

Use either of the following procedures to shut down the server:

  • Press F10 when viewing the XDB Monitor Utility main menu. If users are active, the monitor asks you to confirm the action.
  • Issue the SQL SHUTDOWN command from a client program (i.e. SQLWizard ). If security is on, your AuthID must have super user authority. For information, about the SHUTDOWN command, see the SQL Reference.
  • Double-click the XDB Server icon in the Control Panel, and click Stop.

Keep the following in mind when you shut down an XDB Server:

  • If users are active when you shut down an XDB Server, their sessions are terminated in mid-transaction, as though the XDB Server crashed. When the XDB Server is restarted, all incomplete transactions are rolled back the next time that location is accessed. Use care, since user programs running on the workstations may not handle a case where the XDB Server no longer responds.
  • If a query is active when you shut down an XDB Server, the XDB Server waits until the query is complete before shutting down.
Parent topic: Basic Tasks


Client Sessions and Multiple Logins

An XDB client running on Windows or UNIX platforms can have several concurrent sessions. For example, a Windows user could open a window and start the SQLWizard. Next, the same user could open another window and start the XDB Migrate Utility, logging in to the XDB Server with the same AuthID and Node Name. The XDB Server will show two user sessions, both with the same AuthID and Node Name, but each running a different process, and each showing a different Session ID number. Likewise, a Windows client can start several sessions by clicking on multiple program icons. Again, the user's multiple sessions show up on the XDB Server, all having the same AuthID and Node Name but with unique Session ID numbers.

When a client session fails or otherwise aborts without logging out, the XDB Server automatically detects the aborted session and releases all resources and locks. Any in-process transactions are rolled back. If the user has other sessions running, they are not affected.

Parent topic: Basic Tasks


Administrative (Authority) Levels

Assign system administration activities and responsibilities to others, depending upon the size and complexity of your installation. With the exception of the special super user privilege set, all authorities are effective only within the location where they are defined.

Suggested responsibilities include:

  • Super User. A special set of XDB Server privileges that can be assigned to one or more system users. This privilege set is assigned automatically to the INSTALL AuthID during installation. Super user authority allows access to all functions on the system. Only the super user can create locations, drop locations and edit system tables.
  • System Administrator (SYSADM). A user who has access to almost all functions within the defined location, including the authority to grant and revoke privileges for other users in that location, but excluding the special super user privileges defined above.
  • System Control (SYSCTRL). A user whose privileges apply only to the location in which SYSCTRL is granted. These privileges include almost all privileges except access to user data.
  • Database Administrator (DBADM). A user who has all database-level privileges but only for a specified database.
  • Database Control (DBCTRL). A user who can use DROP on one specified database, and whose privileges include DBMAINT privileges.
  • Database Maintenance (DBMAINT). A user who can use CREATAB, CREATETS, STARTDB, AND STOPDB for one specified database.

With the exception of super user, any of these suggested responsibility levels can be granted by using the appropriate authority (DBADM, SYSCTRL, etc.) on the GRANT command. See the chapter Security and Authority for more information about security, including use of the GRANT and REVOKE commands.

Parent topic: Basic Tasks


Administrative Tasks

This collection of topics covers the following administrative tasks:

  • Configuring System Parameters
  • Managing System Structures and Space Requirements
  • Packing Data Files to Create Free Space
  • Insuring Database Integrity
  • Evaluating and Improving Database Performance
  • Controlling Access at the System, Database, and Table Levels
  • Backing Up and Restoring Data
  • Maintaining Storage Media
Parent topic: Basic Tasks


Configuring System Parameters

The database administrator should be responsible for setting parameters in the XDB Server Configuration utility for multiuser systems, and for assisting users with the parameters in their individual XDB Server Options and Server Configuration utilities.

Parent topic: Administrative Tasks
Related information
To start the XDB Server Configuration Utility


Managing System Structures and Space Requirements

The database administrator should also examine the structure of the various locations on the system and the databases defined within each location with an eye towards reducing unnecessary or redundant data storage. The XDB Server supports distributed processing at various levels. See the chapter Storage Architecture for more information about the system architecture.

The system catalog tables provide information about the tables in a database. To determine the space occupied by a given table or index, use the directory DIR command from your operating system prompt to list the tables in a given directory. The directory DIR command lists the amount of space occupied by each file in addition to the number of free bytes remaining on the disk. You can use the SQL SELECT command to query any of the system catalog tables. See the SQL Reference for a description of the SELECT command. See the chapter Storage Requirements for more information about estimating data storage requirements.

Parent topic: Administrative Tasks


Packing Data Files to Create Free Space

Tables, directories and locations should be periodically packed to improve performance and reduce storage requirements. The SQL COMPACT command can be used to:

  • Free space that was formerly occupied by deleted records.
  • Optimize the dictionary files by freeing space that was formerly used for tables that have since been altered or dropped.
  • Rebuild indexes:
    • When converting from a previous version of the XDB Server.
    • After performing many updates or deletions, to optimize space utilization.
    • To rebuild corrupt index files.
  • Re-order the data in a table according to the order of records in a clustered index.

You can call the SQL COMPACT command from any utility that allows you to issue standard SQL commands (such as the SQLWizard on Windows platform, or Interactive SQL on UNIX). You can also use the SQL COMPACT command in Embedded SQL in COBOL . For more information about this command, see the SQL Reference.

Note:

If you are using XDB Link, you cannot use the COMPACT command against DB2 objects on the mainframe. Instead, log on to the mainframe and use the REORG facility to perform this task.

Parent topic: Administrative Tasks


Insuring Database Integrity

The database administrator needs to oversee data entry and programming tasks that impact each database to insure that proper data validation techniques are enforced.

The XDB Server implements referential and domain integrity checks at the schema level. Data integrity can be directly controlled through the use of these integrity features. For more information, see the ALTER or CREATE command in the SQL Reference.

Parent topic: Administrative Tasks


Evaluating and Improving Database Performance

The database administrator determines if the performance of a database is satisfactory for the application environment. Some factors that influence database performance include:

  • Indexes
  • Optimizing the structure of SQL statements
  • Locking (in multiuser versions)
  • Clustering
  • Database design
  • Caching
  • Storage organization, including use of storage groups (stogroups)
Parent topic: Administrative Tasks


Controlling Access at the System, Database, and Table Levels

The database administrator is responsible for protecting the security of the system, locations, databases, and tables. This is accomplished by creating and deleting AuthIDs (user names) and groups, as well as granting and revoking privileges at various levels within the system.

Activate security privileges by turning security on with the XDB Server Configuration utility. Use the SQLWizard to add and delete AuthIDs. See the chapter Security and Authority for more information.

Privileges on system functions and database objects are managed through the SQL GRANT and REVOKE commands, which are described in the SQL Reference.

Parent topic: Administrative Tasks


Backing Up and Restoring Data

The database administrator is expected to establish a regular schedule for backing up locations and their log files. The frequency of backups depends on the frequency of database updates, the importance of data, and the difficulty involved in recreating the data. You should always backup a location during special operations, such as after using the COMPACT command or before installing a new version of XDB Server software.

Backups can be performed using the BACKUP LOCATION command or by using an operating system backup command.

If you operate a location with recovery turned on, log files are maintained (ideally on a different disk drive). The log files contain after images of records that were changed by database transactions within the location. In the event of a system failure, the log files can be applied to the latest restored backup of the location to recover the changes recorded in the log files. The XDB Server provides a ROLLFORWARD command for this purpose.

See the chapter Backup and Recovery for more information.

Parent topic: Administrative Tasks


Maintaining Storage Media

The database administrator is also expected to ensure that timely and proper procedures are implemented and observed for verifying the integrity of storage media. For example, all drives should be checked regularly for lost clusters, fragmentation and other damage that might accumulate over time to threaten data.

There are various commercially available utilities for checking and repairing disk problems. Check your operating system documentation for more information on this or other comparable commands.

Parent topic: Administrative Tasks


Server Configuration Utility

The Server Configuration utility enables you to change the configuration of your personal XDB Server. For example, you can change the following:
  • The XDB Server name
  • Whether XDB Server security is enabled or not
  • Which protocol is used to access the XDB Server
  • Whether other people can use the XDB Server
  • The amount of system resources available to XDB Server
  • Accessing the Server Configuration Utility
  • Server Configuration Parameters
Parent topic: SQL Option Server Administration Guide
Related information
To start the XDB Server Configuration Utility


Accessing the Server Configuration Utility

You can run the XDB Server Configuration utility in one of two modes:

Blue screen
You have two options:
From Enterprise Developer
  • From the main menu, click > Server > XDB Server Monitor.
From the Start menu
  • Click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2 > Server > XDB Server Monitor
As a Windows service
  1. Start your Windows Control Panel.
  2. Double-click Micro Focus XDB Server.
  3. Click Configure.
Parent topic: Server Configuration Utility


Server Configuration Parameters

This collection of topics covers the following:

  • System Location Path
  • Temporary File Path
  • Server Security
  • Server Version
  • System Usage Monitor
  • Sort Space Size
  • Maximum Number Of Users
  • Lock Table Size
  • Maximum Number of Open Queries
  • Maximum Number of Open Files
  • Governor Cycle Time
  • XDB Server Name
  • Communications Protocols
  • Global Security and Global Security Location Name
  • Buffer Pool Size
Parent topic: Server Configuration Utility


System Location Path

The system location path specifies where the XDB Server looks for system tables containing information about all locations that are accessible to this XDB Server. These system tables are in addition to the system tables that are maintained in the DSNDB06 database for each location.

Enter a path to a specific drive (volume) and directory. Do not specify a location name.

Note: You specify this path when you install the XDB Server. Change the system path only when you need to physically move the files comprising your SYSTEM location.

To set the parameter on Windows 2000:

  1. Click the Paths tab.
  2. Enter the path in the System Location Path text box.
Parent topic: Server Configuration Parameters


Temporary File Path

Set the temporary path to identify where the system should write temporary files used by the XDB Server, such as temporary files that are written when a sort operation overflows the allocated Sort Space Size. Enter a path to a specific drive (volume) and directory. This directory must be accessible to the XDB Server.

To set the parameter on Windows 2000:

  1. Click the Paths tab.
  2. Enter the path in the Temporary File Path text box.
Parent topic: Server Configuration Parameters


Server Security

The XDB Server is shipped with security turned off. If you enable security at the server, you must also enable security at each client workstation accessing the XDB Server. Otherwise, the XDB Server will reject the client logon.

Enabling security requires each user to log in to the XDB Server using a valid AuthID (user name) and password. To set AuthIDs, groups and passwords, use the Admin menu of the SQLWizard. See the Security and Authority chapter, or User Administration in the SQLWizard User's Guide for more information.

If you enable security, the system will also check any privileges configured using the GRANT and REVOKE commands. For information about the GRANT and REVOKE commands, see the SQL Reference.

See the chapter Security and Authority for detailed information about how to plan and construct a security scheme.

To set the parameter on Windows 2000:

  1. Click the General tab.
  2. Mark the Server Security checkbox.
Note: There is no password protection provided by the XDB Server Configuration utility. Anyone with access to the server can run the utility and enable or disable the security. Make sure that the server is physically secure from unauthorized access.
Parent topic: Server Configuration Parameters


Server Version

The XDB Server is shipped with version set to DB2V6.

To set the parameter:

  1. Press F3 SQL Engine Options.
  2. Press F2 Server Version.
  3. Press F1 to select DB2V6 or F2 for DB2V7.
Parent topic: Server Configuration Parameters


System Usage Monitor

The Usage Monitor is a facility for recording location usage. While utilization monitoring is on, the system stores utilization information in the SYSXDB.SYSUSAGE table in the DSNDB06 subdirectory of the system location's directory. If you enable the usage monitor and security, the system will automatically maintain this table, and modify it each time a user logs in or out of a location. You can query the table to audit location usage.

Note: Because the Usage Monitor tracks usage data by individual user session, it contains worthwhile information only when server security is enabled, which forces users to log in.
Note: Enabling the Usage Monitor can decrease performance and require large amounts of disk space.

If the SYSXDB.SYSUSAGE table becomes too large, delete entries from the table using the DELETE or TRUNCATE TABLE command. After deleting entries, you must pack the SYSXDB.SYSUSAGE table using the COMPACT command. COMPACT frees space formerly occupied by deleted records. It is good practice to perform this procedure each time you back up the system location when using the System Usage Monitor.

See the SQL Reference for the structure of the SYSXDB.SYSUSAGE table, and for information about the DELETE, TRUNCATE TABLE, and COMPACT commands. As is the case for all XDB Server system tables, the structure of the SYSXDB.SYSUSAGE table is subject to change.

To set the parameter on Windows 2000:

  1. Click the General tab.
  2. Mark the System Usage Monitor checkbox.
Parent topic: Server Configuration Parameters


Sort Space Size

Set the sort space size to specify the maximum amount of memory that the XDB Server will attempt to acquire when performing a sort operation. Sort space is acquired on a per-sort basis. The sort space size does not define a common pool shared by all users, but rather the maximum amount of space provided for each individual sort request. If a particular sort process does not require the total amount of memory allocated by the Sort Space Size setting, the excess amount of memory is released back to the operating system.

Increasing the sort space size allows the system to process large sorts more quickly, and store larger amounts of data at a single time, requiring fewer merges of sorted information. However, if you set this value too high, relative to the number of concurrent sorts or users, query processing may slow down significantly due to over-allocated memory.

To set the parameter on Windows 2000:

  1. Click the Limits tab.
  2. Enter the desired size in the Sort Space Size text box, or drag the slider.
Note: Do not set the combined amounts of Sort Space Size and other cache to a number greater than the total amount of physical memory (RAM) available on a machine. Doing so can degrade performance due to operating system swapping. When determining how much cache to allocate, be sure to consider all types of caching, including the Caching Options, the XDB Server Sort Space Size option, and operating system cache.
Parent topic: Server Configuration Parameters


Maximum Number Of Users

Set the maximum number of concurrent users logged in the XDB Server to an integer between 1 and 128. Each user will require an additional 128 bytes of memory.

To set the parameter:

  1. Press F4 Configure System Minimums/Maximums.
  2. Press F2 Maximum Number of Users.
  3. Enter the desired number and press Enter.
Parent topic: Server Configuration Parameters


Lock Table Size

Set the size of the lock table to an integer between 4 and 1000 (kilobytes). The recommended setting is 60KB. The XDB Server returns an error code when the lock table is full.

To set the parameter (Windows):
  1. Click the Limits tab.
  2. Enter the desired size in the Lock Table Size text box, or drag the slider.
Parent topic: Server Configuration Parameters


Maximum Number of Open Queries

You can set the XDB Server to support anywhere from 10 to 9,999 open queries. Each additional query specified here requires an additional, but negligible amount of memory. However, specifying too large a number can impact performance because the array of queries is scanned each time a transaction completes. The more queries that are allowed, the longer the scan will be each time.

To set the parameter (Windows 2000):

  1. Click the Limits tab.
  2. Enter the desired number in the Maximum Open Queries text box, or drag the slider.
Parent topic: Server Configuration Parameters


Maximum Number of Open Files

Set the XDB Server to allow between 256 and 32,767 logically open files at any time. Each additional open file adds approximately 100 bytes of memory overhead to the XDB Server.

Once a file has been accessed, the XDB Server keeps the file logically open. A least recently used (LRU) algorithm determines which files to physically close when the limit is reached. The LRU significantly reduces the overhead related to physically opening and closing files during query processing.

If query processing is slow, increase the maximum number of open files.

To set the parameter (Windows:

  1. Click the Limits tab.
  2. Enter the desired number in the Maximum Open Files text box, or drag the slider.
Parent topic: Server Configuration Parameters


Governor Cycle Time

If security is enabled, set the governor cycle time to an integer between 1 and 255 to specify the frequency, in seconds, at which the server checks user activity against limits set in the SYSXDB.SYSGOVERNOR table.

The XDB Server terminates sessions of users who have passed their limits. Limit users by the:

  • Number of API calls
  • Amount of time in the SQL engine
  • Amount of time processing calls
  • Amount of idle time
  • Number of fetches

For example, if Governor Cycle Time is set to 30 seconds, the system checks user activity against governor limits every 30 seconds. A cycle that is too short increases system overhead and decreases performance.

For more information about the XDB Governor and how to assign restrictions to users, see the description in the chapter Security and Authority.

To set the parameter (Windows):

  1. Click the General tab.
  2. Mark the Governor checkbox (if it is not already enabled).
  3. Enter the desired cycle time in the Cycle Time text box, or drag the slider.
Parent topic: Server Configuration Parameters


XDB Server Name

Use this option to set the name by which this XDB Server is known to client applications. Multiple XDB Servers, each with a unique name, can coexist on the same network. Users must supply the appropriate XDB Server Name, using the Options Utility, to connect their client applications to a particular server.

The name given here must also be specified in other places, depending on the client-to-server communications protocol and operating system:

  • For servers using TCP/IP, the xdbnet.ini file contains additional protocol information about each XDB Server on the LAN.

Other networks or operating systems may have other naming conventions and restrictions. Consult your network or operating system documentation for more information.

To set the parameter on Windows:

  1. Click the About tab.
  2. Enter the name in the XDB Server Name text box.
Parent topic: Server Configuration Parameters


Communications Protocols

Local (Windows)
Turn this option on to enable communication between client and server on the same Windows machine.
TCP/IP (all platforms)
Turn this option on to enable communication between TCP/IP clients and the server.
To set the parameter:
  1. Click the General tab.
  2. Mark the checkbox next to the desired communications protocol.
Parent topic: Server Configuration Parameters


Global Security and Global Security Location Name

Once you enable server security, you may enable Global Security if this XDB Server will access another XDB Server or mainframe location for security information (such as AuthIDs and password validation). If you enable Global Security, you must enter the name of the location that contains the global security information.

  • If the global security location is on an XDB Server, you must set up server-to-server connections, including registering the security location of the remote XDB Server in the appropriate system tables of the local XDB Server. See the chapter Server-to-Server Connectivity for more information.

If Global Security is OFF and the XDB Server's regular security feature is ON, AuthID and password validation are performed on the local XDB Server's SYSXDB.SYSACFUSERS, SYSXDB.SYSACFGROUPS and SYSXDB.SYSACFMEMBERS tables in the SYSTEM location.

See the chapter Security and Authority, or User Administration in the SQLWizard User's Guide for information about setting up AuthIDs and groups for users. See the chapter Server-to-Server Connectivity for information about setting up server-to-server connectivity. See the chapter Multiserver Security for information about setting up global security.

When using global security, the following are granted on the XDB Server where the user will be accessing data: server-to-server connections and inbound/outbound mapping database privileges, governor limits, and similar user controls.

To set the parameter (Windows):

  1. Click the General tab.
  2. Mark the Global Security checkbox.
  3. Enter the global security location name in the Location text box.
Parent topic: Server Configuration Parameters


Buffer Pool Size

You can set a buffer pool size to allocate the total amount of memory, in kilobytes, available for caching table, index, and dictionary files. A buffer pool size can range from 16K to 131,072K. The value of BP(0) sets the buffer pool size for data, and the value of BP(1) sets the buffer pool size for indexes. However, if you set BP(0) to a value of zero, this sets the buffer pool size to zero for both data and indexes.

Micro Focus's buffer management system is designed to enhance performance. Memory is allocated by the cache manager at XDB Server start up and then released at XDB Server shut down.

Note: Do not set cache to a number greater than the total amount of physical memory (RAM) available on a machine. Doing so can degrade performance due to operating system swapping. When determining how much cache to allocate, be sure to consider all types of caching, including Caching Options, Sort Space Size, and operating system cache.

To set the cache size in blue screen mode:

  1. Press F6 Caching Options.
  2. Press F1 BP(0) Cache Size or F1 BP(1) Cache Size.
  3. Enter the appropriate cache size in KB and press Enter.
To set the cache size from the Windows XDB Server Configuration Utility service:
  1. Click the Cache tab.
  2. Type a cache size into each of the appropriate fields, or drag the slider to select a value for each.
  • About Caching
Parent topic: Server Configuration Parameters


About Caching

There is one buffer pool cache per XDB Server, and all applications connecting to the XDB Server share this global memory. The overall size of the buffer cache has a large impact on database performance. If the cache is large enough to keep the required data in memory, less disk activity occurs and performance increases. If the cache pool is not large enough, the overall performance of the XDB Server can decrease, with the XDB Server becoming I/O-bound, as physical disk activity is required to service application requests.

The buffer pool cache effectiveness increases with multiple users, when a large amount of repeated access to the same data and index pages occur, and when one primary location is accessed.

The cache manager stores pages (4K each) of database object data. (Therefore, the number of pages is the cache size divided by four.) These database objects consist of table, index, and dictionary pages for all accessed locations. The dictionary pages originate from the dictionary files that reside in every location. As an application requests data from one of these object types, pages containing the data are transferred from the disk into the buffer pool.

Pages are not written to disk until one of the following occurs:

  • The XDB Server is shut down.
  • A checkpoint occurs.
  • Another page needs to be read into a full buffer pool.

Consider the following when determining how much RAM to allocate to cache:

  • A large cache usually speeds up online transaction processing (OLTP). However, if the checkpoint frequency is too infrequent, there can be detectable processing delays each time the checkpoint causes data to be written to the location tables. If checkpoint delays are a problem, either lower the cache amount or increase the checkpoint frequency. For more information about the CHECKPOINT command and the Checkpoint Frequency parameter, see the SQL Reference and the chapter Backup and Recovery chapter in this guide.
  • Decision support systems usually benefit from a larger cache, but the amount of cache does not necessarily have to be as large as the combined size of the database tables and indexes. For example, in a database where much of the data is historical (and rarely accessed), the amount of cache would only have to be large enough to contain the currently active data -- such as the current month or quarter.
  • On systems where sort operations are heavy, you might find that an increase in Sort Space Size gives a better performance gain than increasing or decreasing the cache. Once the appropriate Sort Space Size is defined, you should find it easier to determine the amount of cache needed.

Use the Cache Statistics screen of the Monitor Utility to help determine the best amount of cache for your system. When your XDB Server has reached a steady state (work is well in progress), check the percentage shown for Pages in Use. If Pages in Use is running at or near 100% and the Number of Tosses is high, then most of your allocated cache is being used and you might want to try increasing it. If Pages in Use and Tosses are running low, you have more cache allocated than you need.

Parent topic: Buffer Pool Size
Related information
Performance Tuning


Monitor Utility

The Monitor Utility enables you to monitor the activity of the SQL Option Server.

  • Access and Control
  • Function Summary
  • User Activity
  • Server Status
  • User Resource Statistics
  • Memory Manager Statistics
  • Cache Statistics
  • Halt Query
  • Delete User
  • Shutdown Server
Parent topic: SQL Option Server Administration Guide


Access and Control

Once the XDB Server is running, you can monitor XDB Server activity in any of the following ways:

  • Direct Access. You can run the Monitor Utility xdbmonn.exe on the server machine.
  • Remote Access. You can run the Monitor Utility xdbmonn.exe from a client machine.
  • Virtual Statistics Queries. You can use SQL to query the Virtual Statistics Tables. See the chapter Performance Tuning for more information on Virtual Statistics Tables.
Parent topic: Monitor Utility


Function Summary

The Monitor utility provides access to the information described in the following table. The remainder of this chapter presents detailed information about each function.

Function | Description
User Activity | Displays information about each currently logged on user. Information includes isolation level and time logged on. An asterisk preceding an AuthID indicates that the user has a query open.
Server Status | Provides information on the number of users logged in, the number of queries open, and other useful information.
User Resource Statistics | Displays each user's system resource usage, including the number of queries, table locks (exclusive and shared), and record locks (exclusive and shared).
Memory Manager Statistics | Displays information about the amount of memory currently in use.
Cache Statistics | Displays caching and input/output statistics for the XDB Server cache manager. Monitor cache statistics when your system is running at steady state will help you determine the most effective amount of cache to allocate.
Halt Query | Stops a potentially long sort or query that is in progress.
Delete User | Aborts a user session when a user's workstation fails. The interrupted transaction is rolled back automatically.
Shutdown Server | Shuts down the XDB Server.
Parent topic: Monitor Utility


User Activity

User Activity displays information about the users currently logged in to the XDB Server. If the lines of data exceed the screen size, the information will scroll automatically, pausing at each section.

Note: When a user performs certain functions (such as viewing a list of locations) in text mode tools, the system creates a new internal user in order to access the system location. The monitor will display this user in the User Activity information (with a system-generated name) along with the other "real" users.
User Name
Generally, this is the AuthID used to log on to the XDB Server. If the value in this field is prefixed with an asterisk (*), the user has a query open.

When security is on, the USER NAME displayed is the AuthID under which the user logged into the XDB Server. If security is off, the USER NAME displayed is the same as the Primary AuthID for the client, as set through Options Utility.

If the user has a Secondary ID, the Secondary ID will be shown. If the user has been reassigned a different AuthID via server-to-server inbound or outbound mapping, the re-assigned (new) AuthID is shown.

Some user operations that access the SYSTEM location (such as displaying a list of tables or other browse features) temporarily create a pseudo user, PUBLIC1.

Node ID
This field displays the name of the node from which the user is working. The node name is set through Options Utility for SQLWizard clients on the client workstation. Each client machine must have a unique node name. If there are several clients (AuthIDs or sessions) with the same node name, the node name is appended with a number to indicate the session ID of the client session.

While the same AuthID and node name can be used to log in multiple times (from several different Wintel sessions, for example), the combination of AuthID, node name and session ID together are always unique.

Current Location
This field displays the name of the currently open location.
ILevel
This field displays the isolation level at which the user is currently working. The isolation level is set in any of the following ways:
  • Through the Options Utility
  • By using the SET ISOLATION command
  • By using the new WITH clause on certain SQL statements (DB2 4.x)

See the SQL Reference for information about the SET ISOLATION command and the WITH clause.

Autocommit
This field displays the user's current autocommit level. Set the autocommit level with the Options Utility, or use the SET AUTOCOMMIT command. See the SQL Reference for information about the SET AUTOCOMMIT command.
Logged in Since
This field displays the date and time the user logged in to the XDB Server.
Parent topic: Monitor Utility


Server Status

Server Status information includes the type and number of requests the XDB Server is currently processing and the XDB Server configuration settings.

Note:

When running remotely, the Monitor Utility cannot read the server configuration, and therefore cannot display all of the information in Server Status. The term "N/A" replaces unavailable information.

Server Status displays two types of information:

  • Dynamic information for the current and set maximum of a number of XDB Server parameters.
  • Static information that is constant while the XDB Server is running.
  • Dynamic Server Information
  • Static Server Information
Parent topic: Monitor Utility


Dynamic Server Information

Dynamic server information displays current server activity (CURRENT column), and the limit set in the server configuration (MAXIMUM column) for the following values:

Values | Description
Users | Number of users logged into the XDB Server.
Active Users | Number of users with open SELECT queries.
Open Locations | Number of locations with open SELECT queries.
Open Files | Number of logically open files.
Open Queries | Number of open SELECT queries.
Lock Blocks In Use | Number of lock blocks in use.

Use the XDB Server Configuration Utility to set the limits for open locations, open files, open queries, and lock table size.

Parent topic: Server Status


Static Server Information

Static server information is constant while the XDB Server is running, and includes:

Values | Description
Server Running Since | Date and time the XDB Server was started.
System Location Path | Path where the SYSTEM location for the XDB Server resides.
Temporary Path | Path where temporary files for the XDB Server are stored.
System Usage Monitor | Status of the system usage monitor (on or off).
System Security | Status of system security (on or off).
Packet Ver | Current XDB Server packet version.

Set the system location path, temporary path, system usage monitor, and system security parameters using the XDB Server Configuration utility.

Parent topic: Server Status


User Resource Statistics

User Resource Statistics information includes query and lock statistics for each AuthID/Node currently using the XDB Server. If the user information exceeds the screen size, use PgUp, PgDn, up-arrow, and down-arrow to scroll through the information.

User

Generally, this is the AuthID used to log on to the XDB Server. When security is on, the USER NAME displayed is the AuthID with which the user logged into the XDB Server. If security is off, the USER NAME displayed is the same as the Primary AuthID for the client, as set through the Options Utility.

If the user has a Secondary ID, the Secondary ID will be shown. If the user has been reassigned a different AuthID via server-to-server inbound or outbound mapping, the re-assigned (new) AuthID is shown.

Some user operations that access the SYSTEM location (such as displaying a list of tables or other browse features) temporarily create a pseudo user, PUBLIC1.

Information Description
Node

This field displays the node name from which the user is working. The node name is set through the Options Utility on the client workstation. Each client machine must have a unique node name. If there are several users (AuthIDs or sessions) with the same node name, the node name is appended with a number to indicate the session ID of the client session.

While the same AuthID and node name can be used to log in multiple times (from several different Windows sessions, for example), the combination of AuthID, node name and session ID together are always unique.

QDs

This field displays the number of open queries.

TsLocks

This field displays the number of shared table locks.

TxLocks

This field displays the number of exclusive table locks.

RsLocks

This field displays the number of shared record locks.

RxLocks

This field displays the number of exclusive record locks.

Parent topic: Monitor Utility


Memory Manager Statistics

The Memory Manager Statistics Screen displays information about the amount of memory currently in use as follows:

Information | Description
Total Memory From OS | Total Memory From OS displays the total number of bytes (cumulative) allocated from the operating system.
Number Allocations From OS | Number Allocations From OS is the total number of memory allocations from the operating system (cumulative).
Current Allocations From OS | Current Allocations From OS is the current number of outstanding memory allocations from the operating system.
Parent topic: Monitor Utility


Cache Statistics

The Cache Statistics screen displays caching statistics based on the cache option configured via the XDB Server Configuration utility. The screen displays information in units of 4K memory pages. You can use this information to analyze cache hit ratios and monitor cache effectiveness. The statistics include caching information for all table, dictionary, and index files.

Information | Description
Total Pages | Shows the number of pages in the cache.
Page Size | Size of each page in bytes.
Pages in Use | Percentage of the cache pages allocated to all files that use this cache.
Dirty | Percentage of total pages in the cache that have not yet been written to disk.
Cache Reads | Total number of pages requested from the cache.
Pages Read | Total number of pages read into the cache from disk.
Disk Reads | Total number of read I/O calls performed. Matches pages read, since pages are requested only one at a time.
Read Hit | Percentage of pages requested that did not require a disk read I/O operation.
Cache Writes | Total number of dirty pages released to the cache.
Pages Written | Total number of pages written to disk.
Disk Writes | Total number of disk write I/O calls performed. This number may be less than pages written since flushing causes a series of pages to be written to an accumulator first, and then all written together in one I/O.
Write Hit | Percentage of pages released dirty to the cache that were not written to the disk.
Tosses | Number of cache pages allocated to a file that were written out to disk to make room for a new page.
Checkpoints | Number of checkpoint calls made to this cache.
Parent topic: Monitor Utility


Halt Query

Use the Halt Query option to stop the processing of any DML command (DELETE, INSERT, SELECT, and UPDATE). Halt Query is especially useful when a user's workstation hangs or when a potentially long query needs to be aborted.

If security is on, you must have SYSADM authority on the SYSTEM location (or have super user privileges) to perform this operation.

To halt a query:

  1. Press F8. A window containing AuthIDs (user names) and nodes appears.
  2. Use the up-arrow and down-arrow keys to highlight the name of the user whose query you want to halt.
  3. Press Enter. Confirm the action when requested.
Parent topic: Monitor Utility


Delete User

Use the Delete User option to deactivate (cancel) a particular user session. If security is on, you must have SYSADM authority on the SYSTEM location (or have super user privileges) to perform this operation.

To delete a user:

  1. Press F9. A window containing AuthIDs (user names) and nodes appears.
  2. Use the up-arrow and down-arrow keys to highlight the name of the user whose query you want to halt.
  3. Press Enter. Confirm the action when requested.

If the logging system is on, the XDB Server will roll back and delete the session for the user selected.

Parent topic: Monitor Utility


Shutdown Server

You can press the F10 key to shut down the server. If users are active, the monitor asks you to confirm the action.

  • If users are active when you shut down an XDB Server, their sessions will be terminated in mid-transaction, as though the XDB Server crashed. When the XDB Server is restarted, all incomplete transactions will be rolled back the next time that location is accessed. Use care, since user programs running on the workstations may not handle a case where the XDB Server no longer responds.
  • If a query is active when you shut down an XDB Server, the XDB Server will wait until the function is completed before shutting down.
Parent topic: Monitor Utility


Security and Authority

  • Security System Concepts
  • Setting Up Security
  • System Level Access Control
  • Granted Authorities and Privileges
  • Security User Exit
  • AuthID List User Exit
Parent topic: SQL Option Server Administration Guide


Security System Concepts

XDB Servers are shipped with security turned off to allow you unlimited access to the system. You can continue to operate without security indefinitely, if desired, even in a multiuser environment.

In a multiuser environment, if security is on at the server, then all users must have security on at their individual workstations. After security is turned on, each user or process must log in with a valid AuthID (a "user ID"). If the AuthID has a defined and required password, the password must be entered as well. When the user attempts to access a table, the server also verifies that the user has privileges to that table, which were set up using the GRANT and REVOKE commands. Only someone with super user privileges can establish AuthIDs and passwords.

Super Users

Each XDB Server is shipped with one super user called INSTALL. A super user is the only user who can:

  • Create and drop locations.
  • Add and remove users
  • Edit (update) system tables.
  • Assign super user privileges to another user ID.

You can create other super users at your discretion using the SQLWizard Users command on the Admin menu.

Super user privileges should be limited to a few trusted users with database administration expertise.

Note: In effect, when security is off, all users are super users. As long as security remains off, the Primary AuthID indicated in your client configuration is used as the qualifying name in the three-part object name:

location-name.authid.object-name.

Note: The INSTALL user ID that is shipped with an XDB Server does not have a password assigned to it. Use the SQLWizard Users command or run the ALTER PASSWORD SQL command to assign a password to this user ID as soon as possible. The syntax for ALTER PASSWORD is as follows:
 ALTER PASSWORD old_password TO new_password
Parent topic: Security and Authority


Setting Up Security

The following is an overview of the process used to set up and activate security. This procedure must be performed by someone with super user authority.

Note: The following procedure assumes a single-server environment. If you are working in a multiserver environment or you are using a global security server, see the chapter Multiserver Security for additional setup procedures.

To set up security for an XDB Server:

  1. At the XDB Server, use the XDB Server Configuration utility to enable the server security option. See the chapter Server Configuration Utility for details.

    Note: No one else is allowed access to the server until you are finished setting up user IDs and passwords.
  2. At the XDB Server or at any client workstation attached to the XDB Server, use the client options utilities (Options Utility) to select the XDB Server, specify your super-user ID, and enable security in the Options Utility

    To set the options:

    • On the Connect tab, select the XDB Server on which you want to set up security.
    • On the Connect tab, specify your super user ID (e.g., INSTALL).
    • On the Security tab, enable the Client Security option.
    • On the Security tab, specify the Default Enforcement Level. This value determines the level of complexity that all passwords must have. See the topicPassword Enforcement Level for more information.

  3. Use SQLWizard's User command or the CREATE USER SQL syntax to create a user ID, password, and user type (user or super user) for each user of this XDB Server. Only the users that you define during this step will be allowed to log on to the Server, and they must present the proper user ID/password combination when they do so.

    Note: Apart from permitting access to an XDB Server, the user ID you create in this step also serves as a users default AuthID. You can override this default assignment by assigning a Secondary ID to the user, or the user can change it using the SET CURRENT SQLID command.
  4. A group ID allows you to assign location-level, database-level, and table-level privileges to a group of users. To set up group IDs, you can either use SQLWizard's Group command or run the following command:
     insert into sysxdb.sysacfgroups('group_name', '');

    You can also use a SecondaryID for this purpose. See the section AuthID Ownership and Usage Rules for a comparision of group IDs and SecondaryIDs.

  5. Run the SQL GRANT and REVOKE commands from an SQL utility (i.e. SQLWizard) to assign specific privileges (or pre-defined sets of privileges called authorities) to each AuthID or GroupID. Privileges and authorities are granted within each location. See the topic Granted Authorities and Privileges topic for more information.
  6. When you are finished creating users, run client options/configuration utilities at each user's workstation and turn on the Client Security option. On the Security tab, specify the Default Enforcement Level. Each client must agree with the server about the password enforcement level. See the section Password Enforcement Level for more information. You must also inform your users of their new user IDs and passwords. Once they log on, they can change their password using the SQLWizard Change Password command or run the ALTER PASSWORD SQL command.
Parent topic: Security and Authority


System Level Access Control

System-level access control refers to that part of the security system that controls the login process, passwords, the assignment of users to groups, and the definition of SecondaryIDs. These aspects of security are described in this topic.

  • Password Enforcement Level
  • XDBACF Database
  • AuthID Ownership and Usage Rules
Parent topic: Security and Authority


Password Enforcement Level

Before setting up initial passwords for users (or before users change their passwords), select a password enforcement level from the options provided on the Options Utility.

Password level options are:

Level | Options
Level 1: | Password must be four or more characters.
Level 2: | Password must be six or more characters and include at least one digit (numeric).
Level 3: | Password must be six or more characters, include at least one digit (numeric), and must include the two randomly generated characters that appear in the prompt message on the SQLWizard Add/Modify User screen. (From the SQLWizard Admin menu, select User.)

Users can change their passwords by using the SQLWizard Change Password command.

Note:

Depending on your security needs, you might wish to establish two AuthID/Password accounts on the server; one for Micro Focus locations and one for DB2 locations.

Parent topic: System Level Access Control


XDBACF Database

The system location for each XDB Server contains a database called XDBACF (Access Control Facility). This database contains information you enter for each user and group via the SQLWizard Admin menu. Information in the XDBACF database applies to all users and all locations on the server.

The XDBACF database contains the following tables and columns:

  • SYSXDB.SYSACFUSERS contains a list of all users, including the following information for each user:
    AuthID | AccessAuthority
    SecondaryID | RequirePassword
    Password | UserType
    DateOP (date of password) | Remarks
    TimeOP (time of password)
    Note:

    If you are a super user, do not edit or update a user's PASSWORD or TIMEOP in this table. Use the SQLWizard instead.

  • SYSXDB.SYSACFGROUPS contains a list of all GroupIDs that have been defined. Columns in this table are:
    GroupAuthID
    Remarks
  • SYSXDB.SYSACFMEMBERS contains a list of AuthIDs and the GroupIDs that each is authorized to use. Each user (Primary AuthID) can have several entries, one entry for each GroupID that the person is authorized to use. Columns in this table are:
    UserAuthID
    GroupAuthID
  • SYSXDB.SYSGOVERNOR contains information on the type of activities that can be performed by certain users during certain periods. Columns in this table are:
    Priority | MaxIdleTime
    MaxNumApiCalls | MaxFetches
    MaxTimeEngine | StartFreeTime
    MaxTimePerApi | EndFreeTime
  • SYSXDB.SYSUSERPRIORITY contains information about priorities that have been assigned to users.

See the SQL Reference for the specific format of each of these tables.

Parent topic: System Level Access Control


AuthID Ownership and Usage Rules

Primary AuthIDs, GroupIDs and SecondaryIDs can be used in combination when setting up system security. These IDs are defined and used as follows:

  • Primary AuthID. This is the primary identifier for all users of an XDB Server. A Primary AuthID can be assigned to a process or program that requires access to XDB Server data.
    • Used for logging in to an XDB Server.
    • Appears as an identifier on server screens that are used to monitor activity of users.
    • Used as the default for the AuthID portion of a database object's three-part name when the user creates the object. A different ID will become the default if the SET CURRENT SQLID command is issued, if a SecondaryID is defined, or if a security user exit modifies the Current SQLID. See the Security User Exit topic for information.
    • Used to determine privileges when user attempts to access a database object. If a different ID is in effect (from issuance of a SET CURRENT SQLID command), that ID's privileges are available also. If the Primary AuthID belongs to a group, the privileges granted to the GroupID also are available to the user of the Primary AuthID. If a SecondaryID is defined, the Primary AuthID's privileges are not valid, but rather the SecondaryID's privileges take effect (along with its groups, if any).
  • Group or GroupID. This is a special identifier that can be assigned to one or more Primary AuthIDs. The privileges granted to the GroupID are available to every Primary AuthID to which the GroupID is assigned. In addition, each Primary AuthID can have multiple GroupIDs assigned to it, thus gaining the privileges of all of those groups combined. Other privileges can be granted to the Primary AuthID, providing the user with the assigned group privileges plus the privileges assigned specifically to the Primary AuthID.
    Note: If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.
  • SecondaryID (optional). If defined, this AuthID replaces the Primary AuthID as soon as the user logs in to the XDB Server. The user (or process) is given the privileges that have been granted to the SecondaryID. If the Primary AuthID had privileges granted to it, those privileges would be ignored. When a user with a SecondaryID creates an object, the AuthID portion of the object's name is the SecondaryID. All other users who use the same SecondaryID will have all privileges on that object.
    Note: The XDB Server SecondaryID is not the same as the DB2 Secondary Authorization ID. The IBM method of defining multiple Secondary Authorization IDs and assigning them to Primary AuthIDs in RACF (Resource Access Control Facility) is similar to Micro Focus' group concept.
    Note: If you use an object creator's AuthID as a SecondaryID for other users, those other users will all have all privileges on the object. A user with a SecondaryID is seen by the system as being the SecondaryID, and therefore has all privileges on all objects that carry that AuthID as the second part of the object name. Privileges cannot be revoked from the creator of an object, or from a user who's Current SQLID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on the privileges of an object's creator/owner.
  • Current SQLID. The Current SQLID is a special register that keeps track of which AuthID is in effect for a given client session. A user with SYSADM or super user authority can issue the SET CURRENT SQLID command to change the SQLID to any valid AuthID. If a user has a SecondaryID, the Current SQLID changes from the Primary AuthID to the SecondaryID at the start of the client session.

The table and the descriptions following it illustrate how various GroupID and SecondaryID assignments can affect the naming of and access to database objects.

When security is on, the Primary AuthID and Password are used when each user (or process) logs in to the XDB Server. The system then checks the SYSXDB.SYSACFUSERS table for the existence of a SecondaryID. If present, the user (or process) assumes the identity of the SecondaryID and is accorded all privileges that have been defined for the SecondaryID. If no SecondaryID exists for the user, then privileges are based on what has been granted for the Primary AuthID and the groups to which it belongs.

To grant a particular set of privileges to a group of users, without having to define those privileges for each user individually, assign multiple users to the same SecondaryID. Grant the privileges to the SecondaryID (essentially just another AuthID). However, the preferred method for assigning the same privilege set to many users is to use the XDB Group, which is similar to the DB2 concept of assigning multiple secondary authorization IDs to a primary authorization in IBM's RACF (Resource Access Control Facility).

Note: If several users have the same SecondaryID, all the objects they create will be owned by the SecondaryID and not by the individual users. All users having that same SecondaryID will have all privileges on those objects. The GRANT and REVOKE commands have no effect on privileges of an object's creator/owner, which in this case includes all users with the SecondaryID that is also the AuthID portion of the object's name. All of these users are seen by the system as being the owner of the object.
Primary AuthID | Secondary ID | Group Name | Creates Table... (see note 1) | Owner | Authorized Users
TECHPUBS | -- | -- | Created as a Primary AuthID. Privileges are assigned. Used as a SecondaryID for one or more Primary AuthIDs.
-- | -- | WRITERS | Created as a group. Privileges are assigned to the group. GroupIDs are assigned to Primary AuthIDs.
ERIC | -- | -- | ERIC. TABLE1 | ERIC | ERIC
DEBBIE | -- | -- | DEBBIE TABLE1 | DEBBIE | DEBBIE
DAVID | -- | WRITERS | DAVID. TABLE1 | DAVID | DAVID and if access is granted to WRITERS, then also ARLENE.
ARLENE | -- | WRITERS | ARLENE. TABLE1 | ARLENE | ARLENE and if access is granted to WRITERS, then also DAVID.
ROCHELLE | TECHPUBS | -- | TECHPUBS. TABLE1 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and if access is granted to WRITERS, then also DAVID, ARLENE.
STEVE | TECHPUBS | -- | TECHPUBS. TABLE2 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and if access is granted to WRITERS, then also DAVID, ARLENE.
PABLO | TECHPUBS | WRITERS (ignored, see note 2) | TECHPUBS. TABLE3 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)
BRUCE | TECHPUBS | WRITERS (ignored, see note 2) | TECHPUBS. TABLE4 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)

Table Notes

  1. All scenarios described here assume that the user does not specify an AuthID when creating the object and the user has not changed his Current SQLID.
  2. Pablo and Bruce do not have privileges defined for the group writers because as soon as they log in, they both become techpubs, and techpubs is not assigned to the group writers in this example.

As shown in the above table, the AuthID portion of the name assigned to a database object when it is created, and the users who have access to that object depend on how AuthIDs, GroupIDs and SecondaryIDs are defined. The object naming and usage rules are as follows:

  1. If a user belongs to a group and creates an object, the AuthID portion of the object name will be the user's own Current SQLID, and not the GroupID. This allows more than one user to create objects of the same name within the same location.

    For example, if user david (who is in the writers group) creates a table called staff in the location called books, the table's three-part name would be books.david.staff. If user arlene (who is also assigned to the writers group) attempts to create a table called staff, in the location called books, the table's three-part name would be books.arlene.staff. Since the three-part names of the two tables are unique, each user can have a table of the same one-part name within a location.

    Note: If a user has no Secondary ID and has not otherwise changed his Current SQLID, the Current SQLID is the user's Primary AuthID.
    Note: If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.
  2. If a GRANT command gives privileges to a GroupID, all users who are members of that group will have those privileges.
  3. If a user belongs to multiple-groups, the user has all privileges that have been granted to each group.
  4. If a user has a SecondaryID and creates an object, the AuthID portion of the object name will be the SecondaryID (assuming that the user has not changed his Current SQLID, which by default takes the value of the SecondaryID). Two users with the same SecondaryID cannot create objects of the same name within a location.

    For example, if user rochelle (who has a SecondaryID of techpubs) creates a table called staff in the location called books, the table's three-part name would be books.techpubs.staff. If user steve (who also has techpubs as his SecondaryID) attempts to create a table called staff, the table's three-part name would also be books.techpubs.staff. This is not allowed.

  5. Any object whose name has a SecondaryID as the AuthID qualifier can be accessed by any user who has that same SecondaryID as his Current SQLID. GRANT and REVOKE commands have no effect on these users' access to the objects because these users are all seen by the system as being the owner of the object. All users who have the SecondaryID that is the owner of the object will have all privileges on the object.

    Users rochelle, steve, pablo, and bruce all have all privileges on techpubs.table1, techpubs.table2, techpubs.table3, and techpubs.table4. GRANT and REVOKE commands for these users and tables will have no effect.

    If an object has a different owner, then granting privileges to the SecondaryID will give those privileges to all users who have that SecondaryID as their Current SQLIDs.

  6. If a user has a SecondaryID (as his Current SQLID) and belongs to a group and creates an object, the AuthID portion of the object name will be the SecondaryID. Other users in the group do not have access to the object, because privileges on the object have not been granted to the group. The object is owned by the SecondaryID. Only users with the same SecondaryID (as their Current SQLIDs) can access the object. (However, the original user who created the object of this example can access other objects to which the group has been granted privileges.)
Parent topic: System Level Access Control


Granted Authorities and Privileges

When security is on, the user's Current SQLID must either be the owner of the object, or have specific privileges in the location where the object resides. You can grant privileges to a Primary AuthID, a GroupID or a SecondaryID. An AuthID can be granted an authority, which is a pre-defined set of privileges.

Authorities are suggestive of different levels of responsibility. These responsibilities might or might not suit your needs. See the SQL GRANT command in the SQL Reference for detailed information.

Privileges (and authorities) can be granted at the location level (SYSADM or SYSCTRL), database level (DBADM, DBCTRL or DBMAINT), or by table or column within a table. AuthIDs must be granted privileges within each location they are authorized to use. Privileges in one location do not carry over to another location.

To assign privileges to a given AuthID in two or more locations, set up groups, then assign privileges to each GroupID for one location. The groups that represent the locations for which the user is to be allowed privileges are then assigned to the user's AuthID.

To allow a user to have unlimited privileges throughout the system (all locations), grant super user privileges to the user's Primary AuthID.

Note:

Only a super user can create locations, drop locations, edit (update) system tables, and assign super user status to another user. Super user privileges can be assigned in SQLWizard or by editing the USERTYPE column in the user's record in the SYSXDB.SYSACFUSERS table.

Users cannot grant privileges to themselves and cannot revoke privileges from themselves. Likewise, GRANT and REVOKE commands have no effect on users whose AuthIDs (or SecondaryIDs or GroupIDs) are the same as the AuthID portion of an object's name.

  • The DSNDB06 Database
  • Granting and Revoking Privileges
Parent topic: Security and Authority


The DSNDB06 Database

The DSNDB06 database, which is a system catalog database provided in each location, contains the specific authorities and privileges that you define for each AuthID, SecondaryID or GroupID with the SQL GRANT and REVOKE commands. This information is stored in the following security-related tables:

  • SYSIBM.SYSDBAUTH (Database Authorization)
  • SYSIBM.SYSUSERAUTH (User Authorization)
  • SYSIBM.SYSTABAUTH (Table Authorization)
  • SYSIBM.SYSCOLAUTH (Column Authorization)

See the SQL Reference for a complete definition of each of these tables.

Parent topic: Granted Authorities and Privileges


Granting and Revoking Privileges

After you set up the AuthIDs, SecondaryIDs and groups, you can define the privileges and authority for each, using the SQL GRANT and REVOKE commands. Set up the granted privileges before or after turning on security. However, any grants you issue when security is off will not take effect until you turn security on.

Note: Warning:

Be sure you are operating in the location for which you want to define privileges. Each location has its own DSNDB06 database for maintaining authorization information. (To change locations, use the SET LOCATION TO command in interactive SQL or change your default location in the SQLWizard or Options Utility.)

The basic GRANT command formats supported by XDB Servers are shown below. The REVOKE command formats are similar.

  • Database Privileges
    GRANT privilege
    ON DATABASE database-name
    TO authid
    [ WITH GRANT OPTION ]
  • System Privileges
    GRANT privilege
    TO authid
    [ WITH GRANT OPTION ]
  • Table or View Privileges
    GRANT {ALL | privilege}
    ON TABLE table-name
    TO {PUBLIC | PUBLIC AT ALL LOCATIONS | authid}
    [WITH GRANT OPTION]
  • Column Privileges
    GRANT UPDATE(column-name)
    ON TABLE table-name
    TO {PUBLIC | PUBLIC AT ALL LOCATIONS | authid}
    [WITH GRANT OPTION]

where:

privilege | is one or more Authorities and/or privileges, separated by commas
authid | is a user's Primary AuthID, a SecondaryID or a GroupID.
UPDATE (column-name) | is one or more occurrences of this phrase separated by commas. You must enter the word UPDATE and the column name in parentheses for each column on which the update privilege is to be granted.
PUBLIC | is used to grant the privilege to all users at the current location.
PUBLIC AT ALL LOCATIONS | is used to grant the privilege to all users, including remote users who are accessing this location.

See the SQL Reference for detailed information about using these commands, including descriptions of the various privileges and authorities that are available for each.

Parent topic: Granted Authorities and Privileges


Security User Exit

The Security user exit allows you to use a security program other than the one provided by the XDB Server, such as a network security system or a custom written program.

A custom security system must be compiled into a dynamic link library. On Windows systems this dynamic link library is called XSEC41.DLL, and must be placed in the XDB directory. This security scheme is then used instead of the standard security system.

Parent topic: Security and Authority


AuthID List User Exit

AuthID list user exit allows you to retrieve AuthID, Current SQLID, group membership, and super user information from a source other than the XDB Server user database.

You must compile the AuthID List program into a dynamic link library. On Windows systems this dynamic link library is called XAUT41N.DLL, and must be placed in the XDB directory. This AuthID List is then used instead of the standard XDB Server user database.

Parent topic: Security and Authority


Server-to-server Connectivity

The server-to-server connectivity capability provided with the XDB Server allows a client accessing one XDB Server to actually access the data in a location controlled by another XDB Server in a distributed environment. Server-to-server connectivity extends the concepts of remote unit of work (RUW) and distributed unit of work (DUW) to encompass data controlled by multiple XDB Servers.Location access can be done in two ways: either by using a three-part name (location.authid.object) or alias; or by using the SET LOCATION command or embedded CONNECT command. Server-to-server connectivity removes the need to have to change the client settings to access another remote XDB Server.To allow access to a remote location, you must maintain the system tables to reflect known locations and server names.Throughout the XDB Server documentation, the term primary server is used to refer to the XDB Server to which the user is connected. The term remote server is the XDB Server elsewhere on the LAN that controls the location the user wishes to access.Whether three-part names or connect access is used, information about remote locations must be registered with the XDB Server to which you are currently connected. This is done by inserting information into tables in the system catalog. The system tables that must be updated, as well as sample entries, are listed in each section.Because the information is registered in the system catalog tables, the user does not have to know which XDB Server controls which location. You simply need to know the name of the location to be accessed.

  • Three-Part Name Access
  • Connect (Set Location) Access
Parent topic: SQL Option Server Administration Guide


Three-Part Name Access

One method of accessing data in a remote location involves using a three-part name. An application simply uses the fully qualified name (location.authid.object) of a table or view that resides in another location. Based on information in the system catalog tables on the current XDB Server, the request is sent to the appropriate XDB Server and data is returned. This configuration is also referred to as a distributed unit of work (DUW).

Multiple locations controlled by multiple XDB Servers can be queried in this way. A client application can request data from any XDB Server in the distributed environment, as long as the server and the locations it controls are registered in the system catalog tables.

An alias of a three-part name can also be used. Remember that aliases actually provide better location transparency because the first part of the three-part name need not be specified. Throughout the Server-to-Server Connectivity an alias can also be used wherever a three-part name can be used.

  • Disconnecting
  • Privileges
  • Examples
  • System Tables
  • Sample System Tables
  • Setting Up Server-to-Server Connectivity
Parent topic: Server-to-server Connectivity


Disconnecting

Generally, the connection between the primary and remote server is not broken until the client application ends the session by logging out of the primary server. If the access of the remote server was done interactively, it cannot explicitly disconnect from the remote server. If the access was done through embedded SQL, the program can use the CONNECT RESET command. See the SQL Reference for a description of the CONNECT RESET command.

Parent topic: Three-Part Name Access


Privileges

Control privileges at each individual server. Each server controls its own access security. Privileges granted at each server affect all users who connect to it, whether by logging in directly or accessing the server via a three-part name or alias. Additional access control can be had by using security mapping and global security. See the chapter Multiserver Security for a more detailed discussion of security mapping and global security.

Parent topic: Three-Part Name Access


Examples

Client1 is logged into the XDB Server xdbserve and is running the SQL Wizard. Client1 issues a SELECT command that references the table orders.eastern.may.

This request is received by the XDB Server xdbserve. The xdbserve server checks its system catalog table SYSIBM.SYSLOCATIONS. This table indicates that the location orders is controlled by the XDB Server sales.

The request is then passed on to the XDB Server sales, which processes the query. The query result is returned to xdbserve, which passes the data back to the SQL Wizard on client1.

Now consider that, in the next SQL statement issued, client1 references products.gui.productlist. Again, the same system catalog tables on xdbserve are checked.

This time, the request is sent to the XDB Server, develop.

Parent topic: Three-Part Name Access


System Tables

You must insert data into two XDB Server system tables, SYSIBM.SYSLUNAMES and SYSIBM.SYSLOCATIONS, on the primary XDB Server in order to use three-part names or aliases for server-to-server connectivity. This can be done through SQL commands in the SQL Wizard.

Note: When updating SYSLOCATIONS and SYSLUNAMES, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use server-to-server connectivity. All other columns can have NULL values. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSLOCATIONS
Parent topic: Three-Part Name Access


SYSIBM.SYSLUNAMES

The columns of this table contain information on LUNAMES used for server-to-server or XDB Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used in XDB Server.
USERNAMES | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSLOCATIONS

The columns of this table contain information about all locations that are accessible for RUW and DUW processing, including local locations in SYSXDB.SYSLOCALS plus remote locations accessible using server-to-server connectivity or XDB Link.

Name | Type | Len | Description
LOCATION required | CHAR | 16 | Name of the location.
LOCTYPE required | CHAR | 1 | Indicates the location type:
 |  |  | X | XDB
 |  |  | R | RPC
 |  |  | C | CICS
 |  |  | D | DRDA
LINKNAME required | CHAR | 8 | Name of the XDB Server which controls the location, if using server-to-server connectivity. LUNAME for the accessible system if using XDB Link.
LINKATTR required | VARCHAR | 64 | Type of protocol used to connect to the XDB Server when using server-to-server connectivity:
 |  |  | S | SPX
 |  |  | B | NetBIOS
 |  |  | N | Named Pipes
 |  |  | T | TCP/IP (Set the hostname and IP address in the XDBNET.INI file.)
 |  |  | or The name of the mainframe program with which XDB Link will communicate if using XDB Link.
Parent topic: System Tables


Sample System Tables

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server xdbserve to execute the examples for three-part name or alias access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
sales |  |  |  |  |
develop |  |  |  |  |

The first row indicates that the XDB Server sales can be accessed. The second row indicates that the XDB Server develop can be accessed.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server xdbserve to execute the examples for three-part name or alias access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
staff | X |  |
orders | X | Sales | B
products | X | Develop | N

The first row indicates that the staff location is an XDB location controlled by the current (primary) XDB Server xdbserve.

The second row indicates that the orders location is an XDB location controlled by a remote XDB Server sales and can be reached via the NetBIOS protocol.

The third row indicates that the products location is an XDB location controlled by a remote XDB Server develop and can be reached via the Named Pipes protocol.

Parent topic: Three-Part Name Access


Setting Up Server-to-Server Connectivity

In order to set up server-to-server connectivity, you must configure both the primary XDB Server and the remote XDB Server. The primary XDB Server is the XDB Server which clients will log into. From this server, they will be able to access remote XDB locations by using either three-part names or aliases. The instructions in this topic discuss one primary server with one remote server.

If you wish to have a fully distributed environment, complete the Primary Server Configuration instructions for each XDB Server that you wish to be a primary XDB Server. Complete the Remote Server Configuration instructions for each XDB Server you wish to be a remote XDB Server.

The following instructions assume that security is turned on (through the XDB Server Configuration utility) for the primary XDB Server.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Three-Part Name Access


Primary Server Configuration

To configure a server as a primary XDB Server, you must update the system tables. In the examples, the primary XDB Server is xdbserve.

To update the system tables:

Note:

Do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.

  1. On any client logged in to the primary XDB Server, start SQL Wizard.
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. Open an SQL Window and set the current location to the SYSTEM location:

    SET LOCATION TO system;

  4. Issue the following SQL command to insert information about a remote server into the SYSIBM.SYSLUNAMES table:
    INSERT INTO sysibm.syslunames
    VALUES ("remote-server","","","","","");

    where remote-server is the name of a remote XDB Server to be accessed. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on using these values.

    In the examples used in this topic, the SQL command:

    INSERT INTO sysibm.syslunames
    VALUES ("sales","","","","","");

    would have been issued on the XDB Server XDBSERVE.

  5. Issue the following SQL command to insert information about a remote location into the SYSIBM.SYSLOCATIONS table:
    INSERT INTO sysibm.syslocations
    VALUES ("remote-location","X",
            "remote-server","link-type");

    where:

    remote-location | is the name of the remote location to be accessed (unique among all locations on all servers that are used in distributed processing).
    X | indicates it is an XDB Server.
    remote-server | is the name of the remote server that controls the remote location.

    link-type is the communication protocol used to connect to the remote server.

    In the examples used in this topic, the SQL command:

    INSERT INTO sysibm.syslocations
    VALUES ("orders","X","sales","B");

    would have been issued on the XDB Server XDBSERVE.

  6. Repeat Steps 4 and 5 for each remote XDB Server and location that will be accessed from this primary server.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit SQL Wizard.
Parent topic: Setting Up Server-to-Server Connectivity


Remote Server Configuration

The remote XDB Server must be configured and started, and privileges must be granted. In the examples, the remote XDB Server is sales.

If security is on, clients must have privileges on the tables they wish to access on the remote server. Be sure to grant the appropriate privileges to each client on the remote server.

AuthIDs (usernames) are created using the SQL Wizard Admin menu. Privileges are granted using SQL GRANT command from the SQL Wizard. See the chapter Security and Authority for more information on AuthIDs and privileges.

AuthID mapping can make this task much easier in a large distributed environment. See the chapter Multiserver Security for more information about AuthID mapping.

Parent topic: Setting Up Server-to-Server Connectivity


Connect (Set Location) Access

The second method of accessing data in a remote location involves connecting to the remote XDB Server. To connect to the remote XDB Server interactively, use the SET LOCATION command (an SQL extension). To connect to the remote XDB Server with embedded SQL, use the CONNECT command.

A client interactively issues a SET LOCATION command or an application created using embedded SQL issues a CONNECT command. Based on information in the system catalog tables on the current XDB Server, the client's connection is transferred to the appropriate XDB Server and data is returned. This configuration is also referred to as a remote unit of work (RUW).

When a client is connected to a remote server while still logged in to the initial XDB Server, the system tables used for any new queries are the system tables on the remote location. Note that when connecting to a different XDB Server, you are not completely detached from previous XDB Servers. The routing software on each XDB Server is still used to determine from where the request came and to where it should go.

In this way, a client application can connect to any XDB Server in the distributed environment, as long as the Server and the locations it controls are registered in the system catalog tables.

  • Disconnecting
  • Privileges
  • Examples
  • System Tables
  • Configuring Server-to-Server Connectivity
Parent topic: Server-to-server Connectivity


Disconnecting

Note that when the client application is done with the location on the remote server, the client application can disconnect from the remote server (using the embedded SQL command CONNECT RESET). By disconnecting, all links to the remote server are removed and the connection is returned to the primary server. If multiple XDB Servers have been accessed in sequence, the connection will be returned to the XDB Server most recently controlling the client.

Note:

If SET LOCATION TO was used by any client to connect to the second server, there is no way to break the connection until the user ends the session.

Parent topic: Connect (Set Location) Access


Privileges

Control privileges at each individual server. Each server controls its own access security. Privileges granted at each server affect all users who connect to it, whether by logging in directly or accessing the server by connecting from another server. Additional access control can be had by using security mapping and global security. See the chapter Multiserver Security for a more detailed discussion of security mapping and global security.

Parent topic: Connect (Set Location) Access


Examples

All of the examples assume that each XDB Server has already been set up with the appropriate information in the system tables. If a request is made to connect to an unknown location not listed in the system tables, an X288 error message (Statement reference to remote object is invalid) is returned to the user.

Client1 is logged into the XDB Server xdbserve and is running the SQL Wizard. Client1 issues a SET LOCATION TO ORDERS command. The xdbserve server checks its system table SYSIBM.SYSLOCATIONS, which indicates that the location orders is controlled by the XDB Server sales.

The xdbserve server transfers the clients connection to the XDB Server sales. Note that each communication between client1 and the XDB Server sales must go through xdbserve (shown by the dashed lines through xdbserve).

Now, any requests that are sent by the client are verified by the system tables on the XDB Server sales. If client1 issues a SELECT query that references the table eastern.may without specifying a location, it is assumed that this table is in the location orders on the XDB Server sales.

To continue the example, client1 (who is logged in to xdbserve but connected to sales) issues a SET LOCATION TO PRODUCTS command. In this case, sales checks its system catalog table SYSIBM.SYSLOCATIONS, which indicates that the location products is controlled by the XDB Server develop.

Sales transfers the client's connection to the XDB Server develop. Any requests that are sent by the client are verified by the system catalog tables on the XDB Server develop. Communication between client1 and develop must still pass between the other XDB Servers to which it has been connected, xdbserve and sales. This communication is shown by the dashed lines through the XDB Servers.

Finally, consider that client1, connected to develop via xdbserve and sales, issues a SET LOCATION TO STAFF command. In this case, develop checks its system catalog table SYSIBM.SYSLOCATIONS, which indicates that the location staff is controlled by the XDB Server xdbserve.

This will create a communications loop back to xdbserve. This type of looping is not recommended, as the connections between the various servers creates congestion on each server. In addition, response time is increased because queries have to be passed between multiple servers.

Instead, keep track of the locations and servers you have accessed. If you are working interactively (for example, through the SQL Wizard), then log out and log back in. If you are using embedded SQL, issue CONNECT RESET commands after you no longer need the data on a particular server.

Parent topic: Connect (Set Location) Access


System Tables

You must insert data into two system tables, SYSIBM.SYSLUNAMES and SYSIBM.SYSLOCATIONS, on the primary XDB Server in order to use server-to-server connectivity via connect access. The tables on the primary server must be updated so that clients can get from the primary to the remote server.

Note: When updating SYSLOCATIONS and SYSLUNAMES, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use server-to-server connectivity. All other columns can have NULL values. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSLOCATIONS
  • Sample System Tables
Parent topic: Connect (Set Location) Access


SYSIBM.SYSLUNAMES

The columns in this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used in XDB Server.
USERNAMES | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSLOCATIONS

The columns in this table contain information about all locations that are accessible for RUW and DUW processing, including local locations in SYSXDB.SYSLOCALS plus remote locations accessible using server-to-server connectivity or XDB Link.

Name | Type | Len | Description
LOCATION required | CHAR | 16 | Name of the location.
LOCTYPE required | CHAR | 1 | Indicates the location type:
 |  |  | X | XDB
 |  |  | R | RPC
 |  |  | C | CICS
 |  |  | D | DRDA
LINKNAME required | CHAR | 8 | Name of the XDB Server which controls the location, if using server-to-server connectivity. LUNAME for the accessible system if using the XDB Link.
LINKATTR required | VARCHAR | 64 | Type of protocol used to connect to the XDB Server when using server-to-server connectivity:
 |  |  | S | SPX
 |  |  | B | NetBIOS
 |  |  | N | Named Pipes
 |  |  | T | TCP/IP (Set the hostname and IP address in the XDBNET.INI file.)
 |  |  | or The name of the mainframe program with which XDB Link will communicate if using XDB Link.
Parent topic: System Tables


Sample System Tables

The tables in this topic show the values needed in the system tables on various XDB Servers to execute the examples discussed.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server xdbserve to execute the examples discussed in this topic for connect access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
sales |  |  |  |  |

This table indicates that the XDB Server sales can be accessed from xdbserve.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server xdbserve to execute the examples discussed in this topic for connect access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
staff | X |  |
orders | X | Sales | B

The first row indicates that the staff location is an XDB Server location controlled by the current (primary) XDB Server xdbserve.

The second row indicates that the orders location is an XDB Server location controlled by a remote XDB Server sales, and can be reached via the NetBIOS protocol.

  • Sales Server
  • Develop Server
Parent topic: System Tables


Sales Server

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the XDB Server sales to execute the examples discussed in this topic for connect access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
Develop |  |  |  |  |

This table indicates that the XDB Server develop can be accessed from sales.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server sales to execute the examples discussed in this topic for connect access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
orders | X |  |
products | X | develop | N

The first row indicates that the orders location is an XDB Server location controlled by the current XDB Server sales.

The second row indicates that the products location is a location controlled by a remote XDB Server sales, and can be reached via the Named Pipes protocol.

Parent topic: Sample System Tables


Develop Server

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the XDB Server develop to execute the examples discussed in this topic for connect access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
xdbserve |  |  |  |  |
sales |  |  |  |  |

The first row indicates that the XDB Server xdbserve can be accessed from develop.

The second row indicates that the XDB Server sales can be accessed from develop.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server develop to execute the examples discussed in this topic for connect access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
staff | X | xdbserve | B
products | X |  |

The first row indicates that the staff location is a location controlled by a remote XDB Server xdbserve, and can be reached via the NetBIOS protocol.

The second row indicates that the products location is an XDB location controlled the current XDB Server, develop.

Parent topic: Sample System Tables


Configuring Server-to-Server Connectivity

In order to set up server-to-server connectivity, you must configure both the primary XDB Server and the remote XDB Server. The primary XDB Server is the XDB Server which clients will log into. From this server, they will be able to access remote locations by connecting to the remote server. The instructions in this topic discuss one primary server with one remote server.

If you wish to have a fully distributed environment, complete the Primary Server Configuration instructions for each XDB Server that you wish to be a primary XDB Server. Complete the Remote Server Configuration instructions for each XDB Server you wish to be a remote XDB Server.

The following instructions assume that security is turned on (through the XDB Server Configuration utility) for the Primary XDB Server.

  • Primary Server Configuration
  • Remote Server Configuration
  • Configuring Server Access
Parent topic: Connect (Set Location) Access


Primary Server Configuration

To configure a server as a primary XDB Server, you must update the system tables. In the examples, the primary XDB Server is xdbserve.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. On any client logged in to the primary XDB Server, start SQL Wizard.
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. From an SQL Window set the current location to the SYSTEM location:
    SET LOCATION TO system;
  4. Issue the following SQL command to insert information about a remote server into the SYSIBM.SYSLUNAMES table:
    INSERT INTO sysibm.syslunames
    VALUES ("remote-server","","","","","");

    where remote-server is the name of a remote XDB Server to be accessed. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on using these values.

    In the examples , the SQL command:

    INSERT INTO SYSIBM.SYSLUNAMES
    VALUES ("sales","","","","","");

    would have been issued on the XDB Server XDBSERVE.

  5. Issue the following SQL command to insert information about a remote location into the SYSIBM.SYSLOCATIONS table:
    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES ("remote-location","X",
            "remote-server","link-type");

    where:

    remote-location | is the name of the remote location to be accessed (unique among all locations on all servers that are used in distributed processing).
    X | indicates it is an XDB Server.
    remote-server | is the name of the remote server that controls the remote location.
    link-type | is the communication protocol used to connect to the remote server.

    In the examples used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES ("orders","X","sales","B");

    would have been issued on the XDB Server XDBSERVE.

  6. Repeat Steps 4 and 5 for each remote XDB Server and location that will be accessed from this primary server.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit SQL Wizard.
Parent topic: Configuring Server-to-Server Connectivity


Remote Server Configuration

The remote XDB Server must be configured and privileges must be granted. In the examples, the remote XDB Server is sales.

If security is on, clients must have privileges on the tables they wish to access on the remote server. Be sure to grant the appropriate privileges to each client on the remote server.

AuthIDs are created using the SQL Wizard Admin menu. Privileges are granted using the SQL GRANT command via the SQL Wizard. See the chapter Security and Authority for more information on AuthIDs and privileges.

AuthID mapping can make this task much easier in a large distributed environment. See the chapter Multiserver Security for more information about AuthID mapping.

Parent topic: Configuring Server-to-Server Connectivity


Configuring Server Access

Once you have configured the primary and remote servers, use the following procedure to configure access:

  1. From the Client Options dialog box, Connect tab, configure the following:
    Control Group | Control Name | Value
    Network Info | Server Name | A new server name
    Communication Protocol | TCP/IP
    IP Address | The remote machine name or its IP address
    TCP Port | Port to use on the remote machine (8898 is the default)
    Connect To | Locations | A unique name for the remote location, different from all local location names
  2. Click OK.
  3. Using SQL Wizard, attempt to log onto the remote server. If you are not successful, verify that your settings are correct. To do this:
    1. At a command prompt, use the Windows ping command to verify that the machine name or IP address in the IP Address field is correct and can be resolved. If this doesn't work, verify with IT that the machine name or IP address can be resolved and the destination is reachable.
    2. At a command prompt, use the Windows telnet command to verify that you can establish a connection to the server (telnet machine port). If a connection is refused:
      • Verify that the remote server is running
      • Using the IPCONFIG on the remote machine, verify that the machine name/IP Address is valid
      • Using the NETSTAT command, verify that the server is running and listening on the proper port
      • Ensure that your firewall software isn't preventing the connection
  4. From the Connect tab on the Options dialog box, set the Server Name back to your local server; then click OK.
  5. From SQL Wizard, enter the following INSERT statements to add the server location to the local servers SYSTEM location:

    INSERT INTO SYSTEM.SYSIBM.SYSLUNAMES (LUNAME) VALUES (" ServerName ");

    INSERT INTO SYSTEM.SYSIBM.SYSLOCATIONS VALUES (" LocationName ","X", " ServerName ","T");

    where ServerName is the server name you specified in step 1, and LocationName is the name of the remote location you specified in step 1.

  6. Shut down and restart the local server to ensure that the local server picks up the new location.
  7. Start SQLWizard on the local machine.

The new location should now appear on the list of locations in the Catalog Browser. The remote location should be accessible through the SQLWizard Catalog Browser and available for any program or utility connecting to the local server.

Parent topic: Configuring Server-to-Server Connectivity


Multiserver Security

In a distributed environment with server-to-server connectivity, there will generally be more than two servers and a large number of users. There can be duplicate AuthIDs on different servers, such as a Bob in development and a Bob in sales.

Different servers can have different levels of privileges and table access. For example, on the XDB Server develop all users might be allowed access to all tables in the products location. On the XDB Server sales, access to the orders location might be restricted to a particular group or AuthID.

The XDB Server provides several methods of security and administration control. Outbound mapping allows you to translate an AuthID (username) and password before a request is sent to a remote XDB Server, providing another method of controlling communications with other XDB Servers. Inbound mapping translates an AuthID on a remote server after login, providing another method of controlling access on an XDB Server.

Trusting allows you to bypass verifying a name and password with the system catalog tables on the remote server, eliminating one step in the login and verification process. Global security allows you to set up one server to handle all security, eliminating redundancy and reducing the possibility of erroneous entries in the system catalog tables.

In a distributed environment with multiple administrators, users and servers, cooperation among administrators is imperative. Coordination can eliminate duplicate location names and AuthIDs. Rejected logins and lack of privileges can also be avoided.

Throughout this documentation, the term primary server is used to refer to the XDB Server to which the user is connected. The term remote server is the XDB Server elsewhere on the LAN that controls the location the user wishes to access.

Note:

Be sure to read this Multiserver Security topic carefully before attempting to map AuthIDs or passwords. When using multiple servers, mappings and trusting, it is very easy to miss one step and confuse everything.

  • Outbound Mapping
  • Inbound Mapping
  • Trusting
  • Global Security
  • Outbound, Inbound and Trusting Used Together
Parent topic: SQL Option Server Administration Guide


Outbound Mapping

Outbound mapping allows you to translate an AuthID and passwords before a request is sent to a remote XDB Server. A request can be sent that either references a remote location controlled by another XDB Server (using a three-part name) or the remote XDB Server itself (using CONNECT). The values in the system catalog table SYSIBM.SYSLUNAMES indicate that requests going to the remote XDB Server should be translated. Based on the values in SYSIBM.SYSUSERNAMES, the AuthID is mapped and the request is sent to the remote server as if it came from the newly mapped AuthID.

Mapping AuthIDs before they leave an XDB Server can be useful when a particular remote XDB Server is configured to accept requests from only one or two AuthIDs. This allows you to translate all AuthIDs going to that XDB Server into valid AuthIDs for a remote XDB Server. Outbound mapping can also be used to eliminate duplicate AuthIDs at different XDB Servers. Any potential duplicate AuthID (or all AuthIDs) can be mapped to different AuthIDs before requests are sent to remote XDB Servers.

While remote XDB Servers can be configured to allow all users access from your XDB Server, outbound mapping keeps the administration tasks on one XDB Server. In a distributed environment with many XDB Servers, it can quickly become confusing to have to track the current valid AuthIDs for all other XDB Servers in order to maintain your own system tables. Outbound mapping allows you to control how queries appear when leaving a particular XDB Server.

  • Privileges
  • Examples
  • System Tables
  • Sample System Tables
  • Setting up Outbound Mapping
Parent topic: Multiserver Security


Privileges

Control privileges at each individual server. Each server controls its own access security. When using outbound mapping, make sure that the new AuthID given is a valid AuthID at the remote XDB Server to which the request is being sent. The new AuthID must be a valid AuthID, created by the SQL Wizard Admin menu and listed in the SYSXDB.SYSACFUSERS table. If inbound mapping is not being used on the remote XDB Server, the AuthID sent must also have the appropriate privileges to access data.

Parent topic: Outbound Mapping


Examples

Bob is logged in to the XDB Server develop. He issues a SELECT command referencing orders.eastern.may. This request is received by the XDB Server develop. Develop determines that the orders location is controlled by the XDB Server sales. Develop checks its system catalog table SYSIBM.SYSLUNAMES, which indicates that any request going to sales is subject to outbound mapping.

Develop then checks the system table SYSIBM.SYSUSERNAMES, which indicates the AuthID of Bob should be translated to devbob for all requests to the XDB Server sales. The SELECT request referencing ORDERS.EASTERN.MAY is sent to sales with an AuthID of devbob.

The SELECT request is then received at the XDB Server sales. If inbound mapping is not being used, sales verifies that the AuthID devbob is a valid AuthID in the SYSXDB.SYSACFUSERS table. The SELECT query is processed, privileges are checked and a result is returned to Bob via the XDB Server develop.

As another example, consider that any user accessing develop issues a request referencing data on the XDB Server sales. According to the system table SYSIBM.SYSUSERNAMES on develop, the AuthID on all outbound requests to sales are mapped to developr.

In this case, the system administrator of the XDB Server sales needs to maintain only one account, developr, for users from the XDB Server develop. As users are added and removed from develop, the system administrator of sales does not need to modify accounts or system tables to reflect these changes. No matter what the AuthID on develop, it will be mapped to developr before it is sent to sales.

Parent topic: Outbound Mapping


System Tables

Outbound mapping requires you to update the SYSIBM.SYSLUNAMES and SYSIBM.SYSUSERNAMES tables with information for mapping users on the primary XDB Server that will be performing outbound mapping. This can be done through the SQL Wizard.

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use outbound mapping. All other columns can have NULL values. Other columns in SYSIBM.SYSLUNAMES are used for trusting. See the section Trusting for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSUSERNAMES
Parent topic: Outbound Mapping


SYSIBM.SYSLUNAMES

The columns in this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used.
USERNAMES required | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSUSERNAMES

The columns in the following table contain information used by the XDB Server for processing requests to other XDB Servers using server-to-server connectivity or to DB2 locations through XDB Link.

Name | Type | Len | Description
TYPE required | CHAR | 1 | Indicates how the row is to be used:
 |  |  | I | For inbound IDs.
 |  |  | O | For outbound IDs.
AUTHID required | CHAR | 8 | An authorization ID that is allowed and perhaps translated. If blank, any AuthID with the corresponding LUNAME is translated in the same manner.
LUNAME required | CHAR | 8 | The name of the XDB Server, if using server-to-server connectivity, or LUNAME, if using XDB Link, for which the AuthID is to be translated. If blank, the corresponding AuthID is translated the same for all XDB Servers.
NEWAUTHID required | CHAR | 8 | The translated value of the AuthID. If blank, the translated AuthID and password are the same as the original AuthID.
PASSWORD required | CHAR | 8 | Password for an outbound request.
Parent topic: System Tables


Sample System Tables

The following table shows values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server, develop, to implement the examples discussed in this topic for outbound mapping (without trusting).

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
sales |  |  |  |  | O

This table indicates that all requests sent to the XDB Server sales are subject to outbound mapping.

The following table shows the values needed in the system table SYSIBM. SYSUSERNAMES on the XDB Server develop to implement the outbound mapping examples used in this topic. This table also shows several other valid records, explained after the table. Please note that the NO. column is not actually part of the table, and is only displayed for reference.

NO. | TYPE | AUTHID | LUNAME | NEWAUTHID | PASSWORD
1 | O | bob | sales | devbob | devbpass
2 | O | debbie | sales | developr | devpass
3 | O | bruce | sales | developr | devpass
4 | O | eric | sales |  | devepass
5 | O | david |  | devdavid | devdpass
6 | O | arlene |  |  | arlpass
7 | O |  | sales | developr | devpass

Row 1 maps Bob to devbob for all requests sent to sales. This is the configuration used in the examples on outbound mapping.

Rows 2 and 3 map Debbie and Bruce to developr for all requests sent to sales. Here, developr is assumed to be a group of people.

Row 4 does not map Eric when sending requests to sales. Eric is assumed to be an AuthID on SALES. If Eric tried to go to SALES, the Row 4 mapping would take precedence over the Row 7 mapping because it mentions a specific AuthID.

Row 5 maps David to devdavid anytime outbound requests are sent to any server.

Row 6 does not map Arlene when sending request to any remote servers. Arlene is assumed to be an AuthID on all other servers.

Row 7 maps all AuthIDs to developr when sending requests to sales. The mappings of rows 1 through 6 take precedence over Row 7 mapping because they mention specific AuthIDs.

Parent topic: Outbound Mapping


Setting up Outbound Mapping

In order to use outbound mapping, you must update system tables on the primary XDB Server which will perform the outbound mapping. On the remote XDB Server, you must set up the appropriate AuthIDs, mappings and privileges.

The instructions in each topic discuss outbound mapping on one XDB Server. If you wish to have a fully distributed environment, complete the Primary Server instructions on each XDB Server that will perform outbound mapping. Complete the Remote Server instructions on each XDB Server which will accept mapped AuthIDs.

All of the following instructions assume that security is turned on (through the XDB Server Configuration Utility) for both the Primary and Remote XDB Servers.

The instructions in this topic are written as if you have already set up server-to-server connectivity before setting up outbound mapping. These instructions also assume you will not be setting up inbound mapping on the remote server.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Outbound Mapping


Primary Server Configuration

These steps must be performed on the XDB Server that will be performing outbound mapping. In the examples, the XDB Server develop is performing outbound mapping.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. On any client logged in to the primary XDB Server, start SQL Wizard.
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. From an SQL Window, set the current location to the system location:
    SET LOCATION TO system;
  4. Issue the following SQL command to update information in the SYSIBM.SYSLUNAMES table about server-to-server connectivity and outbound mapping.
    UPDATE sysibm.syslunames SET username = "O"
    WHERE luname = "remote-server";

    where:

    O | indicates that requests going to the remote XDB Server will be subject to outbound mapping.
    remote-server | is the name of a remote XDB Server for which AuthIDs will be mapped.

    Other columns in the SYSIBM.SYSLUNAMES table are used for trusting servers. See the section Trusting for more information on using these values.

    In the examples on outbound mapping used in this topic, the SQL command:

    UPDATE sysibm.syslunames SET username = "O"
    WHERE luname = "sales";

    would have been issued on the XDB Server develop.

  5. Issue the following SQL command to insert information into the SYSIBM.SYSUSERNAMES table about AuthIDs that will be subject to outbound mapping.
    INSERT INTO SYSIBM.SYSUSERNAMES
    VALUES("O","authid","servername",
           "newauthid","password");

    where:

    O | indicates outbound mapping will be performed.
    authid | is the name of the AuthID to be translated from.
    servername | is the name of the server for which this AuthID will be translated.
    newauthid | is the new AuthID that will be given.
    password | is the password to be used with the new AuthID. Enter the password as regular ASCII text. It will be encrypted by the engine before being stored. Subsequent displays of PASSWORD column data show the encrypted password.

    In the examples on outbound mapping used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSUSERNAMES
    VALUES("O","bob","sales", "devbob","devbpass");

    would have been issued on the XDB Server develop.

  6. Repeat Step 4 for each Server for which outbound requests will be mapped. Repeat Step 5 for each AuthID that will be subject to outbound mapping.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit SQL Wizard.
Parent topic: Setting up Outbound Mapping


Remote Server Configuration

The remote XDB Server that will receive the translated ID must be configured to accept the new AuthID and database privileges must be given. In the examples, the remote XDB Server is sales.

Make sure the translated AuthID is a valid AuthID in SYSXDB.SYSACFUSERS. Use the SQL Wizard to add users. In the examples used earlier, the AuthID of devbob would have to be a valid AuthID on the XDB Server sales.

If inbound mapping will not be used on the remote server, grant the appropriate privileges to the translated AuthID using the SQL GRANT command. In the examples used earlier, the AuthID of devbob would have to be given privileges on the XDB Server sales.

If inbound mapping will be used, make sure there is a record in the SYSIBM.SYSLUNAMES on the remote server that references the server from which the request comes. Also, make sure there is a record in SYSIBM.SYSUSERNAMES on the remote server that references the translated AuthID. See the section Outbound, Inbound and Trusting Used Together for more information.

Parent topic: Setting up Outbound Mapping


Inbound Mapping

Inbound mapping means that an AuthID (username) is mapped to a different value after logging in at an XDB Server. A request is received at either the remote server that references a location controlled by the remote server (using three-part names) or the server itself (using CONNECT).

The values in the SYSIBM.SYSLUNAME table indicate that requests coming from the primary XDB Server should be translated. If a password is present, the AuthID and password are checked against SYSXDB.SYSACFUSERS. See the section Trusting for more about password checking. Then, the SYSIBM.SYSUSERNAMES table is checked and the AuthID is mapped. Finally, the request is processed with the AuthID obtained by inbound mapping.

Mapping AuthIDs on an XDB Server that will accept requests from other XDB Servers allows you to have more control over which AuthIDs have access. If inbound mapping is not used, you must update the SYSXDB.SYSACFUSERS table with all AuthIDs that will have access. These users must also be given the appropriate privileges. In a distributed environment, this can mean keeping track of hundreds of individual AuthIDs. You can map incoming AuthIDs into a manageable number of AuthIDs. Then only the mapped AuthIDs must be given privileges to access data objects.

  • Privileges
  • Examples
  • System Tables
  • Sample System Tables
  • Setting Up Inbound Mapping
Parent topic: Multiserver Security


Privileges

Control privileges at each individual server. Each server controls its own access security. When using inbound mapping, make sure that the new AuthID has the appropriate privileges to access data.

Parent topic: Inbound Mapping


Examples

Debbie is logged in to the XDB Server develop. She issues a SELECT command referencing orders.eastern.may. This request is received by the XDB Server develop. Based on the system tables on develop, outbound mapping might occur. Assuming that outbound mapping does not occur, the SELECT request referencing orders.eastern.may is sent to sales with an AuthID of debbie.

The SELECT request is then received at the XDB Server sales. After the presence of a password is checked (see the section Trusting), the SYSIBM.SYSLUNAMES table is checked and indicates requests from the Server develop are subject to inbound mapping. The AuthID of debbie and the accompanying password are checked against the SYSXDB.SYSACFUSERS table.

Next, the values in SYSIBM.SYSUSERNAMES indicate that any request from the XDB Server develop should be mapped to an AuthID of developr. Finally, the SELECT command referencing orders.eastern.may is processed with an AuthID of developr. Privileges are checked and a result is returned to debbie via the XDB Server develop.

Parent topic: Inbound Mapping


System Tables

Inbound mapping requires you to update the SYSIBM.SYSLUNAMES and SYSIBM.SYSUSERNAMES tables with information for mapping users on the remote XDB Server that will be performing inbound mapping. This can be done through SQL commands in the SQL Wizard.

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use inbound mapping. All other columns can have NULL values. Other columns in SYSIBM.SYSLUNAMES are used for trusting. See the section Trusting for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSUSERNAMES
Parent topic: Inbound Mapping


SYSIBM.SYSLUNAMES

The columns of this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used.
USERNAMES required | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSUSERNAMES

The columns in this table contain user information used by the XDB server for processing requests to other XDB Servers using server-to-server connectivity or to DB2 locations through XDB Link.

Name | Type | Len | Description
TYPE required | CHAR | 1 | Indicates how the row is to be used:
 |  |  | I | For inbound IDs.
 |  |  | O | For outbound IDs.
AUTHID required | CHAR | 8 | An authorization ID that is allowed and perhaps translated. If blank, any AuthID with the corresponding LUNAME is translated in the same manner.
LUNAME required | CHAR | 8 | The name of the XDB Server, if using server-to-server connectivity, or LUNAME, if using XDB Link, for which the AuthID is to be translated. If blank, the corresponding AuthID is translated the same for all XDB Servers.
NEWAUTHID required | CHAR | 8 | The translated value of the AuthID. If blank, the translated AuthID and password are the same as the original AuthID.
PASSWORD | CHAR | 8 | Password for an outbound request.
Parent topic: System Tables


Sample System Tables

The following table shows values needed in the system table SYSIBM.SYSLUNAMES on the remote XDB Server sales to implement the examples discussed in this topic for inbound mapping (without trusting).

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
develop |  |  |  |  | I

This table indicates that all requests received from the XDB Server develop are subject to inbound mapping.

The following table shows the values needed in the system table SYSIBM. SYSUSERNAMES on the XDB Server sales to implement the inbound mapping examples used in this topic. This table also shows several other valid records, explained after the table. Please note that the NO. column is not actually part of the table, and is only displayed for reference.

NO. | TYPE | AUTHID | LUNAME | NEWAUTHID | PASSWORD
1 | i | debbie | develop | developr |
2 | i | arlene | develop | nora |
3 | i |  | develop | developr |
4 | i | harold |  | harry |

Row 1 maps Debbie to developr for all requests received from the XDB Server develop. This is the configuration used in the examples on inbound mapping.

Row 2 maps arlene to nora for all requests from the XDB Server develop.

Row 3 maps any AuthID to developr for request received from the XDB Server develop.

Row 4 maps harold to harry for requests received from any XDB Server.

In this example, rows 1, 2 and 4 take precedence over row 3 because they mention specific AuthIDs.

Parent topic: Inbound Mapping


Setting Up Inbound Mapping

In order to use inbound mapping, you must update system tables and privileges on each remote XDB Server that will perform the inbound mapping. If server trusting is not being used, nothing needs to be done on the servers sending requests.

The instructions in each topic discuss inbound mapping on one XDB Server. If you wish to have a fully distributed environment, complete the Remote Server instructions on each XDB Server that will perform inbound mapping.

All of the following instructions assume that security is turned on (through the XDB Server Configuration Utility) for both the primary and remote XDB Servers.

The instructions in this topic assume you have already setup server-to-server connectivity before setting up inbound mapping. These instructions also assume you will not be setting up outbound mapping on the primary server.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Inbound Mapping


Primary Server Configuration

On the primary XDB Server, simply setup server-to-server connectivity so that requests can reach the remote server. No additional configuration is needed on the primary XDB Server to use inbound mapping. However, if you wish to use inbound and outbound mapping together, consult the topic on Outbound, Inbound and Trusting Used Together for more information.

Parent topic: Setting Up Inbound Mapping


Remote Server Configuration

These steps must be performed on the XDB Server that will be performing inbound mapping. In the examples, the XDB Server sales is performing inbound mapping.

To update the system tables:

Note:

When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.

  1. On any client logged in to the remote XDB Server, start the SQL Wizard.
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  4. Issue the following SQL command to update information in the SYSIBM.SYSLUNAMES table about server-to-server connectivity and inbound mapping.
    UPDATE sysibm.syslunames SET username = "I"
    WHERE luname = "servername";

    where:

    I | indicates inbound mapping will be performed.
    servername | is the name of another XDB Server from which AuthIDs will be mapped.

    Other columns in the SYSIBM.SYSLUNAMES table are used for trusting servers.

    In the examples on inbound mapping used in this topic, the SQL command:

    UPDATE sysibm.syslunames SET username = "I"
    WHERE luname = "develop";

    would have been issued on the XDB Server SALES.

  5. Issue the following SQL command to insert information into the SYSIBM.SYSUSERNAMES table about AuthIDs that will be subject to inbound mapping.
    INSERT INTO SYSIBM.SYSUSERNAMES
    VALUES("I","authid","servername",
           "newauthid","");

    where:

    I | indicates inbound mapping will be performed.
    authid | is the name of the AuthID to be translated from.
    servername | is the name of the server from which the AuthID to be translated will originate.
    newauthid | is the new AuthID that will be given.

    In the examples on inbound mapping used in this topic, the SQL command:

    INSERT INTO sysibm.sysusernames
    VALUES("I","debbie","develop","developr","");

    would have been issued on the XDB Server sales.

  6. Repeat Step 4 for each server from which inbound requests will be mapped. Repeat Step 5 for each AuthID that will be subject to inbound mapping.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit the SQL Wizard.

Use the SQL GRANT command to grant the appropriate privileges to the new AuthIDs. In the examples on inbound mapping in this topic, the AuthID developr would have to be granted SELECT privileges on the table MAY in the location orders.

Parent topic: Setting Up Inbound Mapping


Trusting

Without trusting, any time a login request is received by an XDB Server, the AuthID and password must be verified. Trusting (available only in conjunction with inbound mapping) allows an XDB Server to bypass verifying the password with SYSXDB.SYSACFUSERS each time a request is received via server-to-server connectivity. The remote server receives a request that references either a location controlled by the remote server (using three-part names) or the server itself (using CONNECT). If no password is sent to the remote XDB Server, SYSIBM.SYSLUNAMES is checked to ensure that the request from the primary server is already verified and a password is not needed.

The SYSIBM.SYSLUNAMES table is also checked to determine if inbound mapping is being used. If inbound mapping is being used the presence of a password is again checked. If a password was sent, the AuthID and password are verified with SYSXDB.SYSACFUSERS. If no password is included, then the AuthID is not verified because the information from that primary server can be trusted. Then, SYSIBM.SYSUSERNAMES is checked and the AuthID is mapped. Finally, privileges are checked and the query is processed.

If inbound mapping is not being used, the AuthID and password are verified with SYSXDB.SYSACFUSERS. Privileges are then checked and the query is processed.

Trusting can only been performed in conjunction with inbound mapping on a remote server. The remote server will be changing any AuthIDs received from a particular server. The AuthIDs to be mapped can be maintained in SYSXDB.SYSUSERNAMES.

  • Example
  • System Tables
  • Sample System Tables
  • Setting Up Trusting
Parent topic: Multiserver Security


Example

Bruce is logged in to the XDB Server develop. He issues a SELECT command referencing orders.eastern.may. This request is received by the XDB Server develop. Based on the system tables on develop, outbound mapping might occur. Assuming that outbound mapping does not occur, the SELECT request referencing orders.eastern.may is sent to sales with an AuthID of bruce and no password.

The SELECT request is then received at the XDB Server sales with an AuthID of bruce and no password. Since no password is present, SYSIBM.SYSLUNAMES is checked on sales. The values in this table indicate that all requests coming from the XDB Server develop are to be trusted. The values in SYSIBM.SYSLUNAMES also indicate that requests from the XDB Server develop are subject to inbound mapping.

Since no password accompanied the request, SYSIBM.SYSUSERNAMES is checked next. The values in this table indicate that any request from the XDB Server develop should be mapped to an AuthID of developr. Finally, the SELECT command referencing orders.eastern.may is processed with an AuthID of developr. Privileges are checked and a result is returned to bruce via the XDB Server develop.

Parent topic: Trusting


System Tables

Trusting requires you to update the SYSIBM.SYSLUNAMES table on the remote XDB Server that will be receiving requests. Updates can be performed using the SQL Wizard.

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use trusting.

  • SYSIBM.SYSLUNAMES
Parent topic: Trusting


SYSIBM.SYSLUNAMES

The columns in this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY required | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used.
USERNAMES required | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


Sample System Tables

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the remote XDB Server sales to implement the trusting examples (without outbound mapping) used in this topic.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
develop |  | A |  |  | I

This table shows that sales should regard all requests from the XDB Server develop as coming from users who are already verified.

The values needed in the system table SYSIBM.SYSUSERNAMES to implement trusting are the same as those required for inbound mapping. The following table shows the values needed to implement the trusting example used in this topic. This table also shows other valid records for trusting, explained after the table.

TYPE | AUTHID | LUNAME | NEWAUTHID | PASSWORD
I | bruce | develop | developr |
I | david | develop |  |
I |  | develop |  |
I | arlene |  |  |

Row 1 maps bruce to developr for all requests received from the XDB Server develop. This is the configuration used in the examples on trusting.

Row 2 does not map david when requests are received from develop.

Row 3 does not map any AuthIDs from develop.

Row 4 does not map arlene when requests are received from any XDB Server.

In this example, rows 1, 2 and 4 take precedence over row 3 because they mention specific AuthIDs.

Parent topic: Trusting


Setting Up Trusting

In order to use trusting you must update system tables on the remote server which will trust the requests. On the remote XDB Server, you must also set up the appropriate AuthIDs, mappings and privileges.

The instructions in each topic discuss trusting between two XDB Servers. If you wish to have a fully distributed environment, complete the primary XDB Server instructions on each XDB Server from which request will be trusted. Complete the remote XDB Server instructions on each XDB Server which will trust requests.

All of the following instructions assume that security is turned on (through the XDB Server Configuration Utility) for both the primary and remote XDB Servers.

The instructions in this topic are written as if you have already set up server-to-server connectivity and inbound mapping before setting up trusting, and are not using outbound mapping.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Trusting


Primary Server Configuration

On the primary XDB Server, set up server-to-server connectivity so that requests can reach the remote server. No additional configuration on the primary XDB server is needed to use trusting. To use trusting in conjunction with outbound mapping, see the section Outbound, Inbound and Trusting Used Together for more information.

Parent topic: Setting Up Trusting


Remote Server Configuration

You must perform these steps on the XDB Server that will trust requests and perform inbound mapping. In the examples, the XDB Server sales is trusting and performing inbound mapping.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. On any client logged in to the remote XDB Server, start the SQL Wizard.
  2. Once inside the XDB Server Configuration Utility, press F5 to access the Multiuser Configuration screen.
  3. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  4. Issue the following SQL command to update information in the SYSIBM.SYSLUNAMES table about server-to-server connectivity and inbound mapping and trusting.
    UPDATE sysibm.syslunames SET usersecurity = "A"
    WHERE luname = "servername" AND usernames = "I";

    where:

    A | indicates that requests from the XDB Server should be trusted.
    servername | is the name of another XDB Server from which AuthIDs will be mapped.
    I | indicates inbound mapping will be performed.

    In the examples on inbound mapping used in this topic, the SQL command:

    UPDATE sysibm.syslunames SET usersecurity = "A"
    WHERE luname = "develop" AND usernames = "I";

    would have been issued on the XDB Server sales.

  5. Issue the following SQL command to insert information into the SYSIBM.SYSUSERNAMES table about AuthIDs that will be subject to inbound mapping.
    INSERT INTO sysibm.sysusernames
    VALUES("I","authid","servername",
           "newauthid","");

    where:

    I | indicates inbound mapping will be performed.
    authid | is the name of the AuthID to be translated from.
    servername | is the name of the server from which the AuthID to be translated will originate.
    newauthid | is the new AuthID that will be given.

    In the examples on inbound mapping used in this topic, the SQL command:

    INSERT INTO sysibm.sysusernames
    VALUES("I","bruce","develop","developr","");

    would have been issued on the XDB Server sales.

  6. Repeat Step 4 for each server that will be subject to inbound mapping. Repeat Step 5 for each AuthID that will be subject to inbound mapping.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit the SQL Wizard.

Use the SQL GRANT command to grant the appropriate privileges to the new AuthIDs. In the examples on inbound mapping and trusting used in this topic, the AuthID developr would have to be granted SELECT privileges on the table may in the location orders.

Parent topic: Setting Up Trusting


Global Security

The XDB Server allows you to set up one location that will validate access security for all XDB Servers on a LAN. This eliminates duplicate AuthIDs and passwords in a distributed environment.

Using global security, each XDB Server in a distributed environment is configured to point to one location as the security server. This is done through the XDB Server Configuration Utility and by inserting values into the system catalog tables on each XDB Server.

Whenever a user attempts to login to any XDB Server using global security, the AuthID and password are passed to the global security location for verification. Global security extends server-to-server connectivity by allowing all XDB servers to use just one location for verifying passwords.

Note that a user must have a valid AuthID on each XDB Server in SYSXDB.SYSACFUSERS, with valid access to data, on every XDB Server that will be accessed. Global security only verifies AuthIDs and passwords.

The information in the global security system catalog tables can also be used to map AuthIDs and passwords. Be particularly careful when setting up this sort of scheme.

Multiple global security locations can be set up in a distributed environment. This allows you to have multiple security schemes for different XDB Servers. It also allows you to set up a redundant global security system to be used in case of hardware failure on your original global security server.

  • Example
  • System Tables
  • Setting Up Global Security
Parent topic: Multiserver Security


Example

The user Bob tries to login to the XDB Server develop, as shown in the following figure. Develop checks the server configuration settings (in SRVCONFG.XDB) and determines that it is using global security, and that the global security location is on the XDB Server XDBSERVE. The AuthID and password are sent to xdbserve for verification.

On XDBSERVE, the AuthID and password are verified against SYSXDB.SYSACFUSERS in the global security location. Verification is then returned from the XDB Server XDBSERVE and Bob is logged in to develop. Secondary IDs and privileges are then assigned.

Parent topic: Global Security


System Tables

You must insert data into two XDB system tables, SYSIBM.SYSLUNAMES and SYSIBM.SYSLOCATIONS on the primary XDB Server in order to use global security. The only system tables that must be modified on the global security server are modified by using the SQL Wizard. Updates can be made to the tables on the primary XDB Server using the SQL Wizard.

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use global security.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSLOCATIONS
  • Sample System Tables
Parent topic: Global Security


SYSIBM.SYSLOCATIONS

The columns in this table contain information about all locations that are accessible for RUW and DUW processing, including local locations in SYSXDB.SYSLOCALS plus remote locations accessible using server-to-server connectivity or XDB Link.

Name | Type | Len | Description
LOCATION required | CHAR | 16 | Name of the location.
LOCTYPE required | CHAR | 1 | Indicates the location type:
 |  |  | X | XDB
 |  |  | R | RPC
 |  |  | C | CICS
 |  |  | D | DRDA
LINKNAME required | CHAR | 8 | Name of the XDB Server which controls the location, if using server-to-server connectivity. LUNAME for the accessible system if using XDB Link.
LINKATTR required | VARCHAR | 64 | Type of protocol used to connect to the XDB Server when using server-to-server connectivity:
 |  |  | S | SPX
 |  |  | B | NetBIOS
 |  |  | N | Named Pipes
 |  |  | T | TCP/IP (Set the hostname and IP address in the XDBNET.INI file.)
 |  |  | or The name of the mainframe program with which XDB Link will communicate if using XDB Link.
Parent topic: System Tables


Sample System Tables

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server develop to implement the examples discussed in this topic for global security.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
xdbserve |  |  |  |  |

This table indicates that the XDB Server xdbserve can be accessed.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server develop to implement the examples discussed above for global security.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
sysglobal | X | xdbserve | B

This table indicates that the sysglobal location is an XDB location controlled by a remote XDB Server xdbserve and can be reached via the NetBIOS protocol.

Parent topic: System Tables


Setting Up Global Security

In order to set up global security, you must configure both the primary XDB Server and the global security XDB Server. The primary XDB Server is the XDB Server which clients will log into. The global security server will verify AuthIDs and passwords. The instructions in this topic discuss one primary server and one global security server.

If you wish to have a fully distributed environment, complete the Primary Server Configuration instructions (page 8-37) for each XDB Server that you wish to be a primary XDB Server. Complete the Global Security Configuration instructions (page 8-41) for each XDB Server you wish to be a global security XDB Server.

Note: We strongly recommend that you plan your global security scheme before implementing it, especially if you will be allowing outbound mapping, inbound mapping and trusting between servers using global security. Be sure to consider items that are assigned on a per server basis (groups and governor privileges) and those that are assigned on a per location basis (database and table privileges).

Because global security is an extension of server-to-server security, you must register the global security server and location as you would any other server or location. If you have already configured other locations on your global security server, you might need to update values in the system tables rather than insert new ones. See the chapter Server-to-Server Connectivity for detailed instructions.

  • Primary Server Configuration
  • Global Security Server Configuration
Parent topic: Global Security


Primary Server Configuration

To configure the primary server for global security, you must update the system tables before you configure the server. You must follow these procedures in the order in which they appear because you cannot configure the primary server to use a global security location that it cannot access.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. From the primary XDB Server, start the XDB Server.
  2. On any client logged in to the primary XDB Server, start SQL Wizard.
  3. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  4. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  5. Issue the following SQL command to insert information about a remote server into the SYSIBM.SYSLUNAMES table:
    INSERT INTO sysibm.syslunames
    VALUES ("remote-server","","","","","");

    where

    remote-server is the name of a remote XDB Server to be accessed.
    Note:

    If you have already set up server-to-server connectivity for the global security server, use the UPDATE command to update existing records in the SYSIBM.SYSLUNAMES table.

    In the examples used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSLUNAMES
    VALUES ("xdbserve","","","","","");

    would have been issued on the XDB Server develop.

  6. Issue the following SQL command to insert information about the global security location into the SYSIBM.SYSLOCATIONS table:
    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES (remote-location,"X", remote-server,link-type);

    where:

    remote-location | is the name of the remote location to be accessed (unique among all locations on all servers that are used in distributed processing).
    X | indicates it is an XDB Server.
    remote-server | is the name of the remote server that controls the remote location.
    link-type | is the communication protocol used to connect to the remote server.

    In the examples used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES ("sysglobal","X","xdbserve","B");

    would have been issued on the XDB Server develop.

  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit from SQL Wizard.
  9. Shut down the primary XDB Server, as you need to make some changes to the server's configuration.

To configure the server:

  1. From the primary XDB Server, run the XDB Server Configuration Utility.
  2. Press F5 to access Multiuser Configuration options.
  3. Press F9 to turn on Global Security.
  4. Enter the name of the global security location. All logins to the XDB Server will be verified against the SYSXDB.SYSACFUSERS table in the location you specify. In the examples in this topic, the global security location is sysglobal.
  5. Press Enter to save the new location. Then, exit the utility.

Windows 2000

  1. From the primary XDB Server, run the XDB Server Configuration Utility.
  2. Click the Multiuser tab.
  3. Mark the Global Security checkbox.
  4. Enter the name of the global security location. All logins to the XDB Server will be verified against the SYSXDB.SYSACFUSERS table in the location you specify. In the examples in this topic, the global security location is sysglobal.
  5. Click OK.

Even though AuthIDs (usernames) and passwords are verified by a global security server, clients must have access to the tables they wish to use on the primary server. This can be done by granting the appropriate privileges to each client on the primary server. AuthIDs are created using SQL Wizard. Privileges are granted using the SQL GRANT command from SQL Wizard. See the chapter Security and Authority for more information on creating users and setting privileges.

Parent topic: Setting Up Global Security


Global Security Server Configuration

The global security server must be configured to contain information about all of the AuthIDs and passwords that it will verify. In the examples, the global security XDB Server is xdbserve.

Before using global security, you must first create a global security location on the global security server. This process involves renaming your SYSTEM location with the name of your global security location. In the examples, the global security location is sysglobal.

To create a global security location:

  1. From the primary XDB Server, start the XDB Server.
  2. On any client logged in to the primary XDB Server, start the SQL Wizard.
  3. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  4. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  5. Issue the following SQL command to update the information about the global security location in the SYSIBM.SYSLOCATIONS table:
    UPDATE sysibm.syslocations
    SET location = "global-security-location"
      WHERE location = "system";

    In the examples used in this topic, the SQL command:

    UPDATE sysibm.syslocations
    SET location = "sysglobal"
      WHERE location = "system";

    would have been issued on the XDB Server xdbserve.

  6. Issue the following SQL command to update the information about the global security location in the SYSXDB.SYSLOCALS table:
    UPDATE sysxdb.syslocals
    SET location = "global-security-location"
      WHERE location = "system";

    In the examples used in this topic, the SQL command:

    UPDATE sysxdb.syslocals
    SET location = "sysglobal"
      WHERE location = "system";

    would have been issued on the XDB Server xdbserve.

  7. Exit the SQL Wizard.

In order to verify AuthIDs (usernames) and passwords, there must be values in the appropriate system tables, primarily SYSXDB.SYSACFUSERS, on the global security server.

AuthIDs are created using the SQL Wizard Admin menu. Use this utility to enter AuthIDs and passwords for all users who will be accessing any XDB Server using this global security server.

  1. To enter AuthIDs and passwords from the global security XDB Server, start the XDB Server.
  2. On any client logged in to the global security XDB Server, start the SQL Wizard.
  3. Create AuthIDs and passwords for all users who will log into the primary XDB Server, and have their AuthIDs and passwords verified by the global security server.

To implement this topic's examples, create an AuthID Bob on XDBSERVE.

Parent topic: Setting Up Global Security
Related information
Security and Authority


Outbound, Inbound and Trusting Used Together

When used independently of each other, outbound mapping, inbound mapping, and trusting are easy procedures to set up. However, if you wish to use these features together, you should plan out your mapping and trusting scheme before implementing it.

Some concepts, such as AuthID, password, groups, and priorities are controlled on a per server basis. Others, such as database and table privileges, are controlled on a per location basis.

If you will be using inbound mapping and outbound mapping between two servers you must be sure that your system tables cover all possible mappings. For example, requests from Bob on the XDB Server develop to the XDB Server sales will be subject to outbound mapping on develop. Requests from Debbie on develop to sales will be subject to inbound mapping on sales.

To allow this scenario, you must have one additional row in the SYSIBM.SYSUSERNAMES tables on each XDB Server (sales and develop) that indicates requests from these users should not be mapped.

Parent topic: Multiserver Security


Backup and Recovery

  • Log Files
  • Server Configuration
  • Backing Up Locations
  • System Recovery
Parent topic: SQL Option Server Administration Guide


Log Files

Instead of building separate forward and backward logs, the unified logging system automatically builds and names a series of log files for each location when that location is created. These location log files provide protection against both transient system failures (e.g., power outages, operating system crashes), and media failures, such as a hard disk crash.

  • Log File Naming
  • Location of Log Files
  • Log Files During Recovery
  • Turning Logging On and Off
Parent topic: Backup and Recovery


Log File Naming

Each time a location is created the XDB Server logging system creates a file named anchor.log. This file holds information on how to recover the location after a transient system failure or media failure. As work commences in the location, the logging system automatically creates a second log file named a0000000.log, which records all current transaction information necessary for transient system failure recovery.

A series of log files (beginning with a0000000.log) are automatically created by the logging system to record all data table changes since the location was created (or since logging was reset for that location). Log files are named automatically by the system according to the following convention:

xyyyyyyy.log

where the x prefix is a letter of the alphabet, and each y represents a digit of a hexadecimal number (seven digits long). The first in the series of log files built is always named a0000000.log, with the hexadecimal portion of each subsequent log file name indexed upward by one (for example, a0000001.log, a0000002.log, etc.).

Parent topic: Log Files


Location of Log Files

All logging files are stored in the same log path directory, which by default is the parent location directory. This path can be (and should be) set to a separate physical storage device, providing greater protection against a system hard disk crash. The path for your location log files can be changed by issuing a SET LOG command from the SQL Wizard. Make sure that each location on the server has a unique log path.

Parent topic: Log Files


Log Files During Recovery

The server tries to find the anchor.log file each time a location is opened. If anchor.log is not there, the server creates a new one and initializes the new stream of log file names to begin with a0000000.log. If anchor.log is present and the location was shut down normally after its last use, the server will continue writing entries to the end of the last log file created.

If anchor.log is present and the location experienced transient system failure (due to a power outage, operating system failure, etc.) after its last use, the server automatically recovers the location to a logically consistent point. It ensures that all data that was committed before the crash is applied to the location tables, and all other data is rolled back. This recovery occurs when the first user accesses the location. The logging system then continues functioning normally, appending new work to the end of the last log file -- just as if the system had been shut down normally.

Parent topic: Log Files


Turning Logging On and Off

If you have SYSADM authority or higher and exclusive use of the server, you can temporarily turn the logging system off. When issued from the SQL Wizard, the SET LOG OFF command temporarily suspends logging for the location during the remainder of the current session. Turning logging off for a particular location is a temporary expedient for an exclusive user that does not want to incur the overhead of logging during administrative tasks.

Logging is turned off for the current session, only. Logging can be activated again in the current session by issuing a SET LOG ON command. Exiting the session toggles the status of location logging back to on (the default). The next session that accesses the location therefore has logging turned on. Setting the logging system on or off from the SQL Wizard does not affect the logging configuration settings in your xdbsrvco.ini file.

Parent topic: Log Files


Server Configuration

Control the behavior of the XDB Server logging system by setting the four parameters described in this topic.

  • Delete Old Logs (Recovery)
  • Log File Size
  • Log Buffer Size
  • Checkpoint Frequency
Parent topic: Backup and Recovery


Delete Old Logs (Recovery)

If you want to issue the ROLLFORWARD command to initiate location recovery, you must set the bDeleteOldLogs parameter to 0 (off).

To set the parameter (Windows):

  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Turn Recovery on.

See the section Media Failure Recovery and the SQL Reference for information about the ROLLFORWARD command.

CAUTION:
Run-time or mission-critical XDB Servers should always run with recovery turned on (bDeleteOldLogs=0).

Set bDeleteOldLogs to 1 (on) to allow developers to automatically delete location log files not needed for transient system failure recovery from the hard disk. Even with bDeleteOldLogs set to 1 (on), the server will recover to a logically consistent state after a transient system failure, such as terminating abnormally due to a power loss, or operating system failure. The logging system always preserves the last transaction.

To set the parameter (Windows):

  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Turn Recovery off.
Parent topic: Server Configuration


Log File Size

Set the log file size to specify a maximum size for individual log files (ranging from 1 MB to 10 MB). Log file size values are in increments of 1KB, with a default value of 1024 (1 MB). When the server writes the specified number of bytes out to the log file, it will close that file and create the next one. This feature allows users to backup individual log files while the system is up. You can configure log files to fit on a floppy diskette.

To set the parameter on Windows:

  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Enter the desired log file size in the Log File Size text box, or drag the slider.
Parent topic: Server Configuration


Log Buffer Size

The log buffer size parameter governs the size of the internal write buffer used by the logging system. Internal write buffer values are in increments of 1 KB, with a default value of 128.

Note: The quotient of the log file size divided by the buffer size must be a whole number. If this ratio is not an integer value, the logging system adjusts the buffer size and possibly the log file size until an integer ratio is achieved.
To set the parameter (Windows):
  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Enter the desired log buffer size in the Log Buffer Size text box, or drag the slider.
Parent topic: Server Configuration


Checkpoint Frequency

The checkpoint frequency parameter determines the amount of time between automatic logging system checkpoints. These automatic checkpoints cause the contents of log buffer cache to be written to table files on disk, removing the need for applications to issue checkpoints manually. See the SQL Reference for a description of the CHECKPOINT command.

The checkpoint frequency parameter is one of the factors affecting the length of time needed to return location data objects to a logically consistent state after a transient system failure, such as a power outage, or operating system failure. If you increase the checkpoint interval, the system requires more time for log recovery after a transient system failure. Conversely, a shorter checkpoint interval reduces average recovery time, but increases system overhead.

To set the parameter:
  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Enter the desired checkpoint frequency in seconds in the Checkpoint Frequency text box, or drag the slider.
Parent topic: Server Configuration


Backing Up Locations

We strongly recommend that you implement a regularly scheduled and frequent procedure for backing up your locations and data to avoid losses due to media, machine or operator failure. Backup rules for your installation will vary with each application. The frequency with which you run backups depends on the importance of the data, how often it changes, the maximum time needed to recover, and how large the data tables and location are. For each application, you must weigh the time and space costs of backups against the risk of data loss.

The BACKUP LOCATION and Restore batch files commands operate on a specific location and include all paths and files for all data objects in the location. In order to restore any combination of data objects from a particular location you must restore the entire location. The ROLLFORWARD command also operates on an entire location, applying a specified series of log files to a restored backup copy of the location data. See the following topics and the SQL Reference for detailed descriptions of the updated BACKUP LOCATION command and ROLLFORWARD command.

If you use an operating system backup command or another backup utility, be sure to back up all the files in all the paths that are defined for the location, including storage group (stogroup) paths and paths defined in various environment variables, if any. Be sure to archive and then delete the current series of log files after executing each location backup. Deleting the current log files resets location logging, causing a new series of log files to be built the next time the location is accessed.

Note:

If you want to use your operating system's backup, you must first shut down the server or take its locations off line, using the SQL OFFLINE command. See the SQL Reference for detailed descriptions of the ONLINE and OFFLINE commands.

  • BACKUP LOCATION Command
  • Resetting Location Logging
  • Restore
  • ROLLFORWARD Command
  • COMPACT Command
  • Backup Procedure
  • Other Backup Options
Parent topic: Backup and Recovery


BACKUP LOCATION Command

The BACKUP LOCATION command creates copies of all files that reside in the paths defined for the specified location. If stogroups are used in the location, appropriate files are also copied from all the drives and paths that are defined by the stogroups. If you have special paths defined by environment variables (such as XDB_index-name_location-name or XDBIDX_location-name) in the [Server] topic of your server machine's xdb.ini file, files in most of these paths are also backed up.

You can use the BACKUP LOCATION command only if the location being backed up is not currently in use by you or another user. The BACKUP LOCATION command copies the files to the target device and path you specify. The target directory must not already exist. See the BACKUP LOCATION command in the SQL Reference for more information. This can be a file server or a different hard disk drive. Tape drives and diskettes are not recommended.

The syntax of the BACKUP LOCATION command is:

BACKUP LOCATION location-name TO path-name [ AND INDEX | NOT INDEX ]

The AND INDEX | NOT INDEX parameter is optional. If not specified, AND INDEX is assumed and the system copies all appropriate index files along with the other files. If NOT INDEX is specified, the *.idx and *.ptr files are not copied. If you need to restore a location from a backup that did not include the index files, you will need to rebuild the indexes using the COMPACT LOCATION AND INDEX command.

Note:
  • To avoid confusion, always use a different path for each backup of each location. This will provide an xdbrest.cmd or xdbrest.bat file for each backup of each location.
  • BACKUP LOCATION does not copy files onto multiple diskettes.
Note:
  • If the contents of a location are too large to fit on one diskette, and you do not have an alternate high capacity device, use your operating system's backup command or an equivalent utility instead.
  • Be sure to back up all files in all relevant subdirectories.
  • Reset your log files after backing up a location. See the section Resetting Location Logging for more information.
Parent topic: Backing Up Locations


Resetting Location Logging

Whenever a new location is created, the logging system automatically creates a series of log files just for that location. For an existing location, we recommend that these location log files be manually reset after each location backup process. Manually resetting location logging immediately after backing up speeds recovery in the event of a serious media failure, since only log entries originating after your location backup need be replayed against your location tables.

The XDB Server logging system automatically creates a series of log files when a new location is created. Logging should be manually reset as a part of the location backup process.

To manually reset location logging:

  1. Shut down server.
  2. Copy log files from the location logging directory to a separate archive directory.
  3. Depending on whether you are using the BACKUP LOCATION command or an operating system backup command, do one of the following:
    • Bring the server back up and run the BACKUP LOCATION command from the SQL Wizard. (Be sure you execute the BACKUP LOCATION command from a location other than the one you are backing up.)
    • Run your operating system (or other) backup utility as appropriate (be sure to archive all directories associated with the XDB location).
  4. Shut down the server (if using BACKUP LOCATION).
  5. Delete all log files (*.log) from your location logging directory. The next time the location is accessed, a fresh series of log files will automatically be created by the logging system.

Location logging should be manually reset after any type of location backup (that is BACKUP LOCATION command or operating system backup).

Parent topic: Backing Up Locations


Restore

BACKUP LOCATION also creates a batch file (xdbrest.bat) that can be run from the operating system command line to restore the location's data objects. xdbrest.bat is created in the same path you designate for the backup files.

Parent topic: Backing Up Locations


ROLLFORWARD Command

The ROLLFORWARD command does not recover the following kinds of changes:

  • Data Control Language (DCL) commands, such as GRANT and REVOKE.
  • Utility commands such as SET.
  • Compact command.
  • TRUNCATE TABLE command.

Therefore, a backup should be performed after any of the above operations.

Parent topic: Backing Up Locations


COMPACT Command

You must always backup up your location and reset location logging (that is delete old location log files) after performing a COMPACT.

Note:

Never perform a COMPACT on a restored location before replaying log files. Compacting a location modifies the location table data and makes the old log files incompatible with the newly compacted location.

Parent topic: Backing Up Locations


Backup Procedure

The BACKUP LOCATION command will not archive off log files. Log files must be archived manually, after which location logging must be manually reset.

To backup a location using the BACKUP LOCATION command and reset location logging:

  1. Ensure that nobody is currently accessing the location you are backing up, and ensure that no incomplete transactions are in progress. You must be running in Isolation Level EU (exclusive use).
  2. Log into a location other than the one you are backing up (for example, SYSTEM location).
  3. Enter the BACKUP LOCATION command from the SQL Wizard.
  4. If you use removable storage media for your backups, carefully record vital information on the backup media's labels, including:
    • Location Name
    • Database Name
    • Stogroup and log file path names
    • Names of special paths that are defined in the server machine's xdb.ini file such as paths for indexes
    • Logging system information
    • Backup time and date
  5. Bring the server down.
  6. Archive the current series of log files. This series of files should be clearly marked and archived in a separate directory. They may be needed for playing against an older backup, in the event the latest location backup is corrupted or unavailable. Serial numbers can be used to ensure that the correct series of log files are applied to the correct backup copy of the location.
  7. Once Step 6 is complete, delete the current series log files from the location logging directory.
  8. Bring the server back up. Next time the location is accessed, a new set of log files is automatically created in the location logging directory.
Parent topic: Backing Up Locations


Other Backup Options

Most commercially available archival utilities can be used to back up locations. When using a backup utility, it is important to keep in mind that you must backup the contents of all directories for the entire location, including storage group paths (if any) and all subdirectories. This last point is important, as the server could have duplicate file names in different directories, which need to be kept separate on the backup device.

Note:
  • Do not attempt to shortcut the process by backing up only the *.tab files. a *.tab file is useless without the index files (*.idx and *.ptr) and other files associated with the tables.
  • If you want to copy tables or views between locations, use Migrate. See the Migrate User's Guide for more information. Do not use an operating system copy command to copy individual tables from one directory to another.
Parent topic: Backing Up Locations


System Recovery

If your system terminates abnormally due to transient system failure or media failure (disk crash), you can restore all previously committed work by following either the Transient System Failure or Media Failure scenario instructions.

  • Transient System Failure
  • Transient System Failure Recovery
  • Media Failure
Parent topic: Backup and Recovery


Transient System Failure

Transient system failure can occur from power outages, operating system crashes, or termination of the server with users still logged on.

Parent topic: System Recovery


Transient System Failure Recovery

In cases of transient system failure, system recovery occurs automatically either the next time any user attempts to login to a location in which a transaction was abnormally terminated or the next time a SET LOCATION command is issued against an affected location. For any transaction that was abnormally terminated before it completed, the before image stored in the location log files is used to automatically rollback all uncommitted transactions and restore the data tables involved to a logically consistent state.

This transient system failure recovery feature (the same functionality provided by backward logging in previous versions of the XDB Server) is permanently defaulted to on, with no user intervention required.

The average length of time necessary to bring all location data objects to a logically consistent state is affected by the value of the Checkpoint Frequency configuration parameter. This parameter allows the user to adjust the time between automatic logging system checkpoints. See the section Server Configuration for information about setting the Checkpoint Frequency parameter.

When the logging system issues a checkpoint, the contents of the entire log buffer cache are flushed to disk, that is, written to table files.

Parent topic: System Recovery


Media Failure

Media failure is a serious hardware mishap such as a disk crash.

Media Failure Recovery

You can restore a backup copy of a location's files and replay the contents of a discrete series of log files against the restored location using the ROLLFORWARD command.

A discrete series of log files consists of all changes made to the data objects within an location since the last time the logging system for that location was reset (usually after the last location backup). You must configure the server to ensure that your system is keeping log files. See the section Server Configuration - Delete Old Logs for more information.

If you have made periodic backups of your location (resetting the logging system after each backup), and you have configured your server to keep old logs, you can usually recover from a media failure.

To recover from a media failure:

  1. Shut down the server.
  2. For every location affected by a media failure, use your operating system copy command to archive the current series of log files to a drive and path that is different from any of the location directories you are recovering. Under ideal circumstances, the location log files should be on a different physical drive, separate from the corrupted location files.
  3. Delete current series of log files from the location logging directory.
  4. Locate the latest backup copy of the appropriate location, associated stogroup directories and other related directories.
  5. Restore the backup to the respective drives and paths, using one of the following sets of instructions:

    • If you used the BACKUP LOCATION command:

      Make sure that the server is shut down, and that all destination directories and subdirectories exist (the restore program will not create directories). Then, change to the drive and directory where the backup batch file resides and enter the following at the operating system command line:

      xdbrest

      Any files in the destination directories will be overwritten. Log files will not be restored.

    • If you used your operating system or other utility:

      You must restore files using the compatible operating system restore command prior to recovery.

      If you need to restore location files on a different drive or in different paths than they previously resided, be sure to edit the appropriate system tables to make the XDB Server aware of the new location names and paths. Edit SYSXDB.SYSLOCALS and SYSIBM.SYSLOCATIONS tables to specify location names and path names. Edit SYSIBM.SYSSTOGROUP and SYSIBM.SYSVOLUMES to specify stogroup information. Also check the server machine's configuration file for other special directories, such as index paths.

  6. Bring the server back up.
  7. Before replaying the log files with the ROLLFORWARD command, be sure you are running in Exclusive Use (EU) isolation level. Use the SET ISOLATION command or the Options Utility to change your isolation level. Running in EU gives you total control over the server. Likewise, no incomplete transactions can still be in progress.
  8. Even if only one or more tables within a location need to be restored, the ROLLFORWARD command reconstructs the entire location in question. The ROLLFORWARD command operates on the location level only, restoring one complete location with each execution.
  9. In preparation for replaying all outstanding series of log files against the restored location, create a temporary log file directory and copy the current series of log files (or the most current series of log files if more than one) into that directory. Although not strictly required, resetting location logging after each backup ensures that your current series of log files have recorded only those transactions occurring since the last backup.
  10. From the SQL Wizard, execute a ROLLFORWARD command naming the restored location and the temporary log file directory containing the log files.

    Issue the following SQL command:

    ROLLFORWARD location-name
    USING log-path

    where location-name is the name of the location containing the restored backup files and log-path is the drive and path name of the directory containing the anchor file and series of log files to be replayed against the restored location. This directory should contain the anchor.log file plus one or more log files beginning with the file named ?0000000.log (where ? = [a-z]).

    For example, the following ROLLFORWARD command would apply the log files contained in the directory c:\xdbnt\logfiles to the system location

    ROLLFORWARD system
    USING c:\xdbnt\logfiles

    During a ROLLFORWARD, all transactions contained in the location log files are replayed against the restored location.

  11. More than one series of log files may need to be replayed in cases where the location was not backed up (or the backup was corrupted or lost) each time location logging was reset. In these cases, multiple series of log files must be played against the last available backup beginning with the oldest series of log files and finishing with the most recent series.

    In cases where multiple series of log files are being replayed against an older location backup:

    1. Follow the directions in Step 9 to replay the oldest series of log files first (by indicating the directory containing this first series of log files in the ROLLFORWARD command).
    2. Repeat Step A with the next oldest series of log files, being sure to indicate a new directory containing these log files (the same directory can be used as long as the previously replayed series of log files are erased and replaced by the next series).
    3. When the most recent series of log files is ready to be replayed, follow Step 9 one last time to complete the location recovery.

    The sum total of all ROLLFORWARD operations applied against a restored location causes the logging system to run through all the transaction data contained in each series of log files, returning the location to the state it was in immediately before the system failure.

    When the recovery process is complete, press Esc to exit the SQL Wizard.

  12. Shut down the server.
  13. Reset the logging system. See the section Resetting Location Logging.
  14. Start the server. The server is now ready for normal operations to resume.

After all recent log files have been applied to the restored backup copy of the location, your data tables should be returned to a state existing prior to the media failure.

Parent topic: System Recovery


Storage Requirements

Disk storage space requirements depend on which version of the XDB Server you are using and the optional related products you have installed.Each location you create requires a minimal amount of overhead to account for system tables and the default database structure. The overhead for a location, not counting user tables, indexes, and other user objects is approximately 320K.

  • Table Storage Requirements
  • Index Space Requirements
  • Temporary Storage Requirements
  • Log Requirements
  • Other Storage Requirements
Parent topic: SQL Option Server Administration Guide


Table Storage Requirements

To estimate the bytes of disk space a table will occupy you must consider overhead as well as space occupied by data. You must also have a realistic idea of the maximum number of records to be stored in the table.

Formulas for estimating space requirements for tables are described in this topic. The formulas use the following variables:

E | Estimated table storage required (bytes)
I | Estimated index storage required (bytes)
P | Physical record length (maximum 32,767 bytes)
N | Number of records in the table (estimate)
T | Table overhead (88 bytes per table)
F | Field overhead (86 bytes per field)
R | Record overhead (2 bytes per record)
Di | Data storage requirement for field i per record (Depends on data type. See the following table.)
Oi | Overhead for field i per record (2 bytes) (While the number of bytes for data overhead is given as 2 for all data types, character fields of odd length actually require only 1 byte of overhead per record.)
f | Number of fields in table

The formula for calculating the physical record length, P, is:

Formula for calculating the physical record length

The general formula for estimating bytes of storage required by a table is:

Formula for estimating bytes of storage required by a table

Substituting for P yields the formula:

Formula used when substituting for the physical record length

Use the following table to find the data storage (D) and overhead (O) for the i-th field, depending on the data type.

Note:

The maximum physical record length is 32,767, which includes overhead. When determining the length of long records, use the formula for P, given earlier.

VARCHAR and LONG VARCHAR data types are provided for ANSI and DB2 compatibility only. Data for these types is currently stored as regular character data. All of the BLOB data types (image, binary, varbinary and long varbinary) are stored in separate files-- one file per blob column.

Data Type | D | O
smallint | 2 | 2
int | 4 | 2
float 4 | 4 | 2
float 8 | 8 | 2
money | 8 | 2
decimal | (precision/2)+1 | 2
date | 6 | 2
time | 6 | 2
char (odd length) | length | 1
char (even length) | length | 2
varchar (odd length) | length | 1
varchar (even length) | length | 2
long varchar | 4056 | 2
graphic (odd length) | length | 1
graphic (even length) | length | 2
vargraphic (odd length) | length | 1
vargraphic (even length) | length | 2
long vargraphic | 4056 | 2
blob (image, binary, varbinary or long varbinary) | stored in separate file; up to 2GB each | 4
Parent topic: Storage Requirements


Index Space Requirements

Estimating the amount of space occupied by an index is difficult. The XDB Server uses B-tree indexes. The values in an indexed field and a pointer to the record containing it are stored in the *.idx file for the index; pointers to each duplicate instance of the value are stored in the *.ptr file for the index. The *.ptr file will contain 0 bytes if the index was created using the UNIQUE option.

Before you start you must have an estimate of the number of records in the table and the number of distinct values in the index.

Formulas for estimating space requirements for indexes are described in this topic. The formulas use the following variables:

I | Estimated index storage required (bytes)
V | Number of distinct values in index (estimate)
N | Number of records in the table (estimate)
S | Storage requirement for index value (Depends on index type)
Dj | Data storage requirement for field j (Depends on data type. See the following table.)
Oj | Overhead for field j (Depends on data type. See the following table.)
f | Number of fields in index

The bytes of storage required for an index is calculated as follows:

Formula for calculating the bytes of storage required for an index

Note that if the index is created using the UNIQUE option, the number of records is equal to the number of distinct values, and the equation for calculating index storage requirements is reduced to:

The equation for calculating index storage requirements

In either case, S, the storage requirement for indexed values, depends on the type of index.

Regular Index

To compute the storage requirement S for a single field index, use this formula:

Formula to compute the storage requirement for a single field index

Compound Index

To compute the storage requirement S for a compound index on f fields, use this formula:

Formula to compute the storage requirement for a compound index

Parent topic: Storage Requirements


Temporary Storage Requirements

You should have enough space in the temporary directory to store the largest result you anticipate retrieving from the database. As a rule of thumb, you should have at least two to three times the space required for your largest table in order to perform joins. However, the space required for your particular application might differ considerably.

Parent topic: Storage Requirements


Log Requirements

The amount of space required by location logs depends on several factors, including:

  1. Frequency of Location Backups.

    If you backup your locations (and the location log files) frequently, the location log will contain fewer entries, and will therefore require less space.

  2. Frequency and Number of Table Inserts, Updates, Deletes.

    The log file stores the after image and the before images of all records changed by a table transaction. If changes occur often, or changes involve many records, the log file will be large.

Parent topic: Storage Requirements


Other Storage Requirements

Storage requirements for static database components such as forms, report command files, and menus can be determined after each component is created. Use your operating system directory list command to view the size of files after they have been created.

While the size of various components might vary considerably, these files do not generally change size once the components are developed. You might use the size of a component that performs a similar function as an estimate for a new component you are developing.

Parent topic: Storage Requirements


Performance Tuning

  • Optimizing Query Processing
  • Improving Production Processing
  • Increasing Data Import Speed
  • Improving Performance During Object Creation
  • Administrative Performance Tools
Parent topic: SQL Option Server Administration Guide


Optimizing Query Processing

The Query Optimizer uses advanced performance optimizing techniques when processing queries, especially when appropriate indexes are available. Most of the query processing algorithms described in this section are automatic; they do not require user intervention. However, understanding how the various processing algorithms use indexes will help you to decide when indexes are needed as well as help you construct more efficient queries. A list of query guidelines is provided at the end of this section.

  • Indexes and Performance
  • Overriding the Optimizer
  • Retrieval Speed vs. Update Speed
  • List Prefetch
  • Aggregate Clause Processing
  • Predicates
  • Expressions
  • LIKE Predicate
  • Index Usage with AND and OR
  • Nested Queries
  • Correlated Queries
  • Join Optimization
  • Sorting
  • IN LIST with a Range Condition
  • Joins with Non-Join Predicates
  • Join Restrictive List Analysis
  • Query Performance Summary
Parent topic: Performance Tuning


Indexes and Performance

The XDB Server uses B-tree indexes to speed retrieval. Like a book index, a database index reduces the amount of data that must be searched to find an answer. The XDB Server performs automatic query optimization to select the best index to use for a query.

In general, the fewer records accessed, the faster the retrieval time. The XDB Server uses available indexes whenever they help to speed retrieval. But, while indexes generally speed up retrieval, they can slow down updates, inserts and deletes.

Usually, it is faster to execute a query using one or more indexes than to examine every record in the tables involved in the query. The XDB query optimization algorithms examine the indexes available and pick which indexes, if any, to use for a particular query. The user does not need to specify which indexes to use.

The query optimization algorithms analyze the selectivity of a column to determine how to process a query. Selectivity of a column is determined by calculating how unique the values in the column are. The more unique the values, the more likely the column will be a candidate for index use. Selectivity is determined by the formula, 1/x, where x is the number of distinct values in a column or index. The larger the number of distinct values, the more unique the column is and the lower the selectivity is. This increases the probability that the optimizer will use the index.

If a command does not contain a WHERE, ORDER BY, HAVING, or GROUP BY clause, the server generally will not perform an index search; instead, it processes the table sequentially. Some aggregate functions can cause an index to be used in certain cases. Usually, if a column in the WHERE clause is indexed, the index is a candidate for use. Other factors, such as the number of distinct values in an index, determine final index selection.

Parent topic: Optimizing Query Processing


Overriding the Optimizer

You can force the use of an index for a particular query, or force the system to not use an index.

To force the use of an index, enter an asterisk (*) in parentheses after the name of the indexed column when you construct the query. To force the system to ignore the index, use enter a hyphen (-) in parentheses after the name of the indexed column when you construct the query.

For example, assuming that an index exists on C_NO:

This query uses the C_NO index.

SELECT c_no, o_no, o_date
    FROM orders
    WHERE c_no(*)<20

This query does not use the index.

SELECT c_no, o_no, o_date
    FROM orders
    WHERE c_no(-)<20

The (*) and (-) options are valid only for column names that appear in a WHERE clause. You cannot use the (*) and (-) options in GROUP BY, HAVING or ORDER BY clauses.

Parent topic: Optimizing Query Processing


Retrieval Speed vs. Update Speed

There is a trade off between retrieval speed and update speed when indexes are used, since each time a value in an indexed column is changed, the system must also update the index. Overall database performance can actually deteriorate if indexes are built on columns that are seldom searched but are frequently updated. You might want to build a number of indexes on a read-only table, but limit a frequently updated table to a minimal set of indexes.

When importing data into a table, it is significantly faster to create indexes after the data has been inserted. Prior to importing, you should drop all indexes that are not required to enforce uniqueness. Use a batch SQL file or procedure to re-create indexes after importing.

Parent topic: Optimizing Query Processing


List Prefetch

List Prefetch is an Query Optimizer routine that extracts the Record IDs (RIDs) that match a specific search criteria from a particular index. These RIDs are sorted in ascending order, thereby enabling sequential table access. By accessing the table data pages in a sequential fashion, disk head seek time can be drastically reduced and data page prefetching performed. The server considers list prefetch when table data page access is required, when a multiple index access condition is detected, or if data needs to be retrieved in physical order.

Note: List prefetch can be affected by the size of the RID Pool buffer. See the section Improving Production Processing for more information.
Parent topic: Optimizing Query Processing


Aggregate Clause Processing

When all aggregate functions in a query are on the same indexed field, the system will determine the result from the index rather than by using the slower process of accessing the base table. For example, given the following query, the server does not need to look at the table file if an index exists on PAYRATE; the index alone is sufficient to give the result.

SELECT MAX(payrate), MIN(payrate), AVG(payrate)
    FROM employee

Likewise, any COUNT aggregate using a WHERE clause that can be resolved via an index will not access the base table. For example, if an index exists on columns A and B in TABLE1 and the following query is issued:

SELECT COUNT(*) FROM table1
    WHERE a=2 AND b=3;

the information will be available via the index. The base table (TABLE1) is not accessed.

Parent topic: Optimizing Query Processing


Predicates

In the case of a simple predicate involving an indexed column, the XDB Server will generally use the index to speed retrieval. For example, given an index on ZIP, that index will be used to process the following query:

SELECT * FROM employee
    WHERE zip = "20441"
Parent topic: Optimizing Query Processing


Expressions

If an indexed column appears in a query only as a part of an expression that alters the column, the index will not be used. For example, given the following query, an index on the PAYRATE column will not be used, even if it exists:

SELECT * FROM employee
    WHERE payrate * 1.10 > 13.00

Likewise, the index will not be used in the following query:

SELECT * FROM employee
    WHERE payrate > 13.00/1.10

Usually, it is best to perform the constant calculations prior to executing the query.

Parent topic: Optimizing Query Processing


LIKE Predicate

When constructing queries containing a LIKE predicate that involves an indexed column, try to avoid pattern matching strings that begin with percent (%) or underbar (_). If the string in a LIKE predicate begins with either of these two characters, it automatically indicates that a sequential search must be performed on the entire index. For example, given an index on LNAME, the query:

SELECT * FROM employee
    WHERE lname LIKE "_risp%"

might take significantly longer than the query:

SELECT * FROM employee
    WHERE lname LIKE "Krisp%"
      OR lname LIKE "Crisp%"

In the first case, the entire index must be searched for any names that have "risp" as the second through fifth letter. This is virtually the same as having no index at all. In the second case, the search is for two specific starting strings; these are more quickly found because the search does not have to go through the entire index.

Parent topic: Optimizing Query Processing


Index Usage with AND and OR

In the case of compound predicates connected with AND, the server will use all available indexes to find the intersection. For example, given indexes on columns ZIP and DEPT, both indexes might be used to process the following query:

SELECT * FROM employee
    WHERE zip = "20441"
      AND dept = "2020"
      AND payrate < 12.00

If an index had existed on PAYRATE, it would be used, but its absence does not prevent the use of the other indexes.

In the case of compound predicates connected with OR, the server uses an index, only if the two conditions reference the same column (and that column has an index). For example:

This query uses the index on the DEPT column:

SELECT * FROM employee
    WHERE dept = "2020"
       OR dept = "2021"

This query does not use the index on the DEPT or PAYRATE columns:

SELECT * FROM employee
    WHERE dept = "2020"
       OR payrate = 12.00
Parent topic: Optimizing Query Processing


Nested Queries

While algorithms exist on some systems to convert any nested query into a flat join, the benefit of such algorithms is not always significant. Therefore, the server does not perform the conversion. Instead, the server continually makes use of feedback from intermediate results to avoid unnecessary searches. If the server methodology is not the most efficient for your data, you can restructure the query as a flat join.

When processing a nested query, the server first evaluates the inner query (subquery). Consider the following query:

SELECT * FROM dept
    WHERE mgr IN
        SELECT e_no FROM employee
            WHERE city = "Wild Woods"

The XDB Server first finds all employees who live in Wild Woods, and modifies the nested query to process the outer query. If an index exists on MGR, it might be used after the nested query has been processed.

Parent topic: Optimizing Query Processing


Correlated Queries

When processing a correlated query, the outer query is processed first. The server compares the previous value to the current value to see if the inner query needs to be executed again. For example, given the following query to find the supplier who supplies the largest quantity of each product:

SELECT sno, pno FROM partsupp p
    WHERE qty =
        SELECT MAX(quantity) FROM items
            WHERE pno = p.pnoORDER BY pno

For each record in the PARTSUPP table, the inner query is evaluated to find the maximum quantity. If the next PARTSUPP record is for the same product, the maximum quantity is already known, and therefore the subquery is not performed. If PNO is indexed, then adding the ORDER BY PNO clause makes the query faster because the records with the same PNO values are all grouped together.

A correlated query whose correlated query block always evaluates to false is detected and does not continue to execute. If the correlation condition is not the condition that causes the query block to be false, the query block is always false.

For example, in this query:

SELECT * FROM table1 x
    WHERE EXISTS
        SELECT * FROM table2 y,table3 z
            WHERE y.f1 = z.f1
              AND x.f2 = z.f2
              AND y.f3 > 10;

if the inner SELECT does not retrieve any records without evaluating the correlation condition (X.F2=Z.F2), it can be determined that the query will not return any records; no records match the non-correlated criteria.

If only one correlation condition exists, the previous value of the correlation will unconditionally be saved for comparison with the next correlated value. (In previous versions of the XDB Server, this was only saved and compared if the correlated condition was not embedded in a NOT, AND or OR condition.)

Parent topic: Optimizing Query Processing


Join Optimization

The XDB Server uses a number of optimization techniques for processing joins. When performing a multitable join, performance might improve significantly if you specify all possible join conditions; this allows the system to perform the joins with the optimal selectivity ratio first, thus reducing the number of comparisons required.

For example, imagine three tables: EMPLOYEE, DEPARTMENT and PROJECT. Every employee works in a department. Every project is the responsibility of a department. Every project is managed by an employee from the responsible department.

Thus there are three possible join conditions that can be used to join the three tables:

  • DEPARTMENT.DEPT_ID=EMPLOYEE.DEPT_ID
  • DEPARTMENT.DEPT_ID=PROJECT.RESPONSIBLE_DEPT_ID
  • EMPLOYEE.EMPLOYEE_ID=PROJECT.PROJECT_MANAGER_ID

While it is sufficient to provide any two of these join conditions in your query, you might experience significant performance improvement if you provide all three join conditions.

As a general rule, when joining n tables, you should provide at least n-1 join conditions. When the context of a query permits, optimal performance might be achieved by providing any additional, valid join conditions. However the use of redundant join conditions must be balanced against the readability and parsing cost of the query.

Parent topic: Optimizing Query Processing


Sorting

When records are to be retrieved in a sorted order, indexes will speed up sorting.

If no appropriate indexes exist, qualifying records are located by performing a sequential search on the table. The resulting subset of records is sorted. The efficiency of the sort operation is affected by the Sort Space Size setting specified in the Configuration Utility.

If an index exists, a sequential search of the index (index walk) will be performed in some cases. For example, if an index exists on the PNO column, an index walk is performed to process the query:

SELECT * FROM part
    ORDER BY pno

In the following query, the index walk algorithm will make use of a compound index on the SNO and PNO columns:

SELECT * FROM partsupp
    ORDER BY sno, pno

When possible, the server uses the compound index if the first element in the compound index is referenced in a predicate or ORDER BY clause, even if the other columns are not referenced. For example, if the ORDER BY clause in the query above included only the SNO column, the compound index would be used. If the ORDER BY clause included only the PNO column, the index would not be used.

In the case of queries involving predicates and ORDER BY clauses, if appropriate indexes exist, the server will use the index to find the qualifying records, and then sort just those records. For example, given the following query, with indexes on PNO and QTY, the server uses the index on QTY to find the records that qualify, and then orders the result. The index on PNO is not currently used.

SELECT * FROM partsupp
    WHERE qty >= 200
    ORDER BY pno
Parent topic: Optimizing Query Processing


IN LIST with a Range Condition

If an IN LIST exists in conjunction with a range condition, a compound index can be used. In the following example, there is an index on columns A, B and C in TABLE1:

SELECT * FROM table1
    WHERE a = 3
      AND b IN (6,7)
      AND c BETWEEN 2 AND 20;
Parent topic: Optimizing Query Processing


Joins with Non-Join Predicates

Joins will take advantage of additional non-join predicates when compound indexes exist that involve both the join condition and the predicate.

For example, a compound index exists on TABLE2 (A,B,C):

SELECT * FROM table1,table2
    WHERE table1.a = table2.a
      AND table2.b = 3
      AND table2.c BETWEEN 1/1/1992 AND 12/31/1992;

If TABLE2 is an inner table of the join, the additional constraints will be applied when the join condition is applied.

Parent topic: Optimizing Query Processing


Join Restrictive List Analysis

If a restrictive list exists and has been prefetched on the inner table of a join, it might be discarded if the size of the list is larger than a certain percentage of the table size. If the restrictive list is discarded, the join index will be used (no merging is performed).

Parent topic: Optimizing Query Processing


Query Performance Summary

The guidelines listed below summarize the ways you can improve query performance.

  • If nested or correlated queries do not seem to process efficiently, restructure the query as a flat join to see if that method improves processing speed.
  • Use a correlated query instead of a nested query if the correlated column is indexed and the nested query returns a large amount of data.
  • Try to index the columns that have the lowest selectivity values (those with the largest number of different values), and construct your queries to include predicates involving these columns.
  • Try to avoid OR conditions on different columns. Use a union of queries containing AND conditions instead.
  • When creating compound indexes, try to list columns in the same order they appear in the ORDER BY clauses of your queries to allow the compound index to be used to speed up sorts.
  • Avoid numeric conversions. Try to make comparisons between columns of the same type.
  • Avoid the use of LIKE predicates beginning with % or __.
  • Avoid arithmetic expressions in a predicate, especially those that evaluate to a constant. Perform the calculation beforehand, if possible.
  • Select only the columns you need. Avoid SELECT * FROM when possible, especially when retrieving data across a network. Unneeded data creates unnecessary network traffic.
  • Avoid using COUNT(*) to check for existence.
  • Evaluate the benefits of single vs. compound indexes. Use compound index ordering if suitable. If possible, order the columns in the compound index by highest selectivity (that is, order the columns with the most unique values first).
  • Provide redundant information when joining tables, so that the system can select the lowest cost solution for you.
  • If a table is frequently updated or if most searches on the table are sequential searches (every record is accessed), avoid building any indexes on the table except for those used to enforce uniqueness.
  • Use views only when absolutely necessary. Each view access requires additional I/O and processing costs.
Parent topic: Optimizing Query Processing


Improving Production Processing

This section describes options that can help improve overall processing speed when using the XDB Server.

  • Integrity Constraints and Processing Speed
  • Locking Options
  • Caching
  • Special Read-Only Caching
  • Record ID (RID) Pool Buffer
  • Number of Open Files
  • Number of Open Queries
  • Governor Settings
  • Miscellaneous
  • Reducing Disk I/O Contention
Parent topic: Performance Tuning


Integrity Constraints and Processing Speed

The XDB Server supports schema level domain and referential integrity constraints. While integrity checking is a valuable facility, it can impact database performance considerably, especially on UPDATE, INSERT and DELETE operations.

You must determine whether the advantages of schema level integrity constraints outweigh the additional time required to enforce them. You might want to eliminate some of these checks at the schema level, and instead perform them through the validation facilities of the front-end data entry application. Remember that in a LAN environment use of integrity features creates additional network traffic.

Note that some indexes are automatically created and maintained by the system when integrity constraints are imposed on the database. These indexes can be dropped only by dropping the associated constraints.

For more information about referential constraints, see the following in the SQL Reference:

  • PRIMARY KEY, FOREIGN KEY and REFERENCES options on the CREATE or ALTER TABLE command.
  • WITH CHECK OPTION clause on the CREATE VIEW command.
Parent topic: Improving Production Processing


Locking Options

In multiuser systems, the time spent waiting for locks can be considerable. The XDB Server offers three means of adjusting the effect of locks on performance.

  • Isolation Level.

    Adjust the isolation level to increase or decrease the length of time that locks (especially shared or read-only locks) are held. The sooner a lock is released, the sooner the resource can be locked by another transaction. The trade-off for increased concurrency is decreased consistency.

    Each user can set a default isolation level in the client configuration. To specify the isolation level during a session, use the SET ISOLATION command.

    On a single-workstation XDB Server that will be operating only one client session at a time, using the Exclusive Use (EU) isolation level will eliminate locking overhead.

  • Lock Granularity.

    The time to perform many batch operations that affect many records of a table can often be greatly decreased by acquiring a table lock. Table locks are acquired by issuing the LOCK TABLE command. (See the SQL Reference for more information on the LOCK TABLE command.) Performance improves because there is no need to lock individual records as they are accessed. However, in some cases it will take a considerable amount of time to acquire a table lock. Also, other processes that need to access the locked table must wait until the table lock is released.

  • Timeout Period.

    Users can adjust the amount of time the system tries to acquire a lock. If the time is too short, performance might deteriorate because transactions cannot acquire locks and must be continuously rolled back. On the other hand, if the time is too long, performance might deteriorate because it takes longer to resolve potential deadlocks.

    Users can set their own timeout periods by setting the Lock Request Timeout in the client configuration.

Parent topic: Improving Production Processing


Caching

Caching is available for all database objects, including tables, indexes and data dictionary files. The cache size is specified at the server level using the Caching Options screen of the XDB Server Configuration Utility. Cache memory usage and other related information can be monitored on the XDB Cache Statistics screen while the server is running.

The major benefit of using cache is to keep frequently accessed disk blocks in RAM to ensure that subsequent access to these blocks requires no additional disk I/O. The buffer manager uses a searching algorithm to determine if a block exists in cache before deciding to retrieve that block from disk. If a block does not exist in the cache, this searching time can be classified as additional overhead because the search and the disk I/O must be performed.

The buffer manager also has a tossing algorithm. If the cache is full, some current cache blocks must be discarded before new blocks can be added. The determination of which blocks to discard is based upon a modified clock algorithm.

The cache manager can provide a performance boost only if the reduction in I/Os outweighs the CPU cost required to search and toss. The more objects there are to cache and the more random the access, the less useful a cache manager becomes.

For example, consider a database that is significantly larger than available RAM, with a large number of indexes (to optimize query processing) and data access patterns that are mostly random. All those indexes are eligible for caching, but the random access nature of the queries means that there will probably be a high percentage of cache tossing and low percentage of cache hits. This would indicate that each query was accessing either different I/O disk blocks or I/O blocks that had previously been tossed from the cache. In this situation, large cache sizes would have limited use.

If your system shows a high percentage of tossing and low percentage of cache hits, you should choose a cache size that would not assume I/O overlap between the query set, but would allow I/O reduction for an individual query. In this fashion, each individual query could benefit from common disk I/O access, while reducing the amount of CPU time required by the cache manager to search and toss.

It is important to check the cache hits and misses when all or most of your users are actively accessing data. Generally, the cache hit ratio increases as the number of users grows, especially when those users are performing similar tasks.

Parent topic: Improving Production Processing


Special Read-Only Caching

Outside of the normal cache manager, the server provides additional buffer management techniques specific to read-only data. These techniques are available when the user isolation level is set to dirty read (DR), snapshot read (SR) or exclusive use (EU).

In this cases, the server provides buffered I/O at the cursor level.

If sequential access of a database object is detected within an individual cursor, sequential prefetch of data can be triggered, allowing multiple data pages to be read into a buffer controlled by that individual cursor. This method of buffer management enjoys the benefits of reduced I/O without the normal cache manager overhead (search and toss), and eliminates the need for critical sections.

Parent topic: Improving Production Processing


Record ID (RID) Pool Buffer

The Query Optimizer makes use of a Record ID (RID) Pool Buffer when using the list prefetch algorithm for analyzing data access paths. See the section Optimizing Query Processing for more information on the list prefetch algorithm. List prefetch retrieves Record IDs from an index (in response to the constraints of a particular WHERE condition). The RID Pool Buffer is used to store the Record IDs. If required, the records are sorted before being stored in the RID Pool Buffer.

If the number of Record IDs fetched exceeds the available RID Pool size, the list prefetch is aborted and less efficient processing routines are used. For best performance, the size of the RID Pool Buffer should be large enough to contain the number of Record IDs expected from an index search.

The RID Pool size is specified in the XDBRIDPOOL environment variable in the server machine's configuration file. See XDBRIDPOOL in the appendix Environment Variables for more information on using this environment variable, and for a formula for calculating RID Pool Size.

Parent topic: Improving Production Processing


Number of Open Files

The XDB Configuration Utility allows you to specify the Maximum Number of Open Files. This setting, which represents the maximum number of files that can be kept logically open, should include only the required number of files. When a file is opened in response to a user request, the system scans an internal array to see if the file is already open. If it is, then processing time is improved.

Parent topic: Improving Production Processing


Number of Open Queries

The XDB Configuration Utility allows you to specify the Maximum Number of Open Queries. This setting, which represents the maximum number of queries that can be open at a given time, should include only the required number of queries. When an SQL statement is committed or rolled back, the system scans an internal array of open queries to find the one that should be closed. If the number specified for the Number of Open Queries is approximately the same as the number actually open at any given time, then processing time is usually improved. Specifying too large a number can increase processing time.

Parent topic: Improving Production Processing


Governor Settings

Use the Governor to limit user activity on the XDB Server. The settings you enter for the Governor can affect performance. The more frequently the Governor checks a user's activities, the slower the XDB Server will run. There is a trade-off among frequency of checking, performance, and how long the Governor will wait before terminating a user session.

Every n seconds, the Governor checks the status of the various options against actual server activity. Because the monitoring is not constant, the limits you set could be slightly exceeded before the Governor ends the user session. For example, a user might actually make 104 engine calls before the Governor sees that the user was allowed only 100 engine calls. You can make the Governor more accurate by setting the frequency for checking higher (such as every 10 seconds as opposed to every 30 seconds). However, there is a performance penalty for more frequent checking. See the chapter Server Configuration Utility for information about setting the governor cycle time.

Parent topic: Improving Production Processing


Miscellaneous

Some general guidelines that can improve processing speed include the following:

  • Close queries as soon as possible.
  • Commit transactions as soon as possible.
  • Change to dirty read (DR) when doing read-only operations where reading uncommitted changes are acceptable (some report writing, for example).
  • Balance work between the client CPU and the XDB Server CPU. For example, try to minimize ORDER BYs and aggregates. When writing COBOL programs, take advantage of the COBOL sort facility (which can process on the client's workstation) instead of using ORDER BY (which processes on the XDB Server).
  • To improve batch processing speed, consider turning off auto commit and forward logging if the process can be easily re-run.
  • When using embedded SQL in a program (any language), and you are executing many similar queries (same structure, but different values), use a PREPARE statement and multiple EXECUTE statements. For example, specify one PREPARE to set up the structure. Then EXECUTE repeatedly using different host variables for each.
Parent topic: Improving Production Processing


Reducing Disk I/O Contention

The XDB Server allows a single database to span multiple physical devices, as long as no single object of the database spans more than one physical device. Thus, while no database object (table or index) can exceed the size of its physical storage device, objects can be spread among many devices to reduce I/O contention.

For example:

  • Table Placement.

    Ideally, each table should be stored on a different disk drive so queries requiring access to multiple tables will not create I/O contention on one disk. If there are more tables than disk drives, tables can be arranged such that those least likely to be accessed in the same query would be grouped together.

  • Index Placement.

    Generally, indexes should not be placed on the same disk drive as other information (tables or indexes) that will likely be accessed by a query that uses the index. Some indexes, however, can be placed with any other object without creating disk I/O contention.

    If an index is used for list prefetch or an index contains coverage for a particular table (all columns referenced for a particular table are within the index), the index will not be accessed at the same time as the base table. See the section Optimizing Query Processing for more information on list prefetch. Thus, all indexes used for list prefetch can be placed on any physical device because these indexes are accessed once, and only once, during the processing of a particular query. Likewise, an index which contains full coverage and is not involved in a join will be the only object accessed in a particular query, and thus could be placed on any physical device as well.

  • Temporary File Placement.

    Temporary files should be written to or read from a disk drive other than the one used to store data and indexes, or a drive containing data that is little used by most queries. Temporary files are created when the SQL engine performs a sort that overflows the configured Sort Space Size (as specified in the Configuration Utility). Operations that perform sorts include CREATE INDEX statements and SELECTS that involve DISTINCT, ORDER BY, UNION or GROUP BY.

The guiding principle in determining object location is to spread the workload evenly among the drive controllers and disk heads. If disk head movement can be kept to a minimum and drive controller usage evenly dispersed, optimal performance can be obtained. Table and index caching can improve performance even more. See the section Improving Production Processing for more information.

Given that the server stores database objects in separate files, tuning of database object locations can be done at any time. By simply copying the database object file to a different physical device and updating the stogroup or environment variable pathname for that particular database object, different space allocation strategies can be tested.

Paths for stogroups are maintained in the SYSIBM.SYSVOLUMES table. If a table space was created without specifying a stogroup, the table space's path will be that of the database (either ..\loc-path\dbname or the path of the stogroup that was used to create the database). For greatest flexibility, each table should be associated with its own stogroup (drive and path) when it is created.

Paths for indexes and other objects can be specified in environment variables in the server machine's configuration file. (See the chapter Environment Variables for more information.)

Guidelines on how to position tables, indexes and temporary files are provided on the following pages.

  • Positioning Tables
  • Positioning Indexes
Parent topic: Improving Production Processing


Positioning Tables

Each database table can be associated with a physical device (drive and path) by using a stogroup and table space concept similar to that of DB2.

A stogroup is defined and associated with a physical device (drive and path). A database is then created using a particular stogroup. By default, any table subsequently created within that database is placed physically on the device (drive and path) specified by the database's stogroup.

To distribute tables to various disk drives, table spaces and stogroups are created. Each table space is associated with a stogroup, which in turn is associated with a drive and path. When a table is created, a table space can be specified, thus physically placing the table on the drive and path that is associated with the named table space.

For example, the following CREATE commands will create two stogroups (named STOR1 and STOR2) on two separate disk volumes (named MINE and YOURS). The UPDATE commands will define the disk drive and directory for each. (The directories must be created ahead of time using the operating system MAKE DIRECTORY (MD) command.)

CREATE STOGROUP stor1 VOLUMES (mine) VCAT xdb;
CREATE STOGROUP stor2 VOLUMES (yours) VCAT xdb;
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y" ,
        XdbVolPath = "d:\stor1\"
    WHERE Volid = "mine";
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y" ,
        XdbVolPath = "e:\stor2\"
    WHERE Volid = "yours";
Note: The fields XdbPrimeVolPath and XdbVolPath are XDB Server extensions to the SYSIBM.SYSVOLUMES table. These columns do not appear in DB2.

To complete the example, you would use CREATE commands such as the following to specify storage locations for objects you create, in this case tables.

CREATE DATABASE xyz STOGROUP stor1;
CREATE TABLESPACE abc in DATABASE xyz
    USING STOGROUP stor2;
CREATE TABLE firsttable
    (fld1 SMALLINT, fld2 CHAR 1)
    IN xyz;
CREATE TABLE secondtable
    (fld1 SMALLINT, fld2 CHAR 1)
    IN xyz.abc;

The table FIRSTTABLE will reside on d:\stor1 because it uses the stogroup defined for the database. The table SECONDTABLE will reside on e:\stor2 because it uses the stogroup defined for the table space. If desired, you can create a separate table space for each table, each with its own associated stogroup/path.

To move a table to a different device, copy the *.tab file to the desired drive and path, and update the path name for the associated stogroup in the SYSIBM.SYSVOLUMES table. If the index files (*.idx and *.ptr) are stored with the tables and do not have special paths defined for them in environment variables, be sure to copy them along with the related table. (See the section Positioning Indexes for more information about moving indexes.)

See the SQL Reference for more information about the storage architecture (including examples) and the commands shown here.

Parent topic: Reducing Disk I/O Contention


Positioning Indexes

An XDB index can be stored on a physical device different from the device where its related tables are stored by using an environment variable and an extension to the VCAT parameter of the CREATE INDEX command.

  • To store each index on its own path, use the XDB_index-name_ location-name environment variable to specify the path for storing each index. Then create each index using the VCAT NAME option on the CREATE INDEX command (using the index-name specified in the environment variable). If a qualifier is required for the index, you can enter a two-part name such as XDB_eric.orderidx_location1.
  • To store all indexes for a given location on the same path, use the XDBIDX_location-name environment variable to specify the path for storing all indexes for the location. Then create indexes for the location using the VCAT PATH option on the CREATE INDEX command.

For example:

  1. Enter the environment variable XDB_index-name_location-name in the computer's configuration file to specify a drive and path. You can create one or more index paths, such as:
    SET XDB_customerindex_location1= d:\indexes\customer
    SET XDB_ordersindex_location1= d:\indexes\orders
  2. Reboot.
  3. Create the indexes with the VCAT NAME parameter, as follows:
    CREATE INDEX customerindex ON customer(c_no)
    USING VCAT NAME;
    CREATE INDEX ordersindex ON orders(o_no)
    USING VCAT NAME;

    The VCAT NAME option causes the XDB Server to check the environment variable for the drive and path to use when creating the index. XDB index files are placed on the path associated with the environment variable for that particular index.

To move an index to a different device, simply copy the *.idx and *.ptr files to the desired drive and path, and change the path specification in the XDB_index-name_location-name or the XDBIDX_location-name environment variable. If the index path is not specified in an environment variable, then the index files must be in the same path as the related table.

See the CREATE INDEX command in the SQL Reference for more information about VCAT NAME and VCAT PATH. See the chapter Environment Variables for more information about the index environment variables.

Parent topic: Reducing Disk I/O Contention


Increasing Data Import Speed

The SQLWizard Import Utility provides interactive and batch capabilities for transferring data from various formats into tables, including the DSNTIAUL format that can be generated from mainframe DB2 data. The DSNTIAUL format stores data in its internal DB2 representation, thus requiring little or no conversion before insertion into the database.

One additional feature is available in the Import Utility, to speed the processing of import data even more, called Direct Write. This option bypasses all referential integrity features normally imposed by the SQL engine and eliminates all engine overhead that would be encountered during normal record insertions. Instead, information is written directly to the table file. This method of data loading achieves maximum performance.

See the SQLWizard User's Guide for more about the Import Utility and the Direct Write Import feature.

Parent topic: Performance Tuning


Improving Performance During Object Creation

XDB bufferpool caching is consolidated into a buffer management system. Instead of specifying separate cache sizes for table, index and dictionary buffers, a single unified cache size is specified for all accessed locations. The server also provides tuning options for improving the speed at which tables and indexes are created, as well as performance improvements that depend on the methods or options used during object creation. These include:

  • Specifying cache size
  • Using clustered indexes
  • Specifying the percentage of free space for indexes (read-only environments)
  • Specifying the blocking factor for duplicate Record IDs
  • Specifying sort buffer size
  • Buffer Management System
  • Clustered Indexes
  • Read-Only Environments
  • Block Size for Duplicate Record IDs
  • Sort Space Size
Parent topic: Performance Tuning


Buffer Management System

The buffer manager is designed to enhance performance. The buffer manager uses sophisticated search and toss algorithms and is tightly integrated with the log manager. You configure buffer manager memory as a single buffer as opposed to specifying memory amounts for each database object type. This single buffer manager handles access to tables, indexes and dictionary information, and simplifies configuration by allowing more intelligent cache use. Memory is allocated by the cache manager at server start up and released at server shut down.

Use the Configuration Utility to specify the cache size at the server level, and to set the checkpoint frequency parameter, which controls periodic purging of logging system cache. See the chapter Server Configuration Utility chapter for information.

Parent topic: Improving Performance During Object Creation


Clustered Indexes

In read-only environments, or for any table that does not have frequent inserts, it might be beneficial to define a clustered index. (You can have only one clustered index per table.) Specifying the CLUSTER option on the CREATE INDEX command gives you the option to later reorganize (re-order) the table's records into the same sequence as the related clustered index. For example:

CREATE INDEX pnoindex ON part (pno) CLUSTER

To reorganize the table's records into the same sequence as the clustered index's Record IDs, you must use the SQL COMPACT command with the CLUSTER BY INDEX option. For example:

COMPACT TABLE part CLUSTER BY INDEX pnoindex

Determining how often a table needs to be reorganized depends on how often records are added (inserted). The server leaves records in place when an update is issued (maintaining the order of records), but always inserts new records at the end of a table. A table that has many inserts would therefore need a reorganization more often than one that has few inserts.

Note:

If an update is made to the clustering key, the order of records in the table may be compromised. Use COMPACT to correct this situation.

See the CREATE INDEX and COMPACT command descriptions in the SQL Reference for more information about clustered indexes.

Parent topic: Improving Performance During Object Creation


Read-Only Environments

In a read-only environment, you can create all indexes with the parameter PCTFREE 0. This parameter allows all index blocks to be filled to capacity, thus reducing the size and number of index levels. This reduction in size allows faster index creation and searching.

Parent topic: Improving Performance During Object Creation


Block Size for Duplicate Record IDs

A blocking factor for duplicate key Record IDs can be specified using the DUPQTY parameter on the CREATE INDEX command. For best performance, the DUPQTY parameter for each index should closely resemble the index's distribution of duplicates. Indexes with high duplicate content should have high DUPQTY blocking factors, while more unique indexes should have low DUPQTY blocking factors.

Parent topic: Improving Performance During Object Creation


Sort Space Size

The XDB Server performs sorts in a variety of situations, such as the processing of ORDER BY, DISTINCT, UNION and other clauses that appear in SQL statements. Creating or rebuilding indexes, and re-clustering with the COMPACT command requires a significant amount of sorting.

To enhance sorting operations, you can set the amount of memory that the XDB Server will attempt to acquire for this purpose (use the XDB Configuration Utility). You might want to specify a higher amount when creating indexes or compacting/reclustering tables, and set it back to a lower amount for normal operations. The higher the number, the faster large sorts can be processed. Also, larger amounts of data can be processed at a single pass, thus requiring fewer merges of data. However, if set too high relative to the number of concurrent sorts, users or available RAM, processing of queries can be slowed.

The amount you allocate for sorting is the amount of memory that will be made available for each sort request that the system receives. This is not a common pool for all users, but rather a per-sort amount. If a particular sort request does not require the full amount allocated, the excess is released back to the operating system.

Parent topic: Improving Performance During Object Creation


Administrative Performance Tools

The following tools can help you determine how queries are being processed, how memory and cache are being used, and other performance-related information.

  • Virtual Statistics Tables
Parent topic: Performance Tuning


Virtual Statistics Tables

Virtual statistics tables allow you to run SQL queries against a snapshot of server usage data. The kinds of information you can extract depends on the query you construct and run against these special tables. For example, you can create such information as:

  • The number of users currently logged in.
  • A list of logged in users; most recent first (or last).
  • A list of users who have more than one query open and in repeatable read isolation level.
  • Number of users doing joins in a particular location.

The Virtual Statistics Tables contain dynamic information about the state of the server. The tables are populated when they are queried to give you current information. Apart from their dynamic nature, they can be accessed just like normal system tables, using joins, conditional clauses, sorts, aggregate functions, etc. Some of the information in these tables duplicates the data displayed on the various server screens, while some display other kinds of information.

All of the Virtual Statistics Tables have the AuthID XDBSTAT and are created (when queried) in the DSNDB07 database. They have no indexes. The format and content of the Virtual Statistics Tables are defined in detail in the SQL Reference. Examples of queries that can be run against these tables to extract information are presented below and on the next page.

  • Example: Number of Users Currently Logged In
    SELECT COUNT(DISTINCT nodename)
    FROM xdbstat.userlist;
  • Example: List of All Users, Most Recent First
    SELECT * FROM xdbstat.userlist

    ORDER BY attachts desc;

  • Example: List of All Users Having Greater than One Query Open in Repeatable Read (RR)
    SELECT username||"@"||nodename
    FROM xdbstat.userlist a, xdbstat.userresources b
    WHERE a.username = b.username
      AND a.nodename = b.nodename
      AND b.numqds >1
      AND a.ilevel = "RR";
  • Example: Number of Users Doing Joins in System Location
    SELECT COUNT(*)
  FROM xdbstat.queryinfo
  WHERE locname = "SYSTEM"
    AND numtables > 1;
Parent topic: Administrative Performance Tools


Location Management

This collection of topics provides information on configuring XDB Server and managing security, access, concurrency, locking, backup and recovery.

  • Security and Access Control
  • Transaction Processing
  • Concurrency Control
  • ROLLFORWARD Logging
  • Location Backup Options
  • Location Recovery and ROLLFORWARD
  • Distributed Processing
Parent topic: SQL Option Server Administration Guide


Security and Access Control

Table access may be performed interactively, or through a program running in batch mode, or through a CICS or IMS transaction. In all cases it is necessary to control access to the system and to the data stored in table objects. The XDB Server controls access to the system using Authorization IDs (AuthIDs) and passwords. The XDB Server controls access to location objects using privileges. The XDB Server supports both explicit and implicit privileges.

  • Turning Security On
  • User Control
  • Logging On to the XDB Server
  • Ownership
  • Granting and Revoking Privileges
  • Authorization IDs
  • Special Registers
  • Security for Distributed Processing
  • Auditing System Usage
  • The DSNDB06 Database
  • The XDBACF Database
  • Additional Security Information
Parent topic: Location Management


Turning Security On

The XDB Server provides various levels of security, including the ability to turn security on or off. When the XDB Server is initially installed, security is turned off by default. With security off, the system does not require a valid user ID or password to sign on to the system, nor does it check to see whether a user has privileges to perform an operation.

Security is turned on or off through the Configuration Utility. Turning security on or off is usually the responsibility of one of the database or system administrators, rather than of the individual user.

When you turn security on from a client you can also define a password enforcement level, which establishes rules for creating passwords, including password length, and permitted characters.

Once security is turned on you will usually be required to provide a valid user ID and password before you can connect to the system.

If security is on you must have authority to perform certain tasks.

Parent topic: Security and Access Control


User Control

You use theSQL Wizard to add new AuthIDs and GroupIDs to the system, and modify existing information, including passwords The information is stored in the system catalog, as described below. The SQL Wizard can also be used to make an AuthID a member of a group, so that the AuthID has the privileges of the group.

Note: It is possible to temporarily deny an AuthID access to the system by turning off access authority through the SQL Wizard (or by editing the appropriate row of the SYSXDB.SYSACFUSERS table). This method keeps all privileges and memberships intact. See the chapter Multiserver Security for various ideas on setting up security when using multiple XDB Servers.
Parent topic: Security and Access Control


Logging On to the XDB Server

If security is on, when you attempt to access the XDB Server or a local XDB Server, most programs will ask you to log on to the system. Usually you will see a window requesting a user name (or AuthID), followed by a password. When writing your own programs you can modify the log on procedure to meet your needs. This is described in the documentation for the language interface you are using.

Parent topic: Security and Access Control


Ownership

Implicit privileges exist for the owner of an object. For example, the owner of a table has all privileges on that table, including the privilege to drop or alter it. The default owner of an object is the SQLID at the time the object is created. However, a different owner can be recorded by using an AuthID to qualify the object (in the form creator-authid.object-name) when creating the object. For example, using the table name smith.orders when issuing a CREATE TABLE statement creates a table called orders that is owned by the AuthID smith. For additional information on ownership of a particular object, see the appropriate CREATE statement in the command reference topic of this manual.

Note:

If security is turned off, the server uses the default SQLID of the client as the creator of any database objects, and the grantor of privileges.

Parent topic: Security and Access Control


Granting and Revoking Privileges

Explicit privileges are conferred using the GRANT statement, and can be canceled using the REVOKE statement. Both are documented in detail in the command reference topic of this manual. Because the server provides a wide range of privileges covering database objects, components and activities, very precise control over data is achievable. For example, a user can be granted privileges to update, insert or delete rows of a table, to alter the structure of a table, to retrieve data from a table, and so on.

Privileges are generally associated with an object type. (For example, there are table privileges and database privileges.) In addition there are a number of special administration authorities used to confer comprehensive sets of privileges to certain types of users. See the chapter Security and Authority, and the topics on GRANT and REVOKE in the SQL Reference for more information. Included in these types of authorities are database administrator (DBADM), and super user authorities.

Information on privileges and authorities is stored in the system catalog tables. Each location stores privileges on objects within the location. In addition, the SYSTEM location stores information on administrator authorities for the system and for each location.

Parent topic: Security and Access Control


Authorization IDs

An Authorization ID (AuthID) is a string from one to eight characters long. While AuthIDs may logically represent a person, an organizational group, or a function, the server only acknowledges the unique AuthID string itself as the owner of a privilege or database object.

The XDB Server supports three types of AuthIDs to administer security: Primary AuthID, GroupID and SQL AuthID (SQLID). Individual Primary AuthIDs can also be mapped to something called a SecondaryID, which replaces the Primary AuthID as soon as the user logs in to the XDB Server.

How an AuthID is used at a given time determines the type of the AuthID. A given AuthID may be the Primary AuthID for one process, the SQLID for another, and a GroupID for a third. In order for an AuthID to be used as a Primary AuthID, however, it must be registered through the SQL Wizard. See the chapters Security and Authority and Multiserver Security for a full treatment of security issues.

  • Primary AuthID
  • SecondaryID
  • Group or GroupID
  • SQL AuthID (SQLID)
Parent topic: Security and Access Control


Primary AuthID

The Primary AuthID is the AuthID used to identify a process to XDB. Primary AuthIDs, and must be registered through the SQL Wizard. They are typically used with a password to verify that the user is actually entitled to use that particular AuthID. Note that while a Primary AuthID is usually associated with an individual, it might be used by a group of people. For example, if several users will be using a system at different times, they might all be able to log on using the same AuthID and password.

Generally, it is recommended that each individual who accesses the system be assigned a unique AuthID and password. In this way the system is able to maintain more accurate records of who is actually using the system, and password security is more effective because the passwords are not shared. If security is off, the default Primary AuthID stored in the client configuration is used for internal system identification. This default can be modified through the Options Utility.

Parent topic: Authorization IDs


SecondaryID

When the SQL Wizard is used to create a Primary AuthID (with its corresponding password), you are also allowed to specify a SecondaryID. If a SecondaryID is defined, it is used instead of the Primary AuthID to determine the actual privileges available to the session.

Once the user or process logs in, the value defined for the SecondaryID is used wherever the Primary AuthID would normally be used. It is as though the user or process had logged in using the SecondaryID instead of the Primary AuthID. For example, the SecondaryID appears in the special register USER, which normally contains the Primary AuthID of a session.

Note: The SecondaryID is not the same as the DB2 Secondary Authorization ID. The IBM method of defining multiple Secondary Authorization IDs and assigning them to Primary AuthIDs in RACF is similar to the GroupID concept.
Parent topic: Authorization IDs


Group or GroupID

Often an individual using a database system to perform a function is just one of many people who are authorized to perform that function. Rather than granting the privileges necessary to perform the function to each person, the privileges can be granted to an AuthID associated with a group, known as a GroupID. A GroupID is a special identifier that can be assigned to one or more Primary AuthIDs. The privileges granted to the GroupID are available to every Primary AuthID to which the GroupID is assigned.

Individual users can still log in using their own Primary AuthID, but because they are members of a group (with specifically defined privileges), they also possess the group privileges. A Primary AuthID can be a member of several groups -- in which case the AuthID possesses the combination of privileges granted directly to the Primary AuthID, plus the privileges defined for each group to which the Primary AuthID belongs.

All GroupIDs are recorded in the SYSXDB.SYSACFGROUPS table in the SYSTEM location. The relationship between a Primary and GroupID is established in the SQL Wizard by making the Primary AuthID a member of the group. The concept of the GroupID in the XDB Server is analogous to the Secondary Authorization ID in DB2.

Parent topic: Authorization IDs


SQL AuthID (SQLID)

The SQLID (also called SQL Authorization ID in DB2) is the AuthID used as the implicit qualifier for a table, view or index name in dynamic SQL statements, and for authorization checking of dynamic SQL statements. It also performs a special role as the default creator for CREATE statements, and as the grantor for GRANT statements.

Initially the SQLID is the Primary AuthID of a session. If a SecondaryID exists, the SQLID (and the Primary AuthID) is set to the SecondaryID. The SQLID in use by a particular user or process can be changed using the SET CURRENT SQLID statement, or through a Security User Exit. See Security User Exit for more information. See the SQL Reference for more information on the SET CURRENT SQLID statement. Usually the current SQLID must be the Primary AuthID, SecondaryID, or a GroupID of the session.

If security is off, the default Primary AuthID stored in the client configuration is used for internal system identification. This default can be modified through the Options Utility.

Parent topic: Authorization IDs


Special Registers

The XDB Server provides two special registers to store Authorization ID information. These registers can be used like column names in SQL commands.

USER

This register stores the Primary AuthID for the process. Note that if a Secondary AuthID exists for the Primary AuthID, the Secondary AuthID will appear in this register instead. If security is off, the Primary AuthID set through the Options Utility will appear in this register.

Current SQLID

This register is initially set to the value of the register USER. This register reflects the execution of a SET CURRENT SQLID command.

Parent topic: Security and Access Control


Security for Distributed Processing

Security for distributed processing is controlled by the AuthID privileges that have been granted in each location, regardless of which XDB Server controls the location. For a user to be able to access objects or data in a location other than his default location, his AuthID must have privileges at that other location for the objects he is accessing.

Parent topic: Security and Access Control


Auditing System Usage

The system catalog table called SYSXDB.SYSUSAGE audits system usage. If the Utilization Monitor is turned on at a user's workstation (using the Options Utility), the table stores audit information for that user's sessions, including location start time, end time, Primary AuthID, number of illegal access attempts, etc. To track utilization for all users, the Utilization Monitor must be turned on at the server using the XDB Configuration Utility. This overrides the Utility Monitor settings of individual users.

Note that the SYSXDB.SYSUSAGE table exists in the DSNDB06 database of the SYSTEM location only. Because of the overhead involved in maintaining the utilization data, this table should be purged periodically. See the chapter Server Configuration Utility, or the Options User's Guide for information on periodically purging the SYSXDB.SYSUSAGE table.

Parent topic: Security and Access Control


The DSNDB06 Database

Every location contains a set of system catalog tables, stored in the DSNDB06 database. The system catalog contains the following security-related tables, which store various types of authorities and privileges:

  • SYSIBM.SYSDBAUTH (Database Authorization)
  • SYSIBM.SYSUSERAUTH (User Authorization)
  • SYSIBM.SYSTABAUTH (Table Authorization)
  • SYSIBM.SYSCOLAUTH (Column Authorization)

Provided that you have the necessary authority, you can query these tables in the same way you would query any data table.

Parent topic: Security and Access Control


The XDBACF Database

The SYSTEM location contains a database called XDBACF (XDB Server Access Control Facility), which contains the following tables:

  • SYSXDB.SYSACFUSERS

    Contains a list of all users, including AuthIDs and Passwords for each user.

  • SYSXDB.SYSACFGROUPS

    Contains a list of all GroupIDs that have been defined.

  • SYSXDB.SYSACFMEMBERS

    Contains a list of users and the GroupIDs they are authorized to use. Each user (Primary AuthID) may have several entries, one entry for each group ID that the person is authorized to use.

See the SQL Reference for detailed information about the contents of these tables.

Parent topic: Security and Access Control


Additional Security Information

For more information on security, consult the references listed in the following table:

Document Topics
SQL Reference
  • SQL Commands
  • System Tables
The on-line help or the SQLWizard User's Guide
  • User Administration
Server Administration Guide
  • Configuration Utility
  • Security and Authority
  • Server-to-Server Connectivity
  • Multiserver Security
  • Security User Exit
  • AuthID List User Exit
Parent topic: Security and Access Control


Transaction Processing

A transaction is an atomic sequence of database operations. When a transaction is executed, either all or none of the operations are performed. The logging system automatically retains all table changes for any transaction in progress until that transaction is either rolled back or committed.

  • Committing a Transaction
  • Rolling Back a Transaction
Parent topic: Location Management


Committing a Transaction

When all of the data changes in a transaction are complete, commit the transaction using the COMMIT command. The effect of the COMMIT command is to request the system to accept permanently all of the data changes made by the transaction. The point of time at which the COMMIT operation occurs is known as a commit point. Normal exit from an XDB utility or application program causes the system to perform an implicit COMMIT. Alternatively, setting the autocommit feature causes all commands to automatically commit upon execution. See the section Autocommit for more information.

Parent topic: Transaction Processing


Rolling Back a Transaction

Sometimes an unacceptable condition is detected by a user or by the system after some changes have been made to the data. Additionally, two or more concurrently executing transactions could enter into a deadlock waiting for each other to release locked objects, and the system may force one of the transactions to abort. In all cases, all changes made to the data by an aborted transaction must be reversed in order to maintain the data in a consistent state. If the system detects a problem that requires the transaction to abort, it automatically reverses all the changes made to the data by the transaction. If the transaction decides to abort itself, it is the responsibility of the transaction to request a rollback of all changes it made to the data.

When a transaction is to be aborted, all of the changes made to the data during the current transaction must be undone. The ROLLBACK command is provided for this purpose. The effect of ROLLBACK is to undo all of the changes made to the data since the transaction began. Starting the server after a system failure triggers an automatic ROLLBACK of any incomplete transaction.

Note:

The XDB Server does not roll back or recover the Data Control Language (DCL) commands such as GRANT and REVOKE; or utility commands such as SET and DROP TABLE. When working in a production environment, it is recommended that you back up your location before and after such commands.

A program may contain multiple transactions. The first transaction begins when the program starts, and ends with either a ROLLBACK or COMMIT command. Subsequent transactions begin with the last COMMIT or ROLLBACK command, and end with the next COMMIT or ROLLBACK command.

Parent topic: Transaction Processing


Concurrency Control

Concurrency is the ability for multiple transactions to access table resources simultaneously. An integral consideration of data consistency is ensuring that changes made by one user do not negatively affect other users.

Locking is the method used to address both data consistency and concurrency requirements. A trade-off exists between database consistency and concurrency. It is necessary for the locking scheme to strike some sort of balance between consistency and concurrency.

The XDB Server controls concurrency by implementing locking schemes with choices of isolation levels. Each user may select the desired level of data locking.

  • Locking
  • Isolation Levels
  • Lock Compatibility
  • Timeout and Deadlock
  • Autocommit
Parent topic: Location Management


Locking

Locks have three basic attributes: object, mode and duration. Lockable objects include records and tables. Lock modes are shared and exclusive. Duration refers to the length of time a lock is held. Duration is dependent on the type of object locked, the lock mode, and the isolation level currently established.

The XDB Server supports automatic record level locking (R locks). Programs never have to request record level locks explicitly. The server can lock one record at a time, rather than a minimum of a page or block of data, which might result in reduced concurrency among users. In addition to record level locking, the XDB Server provides table locking. Table level exclusive (TX) and table level shared (TS) locks are acquired by using the LOCK command.

The server provides both shared and exclusive locks. In general, shared locks (S locks) are placed on an object when the object will be read only (not updated). This type of lock prevents any other transaction from changing the locked record for the duration of the lock. Other transactions may still read the locked record. The release of shared locks depends on the type and isolation level of the lock.

Exclusive locks (X locks) must be acquired before an object can be changed. When an exclusive lock is held on an object, no other transaction can reference the locked object. Exclusive locks are generally held until the end of the transaction that owns them (or until the transaction issues a COMMIT or ROLLBACK command).

Intentional table level locks will also be automatically acquired by the server. Before any shared record lock is granted, the server first places an intentional share lock (IS lock) on the table. Similarly, the server places an intentional exclusive lock (IX lock) on the table before an exclusive record lock is granted.

Parent topic: Concurrency Control


Isolation Levels

The isolation level in effect determines the manner in which locks are acquired and released by the system. The XDB Server provides the following isolation levels:

  • Level 1: Exclusive Use (EU). At Level 1 the system locks an entire location for the exclusive use of the current user. In essence, the system is operating in single user mode. This level of isolation should be used when performing such tasks as compacting the location, backing up the location, and recovering the location.
  • Level 2: Repeatable Read (RR). Level 2 guarantees that records read will not have been changed by another transaction from the time a lock is acquired on an object until the end of the transaction; that is, at this level of isolation all locks are held until the transaction is either committed or rolled back. This level provides a high degree of consistency and a relatively low degree of concurrency.
  • Level 3: Cursor Stability (CS). Cursor Stability is the default server isolation level. Under Level 3 exclusive locks are retained until commit or roll back, but record level share locks are released when the cursor leaves the record. The system automatically handles the release of all record locks types. This level of isolation provides less consistency and more concurrency than the RR level of isolation.

    The CS level of isolation is often used in combination with autocommit off by interactive applications where users may browse through records one at a time. In such an environment it is only necessary to maintain a lock on a record if the record is modified in some way. After the user moves to the next record, locks on unchanged records are released.

    Level 4: Lock Current (LC). At Level 4 the system acquires a lock when a record is referenced, but holds the lock only until the cursor moves to the next record. Note that exclusive locks are also released when the cursor moves to the next record; therefore this level should be used for read-only transactions, or used only when autocommit is turned on. Autocommit generates a commit command after each update takes place.

    Level 5: Dirty Read (DR). At Level 5 the system acquires no locks on a referenced record. The transaction operates in read-only mode and cannot make changes to database objects. This isolation level can be used to generate reports without delays while the system attempts to lock records. Records read at this isolation level may reflect changes made, but not committed. Note that these changes may be subsequently rolled back.

    Level 6: Snapshot Read (SR). At Level 6 a read-only snapshot of the data is made at the time of execution. No locks are held on the data, so other users can access and make changes to the data without waiting for the transaction working at SR to complete. The transaction working at SR isolation level is assured that the data it is working with will remain the same for the duration of the transaction. The SR transaction cannot make changes to the data.

The locks described above are automatically acquired by the system. At any isolation level it is also possible to explicitly request and release table level locks using the LOCK and UNLOCK commands. Table level locks may also be automatically acquired by the system if a command that affects the table definition is issued (for example, ALTER, RENAME, CREATE INDEX). Table level locks that are held at a commit point are automatically released, therefore it is not necessary to explicitly release a table level lock.

The default level of isolation for the XDB Server is CS (Cursor Stability). In order to ensure a different level of isolation it is necessary to issue a command to reset the isolation level. The startup isolation level is set through the Options Utility. You can also temporarily change the isolation level by using the SET ISOLATION command (described in this manual) and by using the WITH clause (available in DB2 4.x and beyond) on certain SQL statements.

It is important to consider how different users' isolation level settings impact the integrity of the database. The database administrator must coordinate the isolation level requirements for all users, and define those cases in which exceptions will be permitted.

Parent topic: Concurrency Control


Lock Compatibility

A transaction can acquire a lock on an object that is already locked only if the existing lock is compatible with the lock the transaction is trying to acquire.

In the lock compatibility matrices in the following two tables, table locks are exclusive (TX) or shared (TS), record locks are exclusive (RX) or shared (RS). In addition, IX and IS table locks are set by the system automatically when RX and RS locks are placed on records of that table.

 | TX | TS | IX | IS
TX | No | No | No | No
TS | No | Yes | No | Yes
IX | No | No | Yes | Yes
IS | No | Yes | Yes | Yes
 | RX | RS
RX | No | No
RS | No | Yes

For example, assume two transactions, a and b, want to access the part table. When transaction a reads a record in the part table, the system must acquire an RS lock on the record, and implicitly acquires an IS lock on the part table. If transaction b tries to read the same record, there is no conflict, so transaction b will be granted an RS lock on the record and an IS lock on the part table. If transaction b tries to update the current record, a conflict occurs because the RS lock held by transaction a, and the RX lock required by transaction b are incompatible.

The deadlock avoidance mechanism takes one of the following actions:

  • Permits transaction b to wait a user-defined period of time, during which the system periodically attempts to acquire the lock. If, by the end of the timeout period, the system has not acquired the RX lock for transaction b, the transaction must be rolled back and retried (if desired).
  • Withdraws the lock request immediately if it is determined that granting it might possibly result in a deadlock situation. Transaction b must be rolled back and retried (if desired).

However, if transaction b tries to update a different record in the part table, the system will acquire an RX lock on the record, and an IX lock on the table, and transaction b can be completed successfully. If transaction a had explicitly requested a TS lock on the part table, transaction b would not be allowed to update any record in the table, since both TX and IX locks are incompatible with a TS lock.

Parent topic: Concurrency Control


Timeout and Deadlock

The timeout period refers to the length of time a transaction waits to acquire a lock before it gives up. A deadlock occurs when two or more transactions are waiting for each other in a cyclic fashion.

When a transaction is waiting for a resource that is locked by another transaction, it waits until one of the following occurs:

  • The lock is granted.
  • The end of a timeout period occurs.

It is the responsibility of the program to roll back changes already applied, thereby releasing all locks. When a lock is not granted, a lock error message is returned to the program.

If the timeout period concludes before a lock is acquired, the transaction may perform other processing before attempting again to acquire a lock. Alternatively, it may roll back the entire transaction and retry it later. It is the responsibility of a program to retry a transaction that has been rolled back.

The timeout period is measured in seconds and can be set in the client configuration.

Parent topic: Concurrency Control


Autocommit

To shorten the length of time a lock is held and to reduce network overhead while maintaining a reasonable degree of database consistency, configure the system to automatically commit a command as soon as it is executed. Autocommit increases concurrency by immediately committing commands that change tables within a location. Since the transaction is a single command long, the use of ROLLBACK is limited to occasions when a failure occurs that automatically triggers a rollback. When using autocommit, it is important to remember that while you cannot explicitly roll back a transaction, the system is able to roll back a failed command.

For example, under autocommit, if you issue an UPDATE command from within the SQL Wizard, the command is executed and immediately committed if successful. If you issue a ROLLBACK command at this point, it will not roll back the completed UPDATE command; on the other hand, other programs do not wait for you to either explicitly commit the update command or exit from the SQL Wizard before they can acquire locks on the records you just updated.

If a system failure occurs during the UPDATE command (for example, the power goes off), the partially completed update command will be automatically rolled back when the system restarts. If the server discovers that an application node has failed, the server automatically rolls back any incomplete transaction belonging to the failed node.

When working at the LC (Lock Current) isolation level, autocommit should be turned on. The combination of the LC isolation level and autocommit are particularly useful in interactive processing. When a record is updated, inserted or deleted, the change is immediately committed, and all locks released.

Autocommit can be turned on or off through the Options Utility. Autocommit may also be turned on or off temporarily using the SET AUTOCOMMIT command.

Parent topic: Concurrency Control


ROLLFORWARD Logging

The logging system tracks all changes made to each location's tables since the last time the XDB Server BACKUP command was used on the location (or since the last time logging was reset for the location). The logging system maintains a separate series of log files for each location.

In the event of a serious system failure, such as a disk crash or other media failure, you can restore a backup copy of the location's tables and then issue the ROLLFORWARD command to apply the contents of the location's current log files to the restored location tables. These actions bring your tables up to date (to the time just prior to the system failure).

By default, the Forward Log path (where location log files are stored) is the same as your location path. You can and should change the name and path for your location log file storage. Ideally, log files should be placed on a different physical device than the location tables they are logging. This precaution protects against an independent media failure such as a hard disk crash.

You can change the current log path for a location by using the SET LOG command. See the SQL Reference for more information on the SET LOG command.

Location logging should be reset after using the BACKUP command to archive a location and its log files. If you use a different method to create your backups (such as an operating system BACKUP command), you can reset the location log files by deleting the current log files from your operating system prompt.

The logging system automatically creates a new series of location log files when you commence entering transactions. See the chapter Backup and Recovery for more information.

Parent topic: Location Management


Location Backup Options

The BACKUP command operates at the location level, including all paths and files for all tables in the location. Likewise, the ROLLFORWARD command, which applies the current series of location log files to a backup copy of the location data, also operates at the location level. If you have more than one database in a location and only one of those databases needs to be restored and rolled forward, you still have to restore and roll forward all of the databases in the location.

If you use an operating system backup command or other backup utility, and you intend to use the location's log files to reconstruct the data for that location, be sure that you have backed up all the files in all the paths that are defined for the location, including stogroup paths, if any. Also, be sure to reset the location logging after each backup is completed.

If your location backups are infrequent or if activity is high and the number of log files grows rapidly, you may wish to back up your location log files periodically to ensure that logging is available if you need it. Use an operating system BACKUP command or utility to back up the log files.

  • BACKUP Command
  • Other Backup Options
Parent topic: Location Management


BACKUP Command

The BACKUP command creates copies of all files that reside in the paths defined for the specified location, including paths associated with storage groups.

You can use the BACKUP command only if the location being backed up is not currently in use by you or another user. You can use the BACKUP command with or without using the roll forward logging feature.

When backing up a location you can specify whether you want to back up index files. If you need to restore a location from a backup that did not include the index files, you will need to rebuild the indexes using COMPACT LOCATION AND INDEX command.

BACKUP copies the files to the device and path you specify. This may be a tape drive, a file server, or a different disk drive. Use the Restore Utility to return the archived location to your hard disk.

Note: BACKUP does not copy files onto multiple diskettes. If the contents of the location are too large to fit on one diskette, use another backup option.

See the chapter Backup and Recovery and the SQL Reference for additional information on the BACKUP command.

Parent topic: Location Backup Options


Other Backup Options

Most commercially available archival utilities can be used to backup locations. When using a backup utility, it is important to keep in mind that you must backup the contents of all directories for the entire location, including stogroup paths (if any) and including all subdirectories. This last point is important since the server may have duplicate file names in different directories, which need to be kept separate on the backup device.

Parent topic: Location Backup Options


Location Recovery and ROLLFORWARD

If you are maintaining location log files and have made periodic backups of your location, you can usually recover from system failure by restoring the backup copies of the location files (this process copies the backed-up files into their proper directories and subdirectories in the location). Replay the current location log files against the restored location by using the ROLLFORWARD command. See the chapter Backup and Recovery for a more detailed description of this process.

Note: ROLLBACK and ROLLFORWARD do not recover Data Control Language (DCL) commands, such as GRANT and REVOKE, and utility commands, such as SET.
Note: Do not compact tables (or locations) before replaying log files. The log files must be applied to a non-compacted data object. Once a compact is performed, the current set of location log files is useless.
Parent topic: Location Management


Distributed Processing

Distributed processing is an integral part of the XDB Server architecture. It allows a session concurrent access to multiple locations. In conjunction with the multilocation architecture, support is provided for three-part object names (location-name.authid.object-name). These features allow users to access data outside of their default locations (restricted only by the security measures that have been implemented).

In a LAN environment, the locations can be distributed across various volumes on a network simply by specifying the desired path name when creating the location. Support of stogroups provides further opportunity to physically organize databases and tables (using table spaces) on specific volumes. Installation of XDB Link adds to the distributed processing capabilities by providing a transparent connection to a mainframe DB2 location using the Distributed Relational Database Architecture (DRDA) protocol.

  • Distributed Unit of Work (DUW) Processing.
  • Remote Unit of Work (RUW) Processing - XDB Locations
  • Remote Unit of Work (RUW) Processing - DB2 Locations
  • Server-to-Server Connectivity
  • DSNDDF Communications Database
Parent topic: Location Management


Distributed Unit of Work (DUW) Processing.

Use DUW processing to remain connected to your default (or current) location, and have the ability to execute a limited range of statements on data objects in another local or remote location. You can use INSERT, UPDATE, DELETE, and SELECT commands with three-part object names, while OPEN, FETCH and CLOSE commands are valid for DUW processing with embedded SQL.

An application simply uses the fully qualified name (location-name.authid.object-name) of a table or view that resides in the other location. Based on information in the system catalog tables on the current XDB Server, the request is sent to the appropriate XDB Server and data is returned.

Note:

Use of the DUW option requires that you reference no more than one location per SQL statement. If you need to work with objects in several locations, you must use multiple statements, one location per statement.

The XDB Server does not currently support two-phase commit or distributed queries.

Parent topic: Distributed Processing


Remote Unit of Work (RUW) Processing - XDB Locations

Use RUW processing to work with locations and applications at a local or remote location other than your normal (default) location. Remote locations run on another XDB Server on your network. With RUW, you are actually working at the other location. That is, the location you connect to becomes your current location.

You can specify either a local or remote location with which you wish to work by issuing the CONNECT command in embedded SQL, or the SET LOCATION TO command in interactive SQL.

Parent topic: Distributed Processing


Remote Unit of Work (RUW) Processing - DB2 Locations

This form of distributed processing operates in the same manner as the RUW for locations. If you use the SET LOCATION TO command in the SQL Wizard to attach to an XDB Link location, you can get back to a location through that same the SQL Wizard session from within that the SQL Wizard session. Within embedded SQL, a CONNECT RESET command can be used to return to a location.

XDB Link plus a few special entries in the XDB SYSTEM location's DSNDDF database are required to allow access to the mainframe DB2 Location. XDB Link provides transparent access to objects on the mainframe as though the mainframe were just another location on the server. The Distributed Relational Database Architecture (DRDA) is used in this configuration.

Parent topic: Distributed Processing


Server-to-Server Connectivity

Server-to-server connectivity allows a client accessing one XDB Server to access data in a location controlled by another XDB Server in a distributed environment. Server-to-server connectivity works only with SQL Data Manipulation Language (DML) statements, such as INSERT, UPDATE, DELETE and SELECT. Location access is done interactively, either by using a three-part-name (location-name.authid.object-name) or alias, or by using the SET LOCATION command.

Server-to-server connectivity eliminates the need to change the client configuration settings to access a remote XDB Server or DB2 location (through XDB Link). In order to access a remote location, a system administrator must maintain the system tables to reflect known locations and server names. See the chapter Server-to-Server Connectivity for further information on using server-to-server connectivity for RUW and DUW, and for server-to-server setup options.

Parent topic: Distributed Processing


DSNDDF Communications Database

Information about the local and remote locations that are accessible to users is stored in a communications database called DSNDDF in the SYSTEM location. This database contains the tables described below.

Data is entered automatically in the appropriate tables whenever a location is created with the SQL CREATE command, the XDB Server menu system, or the XDB conversion program. If necessary, you can edit these tables.

  • SYSXDB.SYSGATEWAY

    Contains information needed by XDB Link for accessing DB2 locations on a mainframe. For more information about XDB Link, see the XDB Link User's Guide.

  • SYSXDB.SYSGOVERNOR

    Contains information on the type of activities that can be performed by certain users during certain periods. See the SQLWizard User's Guide or on-line help for further information on governor features.

  • SYSXDB.SYSLOCALS

    Contains information about each "local" location, including all locations defined under the XDB Server to which this SYSXDB.SYSLOCALS table belongs.

  • SYSIBM.SYSLOCATIONS

    Contains information about all locations that are accessible for DUW and RUW processing including local locations in SYSXDB.SYSLOCALS, plus remote locations accessible using server-to-server connectivity and XDB Link. With DUW and RUW processing, any object that is referenced by a three-part name (location-name.authid.object-name) or a CONNECT command must have its location defined in this table. Remote locations may include mainframe DB2, DB2/VM or SQL/400 locations, or locations running under another XDB Server.

  • SYSIBM.SYSLUMODES

    Contains information needed by XDB Link for accessing DB2 locations. Each row provides mainframe VTAM with conversation limits for a specific LUNAME/MODENAME combination.

  • SYSIBM.SYSLUNAMES

    Contains LUNAME information needed by XDB Link and server-to-server connectivity. The table defines the name of each XDB Server if using server-to-server connectivity, or the name of the mainframe Logical Unit (LU) for one or more accessible DB2 systems if using the XDB Link. The names identified here are the same names identified in the LINKNAME column of the SYSIBM.SYSLOCATIONS catalog table.

  • SYSIBM.SYSMODESELECT

    Maintained for compatibility with DB2. Not used on XDB Server, but on the mainframe contains information for associating a MODENAME with any conversations created to support an outgoing SQL request.

  • SYSIBM.SYSUSERNAMES

    Contains user information needed by XDB Link for processing requests to and from a DB2 location, and for processing requests to other XDB Servers using XDB's server-to-server connectivity. Each row is used to carry out either an outbound or inbound ID translation or both.

Parent topic: Distributed Processing


Environment Variables

  • XDB_ index-name_ location-name
  • XDBCP
  • XDBIDX_ location-name
  • XDBINI
  • XDBNETINI
  • XDBRIDPOOL
  • XSRVCFG
Parent topic: SQL Option Server Administration Guide


XDB_ index-name_ location-name

XDB_index-name_location-name is an optional environment variable that is used in conjunction with the VCAT NAME option of the SQL CREATE INDEX command. To physically locate each index on a specific storage device (drive and path), specify a path in the [Server] topic of the xdb.ini file for each index/location combination, and subsequently create the index using the VCAT NAME option.

The format for this environment variable is:

XDB_index-name_location-name=drive-and-path

If a qualifier is required, enter a two-part name for the index-name, such as:

XDB_eric.orderidx_location1=m:\anypath

For example, to create and store an index called customerindex on d:\indexes\customer and another index called ordersindex on e:\indexes\orders (both for tables in the TUTORIAL location), you would make two entries in the xdb.ini file, and issue two SQL CREATE INDEX commands as follows:

  1. In the [Server] topic of the xdb.ini file, enter the following:
    XDB_customerindex_tutorial=d:\indexes\customer XDB_ordersindex_tutorial=e:\indexes\orders
  2. Using the USING VCAT Index Options under the Create/Alter Table function in SQL Wizard, issue the following commands:
    CREATE INDEX customerindex ON customer(c_no)
    USING VCAT NAME;
CREATE INDEX ordersindex ON orders(o_no)
    USING VCAT NAME;
Parent topic: Environment Variables


XDBCP

To support a number of non-American code page character sets, set the parameter XDBCP=codepage in the xdbsrvco.ini file [environment] group. Codepages that are directly supported are:

Number | Name
850 | MS-DOS Latin1 (used in the entire European Community except Greece)
863 | MS-DOS French Canada
865 | MS-DOS Nordic
942 | Japanese
949 | Korean
437 | MS-DOS Latin US
860 | MS-DOS Portuguese
Parent topic: Environment Variables


XDBIDX_ location-name

XDBIDX_location-name is an optional environment variable that is used in conjunction with the VCAT PATH option of the SQL CREATE INDEX command. To physically locate all indexes for a location on a specific storage device (drive and path), specify an index path in the xdb.ini file for each location, and subsequently create indexes using the VCAT PATH option.

The format for this environment variable is:

XDBIDX_location-name=drive-and-path

For example, to create and store all indexes for the TUTORIAL location in the path d:\indexes\tutorial , you would:

  1. Make the following entry in the XDB Server machine's configuration file:
    XDBIDX_tutorial=d:\indexes\tutorial
  2. Using the USING VCAT PATH Index Option under the Create/Alter Table function in SQLWizard, issue the following command:
    CREATE INDEX customerindex ON customer(c_no)
    USING VCAT PATH;
Parent topic: Environment Variables


XDBINI

The XDBINI variable specifies the directory where the xdb.ini file lives; this file contains both client and server side information for the SQL Option.

Parent topic: Environment Variables


XDBNETINI

The XDBNETINI variable specifies the directory containing the xdbnet.ini file is; this file contains the TCP/IP information necessary so SQL Option client-side software can speak to a XDB server.

Parent topic: Environment Variables


XDBRIDPOOL

XDBRIDPOOL is an optional environment variable that is specified in the [Server] topic of the xdb.ini file to enhance performance of the Query Optimizer.

The Query Optimizer may at times choose to use an algorithm called list prefetch when analyzing data access paths. This algorithm entails retrieving Record IDs (RIDs) from an index file and then sorting them. List prefetch is invoked when multiple index access is required or when data needs to be retrieved in physical order.

The format for this environment variable is:

XDBRIDPOOL=number-of-kilobytes

where number-of-kilobytes is the amount of memory to allocate for each statement's RID pool. The maximum size that can be specified is dependent on the amount of system memory that is available.

The RID Pool is the buffer that the server uses to store RIDs of this type. The default RID pool size is 512K per query. Since each RID contains 4 bytes, this default RID pool size can hold a maximum of 131,072 RIDs. If the RID pool size is exceeded, the list prefetch algorithm may be aborted, severely hampering performance.

The number of RIDs that can possibly enter the RID pool is determined by the selection criteria defined by a particular WHERE clause. A good rule of thumb for estimating an appropriate RID Pool Size is to determine the number of records that exist in the largest table, and then use the following formula:

RID Pool Size = (max records) * (.20) * (4 bytes per RID)

For example, a table containing 3,000,000 records would have an optimal RID Pool Size determined as shown below:

3,000,000 * .20 * 4 = 2,400,000 bytes

Converting this to kilobytes, we get:

2,400,000 / 1024 = 2344K

This RID Pool Size would allow an index condition that qualifies up to 20% of the table's rows to fit into the RID Pool.

The following XDBRIDPOOL environment variable setting would make available a 2400 kilobyte RID Pool per statement.

XDBRIDPOOL=2400
Parent topic: Environment Variables


XSRVCFG

XSRVCFG is an environment variable (an entry in the xdb.ini file) that indicates the drive and path on which the XDB Server configuration files reside:

  • The crvconfg.xdb file contains configuration parameters for the XDB Server as entered via the XDB Server Configuration utility.
  • The xdbsrvco file contains settings for the XDB Server logging and checkpoint features.
  • The xdbnet.ini file contains information for XDB Servers and clients who use TCP/IP.

The [Server] topic of the xdb.ini file contains various settings for the XDB Server, including the environment variables described in this chapter. If a copy of SQLWizard is on the same machine, it also uses xdb.ini to store configuration settings.

These files are usually located in the directory where the XDB Server software is installed. The XSRVCFG environment variable is entered in the [Server] section of the xdb.ini file when you install the XDB Server.

The format for this environment variable is:

XSRVCFG=drive-and-path

For example, if the XDB Server and its configuration files are located on the \xdbnt directory of the XDB Server machine (on theC drive if a Windows machine), the XSRVCFG environment variable would be entered as follows:

XSRVCFG=c:\xdbnt
Parent topic: Environment Variables


Server Files

  • Location and Database Files
  • Configuration Files
  • Help, Message and Error Files
Parent topic: SQL Option Server Administration Guide


Location and Database Files

Each location consists of a number of files and subdirectories to store location data, system catalog tables, and user-defined tables and indexes for each database in the location. Storage group (stogroup) directories might be used to organize the physical placement of some files. See the Data Storage Architecture for more information.

File Name | Description
numeric. * | Most file names are derived from the first 8 characters of their corresponding objects (location name, table name, etc.) If the first 8 characters do not produce a unique name, a random 8-digit number is generated by the XDB Server and is used as the file name.
location.ddt | Contains information on the tables in a location.
location.ddf | Contains information on the columns in tables in a location.
location.ddi | Contains information on indexes in a location.
location.ddv | Contains information on the XDB Server version.
sys*.tab | XDB Server system catalog tables. (Due to similarity of names, many system tables carry a numeric filename as explained above.)
table.tab | Contains the data stored in an XDB Server table.
index.idx | Contains index values for indexed columns.
index.ptr | Contains record pointers to duplicate occurrences of values. (Contain 0 bytes if the index is unique.)
Parent topic: Server Files


Configuration Files

There are a number of files used to store the configuration items you specify for your XDB Server operating environment. The stored configuration data are used as needed by the various XDB Server programs and utilities you run. These files generally reside in the Directory.

Other configuration files, such as config.sys, autoexec.bat or *.ini sometimes contain XDB information as well. See the appropriate installation guide for specific information.

File Name | Description
srvconfg.xdb | XDB Server environment configuration file. The environment variable XSRVCFG points to the location of this file.
product.ver | Contains version number for installed version of product. To see all .ver files found in the current directory, enter the command XDBVER on an operating system command line.
sort-sequence.seq | Pre-defined user sort sequence files that can be used in place of our standard ASCII or EBCDIC sort sequences.
Parent topic: Server Files


Help, Message and Error Files

Most XDB Server modules have help, message and error files associated with them. Generally, these files have the same file name as the module to which they refer. The extensions of these files use the following conventions:

  • Help and Message files end with the extension .hlp or .xsg.
  • Error files end with the extension .err or .xrr.

See the Error Messages book for a list and description of messages displayed by XDB Server software.

Parent topic: Server Files


Troubleshooting

This collection of topics describes troubleshooting scenarios and solutions for XDB Server, and accessing trace information.

  • Scenarios and Solutions
  • Tracing
Parent topic: SQL Option Server Administration Guide


Scenarios and Solutions

The following sections describe several trouble scenarios and their possible solutions.

  • My client cannot find my xdbnet.ini file.
  • My server-to-server TCP/IP connections are not working.
  • I get the message: Can't assign requested address bind() = 10049 when I try to bring up my XDB Server with TCP/IP threads.
  • I need to verify that a particular IP address is correct when configuring TCP/IP connections.
Parent topic: Troubleshooting


My client cannot find my xdbnet.ini file.

Ensure the xdbnet.ini file is placed in a directory pointed to by the XDBCFG or xdbnet.ini entry in the xdb.ini file. If both XDBCFG and xdbnet.ini have entries, then xdbnet.ini overrules XDBCFG.

Parent topic: Scenarios and Solutions


My server-to-server TCP/IP connections are not working.

  • First check that the basic XDB Server installation is functioning for each XDB Server by itself. If you have problems making a server-to-server connection, try connecting the client directly with each XDB Server (using the same protocol) and observe what happens. Also, if one protocol does not work for a particular connection, then try another one (if available).
  • Ensure that xdbnet.ini is built and present on your XDB Server machine.
  • Insert a single letter T (for TCP/IP) in the LINKATTR column of your SYSIBM.SYSLOCATIONS table. This single character value determines which address information in xdbnet.ini is used for the connection.
Parent topic: Scenarios and Solutions


I get the message: Can't assign requested address bind() = 10049 when I try to bring up my XDB Server with TCP/IP threads.

Ensure that your TCP/IP protocol is loaded. You may need to use the TCP/IP vendor's PING utility to help track down the problem. See the next scenario for information about using PING.

Parent topic: Scenarios and Solutions


I need to verify that a particular IP address is correct when configuring TCP/IP connections.

Use the PING utility (provided by your TCP/IP vendor) to test each XDB Server and client IP address in your Internet environment. PING takes the IP address as input and tests individual server-server, server-client and client-server machine connections for packet loss.

Perform the following PING tests to verify that your TCP/IP network connections are functioning properly:

  1. PING your XDB Server machine from your XDB Server machine.

    This verifies that your server-server machine TCP/IP connection is functioning properly, allowing local clients to both send and receive packets with your XDB Server.

  2. Because each remote client-server TCP/IP connection can employ a unique packet route in each direction across the internet, you should perform the following for each remote client that communicates with the XDB Server:
    • PING your XDB Server machine from your XDB Client machine.
    • PING your Client machine from your XDB Server machine.
Parent topic: Scenarios and Solutions


Tracing

Running a communications trace or an engine trace may help solve configuration and usage problems, and aid in performance tuning. For example, the engine trace file contains timing information that you can use to help you locate bottlenecks in your application. Micro Focus Technical Support will instruct you as to when and how to run a trace.

Contact Micro Focus Technical Support for assistance.

Parent topic: Troubleshooting


SQL Option Link Configuration Guide

  • System Requirements
  • Planning for XDB Link
  • Convening a Planning Meeting
  • Started Task Parameters
  • The Access List
  • xdbappc.ini Parameters
  • Code Page (CCSID) Tables
  • XDB Link Host Option Commands
  • Worksheets
Parent topic: SQL Option for DB2


System Requirements

Before you begin to configure your environment for XDB Link, review the following table and verify that you have the required hardware and software. Also check that your software is at the required levels.

Host System Requirements

 | XDB Link to host via TCP/IP | XDB Link to host via SNA
Hardware |  |
IBM S/390, S/370, or 100% compatible computer | Required | Required
Software |  |
MVS, Version 4.2 or higher | Required | Required
VTAM, Version 3.2 or higher | Required | Required
NCP, Version 4.3 or higher |  | Optional
IBM TCP/IP, Version 2.1 or higher or INTERLINK TCP/IP, Version 4.1 or higher | Required |
RACF or CA-ACF-2 or CA Top Secret | Optional | Optional
DB2/MVS Version 3.1 or higher | Required | Required

PC System Requirements

 |  | XDB Link to host via TCP/IP | XDB Link to host via SNA
Hardware |  |  |
80486-based microcomputer (or higher) |  | Required | Required
40-MB free hard-disk space |  | Required | Required
Network protocol |  |  |
 | TCP | Required |
Note: Minimum requirements (for native TCP/IP access) are DB2 V5.1 AND OS/390 V1R3. Review the PSP for HDB5510 and apply any PTF's applying to DDF and TCP/IP access. Complete the steps outlined in the DB2 for OS/390 Installation Guide (GC26-8970-00) chapter 3-3.
Parent topic: SQL Option Link Configuration Guide


Planning for XDB Link

After verifying that you have the appropriate hardware and software, you should do the following:

  1. Review and select the worksheets that apply to your environment. Micro Focus provides these worksheets to help you gather the information you need to configure the software on both your host system and the computer where XDB Link is installed. The worksheets also ensure that configuration values match, where necessary, across platforms and components.
  2. Convene a planning meeting.
Parent topic: SQL Option Link Configuration Guide


Convening a Planning Meeting

To launch the project, Micro Focus suggests that you schedule a meeting of the project team to plan the configuration effort and ensure that each organization understands its role in the process. The primary objectives of this meeting are to:

  • Identify who must do what and when.
  • Distribute and/or complete the worksheets.
  • Ensure that everyone has the information they need to successfully configure the component for which they are responsible.
  • Define the security measures you will implement between XDB Link and the host.

Because the configuration process involves steps on both the host and the server, some or all of the following people will need to attend:

  • VTAM systems programmers
  • Database administrators for all database systems that XDB Link will access
  • LAN system administrators
  • TCP/IP network administrators
  • Security systems administrators
Parent topic: SQL Option Link Configuration Guide


Started Task Parameters

Sample parameters are shipped in xdblink.v100.PARAM(PARMTCP). This file member contains the following definitions.

Note:

Do not use commas or periods when assigning a numeric value to a parameter.

Parameter Description
ORGANIZATION=
Specifies the organization ID of the owner of the XDB Link software license. The format is:

ORGANIZATION=org-id

where org-id is the organization ID. This parameter must be a string of up to 60 characters. There is no default.

PORT=
Specifies the port number that the Host Option will use. The format is:
PORT=port-number

where port-number is the number of the TCP/IP port dedicated to the XDB Link Host Option. This parameter must be an integer from 1 to 32767. There is no default.

BACKLOG=
 Specifies the length of the backlog queue maintained in TCP/IP for connection requests that have not yet been assigned sockets by the listener. The format is:
BACKLOG=backlog-length

where backlog-length is the length of the backlog queue. This parameter must be an integer from 1 to 32767. The default is 5.

NETWORK ID=
 Specifies the SSCP (system services control point) network ID for ACF/VTAM (the host node). The format is:
NETWORK ID=sscp-id

where sscp-id is the SSCP network ID. This must be a string of up to eight characters. There is no default.

LU6.2 APPLID=
 Specifies the APPLID (LU or ACBNAME) for XDB Link. The format is:
APPLID=applid

where applid is the APPLID for XDB Link. This is a string of up to eight characters, and equals the ACBNAME defined for the VTAM application. There is no default.

APPLID PASSWORD=
 Specifies the password of the APPLID defined in the PTRCT parameter of the VTAM APPLID definition. The format is:
APPLID PASSWORD=applid-pw

where applid-pw is the password. This must be a string of up to eight characters. There is no default.

TRACE=
 Specifies the trace facility name. The format is:
TRACE={GTF | WTOR | SYSPRINT}

This parameter can be set to GTF, WTOR, or SYSPRINT trace facilities. There is no default.

EID=
 Specifies the event ID of the GTF (Generalized Trace Facility) trace record. The format is:
EID=event-id

where event-id is the event ID of the GTF trace record. This must be a two-byte hexadecimal number (for example, 88FF), and it must match the USR value in the GTF trace parameter. There is no default.

TIME OUT FOR CONNECTION=
 Specifies the timeout period used for the TCP/IP accept call to get the connection request. The format is:
TIME OUT FOR CONNECTION=timeout

where timeout is the time out for connection in minutes. This must be an integer from 1 to 32767. Zero (0) specifies no timeout. There is no default.

COMPRESS=
 Not used.
ROUTE=
 Specifies the WTO (Write To Operator) and WTOR (Write To Operator with Reply) console route parameters.
ROUTE=(number1,number2)

Refer to the MVS/ESA SP V5 Auth Assembler Services Reference manual (GC28-1478) for descriptions of the values and their valid ranges. There are no defaults.

PRODUCT PASSWORD=
 Specifies the product password assigned for the software license. The format is:
PRODUCT PASSWORD=password

where password is the assigned product password. This is a six-byte hexadecimal number. The correct password will already be specified in this parameter, so there is no need for you to edit it. There is no default.

Example

The following is an example of a complete parameter definition. Lines beginning with "*" are comments.

****************************************************
  * *
  * XDB STARTED TASK INITIALIZATION PARAMETERS *
  * XDBLINK V1.00 *
  * *
  ****************************************************
  *
  * ORGANIZATION ID
  *
  ORGANIZATION=XDB SYSTEMS, INC.
  *
  * STARTED TASK TCPIP PORT NUMBER
  PORT=5170
  *
  * TCPIP LISTEN BACKLOG PARAMETER
  BACKLOG=5
  *
  * SNA NETWORK ID OF DB2 DDF
  NETWORK ID=USXDB
  *
  * STARTED TASK APPLID
  LU62 APPLID=XDB62APP
  *
  * STARTED TASK APPLID PASSWORD
  APPLID PASSWORD=XDB62APP
  *
  * TRACE OPTION
  TRACE=GTF
  *
  * GTF TRACE EID
  EID=00E9
  *
  * TCPIP ACCEPT TIME OUT PARAMETER
  TIME OUT FOR CONNECTION=0
  *
  * COMPRESSION OPTION
  COMPRESS=YES
  *
  ROUTE=(2,11)
  *
  * PRODUCT PASSWORD
  PRODUCT PSWD=2D0910D9A1C0
  *
  END
Parent topic: SQL Option Link Configuration Guide


The Access List

The access list in xdblink.v100.ACCESS determines whether the XDB Link Host Option accepts or rejects a packet from a particular IP address. You can use the access list to provide an extra layer of security between XDB Link and DB2. For example, you might use it to accept only packets that come from addresses on your company Intranet.

The XDB Link Host Option accepts requests from IP addresses specified by the PERMIT= parameters in the access list, and denies requests from addresses specified by the REJECT= parameters. If an address is not defined by either a PERMIT= or REJECT= parameter, a WTOR message is sent to the console, allowing the operator to reply "PERMIT" to accept the connection or "REJECT" to reject the connection.

The PERMIT= and REJECT= parameters are specified as follows:

PERMIT=IPaddress

REJECT=IPaddress

where IPaddress is the IP address in dotted decimal notation (for example, 204.177.148.255). You can mask an IP address by omitting trailing octets. For example, "PERMIT=204.177.148" accepts requests from IP addresses 204.177.148.0 to 204.177.148.255.

Examples

The following example accepts client connection requests from IP addresses 204.177.148.0 to 204.177.148.255, except for 204.177.148.244.

PERMIT=204.177.148

REJECT=204.177.148.244

The following example accepts client connection requests from IP addresses 198.202.128.18 and 98.2.82.0 to 98.2.82.255, but rejects addresses 204.0.0.0 to 204.255.255.255.

PERMIT=198.202.128.18

PERMIT=98.2.82

REJECT=204

Parent topic: SQL Option Link Configuration Guide


xdbappc.ini Parameters

The following table describes the parameters used by xdbappc.ini.

PU Definition Section

Parameter Description
PU
 Physical Unit name. This parameter must match the entry in the CSCON profile named "Peripheral CP Name."
Profile
 Profile name. This name must match the name of the profile configured with CSCON and loaded with CSLOAD.
Network
 Network Identifier. This parameter must match the entry in the CSCON profile named "SNA Network ID."
LuName
 Logical Unit Name. This is the LU name configured on the host that identifies this computer.
LuAlias
 Logical Unit Alias Name. This is the name of the LU as it will be known locally. We recommend that you use the XDB Server name as the alias.
LocAddr
 LU local address. This address must be 0 for independent LUs.
SessionLimit
 LU Session Limit. This value specifies the number of sessions this LU can have with the host. The value should be less than or equal to the entry in the CSCON profile named "Independent Sessions."
MaxTPs
 Maximum Transaction Program Limit. This entry indicates the number of transaction programs that can use this LU. It should be less than or equal to the session limit above. Each user connected through XDB Link gets an individual session and TP, so MaxTPs represents the maximum XDB Link connections possible with the host.
QueueDepth
 Depth of incoming allocate queue. This is the number of allocate requests that can be in the queue, waiting to be serviced by this LU.
PLU
 Partner Logical Unit Name. This specifies the remote database as it is known to the SNA network. For MVS/VTAM, this is the VTAM DB2 APPLID name.
Network ID
 Network Identifier. This is the name of the SNA network to which the partner LU belongs. This allows for a fully-qualified partner LU name.
Alias
 Partner Logical Unit Alias. This is the name of the partner LU as it will be known locally. The value of this parameter is used by the Gateway Profile Utility to identify the remote database.
Security
 Partner Logical Unit Security Capabilities.
  • 1 = Already Verified
  • 2 = Conversation Level security
  • 4 = Session Level security
  • 128 = Activate link to PLU at Attach LU time

Combinations of security capabilities can be added together. For Example: 3 is Conversation Level security and Already Verified (1 OR 2).

SessionLimit
 Partner Logical Unit Session Limit. This entry is the maximum number of sessions for which this partner is configured.
MaxMcSendLL
 Maximum Mapped Conversation Send Logical Length. Maximum size of data to send on a mapped conversation. The value 0 means use the largest possible value (32767).
DlcName
 Data Link Control Name. This entry identifies the connection type to the host system. Possible values are:
  • SDLC - Synchronous Data Link Control
  • ITRN - Token Ring or Ethernet
  • QLLC - Qllc connection
  • CUSTOM - Custom connection

AdaptNum
 Adapter Number. Indicates which adapter to use. For Token Ring use 0 to indicate the Primary adapter or 1 to indicate the Secondary adapter. All other DLCs should use 0.
AdaptAddr
 Adapter address:
  • SDLC - Omit this entry for this DLC type. It is not used.
  • ITRN - This is a 12-digit hexadecimal value of the locally administered address of a front-end processor (3174/37X5, PC gateway, etc.).
  • QLLC - Target name of the record in the call support layer (CSL) database defined in the NWSAA server. This entry can be up to 16 ASCII characters in length.
  • CUSTOM - Symbolic name used by the custom data link adapter. This entry can be up to 16 ASCII characters in length.

ModeName
 Mode Name. This entry is used to identify which mode definition to use for this partner LU.

Mode Definition Section

Parameter Description
Mode
 The Mode Name. The name of the mode to use for setting up sessions between the Local LU and the Partner LU. The recommended value is IBMRDB.
MaxRu
 Maximum Request/Response Unit. The maximum size (in bytes) of a Request/Response Unit.
MinRu
 Minimum Request/Response Unit. The minimum size (in bytes) of a Request/Response Unit.
MaxNegotiable
 The Maximum Negotiable Session Limit. This value is used to override the PLU max session limit.
Pacing
 Pacing Limit. The maximum number of Request/Response Units allowed before confirmation between LU and PLU.
Parent topic: SQL Option Link Configuration Guide


Code Page (CCSID) Tables

Code page files (TAB files) provided with this version of XDB Link include the following:

Decimal Rep | TAB files (Hex EBCDIC <==> ASCII)
290 - 1041 | 01220411.TAB / 04110122.TAB
300 - 301 | 012C012D.TAB / 012D012C.TAB
930 - 942 | 03A203AE.TAB / 03AE03A2.TAB
933 - 949 | 03A503B5.TAB / 03B503A5.TAB
437 - 37 | 01B50025.TAB / 002501B5.TAB
850 - 37 | 03520025.TAB / 00250352.TAB
273-37 | 01110025.TAB / 0025011.TAB
273 - 437 | 011101B5.TAB / 01B5011.TAB
273 - 500 | 011101F4.TAB / 01F40111.TAB
273 - 850 | 01110352.TAB / -352-111.TAB
500 - 437 | 01F401B5.TAB / 01B50352.TAB
500 - 37 | 01F40025.TAB / 002501F4.TAB
850 - 437 | 035201B5.TAB / 01B50352.TAB
850 - 500 | 035201F4.TAB / 01F40352.TAB

For every code page pair there are 2 TAB files having the format SSSSTTTT.TAB

where:

SSSS | is the source code page value in hex.
TTTT | is the target code page in hex.

Check to see whether the code pages you require are included in the XDB program directory. If you do not find the code pages you need, run the xcpgtab.exe program in the XDB Link program directory. This program will extract additional codes pages for the installed version of XDB Link.

If after running xcpgtab.exe you do not find the code pages you need, contact Micro Focus Technical Support.

Parent topic: SQL Option Link Configuration Guide


XDB Link Host Option Commands

Use the following commands to monitor and control the XDB Link Host Option. In the following command descriptions, stcname represents the name of the started task on MVS.

/F stcname, DISPLAY STATUS
 Displays the DB2 LU status, the conversation status, and the status of the started task.
/F stcname, DISPLAY LU
 Displays the DB2 LU status. If more than one DB2 connection exists, multiple LUs are displayed.
/F stcname, DISPLAY CONVERSATION
 Displays the status of LU6.2 conversations and TCP/IP connection information.
/F stcname, CANCEL
 Abruptly terminates the XDB Host Option without performing the standard shut-down procedure. Use this command only when the STOP command does not work.
/F stcname, STOP
 Stops the XDB Link Host Option using the standard shut-down procedure. It usually takes a few minutes for the program to complete its termination process after you have entered this command.
S stcname
 Starts the XDB Link Host Option.
P stcname
 Stops the XDB Link Host Option using the standard shut-down procedure. It usually takes a few minutes for the program to complete its termination process after you have entered this command.
Parent topic: SQL Option Link Configuration Guide


Worksheets

  • VTAM Worksheet
  • DB2 Worksheet
  • PC LAN Worksheet (Gateway Configuration)
  • SNA Server Worksheet (V2.11)
  • SNA Server Worksheet (V3.x)
  • xdbappc.ini Worksheet
  • TCP XDBPARM Worksheet
  • TCP Host/Service Worksheet
Parent topic: SQL Option Link Configuration Guide


VTAM Worksheet

Have a VTAM systems programmer complete this worksheet. Record your values in the space provided. Where suggested values are given, verify that your settings in VTAM match the suggested values.

Key

  • R denotes required information for XDB Link connections of this type. Settings must be verified or modified to match requirements.

    I denotes informational values may be useful in coordinating installation or in tracking down problems.

Note:

For VTAM, the minimum level is 3.2.

NCP is not required by XDB Link, but it must be at least version 4.2 if it is used.

TCP SNA Parameter Suggested Value Your Value Ref
R PU Definition
DLOGMOD=ANY3270
XID=YES
PUTYPE=2
STATOPT='XDB SAMPLE'

Accept system default for all other values

 A1
R PU Address

Used by SNA software on the PC

 A2
R PU CP Name

Used by SNA software on the PC

 A3
R IDNUM

Used by SNA software on the PC

 A4
R IDBLK

Used by SNA software on the PC

 05D for 3172 device A5
R LU6.2 Mode Entry

(MODEENT ID)

May be used by SNA software on the PC

 Use IBMRDB or the following:
TYPE = X'00'
FMPROF = X'13'
TSPROF = X'07'
PRIPROT = X'B0'
SECPROT = X'B0'
COMPROT = X'50B1'
RUSIZES = X'8989'
PSERVIC = X'060200000000000000002F00'
 A6
R LU Name for LU6.2 Terminals

Used by SNA software on the PC

XDBLU621 LU LOCADDR=0,MODETAB=RDBMODES,
RESSCB=20
 A7
I LU Name for 3270
XDB32701 LU LOCADDR=02,
          LOGAPPL=your3270mode
 A8
R R DB2 APPLID

Used by SNA software on the PC

See the IBM Manual Distributed Relational Database Connectivity Guide.

AUTH=(ACQ)
AUTOSES=1
SECACPT=ALREADYV
SRBEXIT=YES
VERIFY=NONE
VPACING=2

See your DB2 Administration Guide for other values

 A9
R TCP for APPLID, required only if using XDB Link Host Option.
APPL=YES,
AUTH=(ACQ),
DLOGMOD=IBMDB2LM,
DMINWNL=10,
DSESLIM=20,
SECACPT=ALREADYV,
SRBEXIT=YES,
VPACING=8
 A10

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


DB2 Worksheet

Record your values in the space provided. Verify that the settings for DB2 meet the minimum requirements or match suggested values.

Parameter | Minimum Requirement | Suggested Value | Your Value | Ref
DB2 version | Version 3.1 or higher. |  |  | B1
DDF facility | Activated |  |  | B2
Security access to DDF | Required |  |  | B3
MAXDBAT in DSNZParms | MAXDBAT>=20 |  |  | B4
AuthID with authority to bind Used when creating XDB package or plan |  |  |  | B5
DB2 package name for XDB Used when binding XDB Link |  | XDBSYS |  | B6
DB2 collection ID for XDB Used when binding XDB Link |  | XDBDFT |  | B7
Users with plan access |  | PUBLIC/Specific users |  | B8
DB2 location name |  |  |  | B9
DB2 CCSID code page |  |  |  | B10

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


PC LAN Worksheet (Gateway Configuration)

Give this worksheet to your PC LAN administrator or systems support staff. Verify that settings for the PC LAN and the XDB gateway machine meet the minimum requirements or match the suggested values. Record your values in the space provided.

Key:

  • R denotes required information for XDB Link connections of this type. Settings must be verified or modified to match requirements.
  • I denotes informational values that may be useful in coordinating installation or in tracking down problems.
TCP | SNA | Parameter | Minimum Requirement | Suggested Value | Your Value | Ref
R | R | Mainframe connection TCP/IP or SNA |  |  |  | C2
R | R | LAN ID Used by SNA software on the PC |  |  |  | C3
I | R | Cluster Controller Network Address Used by SNA software on the PC |  |  |  | C4
I | I | Communications cards Type of card in the gateway machine |  |  |  | C5
I | I | Max RU size for communication card | 512 |  |  | C6
I | I | 3270 access on gateway machine |  |  |  | C7
I | I | Client workstations | Verify that client workstations meet minimum software and hardware requirements specified in the XDB setup guide. |  |  | C8
R |  | IP address of host system |  |  |  | C9
I |  | IP address of gateway |  |  |  | C10

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


SNA Server Worksheet (V2.11)

Give this worksheet to your PC LAN administrator or system support staff. Verify that settings for the SNA Server match the required value for the field in the specified dialog box. To help you determine the value to use when configuring SNA Server, the value's common name (nick name) and source definition are shown in the table below.

Record your values in the space provided. You will use your values when configuring the SNA Server.

Dialog boxes and field values that are not shown on this worksheet are not used by XDB Link.

Dialog Box | Field | Value Needed for XDB Link Configuration | Suggested Value | Your Value | Ref
Server Properties Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ACSTRxx)

 D1
Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

Nick Name: CPNAME

Source: VTAM PU definition

 D2
Connection Properties | Connection Name | A name for the connection between this server and the remote system. This value is used internally by the SNA Server. | D3
Link Service The DLC type used to reach the host.(802.2 for either Ethernet or Token Ring.)
Note:

Verify that the selected protocol has been installed on the SNA Server machine.

 SnaDlc1 D4
Remote End One of the following system types
  • Host System
  • Peer System
  • Down Stream

For DB2 FOR OS/390, use Host System

 D5
Activation One of the following activation events that SNA Server will use to start this connection.
  • Startup
  • On Demand
  • Manually (by Admin)
 Startup D6
Connection Properties | Allowed Directions | Outgoing. Incoming optional. | Outgoing and Incoming | D7
SETUP Remote Network Address The 12-digit hexadecimal network address (MAC address) for this server. This address starts with 4000...for Token Ring, and with 02...for Ethernet.

Nick Name: Target Mac Address

Source: VTAM controller definition

 D8
Local Node Name Local Node ID The 8-digit hexadecimal local ID number for this server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK.

Nick Name: IDNUM & IDBLK

Source: VTAM PU definition

 D9
Remote Node Name Network Name The SNA network name (NETID) for VTAM. Can be blank for APPN Peer-to-Peer.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 D10
Control Point The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP. Can be blank for APPN Peer-to-Peer.

Nick Name: SSCPNAME

Source: SYS1.VTAMLST (ATCSTRxx)

 D11
XID Format | Format 3 | Format 3 | Format 3 | D12
Remote Node ID IDNUM and IDBLK parameter in VTAM

Nick Name: Remote target NODE ID

 blank D13
APPC LU Properties LU6.2 Type Independent

Nick Name: LOCADDR = 0

Source: VTAM LU definition

 Independent Independent D14
APPC LU Properties | LU Alias | A name that represents this machine in its local SNA communications configuration. We recommend that you use the XDB Server name as the alias. | XDBSERVE | D15
Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 D16
LU Name The LU name for this APPC LU. Must match the independent LU name specified in VTAM.

Nick Name: Independent LU Name

Source: VTAM LU Definition

 D17
Enable Automatic Partnering | Enabled | Enabled | Enabled | D18
Implicit Incoming | (None) | (None) | (None) | D19
APPC Remote LU Properties | LU Alias | A name that will represent the remote APPC LU in this server's SNA communication configuration. | D20
Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

D21
LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPL definition

 D22
Uninterpreted LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPLS

 D23
Mode Mode Name IBMRDB or the mode name (DLOGMODE) defined for LU definition in VTAM.
Note:

MODETAB Name = VTAM mode table

DLOGMODE name = mode name for LU.

Nick Name: DLOGMODE

Source: ISTINCLM (or other specified name for the LOGMODE table)

 D24

1If you have a multi-domain network, use the parameter CDRM = (CDRM name). If you have a single-domain network, use the value found in library member SYS1.VTAMLIST(ATCSTRxx).

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


SNA Server Worksheet (V3.x)

Give this worksheet to your PC LAN administrator or system support staff. Verify that settings for the SNA Server match the required value for the field in the specified dialog box. To help you determine the value to use when configuring SNA Server, the value's common name (nick name) and source definition are shown in the table below.

Record your values in the space provided. You will use your values when configuring the SNA Server.

Dialog boxes and field values not shown on this worksheet are not used by XDB Link.

Dialog/Tab | Field | Value Needed for XDB Link | Suggested Value | Your Value | Ref
SNA Servers General Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E1
Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

Nick Name: CPNAME

Source: VTAM PU definition

 E2
Connection General | Name | A name for the connection between this server and the remote system. This value is used internally by the SNA Server. | E3
Link Service The DLC type used to reach the host. (802.2 for either Ethernet or Token Ring.)
Note:

Verify that the selected protocol has been installed on the SNA Server machine.

 SnaDlc11 E4
Remote End One of the following system types
  • Host System
  • Peer System
  • Down Stream

For DB2 FOR OS/390, use Host System

 E5
Allowed Directions | Outgoing. Incoming optional. | Both | E6
Connection General Activation One of the following activation events that SNA Server will use to start this connection.
  • Startup
  • On Demand
  • Manually (by Admin)
 Startup E7
Connection Address Remote Network Address The 12-digit hexadecimal network address (MAC address) for this server. This address starts with 4000...for Token Ring, and with 02...for Ethernet.

Nick Name: Target Mac Address

Source: VTAM controller definition

 E8
Remote SAP Address SAP address defined by the hardware for this connection. VTAM controller definition

Source: Communications controller

 04 E9
Connection System Identification Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E10
Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

Nick Name: CPNAME

Source: VTAM PU definition

 E11
Local Node ID The 8-digit hexadecimal local ID number for this server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK

Nick Name: IDNUM & IDBLK

Source: VTAM PU definition

 E12
XID Type | Format 3 | Format 3 | Format 3 | E13
Connection System Identification Network Name The SNA network name (NETID) for VTAM. Can be blank for APPN Peer-to-Peer.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E14
Control Point The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP. Can be blank for APPN Peer-to-Peer.

Nick Name: SSCPNAME

Source: SYS1.VTAMLST (ATCSTRxx)

 E15
Remote Node ID IDNUM and IDBLK parameter in VTAM

Nick Name: Remote target NODE ID

 blank E16
Connection 802.2 DLC Max BTU Length The maximum for the BTU length. Use one of the following:
  • Token Ring 4 MB = 4195
  • Token Ring 16MB = 16393
  • Ethernet = 1493

Nick Name: VTAMLST - MAXDATA value

Note: BTU value must be less than or equal to MAXDATA in the VTAM PU definition.

 E17
Local APPC LU Properties General | LU Alias | A name that represents this machine in its local SNA communications configuration. We recommend that you use the XDB Server name as the alias. | XDBSERVE | E18
Local APPC LU Properties General Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E19
LU Name The LU name for this APPC LU. Must match the independent LU name specified in VTAM.

Nick Name: Independent LU Name

Source: VTAM LU Definition

 E20
Local APPC LU Properties Advanced | Member Def. Outgoing Local APPC LU Pool | Disabled | Disabled | Disabled | E21
Implicit Incoming | (None) | (None) | E22
LU6.2 Type Independent

Nick Name: LOCADDR = 0

Source: VTAM LU definition

 Independent Independent E23
SyncPoint Support | Disabled | Disabled | Disabled | E24
Remote APPC LU Properties General | Connection | Must match connection name in E3. | E25
LU Alias | An name that will represent the remote APPC LU in this server's SNA communication configuration. | E26
Network Name The SNA network name (NETID) for VTAM.

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E27
Remote APPC LU Properties General LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPL definition

 E28
Uninterpreted LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPL definition

 E29
Remote APPC LU Properties Options | Supports Parallel Sessions | Enabled if the client is using an independent LU. | Enabled | E30
Implicit Incoming | (None) | (None) | E31
Session-Level Security | Only if using security keys | No Session-Level Security | E32
Mode General Mode Name IBMRDB or the mode name (DLOGMODE) defined for LU definition in VTAM.
Note:

MODETAB Name = VTAM mode table

DLOGMODE name = mode name for LU.

Nick Name: DLOGMODE

Source: ISTINCLM (or other specified name for the LOGMODE table)

 IBMRDB E33
Mode Limits Parallel Session Limit Defined by the number of users accessing the mainframe. Matches DSESLIM in your PU definition.

Nick Name: DSESLIM

Source: PU definition in SYS1_VTAMLST

 >E34

1If you have a multi-domain network, use the parameter CDRM = (CDRM name). If you have a single-domain network, use the value found in library member SYS1.VTAMLIST(ATCSTRXX).

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


xdbappc.ini Worksheet

If you are using the SAA Server for NetWare, the XDB appc.ini file must be created in the root directory of the volume where XDB Link is installed. Verify that the settings in this file match the suggested values. Record your values in the space provided.

Section | Parameter | Minimum Requirement | Suggested Value | Your Value | Ref
PU Definition | Define PU | Must match the entry in the CSCON profile named "Peripheral CP Name" | NETWCP |  | H1
 | Profile | Must match the name of the profile configured with CSCON and loaded with CSLOAD | NETNODE |  | H2
 | Network | Must match the entry in the CSCON profile named "SNA Network ID" | XDBNET |  | H3
 | LuName | Must be configured for independent LU |  |  | H4
 | LuAlias | We recommend that you use the XDB Server name as the alias. | XDBSERVE |  | H5
 | LocAddr | Must be 0 for independent LUs |  |  | H6
 | SessionLimit | Should be less than or equal to the entry in the CSCON profile named "Independent Sessions" |  |  | H7
 | MaxTPs | Should be less than or equal to the session limit (SessionLimit) |  |  | H8
 | QueueDepth | Depth of incoming allocate queue |  |  | H9
PLU Definition | Define PLU | Define PLU name. For MVS/VTAM: The VTAM DB2 APPLID name |  |  | H10
 | Network | Network Identifier |  |  | H11
 | Alias | PLU alias | DRDAHOST |  | H12
 | Security | PLU security capabilities | 3 |  | H13
 | SessionLimit | PLU session limit |  |  | H14
PLU Definition | MaxMcSendLL | Maximum mapped conversation send logical length | 0 |  | H15
 | DlcName | Possible values: SDLC, ITRN, QLLC, CUSTOM |  |  | H16
 | AdaptNum | Token ring primary adapter, and all other DCLs use 0. Token ring secondary adapter use 1 |  |  | H17
 | AdaptAddr | Possible values: SDLC, ITRN, QLLC, CUSTOM |  |  | H18
 | ModeName | For sessions between Local LU and Partner LU | IBMRDB |  | H19
Mode Definition | Define Mode | Same as ModeName in PLU Definition Section | IBMRDB |  | H20
 | MaxRu | Maximum Request/Response Unit | 4096 |  | H21
 | MinRu | Minimum Request/Response Unit | 256 |  | H22
 | MaxNegotiable | Maximum Negotiable Session Limit | 16 |  | H23
 | Pacing | Pacing Limit | 4 |  | H24

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets
Related information
xdbappc.ini Parameters
Configure the PC


TCP XDBPARM Worksheet

Give this worksheet to your MVS systems programmer or system support staff if you are using the XDB Link Host Option on MVS. Record your values in the space provided. The XDBPARM file is located in a PDS file on the host (XDBLINK.V100.PARAM).

Parameter | Requirements | Suggested Value | Your Value | Ref
Organization | Organization ID | Your company name |  | I1
Port | Must match the port number defined in the SERVICES File | 5170 |  | I2
Backlog | A value greater than 0 | 5 |  | I3
Network ID | SNA Network ID |  |  | I4
LU6.2 APPLID | Must match the APPLID defined in the VTAMLST | XDB62APP |  | I5
APPLID Password | Must match the APPLID password defined in the VTAMLST | XDB62APP |  | I6
Trace | Must be GTF or WTOR | GTF |  | I7
GID | Must match the USR value in the GTF trace parameter | 0E9 |  | I8
Time Out for Connection | Between 1 and 32767 | 0 |  | I9
Compress | Not Used |  |  | I10
Route | A value for WTO and WTOR | (2,11) |  | I11
Product Password | Must be the password given by XDB |  |  | I12

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


TCP Host/Service Worksheet

If you are using TCP/IP to connect XDB Link to the host system, you must edit the HOSTS and SERVICES files on the machine where XDB Link is installed to define the IP address and port number of the host system. Record your values in the space provided.

File | Parameter | Requirements | Suggested Value | Your Value | Ref
Hosts | IP address | The IP address defined for the host |  |  | J1
 | Host name | A name that represents this IP address |  |  | J2
Services | Service name | A name that represents this port number | We recommend that you use the name of the XDB Server as the service name. |  | J3
 | Port number | The port number assigned to the XDB Link Host Option | 5170 |  | J4
 | Protocol | TCP protocol | tcp | tcp | J5

Specify the IP address and host name values in the HOSTS file on the machine where XDB Link is installed. For example, you would enter the line:

240.195.165.202 LUDB2

to assign the host name LUDB2 to the IP address 240.195.165.202.

Specify the service name, port number, and protocol in the SERVICES file on the machine where XDB Link is installed. For example, you would enter the line:

XDBSRV 5170/tcp

to assign the service name XDBSRV to tcp port 5170.

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


SQL Option Preprocesor Guide

  • Creating and Embedding SQL in COBOL
  • Using Dynamic SQL in COBOL
  • Static Binding
  • Security
  • DSNTIAR Facility
  • XDB Preprocessor
Parent topic: SQL Option for DB2


Creating and Embedding SQL in COBOL

There are certain requirements your COBOL programs must meet before they can be compiled and debugged. This chapter outlines the processes for creating or modifying SQL code for COBOL programs. It also details the statements that all COBOL programs containing embedded SQL must contain.Use of dynamic SQL in your program is described in the chapter Using Dynamic SQL in COBOL.

  • Using Copybooks
  • Creating a Copybook
  • Representing Data
  • Using Directives
  • SQL Communications Area (SQLCA)
  • SQL Descriptor Area (SQLDA)
  • Sample COBOL Program with Embedded SQL
Parent topic: SQL Option Preprocesor Guide
Related information
Using Dynamic SQL in COBOL


Using Copybooks

In a typical development effort, different COBOL programs access the same data tables. Copybooks allow host variable definitions for a table's columns to be inserted within your COBOL code, allowing data from those columns to be used in your program. If a modification is made to a table (such as a change of data type or column length), then it is only necessary to modify the copybook rather than the source code definition for that table in all the programs that use it.

Parent topic: Creating and Embedding SQL in COBOL


Creating a Copybook

You can use the SQL Option Declaration Generator to create declarations of your tables. See the SQL Option Declaration Generator User's Guide for specific procedures.

  • Copybook Format
  • Including Copybooks in Programs
  • Host Variables
Parent topic: Creating and Embedding SQL in COBOL


Copybook Format

The format of a copybook is shown by the following example. This declaration defines the SQL Option EMPLOYEE table in the TUTORIAL location:

 01 EMP-TABLE.
     03 ENO PIC S9(4) COMP.
     03 LNAME PIC X(10).
     03 FNAME PIC X(10).
     03 STREET PIC X(20).
     03 CITY PIC X(15).
     03 ST PIC XX.
     03 ZIP PIC X(5).
     03 DEPT PIC X(4).
     03 PAYRATE PIC S9(13)V99 COMP-3.
     03 COM PIC S9V99 COMP-3.

All sample tables are shown in the SQL Reference manual.

Parent topic: Creating a Copybook


Including Copybooks in Programs

When including a copybook in your program, make sure that the Compiler can locate the copybook.

If a copybook contains embedded SQL or host variable declarations, include it using one of the following three methods:

  • EXEC SQL INCLUDE ... END-EXEC
  • COPY
  • -INC
Parent topic: Creating a Copybook


EXEC SQL INCLUDE ... END-EXEC

For example:

EXEC-SQL
    INCLUDE EMPREC
END-EXEC
Parent topic: Including Copybooks in Programs


COPY

For example:

COPY EMPREC.

The file named after the COPY verb can contain any COBOL statements that a copybook can, including EXEC SQL statements.

The SQL Option preprocessor works like the mainframe DB2 preprocessor does. However with the SQL Option preprocessor, you need to specify the preprocessor directive COPY to allow host variables to be defined in COPY statements.

Note:

If you specify EXEC SQL statements using the COPY verb, the SQL Option preprocessor will compile the program and will generate an error message for any host variable referenced from the copybook without the COPY directive being set. If you port the same program to the mainframe, the SQL code may not precompile unless your installation has a product that expands copybooks before passing them to the DB2 mainframe preprocessor.

Parent topic: Including Copybooks in Programs


-INC

For example:

-INC EMPREC

The file specified after the -INC verb can contain any COBOL statements that a copybook can, including EXEC SQL statements.

Parent topic: Including Copybooks in Programs


Host Variables

Host variables are used to hold data that is accessed by both COBOL and SQL commands. You define a host variable as a data structure that represents the column names and data types of the tables that are accessed by the COBOL program.

Host variables are usually defined in copybooks. Copybooks can be quickly created from any SQL Option or DB2 table using the SQL Option Declaration Generator utility.

There are two ways to use host variables:

  • To store information returned by the database engine as the result of an SQL statement.
  • To store information sent to the database engine and/or dynamic information that controls what is returned by a SELECT statement.

All host variables appearing inside an EXEC SQL ... END-EXEC block should be preceded by a colon, as shown for the host variable DEPT-NUM in the following example:

 EXEC SQL
     DECLARE EMPCURS CURSOR FOR
     SELECT LNAME, FNAME, PAYRATE, HOURS
       FROM EMPLOYEE
       WHERE DEPT = :DEPT-NUM
 END-EXEC

DB2 V5 does not require all host variables to be preceded by a colon, but DB2 V6 does. If you plan to upgrade in the future, you should set your message level to WARNING in the build setting for every SQL programs in the project.

The use of host variables allows you to design more flexible queries, and to interactively define the criteria for data selection. In the preceding example, the host variable specifies the department for which data will be selected.

For information about null values in host variables, see the section Using Indicator Variables .

Parent topic: Creating a Copybook


Representing Data

When you access data with SQL statements in COBOL programs, you must provide corresponding data definitions in your COBOL source code. This requirement is usually accomplished by stating the data definitions in a copybook and including that copybook in your COBOL source code.

The copybook EMPREC contains a COBOL representation of the column names and data types for the EMPLOYEE sample table. The Declaration Generator generates copybooks from tables, automatically creating a COBOL data definition for each table columnYou can modify the generated copybook file as needed. See the SQL Option Declaration Generator User's Guide for more information about using the SQL Option Declaration Generator.

Note: The SQL Option Precompiler does not accept all COBOL data types. If the COBOL data item you code is not consistent with those shown in the section Allowed Data Declarations, it will not be recognized as a host variable.

The following guidelines are offered to assist you in working with host variables and data declarations.

  • For data declarations of host variables use level number 01 to 77.
  • A varying-length character string data item must have group level 01. The group contains two, level 49 elementary items consisting of:
    • Length Item.

      The first elementary item must be a 2-byte integer variable; for example, PICTURE S9(4) COMP. It represents the length of the character string.

    • Value Item.

      The second elementary item must have the same description as a fixed-length character string; for example, PICTURE X(80), where 80 is the maximum length of the string. This item is used to contain the value of the character string. If you use the host variable to insert a character string into a table, the database manager inserts only as many characters as are indicated by the length item. Also, when data is placed into the field, only the number of characters defined in the length item is returned. This can cause previous information stored in this field not to be cleared.

    The data item and elementary items can have any acceptable COBOL name. However, in SQL statements, refer to this host variable by its group name.

  • COBOL host variables used in SQL statements must be of a type compatible with the database columns with which they are to be used.
    • Numeric data types are compatible with each other. A SMALLINT, INTEGER, DECIMAL, or FLOAT column is compatible with a COBOL host variable of COMP, COMP-2, COMP-3, COMP-4, or COMP-5.
    • Character data types such as CHAR and VARCHAR are compatible with each other. The database manager automatically converts a fixed-length character string to a varying-length string, or vice versa, when necessary.
  • Be careful of overflow. For example, if you retrieve an INTEGER column value into a PICTURE S9(4) host variable and the column value is larger than 32767 or smaller than -32768, you will get an overflow error.
  • Be careful of truncation. For example, if you retrieve an 80-character CHAR column value into a PICTURE X(70) host variable, the rightmost 10 characters of the retrieved string will not be included.

    Retrieving a floating-point or decimal column value into a COMP host variable removes any fractional value.

  • The COBOL declarations for SMALLINT and INTEGER data types are expressed as a number of decimal digits. The database manager uses the full size of the binary integers, and may place larger values than would be allowed in the specified number of digits in the COBOL declaration. This situation can cause data truncation. Ensure that the size of any numbers in your application is within the allowable number of digits.
  • The SQL Option preprocessor also supports using host variables defined with the SQL TYPE IS declaration. The actual data definition for the host variable is then determined by the preprocessor. For example, a host variable for a RESULT SET LOCATOR could be defined as:
    01 my-locator usage SQL TYPE IS RESULT-SET-LOCATOR varying.
  • Allowed Data Declarations
  • Allowed Data Declaration Abbreviations
  • Using Indicator Variables
Parent topic: Creating and Embedding SQL in COBOL


Allowed Data Declarations

The following table shows the COBOL declarations that are allowed for defining host variables. All other types of COBOL declarations will be rejected. Allowed abbreviations are shown in the section Allowed Data Declaration Abbreviations.

Data Type | COBOL Data Declaration | Comments
char | 01 identifier PIC X(n). 01 identifier PICTURE IS X(n). | n is a positive integer representing the length of the CHAR column value assigned to the host variable.
varchar | 01 identifier 49 identifier PIC S9(ni) COMP. 49 identifier PIC X(nc). | ni is a positive integer from 1 to 4, representing the length of the numeric column value assigned to the variable containing the string length. nc is a positive integer equal to the length of the largest VARCHAR column value that can be assigned to the host variable.
smallint | 01 identifier PIC S9(4) COMP. 01 identifier PIC S9(n) COMP. 01 identifier PIC S9(n) USAGE IS COMP. | n is a positive integer from 1 to 4, representing the variable length. No decimal points are allowed. Anything other than 9s in the Picture clause makes data item unacceptable as a host variable. PIC S and COMP are required. You may use COMP-4 or COMP-5 in place of COMP if necessary.
integer | 01 identifier PIC S9(9) COMP. 01 identifier PIC S9(n) COMP. 01 identifier PIC S9(n) USAGE IS COMP. | n is a positive integer from 5 to 9. No decimal point is allowed. Anything other than 9s in the Picture clause will make the data item unacceptable as a host variable. PIC S and COMP are required. You may use COMP-4 or COMP-5 in place of COMP if necessary.
decimal | 01 identifier PIC S9V COMP-3. 01 identifier PIC S9(n) V COMP-3. 01 identifier PIC S9(n) V9(m) COMP-3. 01 identifier PIC S9(n) V9(m) USAGE IS COMP-3. | n and m are positive integers; n + m cannot exceed 15. You must include a V to denote the decimal point. Anything other than 9s and a V in the Picture clause will make the data item unacceptable as a host variable. PIC S and COMP-3. are required.
float | 01 identifier COMP-2. 01 identifier USAGE IS COMP-3. | COMP-2. or COMP-3. is required.
date | 01 identifier PIC X(n). 01 identifier PICTURE IS X(n). | n must be an integer representing the length of the date string. For example, if the date string is in the format MM/DD/YY, n may equal 8. If in the format MM/DD/YYYY, n should equal 10. Make sure your date format is set correctly in the Options utility. See the Option utility's online help for information about modifying the date/time representation.
time | 01 identifier PIC X(n). 01 identifier PICTURE IS X(n). | n must be an integer representing the length of the time string. To include seconds, n must be at least 8. For example, a time string in the format HH:MM requires that n equal at least 5, while a time string in the format HH:MM:SS requires that n equal at least 8.
result set locator | 01 identifier SQL TYPE IS RESULT-SET- LOCATOR. | A 4-byte value used by DB2 to uniquely identify a query result set returned by a stored procedure.
Parent topic: Representing Data


Allowed Data Declaration Abbreviations

The following table shows the COBOL abbreviations allowed for host variables. For a complete list of allowed data types, see the topic Allowed Data Declarations.

Abbreviation | Can be used for...
PIC | PICTURE or PICTURE IS
COMP | COMPUTATIONAL or USAGE IS COMPUTATIONAL
PIC IS | PICTURE IS
USAGE | USAGE IS
S9(5) | S99999
X(10) | XXXXXXXXXX
Parent topic: Representing Data
Related information
Allowed Data Declarations


Using Indicator Variables

An indicator variable is a 2-byte integer variable that can be used for either of the following purposes:

  • To indicate whether its associated host variable has been assigned a null value. If the value for the column you are retrieving is null, a negative value is placed in the indicator variable.
  • To verify that a retrieved character string value has not been truncated. If the indicator variable contains a positive integer, it specifies the original length of the string.

When a column's value is retrieved, you can test the indicator variable. If the indicator variable's value is less than zero, you know the retrieved column's value is null. When a null value is retrieved, nothing is put into the associated host variable that is used to contain the column's value; thus, the value of the host variable is unchanged.

Define indicator variables in the same manner as small-integer host variables. Specify an indicator variable, preceded by a colon, immediately after the host variable to which it relates. For example:

 EXEC SQL
     SELECT PHONENO INTO :CBLPHONE :INDNULL FROM CORPDATA
       WHERE EMPNO = "EMPID"
 END-EXEC

You can then test INDNULL to see if it contains a negative value. If it does contain a negative value, then you know that a null value was retrieved for the row's PHONENO (that is, phone number) column, and you can disregard the contents of CBLPHONE.

When a column value is fetched using a cursor, you can use the same technique to determine whether the retrieved value is null or not.

You can also use an indicator variable to set a null value in a column. When processing UPDATE statements, the indicator variable is checked. If the indicator variable contains a negative value, set the column value to "null value." If the indicator variable is greater than -1, the associated host variable contains a value for the column.

Parent topic: Representing Data


Using Directives

Directives are compiler options that convey information to your compiler and the SQL Option Precompiler. For example, the DBRM directive is used to create a database request module during the compile.

Parent topic: Creating and Embedding SQL in COBOL
Related information
XDB Preprocessor Options


SQL Communications Area (SQLCA)

Every COBOL program containing embedded SQL must have an SQL Communications Area (SQLCA) or the field SQLCODE defined in its Working-Storage Section. This definition is normally accomplished by including the SQLCA copybook provided with Enterprise Developer. A complete description of the SQLCA structure is provided in the SQL Reference.

Important: Enterprise Developer does not default to using the XDB SQLCA. This can lead to problems using DSNTIAR. To ensure that Enterprise Developer uses the XDB SQLCA, you must add the path to the provided XDB copybooks to the in your project properties. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\xdb . To do this

The SQLCA holds information on the status of the SQL statement last executed. It is updated after the execution of each EXEC SQL ... END-EXEC block of code.

Information in the SQLCA can be used in many ways. For example:

  • You can use it to debug your code.
  • You can use it to control the flow of your program by testing its values. For example, when SQLCA indicates an error, you can branch to an error-processing routine. Similarly, you can use it to detect the end-of-data and exit a loop.

The following SQLCA codes are particularly useful:

Table 1.
Field | Description
SQLSTATE The SQL Option Preprocessor provides limited support for DB2-compliant SQLSTATE return codes within COBOL application programs. This limited support is provided on top of already existing support for SQLCODE. SQL Option maps a subset of SQLSTATE values from equivalent SQLCODE return values. SQLSTATE support is limited to applications running against an SQL Option Server in DB2 mode. If running against the SQL Option Link, support for the full range of SQLSTATE return codes is provided by DB2 directly. (Consult your DB2 documentation.) See the SQL Option Link User's Guide for a complete listing of SQLSTATE values supported by SQL Option, plus a table mapping error message return codes.

SQLSTATE values provide COBOL application programs with a standardized set of return codes corresponding to common SQL statement error conditions. SQLSTATE values are structured so that application programs can test for specific errors or classes of errors. In an application program, the SQLSTATE is a status parameter (similar to SQLCODE) that indicates either that an SQL statement completed successfully or that an exception condition was raised during execution. Unlike the SQLCODE (which is an integer parameter), the SQLSTATE is a character string parameter which for COBOL language applications is of data type COBOL PICTURE X(5).

SQLCODE The SQLCODE element in SQLCA contains a return code relating to the last SQL statement executed:
  • If an error occurred, the SQLCODE in the SQLCA will contain a negative number corresponding to the DB2. The equivalent SQL Option Server error code is returned in the SQLERRD (1) field. See Error Messages in your Reference Help for codes and meanings.
  • If SQLCODE is 0, the statement executed successfully but may have had warnings (as indicated in the SQLWARN fields).
  • A code of +100 indicates no more records.

The SQL Option DSNTIAR facility may be used to convert an SQL return code (from the SQLCODE field in SQLCA) to a character string. See the chapter DSNTIAR Facility for more information.

SQLERRD(3) | The SQLERRD (3) element in SQLCA holds the number of rows that were inserted, updated, or deleted by an SQL statement.
SQLERRML | The SQLERRML element in SQLCA is the length of SQLERRMC. If zero, the value of SQLERRMC is not pertinent. For more information, see the description for SQLERRMC.
SQLERRMC The SQLERRMC element in SQLCA holds a character string that describes an error condition. If there is an error, it will contain one or more tokens, separated by X'FF'.

The tokens are substituted for the variables in the descriptions of error messages (for example, the name of a file or table).

SQLWARN0 | The SQLWARN0 element in SQLCA is a warning flag that indicates if any other SQLWARNn field is signaling a potential problem. If SQLWARN0 is blank, then all other SQLWARNn fields are blank (no warnings exist). If SQLWARN0 contains a W, then at least one of the other SQLWARNn variables has a W. For information on the meanings of the other SQLWARNn fields, see the SQL Reference manual.
Parent topic: Creating and Embedding SQL in COBOL


SQL Descriptor Area (SQLDA)

COBOL programs that include dynamic SQL must have an SQL Descriptor Area (SQLDA) defined. This definition is usually accomplished by including the SQLDA copybook provided with Enterprise Developer.

Important: Enterprise Developer does not default to using the XDB SQLDA. To ensure that Enterprise Developer uses the XDB SQLDA, you must add the path to the provided XDB copybooks to the in your project properties. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\xdb . To do this

The default SQLDA copybook used by the SQL Option preprocessor is not mainframe DB2 compatible. Instead it is designed for easy compatibility if you are upgrading from older version of XDB or SQL Option software.

A mainframe compatible SQLDA is provided in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\xdb directory with filename of sqlda.cpy. If you want to use that copybook instead, just rename it. You then need to compile all programs that use this copybook or SQLDA's defined using the mainframe SQLDA structure with the SQL preprocessor directive SQLDA-VER=1 or the program will not map data properly and probably trap.

The SQLDA holds information about dynamic SQL queries, and is required for allocating the proper amount of space for the query.

For more information about dynamic SQL and the SQLDA, see the topic Using Dynamic SQL in COBOL. For a complete description of the SQLDA structure, see the SQL Reference. Refer to your preprocessor documentation on the use of pointer variables and for additional information on dynamic SQL in COBOL programs.

Parent topic: Creating and Embedding SQL in COBOL
Related information
Using Dynamic SQL in COBOL


Sample COBOL Program with Embedded SQL

The following program shows how SQL statements can be embedded in a COBOL program. Note that the copybook EMPREC has been included in the program using the INCLUDE statement.

This program declares a cursor, opens it, and then fetches data into a set of host variables. The host data is displayed. (Note the use of the indicator variable used with the commission variable COM.) When the end of data is reached, or when the user is finished viewing data, the loop is terminated, the cursor is closed, and the program ends.

 IDENTIFICATION DIVISION.

 PROGRAM-ID. TESTALL.
 AUTHOR-NAME. ME.

 ENVIRONMENT DIVISION.

 CONFIGURATION SECTION.
 SOURCE-COMPUTER. IBM-AT.
 OBJECT-COMPUTER. IBM-AT.

 INPUT-OUTPUT SECTION.
 FILE-CONTROL.

 DATA DIVISION.

 FILE SECTION.

 WORKING-STORAGE SECTION.

 EXEC SQL
   INCLUDE EMPREC
 END-EXEC.

 01 DISP-RATE PIC $$$,$$$,$$9.99.
 01 DISP-COM PIC Z.99.
 01 DISP-CODE PIC ----9.
 01 FAKE-CHAR PIC X.
 01 ANSS PIC X.
 01 COM-NULL-IND PIC S9(4) COMP.

 EXEC SQL
   INCLUDE SQLCA
 END-EXEC.

 PROCEDURE DIVISION.

 100-MAIN.
* declare cursor for select
     EXEC SQL
         DECLARE EMPTBL CURSOR FOR
         SELECT *
           FROM EMPLOYEE
         ORDER BY LNAME
     END-EXEC

* open cursor
     EXEC SQL
         OPEN EMPTBL
     END-EXEC
     MOVE SQLCODE TO DISP-CODE
     DISPLAY 'open ' DISP-CODE

* fetch a data item
     EXEC SQL
         FETCH EMPTBL INTO
           :ENO,:LNAME,:FNAME,:STREET,:CITY,
           :ST,:ZIP,:DEPT,:PAYRATE,
           :COM :COM-NULL-IND
     END-EXEC.

 100-test.
     MOVE SQLCODE TO DISP-CODE
     DISPLAY 'fetch ' DISP-CODE

* loop until no more data
     PERFORM UNTIL SQLCODE < 0 OR SQLCODE = 100

* display the record
     MOVE PAYRATE TO DISP-RATE
     MOVE COM TO DISP-COM
     DISPLAY 'department ' DEPT
     DISPLAY 'last name ' LNAME
     DISPLAY 'first name ' FNAME
     DISPLAY 'street ' STREET
     DISPLAY 'city ' CITY
     DISPLAY 'state ' ST
     DISPLAY 'zip code ' ZIP
     DISPLAY 'payrate ' DISP-RATE
     IF COM-NULL-IND < 0
         DISPLAY 'commission is null'
     ELSE
         DISPLAY 'commission ' DISP-COM
     END-IF
     DISPLAY 'Do you want to see the next record? (y/n)'
     ACCEPT ANSS
     IF ANSS = 'Y' OR 'y'
         EXEC SQL
           FETCH EMPTBL INTO
             :ENO,:LNAME,:FNAME,:STREET,:CITY,
             :ST,:ZIP,:DEPT,:PAYRATE,
             :COM :COM-NULL-IND
         END-EXEC
     ELSE
         GO TO CLOSE-LOOP
     END-IF
     MOVE SQLCODE TO DISP-CODE
     DISPLAY 'fetch ' DISP-CODE
     END-PERFORM

     DISPLAY 'All records in this table have been selected'.

 CLOSE-LOOP.
* close the cursor
     EXEC SQL
         CLOSE EMPTBL
     END-EXEC.

 100-EXIT.
     STOP RUN.
Parent topic: Creating and Embedding SQL in COBOL


Using Dynamic SQL in COBOL

Dynamic SQL refers to a special type of embedded SQL statement that is prepared and executed within an application program while the program is running. It differs from static embedded SQL in that part or all of the actual SQL commands may be stored in a host variable, whose value may change numerous times during execution of the program. In the extreme case, the SQL commands are generated in their entirety by the application program at run time.While dynamic SQL is more flexible than static embedded SQL, it does require additional overhead and more programming sophistication.

  • Overall Considerations
  • Non-Select SQL Statements
  • Fixed-List Select Statements
  • Varying-List Select Statements
Parent topic: SQL Option Preprocesor Guide


Overall Considerations

The varying-list SELECT requires use of the SQLDA and address functions (COBOL pointer variables). The other types of dynamic SQL may require those features under certain conditions.

The SQL Descriptor Area (SQLDA) is a data structure that holds information about the execution of dynamic SQL statements. See the SQL Reference for more information about including an SQLDA in your program. Also see your COBOL documentation for an explanation of the use of address functions.

Some SQL statements cannot be executed dynamically, usually because they are needed to enable dynamic SQL commands themselves. The SQL commands that cannot be executed dynamically are shown below.

  • BEGIN DECLARE SECTION
  • FETCH
  • CLOSE
  • INCLUDE
  • DECLARE
  • OPEN
  • DESCRIBE
  • PREPARE
  • END DECLARE SECTION
  • SELECT INTO
  • EXECUTE
  • SET host-variable
  • EXECUTE IMMEDIATE
  • WHENEVER
Parent topic: Using Dynamic SQL in COBOL


Non-Select SQL Statements

When non-SELECT statements are issued dynamically, the coding task is relatively easy because there is no need to dynamically allocate main storage.

To issue a non-SELECT statement dynamically:

  1. (Optional) Test each SQL statement using the SQLWizard to see that proper results are obtained.
  2. Load the SQL statement into a data area.
  3. Issue a PREPARE and then an EXECUTE (or EXECUTE IMMEDIATE) statement.

    Be sure to handle any errors that result.

The following example executes an UPDATE statement that gives every employee a 10 percent raise:

     MOVE 'update employee set payrate=payrate*1.10'
                                                TO SQLCMD
     EXEC SQL
         EXECUTE IMMEDIATE :sqlcmd
     END-EXEC
     ...
Parent topic: Using Dynamic SQL in COBOL


Fixed-List Select Statements

A fixed-list SELECT statement is a statement that returns a predictable number of data items of a known type from an open cursor. For each of these items, a host variable is required to accommodate incoming data.

To issue a fixed-list SELECT statement dynamically:

  1. (Optional) Test each SQL statement using the SQLWizard to see that proper results are obtained.
  2. Load the SQL statement into a data area.
  3. Use PREPARE to validate the statement and translate it into an executable form.
  4. Use DECLARE to declare a cursor for the statement.
  5. Use OPEN to open the cursor.
  6. Use FETCH to retrieve a row into a fixed list of variables.
  7. When the end of data is reached, use CLOSE to close the cursor.

    Be sure to handle any errors.

The following example shows how to execute a fixed-list SELECT statement dynamically.

* include SQLDA copybook
     EXEC SQL
         INCLUDE SQLDA
     END-EXEC

* assign value to variable sqlcmd.
     MOVE 'select e_no, ' &
          'lname from employee where dept="1050"' TO sqlcmd

* prepare SELECT command.
     EXEC SQL
         PREPARE q1 FROM :sqlcmd
     END-EXEC

* declare cursor for SELECT command.
     EXEC SQL
         DECLARE c1 CURSOR FOR q1
     END-EXEC

* open cursor.
     EXEC SQL
         OPEN c1
     END-EXEC

* fetch data into program variables EMPNO, LASTNME and
* FIRSTNME.
     EXEC SQL
         FETCH c1 INTO :EMPNO, :LASTNME
     END-EXEC

* close cursor.
     EXEC SQL
         CLOSE c1
     END-EXEC
Parent topic: Using Dynamic SQL in COBOL


Varying-List Select Statements

A varying-list SELECT statement is one that retrieves data items of varying number and format. Because the number and type of data items are not known, you cannot define host variables in advance.

However, by including the SQLDA in your program, you can use PREPARE to define a SELECT statement and follow it with a DESCRIBE statement. This process inserts the data item information into the SQLDA, which your program can use to execute a SELECT statement. Likewise, record fetches are performed using the SQLDA.

To issue a varying-list SELECT statement:

  1. Include the SQLDA copybook in your program.
  2. Use PREPARE to define a statement (either already in a statement buffer or to be read) so that it may be translated to executable form.
  3. Use DESCRIBE for the prepared statement to determine how many columns will be retrieved and their data types. You may use a PREPARE INTO to PREPARE and DESCRIBE in a single statement.
  4. If the SQLDA is not large enough to contain column descriptions for each column, your program must determine how much space is needed, obtain that storage space, build a new SQLDA, and DESCRIBE again.
  5. The program must now determine how much space is needed for the data in each column (and possibly an indicator variable). Storage must be obtained so that when a value is fetched, your program will know where to put the data. Acquiring this storage is accomplished by analyzing the SQLDA. For more information on the SQLDA, see the SQL Option SQL Reference.
  6. Execute the SELECT statement by declaring and opening a cursor for the prepared statement.
  7. Fetch a row of data by specifying USING DESCRIPTOR SQLDA on the FETCH statement.
  8. When end of data is reached, close the cursor.

The following program excerpt shows how to execute a varying-list SELECT statement dynamically.

* include SQLDA copybook.
     EXEC SQL
         INCLUDE SQLDA
     END-EXEC

* assign value to variable sqlcmd.
     MOVE 'select * from employee where dept="1050"'
                                                   TO sqlcmd

* prepare SELECT command.
     EXEC SQL
         PREPARE q1 FROM :sqlcmd
     END-EXEC

* allocate space for an SQLDA ...
     MOVE 20 TO SQLN

* describe SELECT command.
     EXEC SQL
         DESCRIBE q1 INTO SQLDA
     END-EXEC

* make sure SQLDA is big enough.
     IF (SQLN <= SQLD)
            PERFORM ...
             ...
             MOVE SQLD TO SQLN.
             EXEC SQL
                 DESCRIBE q1 INTO SQLDA
             END-EXEC
         END-PERFORM
     END-IF

* analyze results of DESCRIBE.
...
* allocate storage to hold one row of the result. ...
* declare cursor for SELECT command.
     EXEC SQL
         DECLARE c1 CURSOR FOR q1
     END-EXEC

* open cursor.
     EXEC SQL
         OPEN c1
     END-EXEC

* fetch data into program variables EMPNO, LASTNME and
* FIRSTNME.
     EXEC SQL
         FETCH c1 USING DESCRIPTOR SQLDA
     END-EXEC

* display results fetching next record as long as there
* is one.
     PERFORM UNTIL SQLCODE <> 0
         DISPLAY ...
         EXEC SQL
             FETCH c1 USING DESCRIPTOR SQLDA
         END-EXEC
     END-PERFORM
     DISPLAY 'END OF LIST'.

* close cursor.
     EXEC SQL
         CLOSE c1
     END-EXEC
Parent topic: Using Dynamic SQL in COBOL


Static Binding

  • Overview
  • Creating a DBRM
  • Binding a DBRM
  • Autobinding
  • Specifying Options with AUTOBIND
  • Binding SQL Statements With Literals
  • Using AUTHID to Change Table Qualifier
  • Examples of DBRM Directives
  • Examples of Autobinding Multiple DBRM's
Parent topic: SQL Option Preprocesor Guide


Overview

SQL Option, by default, uses dynamic SQL. However, depending on your application the use of static SQL can have a significant impact on performance. Most applications will run faster when executing static as opposed to dynamic SQL. Also, default qualifiers can be specified during the bind to allow a program to use a particular AUTHID to qualify one part table names when the user does not have authority to execute a SET CURRENT SQLID command. Many sites are reluctant to use SET CURRENT SQLID since it may require SYSADM authority to execute.

Parent topic: Static Binding


Creating a DBRM

To have your program use static SQL, you must create a DBRM (database request module) and bind it to the SQL Option server you are going to run against. To create a DBRM, you need to compile your program with at least the following SQL Option preprocessor directives:

  • DBRM=dbrm-name
  • COLLECTION-ID=collection-id
Parent topic: Static Binding


Binding a DBRM

You must bind the DBRM using the BIND utility provided with SQL Option. After you have bound the DBRM your application will be running static SQL. If you change any SQL statements in the program you will need to rebuild and rebind your DBRM. For details on how to BIND the DBRM, see the BIND Guide.

Parent topic: Static Binding


Autobinding

If you have too many programs to bind using the BIND utility or just don't want to have to manually bind each program, you can compile each program with the SQL Option preprocessor directive called AUTOBIND. When this directive is specified the preprocessor will call BIND for you and will automatically bind the DBRM at the end of the compile.

XDB now supports writing out multiple DBRM's for a single program and you can automatically bind up to 10 DBRM's. The directives that support multiple options are DBRM, COLLECTION-ID, AUTHID, and LOCATION. You must also specify AUTOBIND for this to work properly.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Specifying Options with AUTOBIND

The Bind Guide specifies many bind options. New directives have been added so you can set these options using the AUTOBIND directive. These directives are optional - you do not need to specify them if you want to use default values (recommended in most cases). These additional directives are:

  • EXIST-CHECK
  • GRANT-EXECUTE
  • DEFAULT-CHAR
  • BLOCKING

If any errors occur during the automated bind process, no DBRM will be generated. However in its place will be a log file with name dbrm-name.log The log file will record all errors reported during the bind process. Consult your error documentation to resolve the error.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Binding SQL Statements With Literals

If you have literals in your SQL statements, you need to make sure that the quote character matches your build settings or you could have problems binding the DBRM.

The SQL Option preprocessor defaults to the compiler setting for literals in the build settings. If you use the same character to enclose literals in your SQL statements as you did for COBOL literals, you don't have to do anything. If you use a different character for literals in SQL statements, then you have to use the preprocessor directive of either QUOTE or APOST.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Using AUTHID to Change Table Qualifier

If you have two identical sets of tables, for example YYYYYYYY.table1 and XXXXXXXX.table1 and want to test against both sets of tables, you can use the AUTHID preprocessor directive to switch which qualifier is used.

For example, if you set it to:

XDB(AUTHID=XXXXXXXX)

XXXXXXXX becomes the default qualifier. To run against both sets of data all you need to do is change the value of the AUTHID directive to YYYYYYYY and recompile. The next time you run your application you will be pointing to YYYYYYY.table1.

Parent topic: Static Binding


Examples of DBRM Directives

The following are examples of various DBRM directives used together:

XDB(dbrm=mydbrm location=mvsprod grant-execute=public
    collection-id=nasecoll)
XDB(collection-id=nasecoll authid=naseprod autobind
    exist-check=required)

Directives can be entered on multiple lines or as one long string. Each string must start with "XDB", unless entered on the IDE/Build Settings/EXEC SQL/Preproc Additional directives entry field.

Parent topic: Static Binding


Examples of Autobinding Multiple DBRM's

The following are examples of how to autobind a program and generate multiple DBRM's:

XDB(dbrm=mydbrm1;mydbrm2 location=mvsprod;mvstest
    grant-execute=public collection-id=nasecoll;dbnats
    autobind)
XDB(collection-id=nasecoll authid=naseprod;nasetest
    autobind dbrm=testdbrm1;testdbrm2 exist-check=required )

When multiple directives are specified, they must be delimited by a semi-colon with no spaces in between. Commas and blanks are option delimiters and may cause the directive string to not be processed correctly.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Security

SQL Option security measures control access to the system and protect data stored in table objects. If the security option is turned on at both the server and on the client, you will be prompted for a user ID and password when you compile using the VALIDATE preprocessor directive or execute a program containing embedded SQL.

  • Using the Logon and Logoff Commands
  • Validating Tables
Parent topic: SQL Option Preprocesor Guide


Using the Logon and Logoff Commands

Use the SQL Option Logon and Logoff commands to avoid repeatedly logging into an XDB Server or SQL Option Link during the compile and test phase of development.

To log on to the SQL Option Server once per session, follow these steps:

From the Tools menu, select SQL Option

Select Logon

Enter your user ID and password

The SQL Option Server will automatically reuse your user ID and password each time you compile or execute the program, until you select Logoff or restart your system.

Parent topic: Security


Validating Tables

The following describes how to set up your environment to validate tables during the compile process:

  • With Security Off, the user ID will be the same authorization ID defined as the primary ID unless you define a secondary ID.
  • With Security On, the user ID will be the same ID that you enter in the logon screen and optionally the secondary ID if defined (not applicable to SQL Option Link).

To access tables with the same user ID and authorization ID, use the VALIDATE preprocessor directive. To access tables with different user ID and authorization ID, do one of the following:

  • Use VALIDATE and AUTHID preprocessor directives.
  • Define group IDs or issue a GRANT to the user ID to have access to the authorization ID defined in the AUTHID preprocessor directive.
  • Define secondary IDs.
Parent topic: Security


DSNTIAR Facility

The SQL Option DSNTIAR facility, or DSNTIAC for CICS programs, converts an SQL return code into a character string error message (similar to the IBM DSNTIAR and DSNTIAC facility on the mainframe). It takes an SQL return code from the SQLCODE element of comm-area (usually, SQLCA), and converts it to a descriptive character string. The resulting string is placed in the output area error-message, which is an array. The first element of error-message indicates the length of the message to follow. The second element is the actual message, which is usually defined as a string of the logical record length, error-rec-length, occurring n times. If at run time, the length of the message to be output is larger than one logical record (error-rec-length), and the message is treated as a set of fixed length records of length error-rec-length. The message is word wrapped and indented based on the logical record length. Every logical record begins with a space for carriage control.

  • Calling DSNTIAR or DSNTIAC
  • Example
Parent topic: SQL Option Preprocesor Guide
Related information
Calling DSNTIAR or DSNTIAC


Calling DSNTIAR or DSNTIAC

The format for calling DSNTIAR from a COBOL program is:

CALL 'DSNTIAR' USING comm-area
                     error-message
                     error-rec-length

The format for calling DSNTIAC from a CICS COBOL program is:

CALL 'DSNTIAC' USING comm-area
                     error-message
                     error-rec-length

where:

comm-area | The communications area to be used, generally set to SQLCA. The SQLCODE element of this area should contain the error code for which DSNTIAR will generate a 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 indicating the length of the second element, error-text. error-length >= 240.
error-text | which is the actual 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.
Code | Description
Error-rec-length | A n integer indicating the logical record length of output messages. 72 <= error-rec-length <= 240. If the message is longer than error-rec-length, several logical records will be used to store it.
0 | Successful execution.
4 | More data was available than could fit into the provided message area.
8 | The error-rec-length was not within acceptable limits. (72 <= error-rec-length <= 240)
12 | The message area was not large enough. Message length was >= 240.
16 | Error in message routine.

The following table shows the return codes that result from calling the DSNTIAR or DSNTIAC utility.

Code | Description
0 | Successful execution.
4 | More data was available than could fit into the provided message area.
8 | The error-rec-length was not within acceptable limits. (72 <= error-rec-length <= 240)
12 | The message area was not large enough. Message length was >= 240.
16 | Error in message routine.
Parent topic: DSNTIAR Facility


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: DSNTIAR Facility


XDB Preprocessor

The XDB Preprocessor uses a type of preprocessor interface called an External Compiler Module (ECM) interface which is tightly integrated with the Compiler and debugger. The ECM only gets passed statements that begin with EXEC SQL.

  • Setting the XDB Preprocessor and Compiler Directive Options
    Instructions on the methods provided to set the XDB preprocessor and its options.
  • XDB Compiler Directive Options
  • Setting SQL Option Background Syntax Checking Options
    Explains how to set options that determine the level at which the XDB preprocessor checks syntax in the background.
Parent topic: SQL Option Preprocesor Guide


Setting the XDB Preprocessor and Compiler Directive Options

You can specify the XDB preprocessor and its directive options using any of the following methods:
In your Enterprise Developer Project
Before compiling from within Enterprise Developer:
  1. Open your project properties and .
  2. From the drop-down list, select XDB.
On the Command Line
Use the XDB compiler directive, followed by optional preprocessor options:
XDB[(XDBdirOpts)]

Where XDBdirOpts is one or more additional directive options, each separated by a space.

In a Directives File
You can include XDB preprocessor directives in the cobol.dir system-wide directives file, a user directives file, or both. See System-wide Directives File, cobol.dir and User Directives File for details.
Embedded in a Program
You can also specify the XDB preprocessor and compiler directive options on the program level by embedding a $SET statement into the program itself starting in column 1 on the first line of the program:
$SET XDB

Where XDBdirOpts is one or more directive options, each separated by a space.

Important: Use this method only when the program requires a preprocessor different from other programs in an application.
Parent topic: XDB Preprocessor


XDB Compiler Directive Options

The SQL Option for DB2 preprocessor is specified by the XDB compiler directive, which is used with several options. Certain of these options, such as DB2, are automatically set to a default value. Most XDB compiler directive options have an alternate (or negative) syntax whereby the condition established by the option can be turned off. XDB compiler directive options are not case sensitive. For a complete list of options for the XDB compiler directive, see the topic XDB Directive Options.

For a list of XDB preprocessor error messages, see the topic SQL Preprocessor Errors.

Parent topic: XDB Preprocessor
Related information
XDB Directive Options
SQL Preprocessor Errors


Setting SQL Option Background Syntax Checking Options

Before compiling an XDB application, you can set options that determine the level at which the XDB preprocessor checks syntax in the background. To do this, click one of the following options:
No checking
The preprocessor does not connect to the DBMS and does not validate EXEC SQL statements; however, the preprocessor does check host variables.
Basic
The preprocessor does not connect to the DBMS and does not validate EXEC SQL statements; however, the preprocessor does check simple SQL statements and host variables.
Complete
This option sends all embedded SQL statements to the DBMS for validation, and requires a connection to the DBMS used by the program. Select this option for database providers that do not require SQL statement execution to perform validation.

See your documentation for information on setting properties.

Parent topic: XDB Preprocessor


How to...

  • To access SQL Option for DB2 tools
  • To add a Data Source Name (DSN) for an ODBC driver
  • To install and uninstall the ODBC driver for SQL Option
  • To log onto an XDB Server
  • To log off an XDB Server
  • Bind Utility
  • Declaration Generator
  • Link Configuration
  • Link Utility
  • Migrate Utility
  • Options Utility
  • SQL Wizard
  • SQL Option Server Administration
Parent topic: SQL Option for DB2


To access SQL Option for DB2 tools

From your Windows desktop:
Windows 8, 8.1, and Windows Server 2012
  • From the Windows Start screen, click the tile that corresponds to the tool you want to start.
Windows 10 and Later
  • From your Windows desktop, click Start > ; then click the tool you want to start.
From :
  • From your Windows desktop, click and select a tool from the submenus.
Parent topic: How to...


To add a Data Source Name (DSN) for an ODBC driver

  1. Start the ODBC Data Source Administrator. If you need instructions, see To start the ODBC Data Source Administrator.
  2. On the System DSN tab, click Add.
  3. Select Micro Focus XDB for Enterprise Team Developer n.0, from the list of ODBC drivers.
  4. Click Finish.
  5. Configure the DSN by filling in the following fields:
    • Data Source Name - Any name you choose.
    • XDB Path – Accept the default of %ProgramData%\Micro Focus\Enterprise Developer\mfsql\cfg.
    • Connection – Choose between local and remote. If you choose remote, specify the IpAddress and TcpPort of your XDB server.
    • Server – The name of your XDB Server.
    • Location – The XDB location you want to use.
    • User ID – The XDB userid to use when connecting with this data source.
    • Current SQLID – The authorization ID to use when connecting with this data source (optional). If you don't specify an SQLID, the UserID is used.
  6. Click OK to close the ODBC Driver Setup window.
  7. Click OK to close the ODBC Data Source Administrator.
Parent topic: How to...
Related tasks
To start the ODBC Data Source Administrator
Related information
To install and uninstall the ODBC driver for SQL Option


To install and uninstall the ODBC driver for SQL Option

  1. To install the ODBC driver:
    1. At an Enterprise Developer command prompt, enter:

      xdbodbcinst -i -p product-identifier

      Where product-identifier is one of the following:
      • MFE3.1
      • DX4.0
      • ETD3.0
      • ETD4.0
      • ETD5.0
      • ETD6.0
      • ETD7.0
      Note: The ETD7.0 driver is installed by default when you install Enterprise Developer.
    2. Create and configure Data Source Names (DSNs) for the driver.
  2. To uninstall the ODBC driver, start an Enterprise Developer command prompt with Administrator's rights, and execute the following:

    xdbodbcinst -u -p product-identifier.

Parent topic: How to...
Related information
To add a Data Source Name (DSN) for the ODBC driver for SQL Option


To log onto an XDB Server

  1. From the main menu, click > Client > Log On.
  2. Enter your user name (AuthID) and password.
  3. Click OK.
Note: You need only log on to an XDB Server if server security is enabled. To access an XDB Server that has security enabled, you must enable client security before you try to log on.
Parent topic: How to...
Related information
To log off an XDB Server


To log off an XDB Server

  • From the main menu, click > Client > Log Off.
Parent topic: How to...
Related information
To log on to an XDB Server


Bind Utility

  • To bind an application to a DB2 database
  • To create a default DBRM and package in DB2 for XDB Link
  • To modify an existing package
  • To rebind
  • To drop a package from DB2
  • To bind a DBRM to DB2 from the command line
  • To create a bind transaction file
Parent topic: How to...


To bind an application to a DB2 database

  1. Build your application.
  2. Ensure that client security for SQL Option is enabled.
  3. From the main menu, click > Configuration > Bind Utility.
  4. Select the location of the DB2 database from the Remote Location list.
  5. Type your current SQLID in SQLID.
  6. Click Bind.
  7. Make the selections you require on the Bind Package dialog box.
  8. Click OK.
Note: You need only bind an application when you are executing static SQL against a remote DB2 location accessed using DRDA. The database must be configured in system tables on the gateway XDB Server. Contact your system administrator if you experience difficulty in locating or binding to a DB2 database.
Parent topic: Bind Utility
Related information
To enable client security


To create a default DBRM and package in DB2 for XDB Link

Before you can use XDB Link, you must create a default DBRM for the link, and bind it to DB2. The default DBRM creates a package that XDB Link uses to execute dynamic SQL statements from your application, and to execute statically-bound SQL statements contained in the XDB Link program itself.

Follow these directions only once for each DB2 location with which you will use the XDB Link. See the Link Configuration Guide for more information.

Note:

Do not use the same default package in DB2 for more than one user group or application. To support multiple user groups or applications, you must generate a separate default DBRM and package for each on. After the first application or group uses the Gateway Profile Utility's default values, the development team must agree on the package name and collection ID with which to identify the remaining default packages. See the Link Configuration Guide for more information.

  1. In the Bind Utility window, from the Remote Location drop-down list, select the desired DB2 location.
  2. Click Default. The Create Default DBRM dialog box appears.
  3. Specify the Collection ID, Package Name, Host System, and number of Dynamic Sections.
  4. Click Create. Bind generates a default DBRM that you will use to create a package for the Link. The DBRM is stored locally in your default working directory as a .DBR file.
    Note:

    The DBRM for XDB Link contains three packages. The name of these packages are derived by combining the XDB Link package name with the letters A, B and C. For example, if your package name is XDBSYS, packages XDBSYSA, XDBSYSB and XDBSYSC are created.

  5. In the Bind Utility main window, click Bind. The Bind Package dialog box appears.
  6. In the Bind Package dialog box, select the name of the DBRM file you just created from the DBRM File Name drop-down list.
  7. If desired, set the Package Version, Isolation Level, and Action.
  8. If desired, click the Bind... button to configure additional bind options.
  9. If desired, click the Format... button to specify data formats associated with the DBRM.
  10. Click Execute. Bind creates a package in the selected DB2 location and updates the relevant DB2 tables. The Status bar indicates when the procedure is complete.
Note:
  • The Bind Utility automatically grants execute privileges to all users. Use the SQLWizard to revoke GRANT EXECUTE privileges where necessary.
  • Each time you bind a DBRM, the Bind Utility creates a log file (.LOG) in which it records all errors that occur during the bind. The .LOG file is stored in locally in the same directory as your DBRM (.LOG).

    If no error has occurred during the binding of a particular DBRM, the log file does not exist.

Parent topic: Bind Utility


To modify an existing package

When you generate a DBRM in the Static Bind Administrator, it automatically binds the DBRM, using default bind options, to create the package in DB2.

Follow this procedure if you would like to modify the package by binding the DBRM again with different parameters.

  1. In the Bind Utility window, from the Remote Location drop-down list, select the DB2 location of your application's package.
  2. Click Bind. The Bind Package dialog box appears.
  3. Select the DBRM you want to bind from the DBRM File Name drop-down list.
  4. If desired, set the Package Version, Isolation Level, and Action.
  5. If desired, click the Bind... button to configure additional bind options.
  6. If desired, click the Format... button to specify data formats associated with the DBRM.
  7. Click Execute. Bind creates a package in the selected DB2 location and updates the appropriate DB2 system tables. The Status bar indicates when the procedure is complete.
Note:

Each time you bind a DBRM, the Bind Utility creates a log file (.LOG) in which it records all errors that occur during the bind. The .LOG file is stored in locally in the same directory as your DBRM (.DBR).

If no error has occurred during the binding of a particular DBRM, the .LOG file does not exist.

Parent topic: Bind Utility


To rebind

The Rebind procedure does not read the DBRM. Rather, it recalculates path optimizations for the DBRM information in the existing package.

If you want bind to read the DBRM, see To Modify an Existing Package.

  1. In the Bind Utility window, from the Remote Location drop-down list, select the host location of the package you want to rebind.
  2. Click Rebind. The Rebind Package dialog box appears.
  3. Select the package you want to rebind from the Package drop-down list.
  4. If desired, specify a Package Version and the Isolation Level.
  5. If desired, click Bind under Modify Options to set other rebind options.
  6. Click Execute. The Bind Utility rebinds the package using the options you specified.
Parent topic: Bind Utility


To drop a package from DB2

  1. In the Bind Utility window, from the Remote Location drop-down list, select the host location of the package you want to drop.
  2. Click Drop. The Drop Package dialog box appears.
  3. From the Package drop-down list, select the package you want to remove from the host
  4. Click Execute to drop the package.
Note:

When you drop a package, it is deleted immediately, without confirmation.

Parent topic: Bind Utility


To bind a DBRM to DB2 from the command line

Use the command line if you:

  • Need to run a bind unattended (from a scheduler, for example)
  • Run a particular bind routinely
  • Wish to bind multiple programs in a single operation

Enter the following at your system command line:

BIND40N /d dbr-file /l location [option option option ...]

or

BIND40N /f transaction-file [option option option ...]

where:

dbr-file
The name of the DBRM you want to bind. If you do not specify a path, your DBRM must be in the current directory or in the XDB application path (as specified by Options). If you do not specify an extension, your DBRM must have a .DBR extension.
location
The name of the location to which the DBRM will be bound. (This is the name of the DB2 subsystem as it is registered with XDB Link.)
transaction-file
The name of the bind transaction file (.BND). Be sure to include a space between /f and the filename.
/c stop-status
stop-status can take one of the following values:
N
causes the bind to stop if an error occurs. This is the default.
Y
causes the bind to continue when an error occurs.
/s sqlID
sqlID is the ID used to set the current SQL ID at the time the package is bound.
/name=userID
userID is the user ID that will be used when the Bind Utility logs on the XDB Server.

If the /name option is not specified, you will be prompted for a user ID when the Bind Utility begins to execute.

/pass=password
password is the password that will be used when the Bind Utility logs on the XDB Server.

If the /pass option is not specified, you will be prompted for a password when the Bind Utility begins to execute.

/l location
location is the name of the remote location to which the DBRM will be bound. (This is the name of the DB2 subsystem as it is registered on the XDB Link.)
/existencechecking check-status
check-status can take one of the following values:
optional
creates a package even if the required database objects do not exist. This is the default.
required
creates a package only if the objects exist.
/grantexecute priviliges
priviliges can take one of the following values:
public
grants execute privileges to public. This is the default.
authid
grants execute privileges to authid.
/blocking block-mode
block-mode can take one of the following values:
FSR
Forced Single Row does not use block fetching regardless of cursor type.
SR
Single Row uses block fetching for read-only cursors and fetches a row at a time for ambiguous cursors.
LB
Limited Block uses block fetching for read-only and ambiguous cursors. This is the default.
/defaultchar subtype
subtype can take one of the following values:
BITS
specifies that the target relational database uses the FOR BITS DATA SQL character subtype for all new character columns for which an explicit subtype is not specified.
SBCS
specifies that the target relational database uses the FOR SBCS DATA SQL character subtype for all new character columns for which an explicit subtype is not specified.
DBCS
specifies that the target relational database uses the FOR MIXED DATA SQL character subtype for all new character columns for which an explicit subtype is not specified.
SYSDEFAULT
specifies that the target relational database uses the system default character subtype for all new character columns for which an explicit subtype is not specified. This is the default (and recommended) setting.
/d dbr-file
dbr-file is the name of the DBRM you want to bind. If you do not specify a path, the file must be in the current directory or in the XDB application path (as specified by Options). If you do not specify an extension, your DBRM must have a .DBR extension.
Note:

If you are running a bind unattended, be sure to include the /name and /pass options.

Parent topic: Bind Utility


To create a bind transaction file

To run the Bind Utility in batch mode from the command line, you must create a .BND file that contains at least one transaction. A transaction is a statement that specifies the name of a DBRM file and the location to which it will be bound. A .BND file is an ASCII text file. It can contain multiple bind transactions.

Use any ASCII text editor and type each transaction using the following format. Be sure to include a semicolon at the end of each transaction.

/d dbr-file /l location [/s sqlID];

where:

dbr-file | is the name of the DBRM you want to bind. If you do not specify a path, the file must be in the current directory or in the XDB application path (as specified by Options).
location | is the name of the location to which the DBRM will be bound. (This is the name of the DB2 subsystem as it is registered on the XDB Link.)
sqlID | is the ID to which the current SQL ID will be set when the package is bound. If SqlID is not specified, the current SqlID assignment is used (the assignment specified on the XDBBIND command line or assigned to an earlier transaction in the .BND file, whichever is more recent). Otherwise, AuthID is used.
Parent topic: Bind Utility


Declaration Generator

  • To generate a copybook for a table
  • To run interactively
  • Creating a COBOL Copybook File
  • To create a C header file
  • Running From the Command Line
  • Running in Batch Mode
  • Creating a .DGE File
  • Running a .DGE File
Parent topic: How to...


To generate a copybook for a table

  1. From the main menu, click > Client > Declaration Generator.
  2. On the XDB Declaration Generator window, specify the table you require in the Table group.
  3. In the Declaration group, type a location and name for the copybook in the Output File field.
  4. Optionally, in the Structure Name field, type a name for the group data item to be created.
  5. Optionally, click Options to specify a level for the group data item to be created.
  6. In the Field Prefix group, type a prefix to be added to the column names in the table to create host variables. For example, you might use EMP as the column name prefix for a table called EMPLOYEES.
  7. Select Text if you want the column name to be appended to the specified prefix to create the host variable name.

    Alternatively, select Numbered if you want the column's numeric position in the table to be appended to the specified prefix to create the host variable name.

  8. In the Computation group, click the data format you require for the host variables.
  9. Click Generate.

A copybook containing host variables for accessing the specified table is created.

Tip:

Click Save As to save the settings you made on the Declaration Generator window. You can use the .DGE file that is produced to run the Declaration Generator in batch mode. For more information, see Running in Batch Mode in the Declaration Generator help.

Parent topic: Declaration Generator


To run interactively

To generate a declaration file in interactive mode (through a dialog box), start the Declaration Generator as described below. To specify the procedure from the command line, see Running From the Command Line.

To use the Declaration Generator utility:

  1. From the main menu, click > Client > Declaration Generator.
  2. Provide your AUTHID and desired LOCATION if the Connect dialog box is displayed.

    You must have SELECT privileges on the table for which you are generating a declaration and on the following system tables:

    • SysIBM.SYSLOCATIONS
    • SysIBM.SYSTABLES
    • SysXDB.SYSACFUsers
  3. In the Declaration Generator dialog box, select the language in which you want the declaration file written, and complete the remainder of the dialog box, then click GENERATE.
Parent topic: Declaration Generator
Related information
Running From the Command Line
Creating a COBOL Copybook File


Creating a COBOL Copybook File

In COBOL, a copybook file is used to define data elements that can be referenced by many programs. When the Declaration Generator creates a declaration for a COBOL program, it writes it to a copybook file (.cpy file).

To create a COBOL copybook, start the Declaration Generator utility, then follow the steps below:

  1. In the Language group box, click the COBOL button.
  2. In the Table group box, select the Location, AuthID and Table Name that identifies the table for which you want to create a copybook.
  3. If you want to change the name of the file to which the copybook is written, type a new name in the Output File field (the Declaration Generator automatically places a default name based on the table name in this field).

    If you don't specify a path, the copybook is written to the first directory specified in the COBCPY environment variable. If this variable isn't found, the copybook is written to the current application path (the application path is specified in the PATHS tab in Options).

    If you specify a file that already exists, you are given the choice of appending to it or overwriting it at run time.

  4. If you want to change the name of the record description, type a new name in the Structure field.
  5. If you want to add a prefix to each of the elementary item names, type it in the Field Prefix box. You can end the prefix with a special character such as a dash (-) to set it off from the rest of the name. For example, if a prefix of EMP- were specified, field names would be written as follows:
    EMP-lname PIC X(15)
        EMP-fname PIC X(10)
        EMP-dept PIC X(12)
        .
        .
        .

    Remember the COBOL variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the compiler or one that might make the elementary item name too long.

  6. When you specify a prefix, you can optionally check the Numbered option to assign numbers instead of field names to the elementary items. If Numbered were checked using the EMP- prefix in last example, the declaration would be written as follows:
    EMP-001 PIC X(15)
        EMP-002 PIC X(10)
        EMP-003 PIC X(12)
        .
        .
        .
  7. In the Computation box, select the COMP type that you want use for the table's Int and Smallint fields.
  8. Click Options and set the following options as needed:
    For this option... | Specify...
    Level | The level number you want assigned to the record description. If you leave this field blank, Level 1 is assigned.
    Graphic Type | The PIC type you want to use for graphic, vargraphic and long vargraphic fields in the table.
    Page Size | The page size you want assigned to long varchar, long vargraphic, and long varbinary fields.
  9. Click OK to close the Declare Options dialog.
  10. If you want to save your specifications, click the Save As button, specify a file name and click OK. The specifications will be saved to a .DGE file, which can be used as input to the Declaration Generator's batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.
  11. Click the Generate button to generate the COBOL copybook file.
Parent topic: Declaration Generator


To create a C header file

In C, a header file declares constants, functions and structures. The header file can be referenced (using the #include statement) by many programs. When the Declaration Generator creates a declaration for a C program, it writes the declaration to a header file (.h file). It also generates a corresponding array of short data types to hold the null-indicator variable for each column in the table.

To create a C header file, start the Declaration Generator utility, then follow the steps below:

  1. In the Language group box, click the C button.
  2. In the Table group box, select the Location, AuthID and Table that identifies the table for which you want to create a header file.
  3. If you want to change the name of the file to which the header file is written, type a new name in the Output File field (the Declaration Generator automatically places a default name based on the table name in this field).

    If you don't specify a path, the header file is written to the directory specified by the current application path (the application path is specified in the PATHS tab in Options).

    If you specify a file that already exists, you are given the choice of appending to it or overwriting it at run time.

  4. If you want to change the name of the structure, type a new name in the Structure field.
  5. If you want to add a prefix to each element name, type it in the Field Prefix box. You can end the prefix with a special character such as an underscore (_) to set it off from the rest of the name. For example, if a prefix of emp_ were specified, element names would be written as follows:
    char emp_lname[15];
        char emp_fname[10];
        char emp_dept[12];
        .
        .
        .

    Remember to take into account C variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the compiler or one that might make the variable name too long.

  6. If you want to assign numbers instead of field names as element names, check the Numbered option. (This option can be selected only when a field prefix is used. See the previous step.) If the Numbered option were checked in the example above, the declaration would be written as follows:
    char emp_001[15];
        char emp_002[10];
        char emp_003[12];
        .
        .
        .
  7. Click the Options button.
  8. In the C Declaration Options dialog box, specify the way in which you want the structure written.
    • Use the options in the Structure Elements box to specify the case in which you want the element names written.
    • Use the Declare The Structure option to assign a variable name to the structure as shown in the following example. The variable name is derived from the Structure field specified in step 4).
      .
        .
        .
        double emp_payrate;
        double emp_com;
        } dcl_employee;

    If you don't set Declare The Structure, the structure is written as a data-type definition. The name specified in the Structure field is assigned as the name of the data type, as shown in the following:

    struct dcl_employee
        {
        short emp_ssn;
        char emp_lname[11];
        char emp_fname[11];
        .
        .
        .
  9. If you want to save your specifications, click the Save As button, specify a file name and click OK. The specifications will be saved to a .DGE file, which can be used as input to the Declaration Generator batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.
  10. Click the Generate button to generate the C header file.
Parent topic: Declaration Generator
Related information
Running in Batch Mode
Example C Structure


Running From the Command Line

You can create your declaration file without opening the Declaration Generator window. This is done by running the Declaration Generator and specifying its options from your Enterprise Developer command prompt.

To run the Declaration Generator from the Enterprise Developer command prompt, you call the dclg40n program using the following syntax:

dclg40n -tTableName [option1 option2 option3...]

where TableName specifies the name of the table for which a declaration file will be generated. Location and AuthID can be specified using location.authid.tablename notation.

The following table describes the command line options.

Option | Description
-a | Writes element names in a C structure in uppercase. If -a is not specified, element names are written in lowercase.
-cCompValue CompValue specifies the computation type assigned to COBOL binary integers.

CompValue must be one of the following numeric values:

  • 0 - uses COMP
  • 4 - uses COMP-4
  • 5 - uses COMP-5

If this option is not included, 0 (COMP) is used.

-d | Includes a variable declaration for the defined C structure. If -d is not specified, a C structure is defined, but it is not declared as a variable.
-fDecFileName DecFileName specifies the name of the file to which the Declaration Generator will write the declaration.

If you do not include this option, the source table name will be used as the declaration file name (with the extension .h for C, .cpy for COBOL, or .inc for PL//I).

If a path is not specified, the file is written to the directory specified in the application path. Do not include an extension with the file name.

If you specify a file name that already exists, and the -r option is not specified, the Declaration Generator will ask whether you want to replace or append to the file at run time. If -r is specified, the file will automatically be overwritten (see -r below).

-gPicType Pictype specifies the COBOL data type that will be used for graphic, vargraphic and long vargraphic fields.

Pictype must be one of the following:

  • PICN declares graphic fields as PIC N(x).
  • PICG declares graphic fields as PIC G(x) DISPLAY-1
  • PICX declares graphic fields as PIC X(x)

If this option is not included, PICN is used.

-h | Opens the Declaration Generator help file.
-iIniFileName IniFileName specifies the disk, directory, filename and extension of the initialization file to be used.

If this option is not included, the XDB.INI file in the current working directory is used.

-kPageSize PageSize specifies the page size that will be assigned to COBOL declarations for long varchar, long vargraphic, and long varbinary fields.

PageSize must be one of the following:

  • 4k
  • 32k

If this option is not included, 4K is used.

-lLanguage Language specifies the language in which the Declaration Generator will write the declaration file.

Language must be one of the following:

  • C
  • COBOL
  • PLI

If this option is not included, COBOL is used.

-n | Runs the Declaration Generator without stopping on errors or for user responses.
-pPrefix Prefix is a 1 - 27 character string to be prefixed to each field name to form an element name.

For example, if the option -pemp_ were used, the field names ssn and lname would become element names emp_ssn and emp_lname, respectively.

-r | Automatically replaces a declaration file if it already exists. If -r is not specified, the program asks whether to replace or append to a file that already exists.
-sStructure Structure specifies the name to be assigned to the record definition (COBOL) or structure (C).

If this option is not included, the table name is assigned to the structure.

-uNames Specifies whether field names will be concatenated with the string specified by -pPrefix (above), or whether they will be replaced with numbers.

If Names is set to real, field names are concatenated to Prefix.

If Names is set to n/a, a 3-digit, sequential number is concatenated to prefix.

For example, if the option -ureal were used, field names would be concatenated with the string specified in -pPrefix.

If -psales- and -un/a were used, the prefix sales- would be combined with a three-digit number to form element names such as sales-001, sales-002, and so on.

-vLevel | Level assigns a level number to a COBOL record description. If -v is not used, field-level definitions are set to 2.

Example Command Line

The following example shows the command line for a COBOL copybook created for an EMPLOYEE table on a Windows system.

dclg40n -ic:\xdb\xdb.ini -tinstall.employee -lcobol -femployee.cpy -sdclemployee -psales -ureal -c4 -v2

In this example, the Declaration Generator will assign the name dclemployee to the record definition, and will prefix each elementary item with the string sales. COMP-4 class will be assigned to int and smallint fields. Level 2 will be assigned to the field-level definitions.

Parent topic: Declaration Generator


Running in Batch Mode

If you have several tables for which you want to generate declaration files, you can create them using the Declaration Generator's "batch mode."

In batch mode, you can type the specifications for one or more tables in a .DGE file, then use the file as input to the Declaration Generator program. This process lets you generate declaration files for several tables in a single operation rather than generating them one-by-one interactively or from the command line.

Parent topic: Declaration Generator


Creating a .DGE File

To run the Declaration Generator in batch mode, you must create a .DGE file specifying the tables for which you want declaration files generated, and the language(s) in which you want the declaration files written.

A .DGE file can be created in two ways:

  • You can enter your specifications in the Declaration Generator window and save them with the SAVE AS button. See Running Interactively.
  • You can create a .DGE file using any ASCII text editor.

The .DGE file must be stored in the DEFAULT APPLICATION PATH as specified in Options, PATHS tab, and it must have a .DGE extension.

A .DGE file contains the instructions needed to generate one or more declaration files. Each line in the file specifies a single "transaction," which creates a single declaration file in a single language (COBOL, C or PL/I). A transaction is specified as follows:

            tablename
            decFileName [option1
            option2
            option3...]

Where:

tablename specifies the name of the table for which a declaration file is generated. You can specify location and AuthID information using location.authid.tablename notation.

decFileName specifies the name of the file to which the declaration statements are written.

  • Do not include path information in decFileName. The Declaration Generator automatically writes the file to the application path (the application path is specified in the PATHS tab of Options).
  • Do not include an extension in decFileName. An extension is automatically assigned based on the language you've specified.

The option parameters specify the programming language, structure name and other parameters, if you don't want to use the defaults. See

DGE File Transaction Options

The following table describes the optional parameters you can include in a transaction statement. If an option is not included in a transaction statement, a default value is used.

Option Description Example
a=Case Where Case determines whether C element names are written in upper or lower case.

If Case is set to upper, element names are written in uppercase.

If Case is set to lower, or if this option is not set, element names are written in lowercase.

 a=upper generates uppercase elements.
c=CompValue CompValue specifies the COMP type assigned to binary integers (for COBOL only; this option is ignored if language is set to C).

CompValue must be one of the following:

  • 0 - uses COMP
  • 4 - uses COMP-4
  • 5 - uses COMP-5
  • 0 (COMP) is the default.
 c=4 assigns COMP-4 to binary integers.
d=DStuc Where DStruc determines whether a C structure is written as a variable declaration.

If DStruc is set to decl, the structure is declared as a variable.

If DStruc is set to nodecl, or if this option is not set, the C structure is defined as a data type, but is not declared as a variable.

 d=decl creates a variable declaration from the structure.
g=PicType Where Pictype specifies the COBOL data type that will be used for graphic, vargraphic and long vargraphic fields.

Pictype must be one of the following:

  • PICN declares graphic fields as PIC N(x).
  • PICG declares graphic fields as PIC G(x) DISPLAY-1
  • PICX declares graphic fields as PIC X(x)
  • PICN is the default.
 g=PICG declares graphic fields as follows:

PIC G(x) DISPLAY-1,

k=PageSize Where PageSize specifies the page size that will be assigned to COBOL declarations for long varchar, long vargraphic, and long varbinary fields.

PageSize must be one of the following:

  • 4K
  • 32K
  • 4K is the default.
 k=32K assigns a 32k pages size to long variables.
l=Language Language specifies the language in which the declaration will be written. Language must be one of the following:
  • C
  • COBOL
  • COBOL is the default.
 l=C generates a C header file.

l=COBOL generates a COBOL copybook.
p=Prefix Prefix specifies the prefix that will be affixed to each of the element names.

Depending upon the state of the u=Names option, this prefix will either be concatenated with a field name or a number to form an element name.

See u=Names, below.

 p=sales- u=real

combines the prefix sales- with the field names to form element names such as sales-dept, sales-mgr, and so on.

p=sales- u=n/a

combines the prefix sales- with a three-digit number to form element names such as sales-001, sales-002, and so on.

s=Structure Structure specifies the name of the record definition (COBOL) or structure (C). This name must be valid for the chosen language.

If Structure is not specified, the following defaults are used:

  • For C: c_tablename
  • For COBOL: dcltablename
 s=c_SalesReps assigns the name c_SalesReps to the generated structure
u=Names Where Names specifies whether field names or numbers are concatenated to Prefix to form element names (see p=Prefix, above).

If Names is set to real, field names are concatenated to Prefix.

If Names is set to n/a, or if this option is not set, numbers are concatenated to Prefix.

 p=sales- u=real

combines prefix sales- with field names to form element names such as sales-dept,sales-mgr, and so on.

p=sales- u=n/a

combines the prefix sales- with a three-digit number to form element names such as sales-001, sales-002, and so on.

v=Level Where Level is an integer specifying the number to be assigned to the field-level definitions in a COBOL record description. v=3 writes level-3 field definitions, for example:
3 ST PIC X(2).
3 ZIP PIC X(5)
Parent topic: Declaration Generator


Running a .DGE File

Once you have created a batch declaration file, you can run the batch version of the Declaration Generator from your Enterprise Developer command prompt.

To run the Declaration Generator in batch mode, you call the dclg40n program using the following syntax:

dclg40n [-iIniFile -r -n]-b FileName

where:

IniFile specifies the disk, directory, filename and extension of the initialization file to use. If this option is not included, the initialization file in the current working directory is used.

FileName is the name of the .DGE file containing the transactions you want to run. If you don't specify a path, the Declaration Generator looks for the .DGE file in the application path (the application path is specified by in the PATHS tab in Options).

-r and -n are options that affect the presentation of error messages and the treatment of existing declaration files. For more information about these options, see Running From the Command Line.

The following example generates the declaration files specified by the EMPDATA.DGE file.

dclg40n -b c:\BATCH\EMPDATA

The following example generates the declaration files specified by the EMPDATA.DGE file, using the EMP.INI initialization file.

dclg40n -iEMP.INI -b c:\BATCH\EMPDATA
Parent topic: Declaration Generator
Related information
Running From the Command Line


Link Configuration

  • Configure the Host
  • Configure the PC
  • Configure DB2 Access
Parent topic: How to...


Configure the Host

  • Configuring the Host for TCP/IP Access to XDB Link
  • XDB Link Host Option
  • Installing and Configuring the XDB Link Host Option
  • Starting the XDB Link Host Option on the Mainframe
  • Configuring the Host for SNA Access to XDB Link
  • Configuring DB2 to Accept DRDA Requests
Parent topic: Link Configuration
Related information
Configure the PC
Configure DB2 Access


Configuring the Host for TCP/IP Access to XDB Link

If you are using TCP/IP to connect XDB Link to OS/390, and you are using a version of DB2 that does not support direct access to the DDF facility via TCP, you must install and configure the XDB Link Host Option on the host. This program receives TCP/IP packets containing DRDA-compliant requests from XDB Link and routes them to DB2 via APPC. If DB2 security is a concern, it is suggested the XDB Link be used in all cases.

Parent topic: Configure the Host
Related information
XDB Link Host Option
Installing and Configuring the XDB Link Host Option
Configure the Host


XDB Link Host Option

  1. Before installing the XDB Link Host Option, verify the host IP address and reserve a port number for XDB Link.
  2. Install and configure the XDB Link Host Option.
  3. Start the XDB Link Host Option on the mainframe.
  4. Work with the Access List.
Parent topic: Configure the Host
Related information
Installing and Configuring the XDB Link Host Option
Starting the XDB Link Host Option on the Mainframe
The Access List


Installing and Configuring the XDB Link Host Option

The following describes the steps to install and configure the XDB Link Host Option.

Note:

To install the software, you will need the information provided by your TCP/IP network administrator on the TCP XDBPARM worksheet. If you do not have a completed copy of this worksheet, get one before you begin.

To install the XDB Link Host Option

  1. Create and install JCL PDS with FB LRECL 80.
  2. Create and submit the following JCL to unload the INSTALL JCL file (file 1) of the installation tape:
    //jobname JOB jobcard information
        //STEP1 EXEC PGM=IEBGENER
        //SYSPRINT DD SYSOUT=A
        //SYSUT1 DD DSN=XDBLINK.V100T.INSTALL,DISP=OLD,
        // UNIT=inputdev,VOL=SER=volser,LABEL=(1,SL),
        // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)
        //SYSUT2 DD DSN=xdblink.v100.INSTALL,
        // DISP=(,CATLG),
        // UNIT=dasd,VOL=SER=vvvvvv, // DCB=*.SYSUT1,SPACE=(TRK,(1,1))
        //SYSIN DD DUMMY

    where:

    inputdev | is the tape input device unit parameter
    volser | is the input tape volume serial number
    xdblink | is the XDB Link installation data set prefix
    v100 | is the high-level data set prefix
    dasd | is the DASD device unit of the install data set to be created
    vvvvvv | is the volume serial number of the install data set
  3. Edit and submit the JCL created by step 2 (xdblink.v100.INSTALL). Correct errors and rerun the job if the return code is not zero.
  4. Edit the sample VTAM application definition for XDB Link in xdblink.v100.CNTL(VTAMLST). The value of the LU62 APPLID parameter must match the ACBNAME of the XDB Link Host Option. Also, the value of the APPLID PASSWORD parameter must match the PRTCT parameter of the application definition.
  5. Edit the sample access list in xdblink.v100.ACCESS.
  6. If you are a RACF user, edit and submit the sample JCL (optional) in xdblink.v100.CNTL(RACFACC) to protect the access list. Otherwise, create and submit equivalent JCL.
  7. Edit the xdblink.v100.CNTL(XDBGTF) member (optional) and copy it to a cataloged procedure library. Modify the DSNAME for IEFRDER to conform to the naming standards for your site.
  8. Edit the xdblink.v100.CNTL(GTFXDB) member for the GTF procedure (optional). USR=(xxx) must match the EID parameter in the parameter member.
  9. Edit the sample parameter member in xdblink.v100.PARAM(PARMTCP).
  10. Copy the VTAM application definition to the active VTAMLST library and put the major node into the ATCCONxx member of the VTAMLST library. VTAM must be cycled for the updated ATCCONxx member to take effect.
    Note:

    To avoid cycling VTAM, use the VTAM vary command to activate the major node.

  11. Edit the sample started task xdblink.v100.CNTL(#PROCLNK) and copy it to a system procedure library.
Parent topic: Configure the Host
Related information
Started Task Parameters
Configure the Host


Starting the XDB Link Host Option on the Mainframe

The XDB Link Host Option must be running in order for XDB Link to access DB2 using TCP/IP. To start the Host Option, issue the following command from the system console:

S stcname

where stcname is the name of the started task created in step 11.

To display the status of the started task and verify that the correct port number is selected, use the following command:

F stcname, DISPLAY STATUS
Parent topic: Configure the Host


Configuring the Host for SNA Access to XDB Link

To use XDB Link with SNA:

  1. Verify that VTAM is set up to allow independent LU6.2 access to host data. Have the VTAM systems programmer complete the VTAM Worksheet.
  2. Ensure that independent LU6.2 and 3270 support have been generated for the physical unit (PU) supporting XDB Link:
    • Create the PU.
    • Create an independent LU definition.
    • Create a mode entry that supports parallel sessions and is compatible with IBMRDB.
Note: Do not discard the VTAM worksheet when you are finished configuring VTAM. It contains information that you will use to configure other parts of XDB Link.
Parent topic: Configure the Host
Related information
VTAM Worksheet
Configuring XDB Link for DB2 Access


Configuring DB2 to Accept DRDA Requests

To use XDB Link to access DB2 data on an OS/390 system, have a database administrator (DBA) or the DB2 system administrator configure DB2 to accept DRDA requests as described in the following steps.

To configure DB2 to accept DRDA requests from XDB Link

  1. Complete the DB2 worksheet and ensure that the Distributed Data Facility (DDF) is activated.
  2. Execute one of the following statements to add a record to the DB2 SYSIBM.LUNAMES table (for DB2 Version 5 and later) or to SYSIBM.SYSLUNAMES (for DB2 Version 4 and earlier). These statements enable any remote location (including XDB Link) to access DB2 if a valid user ID and password are supplied.

    For DB2 Version 4 and earlier, execute the following statement:

    INSERT INTO sysibm.syslunames (luname, sysmodename, usersecurity,encryptpswds, modeselect, usernames) VALUES (' ', ' ', 'C', 'N', 'N', ' ');

    For DB2 Version 5 and later, execute the following statement:

    INSERT INTO sysibm.lunames (luname, sysmodename, security_in, security_out, encryptpswds, modeselect, usernames) VALUES (' ', ' ', 'A', 'A', 'N', 'N', ' ');
  3. Execute the following statement to add a record to the DB2 SYSIBM.LOCATIONS table (for DB2 Version 5 and later) or to SYSIBM.SYSLOCATIONS (for DB2 Version 4 and earlier). This statement specifies the local location name for DB2:

    For DB2 Version 4 and earlier, execute the following statement:

    INSERT INTO sysibm.syslocations (location, loctype, linkname, linkattr) VALUES ('your-location-id', ' ', ' ', ' ');

    For DB2 Version 5 and later, execute the following statement:

    INSERT INTO sysibm.locations (location, loctype,   linkname, linkattr) VALUES ('your-location-id', ' ', ' ', ' ');
  4. Cycle DDF to put the updated tables into effect.
Note:

Do not discard the DB2 worksheet when you are finished configuring DB2. It contains information that you will use to configure other parts of XDB Link.

Parent topic: Configure the Host
Related information
DB2 Worksheet
Worksheets


Configure the PC

  • Configuring TCP/IP Software for the PC
  • Configuring the Microsoft SNA Server
  • Installing the DLC Protocol
  • Configuring SNA Server 2.11
  • Configuring SNA Server 3.0
Parent topic: Link Configuration
Related information
Configure the Host
Configure DB2 Access


Configuring TCP/IP Software for the PC

Use the following procedure to configure the TCP/IP software for XDB Link. Use your values from the TCP Host/Service worksheet to complete these steps.

To configure TCP/IP perform the following steps:

  1. Install a TCP/IP protocol. If a TCP/IP protocol is already installed (for example, Microsoft TCP/IP), ensure that it is enabled.
  2. Make a backup copy of the HOSTS and SERVICES files.
  3. Add the following line to the HOSTS file:
    IPAddress IPName

    where:

    • IPAddress specifies the TCP/IP address of the host system. Use the value in J1 of the TCP Host/Service worksheet.
    • IPName is a name that you assign to this address. Type IPName in uppercase letters. Lowercase characters will cause problems under certain circumstances. Use the value in J2 of the TCP Host/Service Worksheet.

    For example: 204.17.148.230 LUDB2

    Note:

    If this is the last line in the HOSTS file, type a carriage return at the end of the line.

  4. Edit the SERVICES file by adding the following line:
    ServiceName Port/tcp

    where:

    ServiceName specifies a name that represents the port number on the host system. (You will use this name when you configure XDB Link in a later step.) Type the ServiceName in uppercase letters. Lowercase characters will cause problems under certain circumstances.

    Port specifies the dedicated TCP/IP port assigned to the XDB Link Host Option on the host system. Use the value in J4 of the TCP Host/Service worksheet.

    For example:

    XDBSRV 5170/tcp
    Note:

    If this is the last line in the SERVICES file, type a carriage return at the end of the line.

When connecting to DB2 with native TCP/IP:

  • Choose DRDA(TCP/IP) as your Connection Type
  • The Remote Host entry should match the mainframe's IP address entry in your HOSTS file.
  • The port entry should match the DB2 port entry in your SERVICES file. IBM's default port is 446/tcp but users should check with their administrators to find out what port their DB2 listens on.
Parent topic: Configure the PC
Related information
TCP Host/Service Worksheet
Worksheets


Configuring the Microsoft SNA Server

Use the following procedures to configure Microsoft SNA Server for XDB Link. After initially configuring the server, you can make additional modifications to boost throughput, add more users, or add another connection.

To configure the SNA Server

  1. Install the DLC protocol on your server
  2. Configure the SNA Server settings for for SNA Server 2.11 or SNA Server 3.0.
Parent topic: Configure the PC
Related information
Configure the PC
Installing the DLC Protocol


Installing the DLC Protocol

You must install the DLC protocol on your server machine before you configure the Microsoft SNA Server software.

This procedure assumes that you have installed the SNA Server. If you have not already done this, install this software before proceeding.

Note: If the program cannot find the DLC Protocol files on your workstation, it will ask you to insert the Windows CD. Make sure you have this CD on hand during this procedure.

When the installation is finished, the program will ask you to reboot the system. If this is a production machine, you may want to schedule this task for a maintenance period or for off-peak hours.

To install the DLC protocol:

  1. In the Windows Control Panel, select Network.
  2. In the Network Settings dialog box, select the Protocols tab (4.0 only) and click Add or Add Software.
  3. Select DLC Protocol from the network settings list and click Continue or OK.
  4. Complete the installation process as directed by the instructions on the screen.
  5. After you reboot, make a backup copy of your current SNA configuration (optional) and then configure SNA Server Version 2.11 or SNA Server Version 3.0.
Note: Micro Focus provides a sample configuration file, xdb_novl.sna, for you to examine and use as a guide. This file is located in your XDB application directory. It defines an Ethernet connection to a network node.
Parent topic: Configure the PC
Related information
Configuring SNA Server 3.0


Configuring SNA Server 2.11

This procedure describes the steps you use to configure the SNA Server 2.11 software. Be sure that you complete all four tasks.

Use the values from your SNA Server worksheet (V2.11).

  1. Configure server properties
    1. Start the SNA Server Admin program if it is not already running.
    2. If the Servers and Connections window is not open, double-click the Servers and Connections icon.
    3. In the left pane of the Servers and Connections window, double-click the name of your SNA Server to open the Server Properties dialog box.
      In this field... Specify...
      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value D1.

      Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

      Worksheet value D2.

    4. Click OK to apply your settings and close the Server Properties dialog box.
  2. Create and configure a connection
    1. In the left pane of the Servers and Connections window, highlight the name of your SNA Server, then select New Connection from the Services menu.
    2. In the Insert Connection dialog box, select 802.2, then click OK.
    3. In the Connection Properties dialog box, type a name for this connection in the Connection Name field. Use the value in D3 of the TCP Host/Service Worksheet.

      Then, complete the following:

      In this field... | Select...
      Link Service | SnaDlc1
      Remote End | Host System
      Activation The event that will activate this connection. We recommend that you select On Server Startup.

      Worksheet value D6.
      Allowed Directions | Outgoing Calls and Incoming Calls
    4. Click Setup to open the 802.2 Setup dialog box and specify the following:
      In this field... | Specify...
      Remote Network Address The 12-digit hexadecimal network address (MAC address) as defined in the MACADDR= parameter in VTAM or NCP controller definition.

      Worksheet value D8.

      Local Node ID The 8-digit hexadecimal local ID number for this SNA server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK

      Worksheet values D9.
      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value D1.

      Control Point Name The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP.

      Worksheet value D11.

      Remote Node ID | Leave blank.
    5. Click Advanced>> to display the advanced options
    6. In the XID Type group box, select Format 3.
    7. Click OK to close the 802.2 Setup dialog box.
    8. Click OK to close the Connection Properties dialog box.
  3. Create and configure the Local APPC LU
    1. In the left pane of the Servers and Connections window, highlight the name of your SNA Server.
    2. Select the Insert command from the Edit menu.
    3. In the Insert dialog box, select APPC [Local] and click OK.
    4. In the New APPC LU Properties dialog box, complete the following:
      In this field... | Specify...
      LU6.2 Type | Independent
      LU Alias A name that represents this machine in its local SNA communications configuration.

      We recommend that you use the XDB Server name as the alias for this machine.

      Worksheet value D15.

      LU Name The LU name of this APPC LU as it is specified in VTAM.

      Worksheet value D17.

      Enable Automatic Partnering | Enable
      Implicit Incoming Remote LU | (None)
    5. Click OK to close the APPC LU Properties dialog box.
  4. Create and configure the remote APPC LU
    1. In the left pane of the Servers and Connections window, highlight the name of the Microsoft SNA server connection you created and select the Insert command from the Edit menu.
    2. In the Insert dialog box, select APPC [Remote] and click OK.
    3. In the New APPC Remote LU Properties dialog box, complete the following:
      In this field... | Specify...
      LU Alias A name to represent the remote APPC LU in this SNA server's communication configuration.

      Worksheet value D20.

      LU Name The VTAM APPLID for DB2.

      Worksheet value D22.

      Uninterpreted LU Name | The same VTAM APPLID specified in LU Name above, or nothing (leave blank).
      Supports Parallel Sessions | Enable
      Enable Automatic Partnering | Enable
      Implicit Incoming Mode IBMRDB, an independent mode definition that you have defined, or (None)

      If you use your own mode definition, it must support parallel sessions.

    4. Click Partners to open the LU6.2 Partner LUs dialog box, then click Add.
    5. In the Add APPC LU Partner dialog box, select the following:
      In this field... | Select...
      Partner LU | The Local LU you created when you configured Microsoft SNA Server.
      Mode | IBMRDB
    6. Click OK to close the Add APPC LU Partner dialog box. Click Close to close the LU6.2 Partner LUs dialog box, then click OK to close the New APPC Remote LU Properties dialog box.
    7. Select Save Configuration from the File menu to save the new configuration, then restart the server to put the new configuration into effect.

      The connection is ready to use with XDB Link.

Parent topic: Configure the PC


Configuring SNA Server 3.0

This procedure describes the steps for configuring the SNA Server, version 3.0. Be sure to complete all tasks. Use the values from your SNA Server Worksheet (3.0).

  1. Insert a Link Service
    1. Start the SNA Server Manager if it is not already running.
    2. In the Server Manager window, select the name of your SNA Server.
    3. Select the Link Service command from the Insert menu.
    4. Select DLC 802.2 Link Service in the Insert Link Service dialog box, then click Add.
    5. Click OK in the DLC 802.2 Link Services Properties dialog box to accept the default settings.
  2. Configure SNA Server Properties
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the Properties command from the View menu.
    3. On the General tab in the Properties dialog box, set the following:
      In this field... Specify the following...
      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value E1.

      Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

      Worksheet value E2.

    4. Click OK to close the Properties dialog box.
  3. Create and configure a connection
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the Connection command from the Insert menu, then select 802.2.
    3. On the General tab in the Connection Properties dialog box, set the following:
      In this field... | Specify...
      Name A name for this connection.

      Worksheet value E3.

      Link Service | SnaDlc1
      Support Dynamic Remote APPC LU Definition | Enable
      Remote End | Host System
      Allowed Directions | Both Directions
      Activation The event that will activate this connection. We recommend that you select Server Startup.

      Worksheet value E7.
    4. Select the Address tab in the Connection Properties dialog box and set the following:
      In this field... Specify...
      Remote Network Address The 12-digit hexadecimal network address (MAC address) as defined in the MACADDR= parameter in VTAM or NCP controller definition.

      Worksheet value E8.

      Remote SAP Address The remote SAP address. For most installations, the default value of 04 is appropriate.

      Worksheet value E9.

    5. Select the System Identification tab in the Connection Properties dialog box and set the following:
      In this field... | Specify...
      Network Name

      (Local)

              The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx). (The Network Name specified in TASK 2 will automatically appear in this field.)

      Worksheet value E1.

      Control Point

      (Local)

              The control point name of your VTAM system as defined by the VTAM PU. (The Control Point name specified in TASK 2 will automatically appear in this field.)

      Worksheet value E11.
      Local Node ID The 8-digit hexadecimal local ID number for this server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK

      Worksheet value E12.

      XID Type | Format 3
      Network Name

      (Remote)

              The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value E1.

      Control Point

      (Remote)

              The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP.

      Worksheet value E15.

      Remote Node ID | Leave blank
    6. Select the 802.2 tab in the Connection Properties dialog box and verify that the Max BTU Length is less than or equal to MAXDATA in the VTAM PU definition.
    7. Click OK to close the Connection Properties dialog box.
  4. Create and configure the APPC Mode Definition
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the APPC command from the Insert menu, then select Mode Definition.
    3. On the General tab in the Remote APPC Mode Definition dialog box, set the following:
      In this field... Specify the following...
      Mode Name IBMRDB or an independent mode definition that you have defined in VTAM.

      If you use your own mode definition, it must support parallel sessions.

      Worksheet value E33.

    4. Select the Limits tab and set the following:
      In this field... | Specify the following...
      Parallel Session Limit The DSESLIM value for your PU definition in SYS1_VTAMLST.

      Worksheet value E34.

      Minimum Contention Winner Limit | Half the number specified in the Parallel Session Limit field.
    5. Complete the Limits tab by setting the following suggested values or specifying appropriate values for your network configuration:
      Field Name | Suggested Value...
      Partner Minimum Contention Winner Limit | 0
      Automatic Activation Limit | 0
    6. Select the Characteristics tab and set the following suggested values or use values appropriate for your network configuration:
      Field Name | Suggested Value...
      Pacing Send Count | 7
      Pacing Receive Count | 7
      Max Send RU Size | 4096
      Max Receive RU Size | 4096
      High Priority Mode | Enabled
    7. Click OK to close the Local APPC LU Properties dialog box.
  5. Create and configure the local APPC LU
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the APPC command from the Insert menu, then select Local LU.
    3. On the General tab in the Local APPC LU Properties dialog box, set the following:
      In this field... Specify...
      LU Alias A name that represents this machine in its local SNA communications configuration.

      We recommend that you use the XDB Server name as the alias for this machine.

      Worksheet value E18.

      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx). The Network Name specified earlier should automatically appear in this field.

      Worksheet value E1.

      LU Name The LU name of this APPC LU as it is specified in VTAM.

      Worksheet value E20
    4. Select the Advanced tab in the Local APPC LU Properties dialog box and set the following:
      In this field... | Specify the following...
      Member of Default Outgoing Local APPC LU Pool | Disable
      Implicit Incoming Remote LU IBMRDB, an independent mode definition that you have defined, or <None>.

      If you use your own mode definition, it must support parallel sessions.

      LU6.2 Type | Independent
      SyncPoint Support | Disabled
    5. Click OK to close the Local APPC LU Properties dialog box.
  6. Create and configure the Remote APPC LU
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the APPC command from the Insert menu, then select Remote LU.
    3. On the General tab in the Remote APPC LU Properties dialog box, set the following:
      In this field... | Specify...
      Connection | The name of your connection
      LU Alias A name to represent the remote APPC LU in this server's SNA communication configuration.

      Worksheet value E26.

      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx). The Network Name specified earlier should automatically appear in this field.

      Worksheet value E1.

      LU Name The VTAM APPLID for DB2.

      Worksheet value E28 and A9.

      Uninterpreted LU Name | The same VTAM APPLID specified in LU Name above, or nothing (leave blank).
    4. Select the Options tab in the Remote APPC LU Properties dialog box and set the following:
      Set this field... | To...
      Supports Parallel Sessions | Enabled
      Implicit Incoming IBMRDB, an independent mode definition that you have defined, or <None>

      If you use your own mode definition, it must support parallel sessions.

      Session-Level Security | No Session-Level Security
    5. Click OK to close the Local APPC LU Properties dialog box.
    6. Select the Save command on the File menu to save this configuration, then restart the server to put the new configuration into effect.

      The connection is ready to use with XDB Link.

Parent topic: Configure the PC
Related information
SNA Server Worksheet (V3.x)
Worksheets


Configure DB2 Access

  • Configuring XDB Link with the Gateway Profile Utility
  • Defining Remote XDBHOST Connection Types
  • Defining Remote DRDA(APPC) Connection Types
  • Binding XDB Link to DB2
  • Creating Required Tables and Views
  • Configuring the Client Workstation
  • Configuring XDB Link Security
  • Creating User IDs for XDB Link
  • Enabling Security on the Client Workstation
  • Configuring Communications Software on the PC
Parent topic: Link Configuration
Related information
Configure the Host
Configure the PC


Configuring XDB Link with the Gateway Profile Utility

You can use the Gateway Profile Utility to:

  • Define remote locations to XDB Link so that XDB client applications can access data in those locations.
  • Configure the settings XDB Link needs to translate data correctly and control client conversations.

If you have installed XDB Link on an XDB Server as part of a gateway configuration, you must:

  • Have super-user privileges on the XDB Server where XDB Link is installed.
  • Run the Gateway Profile Utility on the machine where XDB Link is installed.

If you need additional information about the Gateway Profile Utility while doing this procedure, see the topic Gateway Profile Utility.

To configure XDB Link using the Gateway Profile Utility

  1. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  2. Start the Options utility. (If you are using the gateway configuration, do this at the machine where XDB Link is installed).
  3. When the Options window opens, set the following values on the Connect page:
    If you are using ... | Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Location field, select the SYSTEM location.

    In the Protocol field, select the Local protocol.

    Direct-connect configuration | In the Protocol field, select DRDA.
  4. Click OK to save your settings and close Options.
  5. Start the Gateway Profile Utility by selecting its icon in the XDB program group or folder. (If you are using the gateway configuration, do this at the machine where XDB Link is installed.) If prompted for a user ID, enter an ID that has super-user or SYSADM privileges.
  6. When the Gateway Profile Utility window opens, click Register to display the Location Configuration dialog box. You use this dialog box to add the remote database to XDB Link.
  7. In the Location Name field, type the name of the remote database from row B9 in your DB2 worksheet. This is the DB2 location name used by the DDF facility.
    Note:

    A common mistake is to specify theDB2 APPLID in VTAM or the 4-character SUBSYSTEM name for DB2. These names are usually NOT the same name as the DB2 location name (although your DB2 systems programmer may have decided that all three of these names should be the same.) See your DB2 systems programmer to determine the DB2 location name.

  8. Complete the configuration process using the appropriate steps for your connection type:
    If XDB Link will use ... | Follow the procedures in the section ...
    TCP/IP to access DB2 | Configuring XDB Link for DB2 Access.
    SNA to access DB2 | Configuring XDB Link for DB2 Access.
Parent topic: Configure DB2 Access
Related information
Gateway Profile Utility
Defining Remote XDBHOST Connection Types
Defining Remote DRDA(APPC) Connection Types


Defining Remote XDBHOST Connection Types

Use the following procedure to complete the Location Configuration dialog box if you are using TCP/IP to access DB2 through the XDB Link Host Option.

To define an XDBHOST connection

  1. Select XDBHOST(TCP/IP) from the Connection Type list box.
  2. In the DRDA Setup group box, specify the Package Name and Collection Identifier of the package that XDB Link will use to pass dynamic SQL to DB2. If your DBA or XDB administrator has already created a package on the host for XDB Link, make sure that you enter the package name and collection ID as it has been specified on the host.
    Note:

    If you have an earlier version of XDB Link, give this version a new package name. We suggest that you adopt a package naming convention that includes the XDB Link version number-- for example, XLNK600, XLNK601, XLNK602. In a multiple-gateway environment, this allows XDB Links with older software to continue to function. It also preserves the original package name in case you want to revert to the earlier version of XDB Link software.

  3. In the TCP/IP Setup group box, set the following values:
    In this field... Specify the following...
    Remote APPLID The APPLID of the remote DB2 subsystem.

    Worksheet row A9.
    Remote HOST The name of the host IP address as specified in the HOSTS file on this machine.

    Worksheet row J2.
    Port The name of the TCP/IP port dedicated to the XDB Link Host Option as specified in the SERVICES file on this machine.

    Worksheet row J3.
    Note:

    The Local HOST field in this group box displays the name of the XDB Server on which your XDB Link software resides. You cannot change this value.

  4. Modify other settings as you need or accept the defaults. See the XDB Bind Utility User's Guide for additional information about the Location Configuration dialog box.
    Note:

    The host code page values are the current default settings. The actual code page values used for this connection are dynamically determined when XDB Link connects with this remote host. (See Code Mappings for more information regarding host code pages.)

  5. Click Update to add this location to XDB Link.
  6. Click Exit to close the Location Configuration dialog box.
Parent topic: Configure DB2 Access


Defining Remote DRDA(APPC) Connection Types

Use the following procedure to complete the Location Configuration dialog box if you are using an SNA connection to access DB2.

To define a DRDA(APPC) connection

  1. Select DRDA(APPC) from the Connection Type list box.
  2. In the DRDA Setup group box, specify the Package Name and Collection Identifier of the package that XDB Link will use to pass dynamic SQL to DB2. If your DBA or XDB administrator has already created a package on the host for XDB Link, make sure that you enter the package name and collection ID as it has been specified on the host.
  3. Note:

    If you have an earlier version of XDB Link, give this version a new package name. We recommend that you adopt a package naming convention that includes the XDB Link version number-- for example, XLNK600, XLNK601, XLNK602. In a multiple-gateway environment, this allows XDB Links with older software to continue to function. It also preserves the original package name in case you want to revert to the earlier version of XDB Link software.

  4. In the APPC Setup group box, set the following values:
    In this field... | Specify the following...
    Local LU Alias The name that represents this machine in its local SNA communications configuration.

    This value must match the Local LU Alias that you assigned to this computer when you configured its SNA software.

    Worksheet row D15, E19, F13, or H5, depending on which SNA server you use.
    Partner LU Alias The name that represents the remote APPC LU in this machine's local SNA communications configuration.

    This value must match the Partner (or Remote) LU Alias you assigned to the host LU when you configured the SNA software on this machine.

    Worksheet row D20, E27F16, or H12, depending on which SNA server you use.
    Mode Name IBMRDB or the name of an independent LU6.2 mode definition that you have specified in the mode table (MODETAB) associated with this machine's LU definition in VTAM.

    If you use your own mode definition, it must support parallel sessions.

    VTAM worksheet row A6
    Transaction ID | X'07F6C4C2'
  5. Modify other settings as you need or accept the defaults. See the topic Location Configuration Window for information about the Location Configuration dialog box.
    Note:

    The host code page values are the current default settings. The actual code page values used for this connection are dynamically determined when XDB Link connects with this remote host. (See Code Mappings for more information regarding host code pages.)

  6. Click Update to add this location to XDB Link.
  7. Click Close to close the Location Configuration dialog box.
Parent topic: Configure DB2 Access


Binding XDB Link to DB2

Every DB2 application must have an application package to support the execution of statically-bound and dynamic SQL contained in the program. Under DB2, an application package is created when you bind the application using the BIND PACKAGE subcommand.

Because XDB Link runs against DB2, it must have an application package on the host. XDB Link uses its application package to process dynamic SQL from client applications (statically bound SQL is executed through the appropriate application package) and to execute statically-bound SQL statements contained in the XDB Link program itself.

To create the application package for XDB Link, you must create a database resource module (DBRM) for XDB Link and bind it to DB2 using the XDB Bind Utility.

Note:

You only need to bind XDB Link once. If this version of XDB Link has already been bound with your DB2 database, you can skip this procedure.

To perform these steps, you must have a valid user ID and password on the XDB Server where XDB Link is installed (if you are using XDB Link in a gateway configuration) and on the host system. Additionally, your user ID must have the following privileges under DB2 on the host.

  • BINDADD authority
  • BIND authority for XDB Link
  • CREATE authority for the XDB Link collection ID (needed only if your DB2 system imposes collection ID security)

If you do not have these privileges, you (or someone authorized to grant such privileges) must execute the following SQL statements on DB2.

GRANT BINDADD to UserID
GRANT BIND ON PACKAGE PackageName TO UserID
GRANT CREATE ON COLLECTION CollectionID TO UserID

where:

UserID | is your user ID
PackageName | is the name of the XDB Link package as specified in the Gateway Profile Utility
CollectionID | is the collection ID assigned to XDB Link in the Gateway Profile Utility

For additional information about these SQL statements, see your DB2 SQL Reference.

If you need additional information about the XDB Bind Utility while performing the following procedure, see the XDB Bind Utility User's Guide.

To create the default package for XDB Link

  1. On the machine where XDB Link is installed, start the communications software (SNA or TCP/IP) if it is not already running.
  2. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  3. On the machine where XDB Link is installed, or from any client workstation with access to that machine, start Options by selecting its icon in the XDB program group or folder.
  4. When the Options window opens, set the following values on the Connect page:
    If you are using a... | Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Protocol field, select protocol this machine will use to commu-nicate with the XDB Server on which XDB Link is installed.
    Direct-connect configuration | In the Protocol field, select DRDA.
  5. Click OK to close Options and save your settings.
  6. Start the XDB Bind Utility by selecting its icon in the XDB program group or folder.
  7. When the XDB Bind Utility window opens, select the name of the host system from the Remote Location drop-down list.
  8. Click Default to display the Generate Default DBRM screen and complete the following:
    In this field... | Specify...
    Package Name | The package name for XDB Link. This value must match the package name assigned to XDB Link in the Gateway Profile Utility.
    Collection ID | The collection ID for XDB Link. This value must match the collection ID given to XDB Link in the Gateway Profile Utility.
    Host System The type of DRDA host to which you want to bind XDB Link.

    Select MVS if you are using a DB2 version that does not support stored procedures (versions below 4.1)

    Select MVS + SPC if you are using a version of DB2 that supports stored procedures (version 4.1 or higher).
    Dynamic Sections | The number of dynamic sections that DB2 will include in the package it builds for XDB Link. This value determines how many dynamic SQL statements a client can have open at one time. The default value (32) is appropriate for most applications.
  9. Click Create to generate the default DBRM in your XDB application directory.
  10. Click Cancel to return to the XDB Bind Utility window, then click Bind to display the Bind Package dialog box.
  11. In the DBRM File Name list, select the name of the DBRM file created in step 9. Modify the other settings in this dialog box as you need or accept the defaults.
  12. Click Execute to bind XDB Link to DB2.
  13. When the bind process is finished, click Cancel to exit the Bind Utility.
  14. Use SQLWizard or another database management tool execute the following statement to grant public EXECUTE privileges for XDB Link.
    GRANT EXECUTE ON PACKAGE collid.* TO PUBLIC

    where collid is the collection id of your XDB Link package.

Parent topic: Configure DB2 Access


Creating Required Tables and Views

A few Micro Focus development tools, such as SQLWizard and XDB Migrate, use special tables in which they maintain control information. These programs also need access to system tables. Before you can successfully use these tools with XDB Link, you must do the following in DB2:

  1. Create the special tables these programs need.
  2. Grant public access to these special tables or grant access to XDB Link users on a user-by-user basis.
  3. Create views of the system tables these programs use (optional).
  4. Grant public access to these system tables (or views), or grant access to XDB Link users on a user-by-user basis.

Micro Focus provides a script file (XDBLINK.SQL, in the XDB program directory) to create the necessary files and grant the required privileges. Ask your DB2 database administrator to examine this script file and customize it for your DB2 site. He or she may want to edit this script to:

  • create views of the system tables rather than allowing users direct access to them
  • grant access to all users (public access) or to specific users
  • create the new tables in a database other than the default

After the script is customized, run it against your DB2 location using a tool such as SPUFI on the host. Or, use the following steps to run the script with SQLWizard from an XDB client workstation.

To perform these steps, you must have SELECT privileges on the DB2 system tables and you must be authorized to create tables.

To run the XDBLINK script using SQLWizard

  1. On the machine where XDB Link is installed, start the communications software (SNA or TCP/IP) if it is not already running.
  2. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  3. On the machine where XDB Link is installed, or from any client workstation with access to that machine, start Options by selecting its icon in the XDB program group or folder.
  4. When the Options window opens, set the following values on the Connect page:
    If you are using XDB Link in a... Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Location field, specify the name of the DB2 location.

    In the Protocol field, select protocol this machine will use to commu-nicate with the XDB Server on which XDB Link is installed.
    Direct-connect configuration In the Location field, specify the name of the DB2 location.

    In the Protocol field, select DRDA.
  5. Set these additional options:
    • On the Security page, enable the Client Security option.
    • On the SQL page, set SQL Compatibility Mode to DB2.
  6. Click OK to close Options and save your settings.
  7. Start SQLWizard by selecting its icon in the XDB program group or folder.
  8. Use the Run Batch command on the File menu to run the script file XDBLINK.SQL against each host location. This file is located in the XDB program directory.
Parent topic: Configure DB2 Access


Configuring the Client Workstation

To access a DB2 database through XDB Link from an XDB client application, you must use the Options program to point the workstation to the DB2 database and establish an operating environment compatible with the DB2 host system.

To configure the client workstation, take the following steps before you execute an XDB client application.

To configure an XDB client workstation for DB2

  1. On the machine where XDB Link is installed, start the communications software (SNA or TCP/IP), if it is not already running.
  2. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  3. At the client workstation, start Options by selecting its icon from the XDB program group or folder.
  4. When the Options window opens, set the following values on the Connect page:
    If you are using a... Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Location field, specify the name of the DB2 location.

    In the Protocol field, select protocol this machine will use to communicate with the XDB Server on which XDB Link is installed.

    Direct-connect configuration In the Location field, specify the name of the DB2 location.

    In the Protocol field, select DRDA.

  5. Set these additional options:
    • On the Security page, enable the Client Security option.
    • On the SQL page, set SQL Compatibility Mode to DB2.
  6. Click OK to save your settings and close Options.
  7. Run the client application.
Parent topic: Configure DB2 Access
Related information
Enabling Security on the Client Workstation
Configure DB2 Access


Configuring XDB Link Security

Because of the security imposed by DB2 and the host system, you must implement the following security measures on your network.

  • On the machine where XDB Link is installed, create a user ID and password for each user that will access DB2 using XDB Link. (Gateway configuration only.)
  • On the machine where XDB Link is installed, set the XDB Server Security option using the XDB Server Configuration Utility (Gateway configuration only). For specific procedures, see the SQL Option Server Administration Guide.
  • On each client machine that will access DB2 though XDB Link, enable the XDB Client Security feature.
Parent topic: Configure DB2 Access
Related information
Creating User IDs for XDB Link
Configure DB2 Access


Creating User IDs for XDB Link

If you are using XDB Link in a gateway configuration, each user that will access DB2 through XDB Link, must have a valid user ID and password on the host, and must have a matching user ID and password on the machine where XDB Link is installed. This is because XDB Link automatically presents a client's XDB user ID and password to the host when the client requests data from DB2. If the XDB user ID and password are not also valid on the host machine, the user won't be allowed on the system.

To create user IDs and passwords on the XDB Server, use the Users or Groups command in SQLWizard (you must have super-user authority to do this). Make sure the user ID and password you create with SQLWizard match the user ID and password on the host.

Note:

When passwords are created, note the XDB software is case-sensitive.

For users who will connect only to DB2, and not to databases on an XDB Server, you can configure their user IDs to bypass the password checking process. Doing so eliminates a redundant password check and prevents confusion when a user changes a password on one machine and not another. You may also want to configure a system where the host system acts as a "global" security server.

For complete information about designing a security scheme, see the SQL Option Server Administration Guide. For more information about creating user IDs on an XDB Server, see the topic Managing Users and XDB Server Access Overview.

Parent topic: Configure DB2 Access


Enabling Security on the Client Workstation

To use XDB Link with DB2, you must enable the Client Security option on your workstation using Options. This option instructs the XDB run-time software to prompt you for a user ID (AuthID) and password when it connects to an location (including the location that represents DB2).

To enable security on a client workstation using Options

  1. At the client workstation, start Options by selecting its icon from the program group or folder.
  2. When the Options window opens, select the Security page and enable the Client Security option.
  3. Click OK to save your settings and close Options.
Parent topic: Configure DB2 Access


Configuring Communications Software on the PC

Use one of the following procedures to configure the communications software on the machine where XDB Link is installed:

  • If XDB Link will connect to the host via TCP/IP, follow the procedure described in the section Configuring TCP/IP Software for the PC.
  • If XDB Link will connect to the host via SNA, follow the procedure described in the section Configuring the Microsoft SNA Server . When the procedure asks you to enter the VTAM APPLID for DB2, enter the VTAM APPLID assigned to the XDB Link Host Option for PEM instead.
Parent topic: Configure DB2 Access
Related information
Configure the PC
Configuring TCP/IP Software for the PC
Configuring the Microsoft SNA Server


Link Utility

  • Configuring the Link for a Gateway Server
  • Starting a GTF Trace
  • Starting the Host Option for TCP/IP
Parent topic: How to...


Configuring the Link for a Gateway Server

To configure the Link for a Gateway Configuration, you must:

  • Run the Gateway Profile Utility locally on the machine where the XDB Server and Link are installed
  • Have super-user privileges that give you write access to the XDB Server's system location tables
  • Check your client application settings in Options to make sure they point to the system location of the local XDB Server

See the Options Utility Overview for instructions.

Parent topic: Link Utility
Related information
Starting a GTF Trace
Starting the Host Option for TCP/IP


Starting a GTF Trace

To start the GTF trace procedure, issue the following command from the MVS console:

S _GTF_procedure

or

S XDBGTF

Respond to the "AHL125A RESPECIFY TRACE OPTION OR REPLY U" message with:

R nn,U

where nn is the WTOR message number.

Parent topic: Link Utility
Related information
Configuring the Link for a Gateway Server
Starting the Host Option for TCP/IP


Starting the Host Option for TCP/IP

To start the Host Option for TCP/IP, issue the following command from the MVS system console:

S Catalogued Procedure name for Host Option for TCP/IP

or

S XDBLink

The following message is displayed on the system console:

@08 Enter XDBLINK Command

Next issue the following command to verify the status of the started task and verify the port number:

R nn,DISPLAY STATUS

where nn is the reply number message related to the Host Option for TCP/IP.

Parent topic: Link Utility
Related information
Configuring the Link for a Gateway Server
Starting a GTF Trace


Migrate Utility

  • To start the Migrate Utility
  • To open and close the Browser
  • To refresh the Catalog Browser
  • To open and close the Schema Viewer
  • To log onto a server
  • To migrate tables
  • To migrate one or more databases
  • To migrate certain rows and columns
  • To replicate data
  • To add SQL to a migration
  • To save your migration specifications
  • To recall a migration specification
  • To run a MIG file without opening it
  • To run a MIG File from the command line
  • To create an SQL script file of the migration
  • To transfer data and its metadata definitions between a DB2 subsystem and an XDB server
Parent topic: How to...


To start the Migrate Utility

  • From the main menu, click > Client > Migrate.
Parent topic: Migrate Utility
Related information
To log onto a server
The Migrate Window


To open and close the Browser

The Catalog Browser is automatically displayed when you open Migrate. To close the Browser, double-click the Control-menu ( Control-menu button) button.

To reopen the Catalog Browser after it has been closed, click the Catalog Browser button in the toolbar ( Catalog Browser button) or select the Catalog Browser command from the View menu.

Parent topic: Migrate Utility


To refresh the Catalog Browser

Catalog Browser button
To refresh the contents of the Catalog Browser, click the Catalog Browser button, or click Catalog Browser on the View menu. You must do this at the end of a migration in order to display the names of the newly migrated tables.

Parent topic: Migrate Utility


To open and close the Schema Viewer

The Schema Viewer is automatically displayed when you open Migrate. Only one Schema Viewer is active at a time. To close the Schema Viewer, double-click its Control-menu button in the upper-left corner.

Note:

When you close the Schema Viewer, the table and query specifications it contains are discarded.

To open a new Schema Viewer, select the New command from the File menu. When a new Schema Viewer is opened, Migrate clears the current table and query specifications. If you want to save these specifications, you must do so before opening a new Schema Viewer.

Parent topic: Migrate Utility


To log onto a server

When you start Migrate, it attempts to connect to your "default" XDB Server and location. Depending on how your AutoConnect and Security options are set, you receive either the Connect dialog box (from which you can select the server and location to which you want to connect) or you are automatically connected to your default server and location.

  • The Connect dialog box appears if the Security option in Options is enabled, or if AutoConnect is disabled.
  • The Connect dialog box is bypassed if the AutoConnect option in Options is enabled.

See the Options Utility online help for more information about the AutoConnect and Security options.

Parent topic: Migrate Utility


To migrate tables

The procedure in this section describes how to copy tables from one location to another. If you want to migrate only certain rows and/or columns of a table, see Migrating Certain Rows and Columns.

Before you begin, review the following:

  • If you are migrating tables to/from the mainframe, make sure XDB Link is installed and operating properly.
  • If you are migrating tables between servers, make sure the SYSLUNAMES and SYSLOCATIONS tables on the server to which you are connected are configured for all locations to which you need access. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about setting up server-to-server communications.
  • Make sure you have SELECTprivileges on the tables you are migrating and on the following system catalog tables:
    SYSIBM.DATABASE | SYSIBM.SYSRELS
    SYSIBM.SYSCOLUMNS | SYSIBM.SYSSYNONYMS
    SYSIBM.SYSFOREIGNKEYS | SYSIBM.SYSTABLES
    SYSIBM.SYSINDEXES | SYSXDB.SYSLOCALS
    SYSIBM.SYSKEYS | SYSXDB.SYSPROMPTQUERY
    SYSIBM.SYSLOCATIONS | SYSXDB.SYSQUERY

    For more information about system catalog tables, see the SQL Reference or consult your XDB Server Administrator.

    Make sure the Catalog Browser and the Schema Viewer are open.

    *
    Open the Browser by selecting the Catalog Browser button on the toolbar. Open the Schema Viewer by selecting New from the File menu.

    Note:

    The location to which you want to migrate a table must exist. If it does not, you must first create it using a database management tool such as SQLWizard.

  1. In the Catalog Browser, locate and highlight the table you want to migrate.
    • Click the + buttons to expand the hierarchy and show subordinate objects.
    • Tables can be selected and migrated. Databases and locations cannot.

    For more information about using the Catalog Browser, see The Catalog Browser.

  2. Drag the highlighted table to the Schema Viewer. When you release the mouse button in the Schema Viewer, the table's schema displays in the viewer.
    Note:
    • You can double-click the table name to place it in the Schema Viewer.
    • You can hold the Shift or Ctrl key while you click the tables in the Catalog Browser to select multiple tables.
  3. If you want to migrate tables that are dependent on or referenced by a particular table (a referential integrity constraint), click the table in the Schema Viewer (its title bar will be highlighted indicating that it is "selected") and select the Show Dependent or Show Referenced command in the Object menu.

    When you select Show Dependent or Show Referenced, dependent and referenced tables (respectively) are automatically placed in the Schema Viewer along with arrowed lines showing their foreign key/primary key relationships.

    If all the rows of the referenced table are migrated, Migrate processes the DDL and DML so that the referential integrity constraints are not violated. However, if the user intends to restrict the domain of data being processed by Migrate, the domain (subset of the rows) must be defined by using the Define Query command on the Object menu. Queries can then be constructed against the referenced and dependent tables to ensure that only the rows matching the search criteria will be migrated. This will guarantee that foreign key values in the referenced and the dependent tables are consistent with each other. See Migrating Certain Rows and Columns for more information.

    Note:

    You can select the Show Dependent and Show Referenced commands from the control menu. To access this menu, click the Control-menu button in the upper-left corner of the table's schema window.

  4. Click the Table/Query Options * button in the toolbar or select the Table/Query Options command on the Object menu.
    In this field... | Specify the following...
    AuthID The name to be used as the creator of the destination table.

    If you want Migrate to use the source table's Auth ID by default, select the Default To Source checkbox next to the Auth ID text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify an Auth ID by typing it in text box.

    Table | The name of the table to which you will be migrating the data. If this table doesn't exist, Migrate will create it for you.
    Tbl Space The table space name for the target table to which you will be migrating the data.

    If you want Migrate to use the name of the source table space by default, select the Default To Source checkbox next to the Tbl Space text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a table space name by typing it in this text box.

    Database The database name for the target table where you will be migrating the data.

    If you want Migrate to use the name of the source database from which the source table is selected by default, select the Default To Source checkbox next to the Database text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a database name by typing it in this text box. If this field is left blank, the default database name "DSNDB04" is used.

  5. In the Migrate group box, select the database objects you want to copy with the table. You can migrate primary keys, unique keys, indexes, foreign keys, synonyms, comments, privileges and distinct types.
    CAUTION:
    If you do not migrate primary keys, unique keys, and foreign keys, applications that are dependent on the database to implement these business rules may not work.
  6. In the If Table Already Exists group box, specify the action you want Migrate to take if the target table already exists.
    Select... | If you want Migrate to...
    Abort | End the migration.
    Append Data | Append the migrated records to the existing table.
    Replace Data | Replace all records in the existing table with the migrated records (all data in the existing table will be deleted).
    Replace Table | Drop the existing table and create a new table with the migrated records.

    For information about the Update No Insert, Update Insert, and Delete Match options, see the instructions for Replicating Data.

  7. In the Limit Data To group box, specify how much data you want Migrate to copy.
    Select... | If you want Migrate to...
    All Rows | Copy all records from the source table to the destination.
    No Data Copy no records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature.

    The behavior of this option depends on the following:

    If the destination table does not exist, an "empty" table is created.

    If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).

    If the destination table exists, and the Append Data option is used, no records are copied to it.

    First N Rows | Copy the first N records from the source table to the destination.
    Every Nth Row | Copy every N records from the source table to the destination.
  8. In the Commit Work After group box, specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
  9. Click OK to confirm the settings.
  10. Repeat steps 1 through 9 for each table you want to migrate. If you want to remove a table that you have inadvertently added to the Schema Viewer, select the table in the Schema Viewer, then select the Remove command in the Object menu.
  11. Once all the tables you want to migrate are in the Schema Viewer, open the To drop-down list on the toolbar and select the location to which you want the tables copied.
    Attention: If a location to which you want to migrate records is not listed in the drop-down list, check that you are connected to the correct server and verify that the server has access to the location you need. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about server-to-server communications.
  12. When you are ready to begin the migration, click the Run ( *) button in the toolbar, or from the Commands menu, select Run.
  13. In the Run dialog box, make sure the Execute Migrate checkbox is selected. If this box is not selected, Migrate will not copy any records to the destination. This option can be disabled if you want to generate SQL without performing a migration. See Creating an SQL Script File of the Migration.
  14. In the Migrate Options group box, select the kind of reports and SQL scripts you want Migrate to produce when it migrates your data.
    Select this option... To request...
    Generate SQL A copy of the SQL script used to execute the migration. (This script contains the DDL statements used to define the destination table, but does not contain the individual INSERT statements for each migrated record.)

    In the text-entry field next to the checkbox, type the name of the file to which you want the script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new SQL script.

    Post Execution Report A report that lists the tables that were migrated.

    In the text-entry field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

    Error File A report that lists any errors encountered during the migration. If there are no errors during the migration, this error file will be empty.

    In the text box, type the name of the file to which you want the errors written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Error File and the Post Execution Report to combine these two reports into one file.

    Tip: If you want to produce a report describing the effect of the specified migration, select the Impact Analysis Report. This option gives you a report describing the schemas of the currently selected source and destination tables, without performing the migration. See Generating Reports for more information about this and other reports.
  15. Click OK to start the migration. The migration's progress is reported in the Status bar at the bottom of the window.
  16. When the migration is finished, click the Catalog Browser ( *) button to refresh the contents of the Catalog Browser. The destination tables, if they are new, do not appear in the Browser until you do this.
    Tip: You can save your migration as a MIG file to save time recreating it later. See Saving Your Migration Specifications.
Parent topic: Migrate Utility


To migrate one or more databases

  1. Start the Migrate Utility.
  2. Click Commands > Migrate Database.
  3. From the Database list, click a database you want to migrate, or press Shift or Cntl as you click to select more than one database. This populates the Migrate Tables list with the tables defined for the database or databases you selected.
  4. To exclude one or more tables from the migration, on the Migrate Tables list, select the tables to exclude. To select one table, click it. To select more than one, press Shift or Cntl as you click. Then click Exclude. This puts the table or tables you selected onto the Not Included list. Optional.
  5. To include one or more tables that you previously excluded, on the Not Included list, select the tables to include. Then click Add. This places the selected tables back onto the Migrate Tables list. Optional.
  6. To set options for a table on the Migrate Tables list, click the table, then click Options. On the Table Options dialog box, set the options for the selected table, then click OK. Optional.
    Note:

    The default options for each table are those defined on the Default Options dialog box.

  7. Click Save. In the File name field, type a name for the .mig script file you want to contain the information you specified for this migration, then click Save. Optional.
  8. Click Execute to invoke the Run dialog box.
  9. From the To drop-down list, select a location to migrate to.
  10. Make any necessary changes to the migration options by checking or unchecking the appropriate checkboxes. Optional.
  11. Click OK to perform the migration.
Note:
  • If you choose to save the migration information, the Migrate Utility generates a .mig script file. The script file created here works the same as any other .mig script file except that you cannot view it in the Schema Viewer. However, you can execute it using the Execute Batch command or from the command line as often as you would like. You cannot execute a saved .mig script file from the from the Migrate Database dialog box.
  • Information pertaining to migration execution appears in the Execution Information window. Following successful migration, you can close this window.
Parent topic: Migrate Utility


To migrate certain rows and columns

You can copy certain columns or certain rows from one table to another using Migrate's query feature. You can also use this feature to combine data from different tables into one result.

See Replicating Data if you wish to update, insert, or delete specific rows and columns.

Note:

Migrate's query feature is designed to migrate tables. It is not an all-purpose SQL processor. Do not use it to perform any SQL other than a single SELECT statement; for example, do not try to CREATE or DROP a location. If you need to include SQL with your migration, use prologue and epilogue scripts. See Adding SQL to a Migration.

The procedure in this section describes how to create a query and migrate its result. Before you begin, review the following prerequisites:

  • If you are migrating tables to/from the mainframe, make sure XDB Link is installed and operating properly.
  • If you are migrating tables between servers, make sure the SYSLUNAMES and SYSLOCATIONS tables on the server to which you are connected are configured for all locations to which you need access. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about server-to-server communications.
  • Make sure that you connect to a "non-mainframe" location when you start Migrate, as you will not be able to migrate data to any other location otherwise. See Logging onto a Server.
  • Make sure the Catalog Browser and the Schema Viewer are open.

    *
    Open the Catalog Browser by selecting the Catalog Browser button on the toolbar. Open the Schema Viewer by selecting New from the File menu.

  • Make sure you have SELECTprivileges on the tables you are migrating and on the following system catalog tables:
    SYSIBM.DATABASE | SYSIBM.SYSRELS
    SYSIBM.SYSCOLUMNS | SYSIBM.SYSSYNONYMS
    SYSIBM.SYSFOREIGNKEYS | SYSIBM.SYSTABLES
    SYSIBM.SYSINDEXES | SYSXDB.SYSLOCALS
    SYSIBM.SYSKEYS | SYSXDB.SYSPROMPTQUERY
    SYSIBM.SYSLOCATIONS | SYSXDB.SYSQUERY

    For more information about system catalog tables, see the SQL Reference or consult your XDB Server Administrator.

Note:

The location to which you want to migrate the results of your query must already exist. If it does not, you must first create it using a database management tool such as SQLWizard.

  1. In the From drop-down list, select the location containing the tables you want to query.
  2. In the To drop-down list, select the location to which you want the query result migrated.
    Note:

    If a location to which you want to migrate records is not listed in the drop-down list, check that you are connected to the correct server and verify that the server has access to the location you need. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about server-to-server communications.

  3. Select the Define Query command on the Object menu to display an empty Query window.
  4. In the upper pane of the Query window, enter a Table and AuthID for the result of the query.
    Note:

    If this table does not exist already, Migrate will create it for you. If it does exist, the result of your query must match the existing table's schema exactly. That is, it must produce the same number of columns, of the same size and type, and in the same order as the destination table.

  5. If you want the result stored to a specific database and table space, type their names in the Database and Tablespace fields.
  6. In the lower pane, type a single SELECT statement. If you want to open a saved query that you have created using SQLWizard, double-click its name in the Catalog Browser's Query tab. For more information about recalling a saved query, see The Query Tab.

    You can enter any valid SELECT statement, even those containing joins and unions.

    Note:

    To ensure a successful query, specify your tables using fully-qualified (i.e., three-part) names.

    The following are examples of valid query statements:

    SELECT *
        FROM tutorial.tutorial.employee
        WHERE city = 'miami'
        SELECT e_no, lname, city
        FROM tutorial.tutorial.employee
        SELECT pname, qty
        FROM tutorial.tutorial.part p1,
        tutorial.tutorial.partsupp p2
        WHERE p1.pno = p2.pno
  7. After you have entered a SELECT statement, click the Table/Query Options (
    *
    ) button in the toolbar or select the Table/Query Options command on the Object menu.
  8. In the Query Options dialog box, specify how you want the results of this query written, then click OK. You can specify what action Migrate should take if the destination table already exists, and how many total records should be copied.

    If you need specific information about an option in this dialog box, click Help or see Query Options.

  9. If you want to process multiple queries, repeat steps 1 - 8. Each SELECT statement must use a separate Query window (you can minimize a Query window to reduce screen clutter).
  10. When you have finished specifying the query(s), click the Run
    *
    button in the toolbar, or select the Run SQL command on the Commands menu.
  11. In the Run dialog box, make sure the Execute Migrate check box is selected. If this box is not selected, Migrate will not copy any records to the destination. This option can be disabled if you want to generate SQL without performing a migration. See Creating an SQL Script File of the Migration.
  12. In the Migrate Options group box, select the kind of reports and scripts you want Migrate to produce when it migrates your data.
    Select this option... To request...
    Generate SQL A copy of the SQL script used to execute the migration. (This script contains the DDL statements used to define the destination table, but does not contain the individual INSERT statements for each migrated record.)

    In the text-entry field next to the checkbox, type the name of the file to which you want the script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new SQL script.

    Post Execution Report A report that lists the tables that were migrated.

    In the text-entry field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

    Error File A report that lists any errors encountered during the migration. If there are no errors during the migration, this error file will be empty.

    In the text box, type the name of the file to which you want the errors written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Error File and the Post Execution Report to combine these two reports into one file.

    Note:

    If you want to produce a report describing the effect of the specified migration, select the Impact Analysis Report. This option gives you a report that describes the schemas of the currently selected source and destination tables without performing the migration. See Generating Reports for more information about this and other reports.

  13. Click OK to start the migration. The migration's progress is reported in the Status bar at the bottom of the window and in a progress window.

    When a migration is processed, queries are processed after any tables in the Schema Viewer. When multiple queries are specified, they are processed in window-number order.

  14. When the migration is finished, click the Catalog Browser (
    *
    ) button to refresh the contents of the Catalog Browser. The destination tables, if they are new, do not appear in the Browser until you do this.
    Note:

    You can save your migration as a MIG file to save time recreating it later. See Saving Your Migration Specifications.

Parent topic: Migrate Utility


To replicate data

Production database users can specify insert, update, and delete actions for tables that already exist. The instructions for replicating data are the same as Migrating Certain Rows and Columns, with the following exceptions:

  • In the Query Options window, choose one of the following options from the "If table already exists" group:
    • Update No Insert

      update the information only if a row with the key already exists

    • Update Insert

      update the existing row, or insert new row

    • Delete Match

      delete existing matching row

  • In the Define Query window, if you selected either the Update No Insert option or the Update Insert option, click the Update Rule button. In the Query Update Rules window:
    1. Identify the key fields.
    2. The Update Rule value of each field will change between None and Replace, depending on whether or not the field is a key.
      • Replace

        overwrite existing data with new data

      • None

        take no action

Parent topic: Migrate Utility


To add SQL to a migration

Migrate gives you two ways to incorporate additional SQL in a migration.

  • You can execute a "prologue script" script before the migration to perform preparatory operations such as location creation and table initialization. A prologue script can be any batch SQL file containing valid SQL statements.

    To include a prologue script, select the Prologue option in the Migrate Options dialog box when you execute the migration. In the text box next to this option, specify the name of the SQL file that you want Migrate to run.

  • You can execute an "epilogue script" script after the migration to perform "housekeeping" operations such as dropping temporary tables or creating an index. An epilogue script can be any batch SQL file containing valid SQL statements.

    To execute an epilogue script, select the Epilogue option in the Migrate Options dialog box when you execute the migration. In the text box next to this option, specify the name of the SQL file that you want Migrate to run.

    Note:

    Prologue and Epilogue SQL statements are executed against the destination location.

Parent topic: Migrate Utility


To save your migration specifications

Once you have specified a migration, you can save your specifications so they can be reused at a future date. To save a migration, select the Save As command from the File menu. In the Specify Batch File dialog box, specify a file name and click OK.

Note:

If a Query window is active when you select Save As, you can save just the query (to an SQL file) or the entire migration (to a MIG file). To specify which type of file you want Migrate to create, select *.SQL or *.MIG in the Save As dialog box before you click OK.

Migration specifications are saved in MIG files. A MIG file records the following information about a migration:

  • Source and destination settings
  • Tables selected for migration
  • Query statements
  • Table, query and run option settings
  • Migration option settings, including prologue and epilogue script specifications.

Using a MIG file, you can run a migration in "batch mode" (that is, run the migration without respecifying its options manually). Batch mode is useful for executing a migration that is run on a regular basis, or for running a migration in unattended mode. For information about running a migration from a MIG file, see Recalling a Migrate Specification.

Parent topic: Migrate Utility


To recall a migration specification

If you have saved your migration specifications to a MIG file, you can recall the specifications using the Open command on the File menu.

Note:

When you open a MIG file, the specifications from the file replace the current migration specifications. If you want to preserve your current specifications, save them before opening a MIG file.

After opening a MIG file, you can examine and modify its specifications before executing the migration. (If you want to save the revised migration, use the Save or Save As command on the File menu.)

You can view the contents of a MIG file using the Batch Commands command on the View menu. After the file is displayed, you can print it using the Print command on the File menu.

Parent topic: Migrate Utility


To run a MIG file without opening it

Migrate's Execute Batch command lets you run a migration without opening the MIG file in the Migrate window. To run a MIG file in this way, select Execute Batch from the File menu. In the Select Batch File dialog box, select the MIG file you want to run. When you click OK, the migration is immediately executed.

The Execute Batch command does not affect the current migration settings (e.g., selected tables and options). Specifications in effect before Execute Batch is invoked will be in effect when execution of the MIG file is complete.

Parent topic: Migrate Utility


To run a MIG File from the command line

If you have saved your migration specifications to a MIG file, you can rerun the migration without opening Migrate. This is done by invoking Migrate from your development environment's command prompt and giving it the name of your MIG file.

The command used to invoke Migrate with a MIG file is as follows:

xmig40n -bMIGFile -iINIFile

where:

MIGFile | is the name of your MIG file. If this file isn't in the application path specified in the Path tabs of Options, you must specify the path in addition to the filename.
INIFile | is the name of the initialization file under which you want Migrate initialized. If you don't include the -i parameter, Migrate uses XDB.INI in the current working directory.
Parent topic: Migrate Utility


To create an SQL script file of the migration

To create a script file containing the DDL statements used to perform the migration, select the Generate SQL checkbox in the Run dialog box when you execute the migration. In the text-entry field next to the checkbox, type the name of the file to which you want the script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new script.

Note:

The script that Migrate creates contains only the DDL statements that define the destination table. It does not contain individual INSERT statements for each migrated record.

You can use the SQL command on the View menu to display the contents of an SQL script file, including one to which you have saved migration SQL.

When the Select SQL File dialog box is displayed, select the SQL file and click OK.

After the file is displayed, you can print it using the Print command on the File menu.

Parent topic: Migrate Utility


To transfer data and its metadata definitions between a DB2 subsystem and an XDB server

  1. From the main menu, click > Client > Migrate.
  2. Specify the information required
  3. Click OK.
Parent topic: Migrate Utility


Options Utility

  • To enable client security
  • To change the default XDB Server
  • To define and configure remote DB2 data locations
  • To enable connection to a new remote XDB Server
  • To set up or configure an XDB Server's parameters
Parent topic: How to...


To enable client security

  1. From the main menu, click > Configuration > Client Options.
  2. Click the Security tab.
  3. Select Client Security Enabled.
  4. Click OK.
Parent topic: Options Utility


To change the default XDB Server

  1. From the main menu, click > Configuration > Client Options.
  2. Click the Connect tab.
  3. In the Network Info group, choose a server from the Server Name list.
  4. Click OK.
Parent topic: Options Utility
Related information
To start the XDB Server
To stop the XDB Server


To define and configure remote DB2 data locations

  1. From the main menu, click > Configuration > Link Profile.
  2. Specify the information required
  3. Click OK.
Parent topic: Options Utility


To enable connection to a new remote XDB Server

  1. From the main menu, click > Configuration > Client Options.
  2. Click the Connect tab.
  3. In the Network Info group, type the server name in the Server Name field.
  4. Select the communications protocol you want to use to connect to the XDB Server from the list.
  5. In the Connect To group, type a default location for the new server.
  6. Type the AuthID you want to user to connect to the new server.
  7. Click OK.
Note: Some communications protocols require additional information to be specified in the xdb.ini file. Contact your system administrator if you experience difficulty in connecting to a new server.
Parent topic: Options Utility


To set up or configure an XDB Server's parameters

  1. From the main menu, click > Configuration > Server Configuration.
  2. Specify the information required.
  3. Click OK.
Parent topic: Options Utility


SQL Wizard

  • To start SQL Wizard
  • To exit SQL Wizard
  • Use the Catalog Browser
  • Manage Databases
  • Query Databases
  • Work with Query Results
  • Use the Result Window for Data Entry
  • Import Files
  • Export Files
  • Use Batch SQL Scripts
  • Administer XDB Users and Groups
  • Implement Security and Authority
Parent topic: How to...


To start SQL Wizard

  • From the main menu, click > Client > SQL Wizard.

The Connect Dialog Box

The Connect dialog box is used to specify the XDB Server you want to use with SQLWizard and to enter a password if one is required.

The Connect dialog box may or may not be displayed when you start SQLWizard, depending on certain settings you make in the Options Utility. Likewise, certain items may or may not be selectable, depending on the settings in Options.

To use the Connect dialog box:

  1. Type the name of the XDB Server you want to access, or click the down arrow button next to the Server field to select an XDB Server from the drop-down list.

    To connect to an XDB Server that you never used before, run the Options utility before starting SQLWizard. Use the Connect tab in Options to set up the communication protocol, client node name, and default location.

    If the server name is displayed as a label rather than in a text-entry field, you cannot select or type a different server name.

  2. In the Location field, type the name of the location you want to access, or click the Browse button to select a location from the Browse Dialog box. The Browse Dialog box shows all locations known to the selected XDB Server.
    Note:

    Each time you access the Browse Dialog box, the selected XDB Server is checked for the list of all known locations available and you are logged in to the specified XDB Server with the current AuthID and password. If security is on, you must have SELECT privileges on the XDB Server's system location for this feature to operate correctly. (For more information, refer to the description of the WSQL043 message in online help.)

    If you do not click the location drop-down list, the XDB Server is not accessed until you connect.

  3. Type your AuthID in the Username field. If you need to access a multi-user XDB Server on the LAN, ask your XDB Server Administrator what AuthID to use.
  4. If security is turned on, type your password. Asterisks (*) are displayed for each character you type to prevent others from seeing your password.
    Note: Passwords are case-sensitive; be sure to use the correct combination of upper and lower case letters.

    If security is off, the Password field will not be displayed on the Connect dialog box.

  5. After making your selections, click OK to start SQLWizard and connect to the specified XDB Server and location.
    Note: If the Catalog Browser is set up to load on SQLWizard startup and the location you are trying to connect is an XDB Link location, a transaction dialog box appears. This dialog box asks you to complete the transaction to free up locks and close queries. Of the three options the dialog box presents you with, Commit and Rollback free the locks, while Proceed keeps them in place. Keeping the locks interferes with other DB2 users who are attempting to perform Data Definition Language (DDL) SQL statements.

If you enter your AuthID or password incorrectly, an error message is displayed. You have three chances to enter the correct AuthID and password.

Parent topic: SQL Wizard


To exit SQL Wizard

You exit SQLWizard in just the same way you exit most other standard Windows or Presentation Manager applications.

To exit SQLWizard:

  1. Click the File menu to open it.
  2. Click the Exit command.

Optionally, you can double click the Control Menu button in the top left corner of the SQLWizard main window.

If there are open windows on your SQLWizard screen and you have not yet saved changes, you will be asked if you want to save before exiting. If you answer yes, you may be asked to provide a name for the object being saved, just as if you had clicked the Save As command in the File menu. If you answer no, the changes will be discarded. If you click Cancel, SQLWizard remains running and all open windows remain open.

Parent topic: SQL Wizard


Use the Catalog Browser

  • Accessing the Catalog Browser
  • Closing the Catalog Browser
  • Opening Tables with the Catalog Browser
  • Opening Queries with the Catalog Browser
  • Selecting Items
  • Select and Drag
  • Filtering Items in the Catalog Browser
Parent topic: SQL Wizard


Accessing the Catalog Browser

To access the Catalog Browser, click the Catalog Browser button on the toolbar. Alternatively, click the Locations, Tables, or Queries command from the View menu.

Catalog Browser Button Catalog Browser button | The Catalog Browser button on the toolbar makes the Catalog Browser dialog box active. This button is useful when the Catalog Browser dialog box is covered by other SQLWizard windows or when the Browser's AUTOSTARTUP feature has been turned off.
View Menu Commands | The first three commands in the View menu always change the active window to the Catalog Browser dialog box. The Locations command displays the Location tab. The Tables command displays the Table tab, and the Queries command displays the Query tab.
Parent topic: Use the Catalog Browser


Closing the Catalog Browser

By default, the Catalog Browser dialog box opens when you start SQLWizard. To prevent the Catalog Browser dialog box from automatically loading when you start SQLWizard, turn off AUTOSTARTUP on the Browser tab in the Options utility.

To close the Catalog Browser dialog box, use the Control or Close button in the title bar.

Note:

To provide quick access to system catalog information, the Catalog Browser dialog box is never actually closed while SQLWizard is active. When you close the Catalog Browser dialog box, SQLWizard just hides it. This improves performance by keeping the Catalog Browser dialog box active in memory, which reduces the need to continually re-query the system catalog tables.

Parent topic: Use the Catalog Browser


Opening Tables with the Catalog Browser

You can use the Catalog Browser to open a table for viewing or editing.

To examine and open tables from the Catalog Browser:

  1. Access the Catalog Browser dialog box, then click the Table tab. Notice the list of locations, each preceded by a + button.
  2. Click a Location's + button to display a list of AuthIDs. Each AuthID is preceded by a + button.

    Notice that as you click each + button, SQLWizard displays a list of the sub-items for that object, and replaces the + button with a - button. Click the + button to expand an object list and the - button to collapse the list. If no button appears next to an item, no sub-items are available.

  3. Click the + button preceding an AuthID. SQLWizard displays the Tables/Views/Synonyms/Aliases objects.
  4. Click the + button in front of Tables to see a list of the tables.
  5. Click the + button preceding a table. SQLWizard displays a list of columns in the table. The Catalog Browser lets you view the column names in your table without displaying the table. Click the - button to remove the columns from the Catalog Browser display.
  6. Click a table name to highlight it.
  7. Click the Open button, or click and drag the table's name to the SQLWizard desktop.

    SQLWizard displays the table in a Result window.

  8. Close the Result window using the Close command from the File menu, or double click the Control Menu box in the upper left corner of the window.
Parent topic: Use the Catalog Browser


Opening Queries with the Catalog Browser

You can use the Catalog Browser to open a previously saved query. Once open, you can run the query. If desired, you can change the query before running it. Optionally, you can use the Catalog Browser to run a query in Batch mode (without first opening and displaying it).

To examine and open queries from the Catalog Browser:

  1. With the Catalog Browser dialog box displayed, click the Query tab.

    The Catalog Browser lists the locations, the AuthIDs, and the queries available to you from your current server. If you do not see these three levels of organization, click the + buttons preceding locations and AuthIDs to expand the detail beneath them.

  2. Click a query name to highlight it.
  3. Click the Open button or drag the query's name to the SQLWizard desktop.

    SQLWizard displays the query for you to view, edit, or run.

Parent topic: Use the Catalog Browser


Selecting Items

To select an object in the Catalog Browser dialog box, click its name or on the object icon. SQLWizard highlights the object that you select.

Double clicking on an object performs the default command for that object. For example, double clicking on a table is the same as selecting the table and then clicking the Open button.

You can select more than one item by holding down Ctrl while you click an item with the mouse. For example, you can Ctrl+click to select multiple tables, release Ctrl, and then click Open to display the Result window.

You can select a contiguous group of objects by first using the mouse to click the name of the first one; then while holding down Shift, click another object further up or down the list to select all objects in between, including the first and last objects you clicked. Once the desired objects are highlighted, release Shift and click Open to display the Result window.

Parent topic: Use the Catalog Browser


Select and Drag

You can select (highlight) one or more tables and drag them to the Query Design or SQL Edit window. You can select multiple columns and drag them to an SQL Edit window or a Create/Alter Table window. Dragging a table name to the SQLWizard desktop will open the table (displaying the data in a Result window).

The mouse pointer changes shape to indicate where you can drop the object.

Mouse pointer indicating drop
When the mouse pointer is in the Catalog Browser or in an area where you can drop the object, the mouse pointer appears as a pile of papers.

Mouse pointer is an international NO symbol
When the mouse pointer is in an area that cannot accept the object, the mouse pointer appears as the international NO symbol.

Note:

You can select from only one hierarchy level at a time.

Parent topic: Use the Catalog Browser


Filtering Items in the Catalog Browser

The Set Database/Authid/Table Filter dialog box (displayed by clicking Filter on the Catalog Browser's Location tab) enables you to control the databases, AuthIDs and table items that are displayed in the Catalog Browser for any particular location.

To specify the desired pattern of characters (or filters) for the database, AuthID, and table levels, specify values into the Database Pattern, Authid Pattern, and Table Pattern text boxes respectively. Clicking OK refreshes the Catalog Browser according to the filter settings entered in these text boxes. If no error occurs, the filter settings are saved to the xdb.ini file.

The values you specify in the Database Pattern, Authid Pattern, and Table Pattern text boxes must follow DB2's rules for specifying character patterns for the SQL LIKE predicate. The following examples use the TUTORIALS location:

  • Database Pattern: DSN%

    Authid Pattern: TUT%

    Table Pattern: PART%

    This set of filters will only make databases whose names begin with "DSN" visible in the Catalog Browser. If a database object is expanded, only tables that begin with the string "PART" under an authid that begins with the string "TUT" will be displayed. In this case, two tables, TUTORIAL.PARTS and TUTORIAL.PARTSUPPS would match.

  • Authid Pattern: TUTORIA_

    Table Pattern: PART____

    This set of filters uses the underscore character (_) to match any given character. In this case, there is one underscore at the end of the authid pattern (TUTORIA_) and four underscores in the Table Pattern (PART____) so table TUTORIAL.PARTSUPP would be a match.

Parent topic: Use the Catalog Browser


Manage Databases

  • To view and copy SQL statements
  • Changing Your Current Location and SQLID
  • Creating a Location
  • Altering a Location
  • Dropping a Location
  • Creating a Table
  • To create a new table
  • Altering a Table
  • To edit a table
  • Dropping a Table
  • To drop a table
  • To change the structure of a table
  • Creating an Index on a Table
  • Altering an Index
  • Dropping an Index
  • Creating a Foreign Key Relationship
  • Altering a Foreign Key Relationship
  • Dropping a Foreign Key Relationship
  • To create a new index or key
  • To change an index or key
  • To drop an index or key
  • To create new relationships
  • To change relationships
  • To drop relationships
  • Creating Synonyms
  • Dropping Synonyms
  • Creating Aliases
  • Dropping and Altering Aliases
Parent topic: SQL Wizard


To view and copy SQL statements

  1. Enter data into the fields on a Create, Alter, or Drop dialog box as described elsewhere.
  2. Click the SQL button to access the Show SQL window and display the resulting SQL statement.
  3. Use your mouse to highlight the desired text. Click the Copy command from the Edit menu.
  4. Switch to your editor or open an SQL Edit window (from the File menu, click New, then click SQL).
  5. With your cursor positioned in the desired destination text field, click Paste from the Edit menu.
  6. Return to SQLWizard and close the Show SQL window and return to the Create, Alter, or Drop dialog box you were using.
Parent topic: Manage Databases


Changing Your Current Location and SQLID

SQLWizard allows you to connect to a different location than the one you are currently using without exiting the program. If you have an alternate AuthID, you can change that also. These changes are made by clicking on the Set Location command from the Location menu or by clicking the Set button on the Catalog Browser dialog box.

In some cases, it may not be necessary to change to another location. For example, to query data that resides in another location of the XDB Server to which you are connected, simply enter a three-part name for the table being queried. It is also possible to set up alias names for tables in other locations.

Note: To change to a location on another XDB Server on your LAN, you must exit SQLWizard and restart it, choosing the desired server and location when the Connect dialog box appears. To change your default XDB Server and Location, use the Connect tab in the Options utility. If your organization uses the server-to-server connectivity features, you can access locations on multiple XDB Servers without having to log on to each individually.

To set the current location and SQLID:

  1. From the Location menu, choose the Set Location command.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Location tab; then click the Set button.

    SQLWizard displays the Set Location/SQLID dialog box.

  2. Enter a location name in the Current Location field or select a location from the drop-down list. For more about setting locations, see the description for the Set Location command in the .
  3. Enter a new SQLID if you wish to work using a different name. (Note that you are still logged in as the AuthID you used at the Connect dialog box, even though you changed your SQLID to a different name.) For more about CURRENT SQLID, see the description for the Set Current SQLID command.
  4. Click OK to accept the changes. The current location and SQLID are displayed in the status bar at the bottom of the SQLWizard window.
Parent topic: Manage Databases


Creating a Location

When SQLWizard creates a location, the system creates a directory structure for the new location, as well as all of the system catalog tables required by the location. Information about the new location is added to the catalog tables in the SYSTEM location. You create a location using the Create command from the Location menu. See Create/Alter/Drop Location Dialog Box for an explanation of each option on this dialog box.

To create a location:

  1. Click the Create command from the Location menu.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Location tab; then click the Create button.

    SQLWizard displays the Create Location dialog box.

  2. Provide a name for the new location in the Location Name field. The name can be up to 16 characters long. This name must be unique among all locations you can access on the current XDB Server. To be sure you do not attempt to use the name of an existing location, click the down-arrow button to view the existing names on the drop-down list.
  3. Provide a drive and directory in the Location Path field. SQLWizard creates the location in this directory. Use a different directory for each XDB Server location you create. Do not use an XDB Server location directory for storing anything else.
  4. If you want to change the name of the file to which the Forward Log is written, type a new name in the Forward Log Name field (in XDB Server version 4.x and earlier, only).
  5. If you want to change the directory to which the Forward Log is written, type a new path name in the Forward LogPath field (in XDB Server version 5 and later; the Backward Log is placed in this directory too).

    If possible, assign the log file to a physical device different from that of your database. This will ensure that you can recover if the disk containing your database fails.

    Note:

    You must specify a directory that will be used exclusively for this location's log files. Be certain not to specify a directory that is already assigned to another location.

    The directory path is limited to 255 bytes. This restriction is due to limits imposed by the XDB SYSTEM location.

  6. If you want to disable forward logging, clear the Forward Log On checkbox (XDB Server version 4.x and earlier, only; this checkbox will be grayed if you're running version 5 or later).

    Since the forward logging facility used by XDB Servers version 4.x and earlier increases your overhead, you may choose not to use it for performance reasons. Be aware, however, that disabling this option will significantly limit your ability to recover data in the event of a failure.

  7. Select a Sort Sequence for the location, or use the default specified. Click the down-arrow button to view the existing options on the drop-down list. The sort sequence is used for XDB Server indexes, as well as for user-program sorts.
  8. Click OK to create the location.
Parent topic: Manage Databases


Altering a Location

Once you have created a location, you cannot change its name, path, or sort sequence. You can change the Location Creator, Forward Log settings, and Remarks as necessary.

To alter a location:

  1. Click the Alter command from the Location menu.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, choose a location from the Location folder and click the Alter button.

    SQLWizard displays the Alter Location dialog box .

  2. Specify the name of the location you want to alter in the Location Name field. Click the down-arrow button to view the existing names on the drop-down list. SQLWizard reads the system catalog entries for the location and displays the appropriate information.

    Optionally, you can type a name in the Location Name field instead of choosing a name from the drop-down list. If you type a location name, be sure to click a different field on the window to let SQLWizard know that you are done typing.

  3. Modify fields by typing in new information.
    Note:

    You cannot change the Location Path. This field is disabled.

  4. Click OK to accept the location changes.
Parent topic: Manage Databases


Dropping a Location

When you drop a location, its directory and all of the tables, indexes, and associated files are deleted. You cannot reverse this process. Use the Drop command with care!

Note:

To drop a location, you must be connected to a different location. To change your current location, click Set Location on the Location menu.

You cannot drop a location to which you are attached. If you receive the error "X131:Attempt to drop location in use" when dropping a location, exit SQLWizard and restart the program, logging onto a different location. Then drop the other location.

To drop a location:

  1. Click the Drop command from the Location menu.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, choose a location from the Location folder and click the Drop button.

    SQLWizard displays the Drop Location dialog box.

  2. Specify the name of the location you want to drop in the Location Name field. Click the down-arrow button to view the existing names on the drop-down list. SQLWizard reads the system catalog entries for the location and displays the appropriate information.

    Optionally, you can type a name in the Location Name field instead of choosing a name from the drop-down list. If you type a location name, be sure to click a different field on the window to let SQLWizard know that you are done typing.

  3. Review the information to verify that this is the location you want to drop and that you are currently connected to a different location. Your current location is displayed in the status bar at the bottom right of the SQLWizard window.
  4. Click OK to drop the location.
  5. Click OK to confirm dropping the location.
Parent topic: Manage Databases


Creating a Table

You can use SQLWizard to create and manage your database tables. You can define indexes, primary keys, foreign keys, synonyms, and aliases using buttons available from the Create Table dialog box.

To create a table:

  1. Click the Create command from the Table menu.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Table tab; then click the Create button.

    SQLWizard displays the Create Table dialog box.

  2. Type a name in the Table Name field. You can enter a one, two, or three-part name.
    Note:

    If you create a table in a different location than your current location, SQLWizard performs a connect to that location and then resets the location after the create is complete.

  3. Position the cursor in the Column Definition Grid in the lower half of the dialog box. Start in Field Name of Fld No. 1 and type a name for the first column of your table.

    You must define at least one column in the table when you create it. You can alter the table later to add, delete, or move columns.

  4. Position the cursor in the Data Type field to display a down-arrow button. Click the down-arrow button to display a drop-down list of data types. (This button does not become visible until the cursor is positioned in the Data Type field.) Choose a data type from the list.

    Alternatively, you can type a data type without displaying the list. Usually, the first letter you type is enough; SQLWizard completes the entry.

  5. Provide Length and Not Null information, or accept the defaults.
  6. Add, delete, or move rows as desired.

    Add rows to the table by clicking on the + button, while the cursor is inside the Column Definition Grid. The + button adds a row immediately after the row of the cursor's position. (Alternatively, press the keyboard down arrow cursor key to move the screen cursor down to a new row.)

    Delete a row by clicking on a number under the Fld. No. column to select a row. Click the - button to delete the selected field number from the list. You can select any number of rows to be deleted at one time.

    Move a column definition up or down in the list by selecting the row to move and clicking on its field number under the Fld No. column. Click the up or down arrow buttons to move the fields up or down the list, one row at a time. You can move more than one row at a time if you highlight contiguous rows by clicking on the field-number button on the left.

  7. If your table requires the specification of options relating to compatibility with DB2 or another supported database, click the Options button to display the Table Options dialog box. When you have finished specifying table options, click OK to return to the Create Table dialog box.
  8. Click OK to create the table.
Parent topic: Manage Databases


To create a new table

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click Create.
  5. Type a name for the table in Table Name.

    If you use a three-part table name and the location is not the current one, a temporary connection to the new location is established.

  6. Define the columns (fields) in your table by typing a column name, data type, length and whether nulls are accepted in the appropriate fields.

    To define a new column, click +.

  7. When you have finished, click OK to create the table.
Parent topic: Manage Databases


Altering a Table

The Alter Table dialog box lets you add, change, or delete a table's columns, as well as to add or change an existing table's indexes, primary keys, foreign keys, synonyms, and aliases.

If you are running against an XDB Server (local or multi-user), just about any part of a table specification can be altered, even if the table already contains data. You can rename the table or its columns, change column data types, change the ordering of the columns, and add or drop columns.

Note:

If you are running against DB2, there are limits on the changes you can make to a table because the DB2 ALTER TABLE statement is not as comprehensive as the XDB Server ALTER TABLE statement. When connected to DB2 via XDB Link, only those functions that are supported on DB2 (such as adding columns) are enabled on the Alter Table dialog box.

To alter a table:

  1. Click the Alter command from the Table menu.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Table tab and choose a table; then click the Alter button.

    SQLWizard displays the Open dialog box.

  2. Choose a table and click OK. SQLWizard displays the Alter Table dialog box.
  3. Modify the table specification as you wish. Making changes is similar to the initial entry of table specifications when creating a table.
    Note:

    If you wish to change the data type of an existing field, be sure that the new data type is compatible with the old data type. For example, you would not be allowed to change a date field to a decimal field. Other changes may be possible, but not desirable, such as changing an integer field to a character field.

  4. Click OK to alter the table.
  5. Click OK to confirm the table alterations.
Parent topic: Manage Databases


To edit a table

Before you start, ensure that the current location is set to the location where the table resides.

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want to edit.
  5. Click Open.
  6. Enable editing by clicking Allow Editing on the Record menu.
  7. Edit the table as required.
  8. Close the Result Table window.
Parent topic: Manage Databases


Dropping a Table

When you drop an XDB Server table, SQLWizard deletes all files associated with the table and removes its entries from the system catalog. Related indexes, keys, and relationships are also dropped. You cannot reverse a drop table action. Use the Drop command with care!

To drop a table:

  1. Click the Drop command from the Table menu.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Table tab and choose table; then click the Drop button.

    SQLWizard displays the Open dialog box.

  2. Choose a table and click OK. SQLWizard displays the Drop Table dialog box.

    The table definition is shown so that you can verify it is the table you wish to drop. All fields in this window are disabled except for the five main buttons on the right.

  3. Click OK to drop the table.
  4. Click OK to confirm dropping the selected table.
Parent topic: Manage Databases


To drop a table

To drop a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want to drop.
  5. Click Drop.
  6. Click OK to confirm your request.

SQL Wizard deletes the files associated with the table and removes the entries about the table from the system catalog.

Note: You cannot recover a table once it has been dropped.
Parent topic: Manage Databases


To change the structure of a table

Before you start, ensure that the current location is set to the location where the table resides.

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want to alter.
  5. Click Alter.
  6. Change the column definitions, indexes, keys and relationships as required.

    You can look at the SQL statements that will be used to make your changes by clicking SQL at any time.

  7. Click OK.
Note: XDB databases support extensive alterations to a table, even if it contains data. DB2 databases support a much more restricted set of alterations. If the target database is a DB2 database, unsupported options are not available on the Alter Table window.
Parent topic: Manage Databases


Creating an Index on a Table

After defining the columns for your table, you are ready to define its indexes. You can define an index when you create the table, or you can use the Alter Table window to define an index for an existing table.

Options are provided for compatibility with DB2 and other XDB Server-supported databases.

To create an index:

  1. Click the Create command from the Table menu to display the Create Table or Alter Table dialog box, or click the Alter command to display the Open Table dialog box and choose a table. If you are creating a new table, or you need to change the column specifications for an existing table, make the column entries before proceeding.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Table tab; then click the Create button, or choose a table and click the Alter button

  2. Click the Create button in the Indexes and Keys group box.

    SQLWizard displays the Create Index dialog box.

  3. Type a name for your index in the Index Name field.
  4. Choose the type of index by clicking one of the three types in the Type group box: Index, Unique Index, or Primary Key.
  5. Choose the column(s) you wish to use as the key for the index. Any column names included in the Index Columns list when you exit the Create Index dialog box are used as your index key(s). Use the following descriptions as a guide for choosing columns.

    To move a column name from one list to the other, click its name to highlight it; then click the right or left arrow button to move it to the other list. Alternatively, double-click a column name to move it to the other list.

    To select multiple contiguous items, hold down the Shift key when clicking on the first and last entry of the desired list of names. To select multiple non-contiguous items, hold down the Ctrl key while clicking on each item you want to select. When the desired items are highlighted, click the appropriate arrow button to move them to the other list.

    To move all column names from one list to the other, click a double-arrow button.

  6. To change the order of columns in the Index Columns list, click a column name and click the up- or down-arrow button.
  7. Click the Options button to specify additional index items.

    Most of these additional options are provided for compatibility with DB2 or other XDB Server-supported databases. For DB2, these include the equivalents of USING BLOCKS, FREE BLOCKS, CLUSTERS, BUFFER POOLS and other options.

  8. Click OK to accept the index definition.

    SQLWizard adds the name of the new index to the Indexes And Keys group box, preceded by a + sign to indicate a new index definition.

  9. Click OK from the Create/Alter Table dialog box to create the new index.

    SQLWizard creates the new index definition for the selected table.

Parent topic: Manage Databases


Altering an Index

When you alter an index, the index is actually dropped and recreated using your new specifications.

Additional options are provided for those requiring compatibility with mainframe DB2 or other XDB Server-supported databases.

To alter an existing index:

  1. Click the Alter command from the Table menu.

    SQLWizard displays the Open Table dialog box.

  2. Choose the desired table and click OK. If you need to change column specifications for an existing table, make these entries before proceeding.
    Note:

    Catalog Browser button
    From the Catalog Browser dialog box, click the Table tab and choose a table; then click the Alter button.

  3. Choose an index from the Indexes And Keys list on the Alter Table dialog box either by double clicking on an index name or by highlighting a name and clicking the Alter button.
  4. Modify the column selection using the arrow buttons.
  5. Change any DB2-related index items by clicking on the Options button. These include the equivalents of Using Blocks, Free Blocks, Clusters, Buffer Pools and other options.
  6. Click OK to accept the changes.

    SQLWizard returns you to the Alter Table dialog box. An asterisk (*) precedes the index entry in the Indexes And Keys list to show that the index definition has been changed.

  7. Click OK to exit the Alter Table dialog box.
  8. Click OK to confirm altering the table.

    SQLWizard modifies the index specifications on the selected table.

Parent topic: Manage Databases


Dropping an Index

When you drop an index using the Alter Table facility, there is no effect on the table data because the index is a structure independent of the table.

Once index specifications are saved for a table, you can drop them by reopening the Create/Alter/Drop Table dialog box and accessing the Alter Index dialog box. You can also use the Undo button from this dialog box to cancel a drop index specification before resaving the table information from the Create/Alter/Drop Table dialog box. Once completed, SQLWizard drops the old index and creates a new one using the new specifications you provide, if any.

To drop an index:

  1. Click the Drop command from the Table menu.

    SQLWizard displays the Open Table dialog box.

  2. Choose the desired table and click OK.

    SQLWizard displays the Drop Table dialog box.

    Note:

    From the Catalog Browser dialog box, click the Table tab and choose a table; then click the Drop button.

  3. Choose an index from the Indexes And Keys list on the Drop Table dialog box by highlighting a name and clicking the Drop button.

    SQLWizard modifies the index entry by preceding it with a - sign to indicate it will be dropped when exiting the Drop Table dialog box.

    Note:

    If you decide you want to keep an index before exiting the Drop Table dialog box, double click the name of the index to display the Drop Index dialog box. Click the Undo button. The - sign will be removed and the index will remain intact.

  4. Click OK from the Drop Table dialog box to drop all indexes that have the - sign.
  5. Click OK to confirm altering the table.

    SQLWizard drops the selected indexes on the selected table.

Parent topic: Manage Databases


Creating a Foreign Key Relationship

You can create a foreign key when you are creating or altering a table. Instructions on how to create a foreign key are provided below.

To create a foreign key relationship:

  1. Verify that your key columns in the referenced table and the dependent table have the same data types, sizes, and null status. You can examine these column attributes using the Catalog Browser dialog box.
  2. Display the Create Table or Alter Table dialog box for the dependent table. This is the table on which you are creating a foreign key.
  3. Click the Create button from the Relationships group box.

    SQLWizard displays the Create Relationship dialog box.

  4. Type a name for your foreign key in the Foreign Key Name field.
  5. Type the name of a table in the Referenced Table field, or click the Browse button and choose a table from the Open Table dialog box. When you specify a referenced table, remember that it must have a primary key already defined.
  6. The Table Columns list displays the column names from the dependent table (the EMPLOYEE table in the example above). These are available for you to match to the Referenced Columns that are displayed in the other list.
  7. Match a column name from the Table Columns list to each of the Referenced Columns. There are two ways to do this:
    • Highlight a column name and click the right arrow button.
    • Double-click a column name.

    SQLWizard moves the selected field from the dependent Table Columns list to the Foreign Key Cols list, next to the first available referenced column.

    If you make any errors in assigning fields, highlight the name in the Foreign Key Cols list and move it back to the Table Columns list by clicking on the left arrow button.

  8. To change the ordering of the foreign key columns, click a foreign key column and use the up and down arrows to reposition it next to the correct column from the referenced table. The column only moves up or down if there is another matching referenced column (i.e., the same data type, length, and null permission) above or below it in the list.
  9. Click OK to accept the relationship definition.

    SQLWizard displays the name of the foreign key in the Relationships group box on the Alter Table dialog box, preceded by a + sign to indicate a new relationship. The name of the referenced table appears in parentheses.

  10. Click OK from the Alter Table dialog box.
  11. Click OK to confirm altering the table.

    SQLWizard creates the foreign key on the selected table.

Parent topic: Manage Databases


Altering a Foreign Key Relationship

You can alter some of the specifications of a relationship, particularly the On Delete and On Update options.

Instructions for how to alter a relationship are provided below.

To alter a foreign key relationship:

  1. Display the Alter Table dialog box for the dependent table.
  2. In the Relationships group box, either highlight a relationship name and click the Alter button, or double click a relationship name. The Alter Relationship dialog box is displayed.
  3. Make changes to any field or selection in the foreign key definition.
  4. Click OK to accept the changes and return to the Alter Table dialog box.

    SQLWizard displays the name of the foreign key in the Relationships group box. The relationship name is preceded by an * to indicate that the foreign key specifications have been modified.

  5. Click OK to accept the foreign key changes.
  6. Click OK to confirm altering the table.
Parent topic: Manage Databases


Dropping a Foreign Key Relationship

To drop a foreign key, use the Alter Table dialog box. Instructions for how to drop a foreign key relationship are provided below.

To drop a foreign key relationship:

  1. Display the Alter Table dialog box for the dependent table.
  2. In the Relationships group box, highlight a relationship name and click the Drop button.

    SQLWizard displays a - sign preceding the foreign key name to indicate it will be dropped when you exit the Alter Table dialog box.

    Note:

    If you realize you want to keep a foreign key (relationship) before exiting the Alter Table dialog box, double click the name of the foreign key and display the Drop Relationship dialog box. Click the Undo button. The - sign will be removed, and the foreign key will remain intact.

  3. Click OK from the Alter Table dialog box to drop the foreign key.
  4. Click OK to confirm altering the table.
Parent topic: Manage Databases


To create a new index or key

To create an index or key on a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. Click Create in the Indexes and Keys group.
  7. Type a name for your index or key.
  8. Select the type of index or key you want to create.
  9. Use the arrow pushbuttons to create a list of columns that define the index or key.
  10. When you have finished, click OK to close the Create Index dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  11. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To change an index or key

To change an index or key on a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. In the Indexes and Keys group, select the index or key you want to change from the list.
  7. Click Alter.
  8. Make the changes you require.
  9. When you have finished, click OK to close the Alter Index dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  10. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To drop an index or key

To drop an index or key on a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. In the Indexes and Keys group, select the index or key you want to change from the list.
  7. Click Drop.
  8. Click OK to close the Create Index dialog box.
  9. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To create new relationships

To create relationships on columns in a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. In the Relationships group, click Create.
  7. Type a name for the foreign key.
  8. Type the name of the parent (referenced) table for the foreign key or click Browse to search for it.
  9. Select the behavior you require in the On Delete and On Update groups.
  10. Use the arrow pushbuttons to create a list mapping columns that you want to be foreign keys to the corresponding primary key columns in the parent table.
  11. When you have finished, click OK to close the Create Relationship dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  12. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To change relationships

To change relationships on columns in a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. Select the name of the foreign key you want to alter from the list.
  7. In the Relationships group, click Alter.
  8. Make the changes you require.
  9. When you have finished, click OK to close the Alter Relationship dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  10. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To drop relationships

To drop relationships on columns in a table in the current location:

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. Select the name of the foreign key you want to drop from the list.
  7. In the Relationships group, click Drop.
  8. Click OK to close the Alter Table window.
Parent topic: Manage Databases


Creating Synonyms

You can create a synonym when you are creating or altering a table. Synonyms are defined on the Table Options dialog box.

To create a synonym:

  1. Display the Create Table or Alter Table dialog box.
  2. Click the Options button to display the Table Options dialog box.
  3. Click the Create button in the Synonyms group box.

    SQLWizard displays the Create Synonym dialog box.

  4. Type a name for the synonym in the Synonym Name field.
  5. Click OK to accept the synonym.

    Your new synonym is now listed in the Synonym group box of the Table Options window with a + sign preceding it.

  6. Click OK from the Table Options dialog box.
  7. Click OK from the Create Table or Alter Table dialog box to create the synonym.
  8. Click OK to confirm altering the table.

    SQLWizard creates the new synonym.

Parent topic: Manage Databases


Dropping Synonyms

A synonym is not dropped until you exit the Alter Table dialog box. Before you exit this dialog box, be sure you have made all appropriate changes and wish to save the table specifications.

To drop a synonym:

  1. Display the Alter Table dialog box for the table on which the synonym is defined.
  2. Click the Options button to display the Table Options dialog box.
  3. Highlight a synonym in the Synonyms group box and click the Drop button. The Table Options dialog box displays the synonym with a - sign preceding it to indicate that it will be dropped.
    Note:

    If you mark a Synonym name and then realize you want to keep it, before exiting the Alter Table dialog box, double click the name of the Synonym to display the Drop Synonym dialog box. Then click the Undo button. The - sign will be removed, and the original synonym will remain intact.

  4. Click OK from the Table Options dialog box and click OK in the Alter Table dialog box to drop the synonym.
  5. Click OK to confirm altering the table.
Parent topic: Manage Databases


Creating Aliases

Before you create an alias for a table, you must be connected to the location where the table resides.

To create an alias:

  1. Display the Create/Alter Table dialog box.
  2. Click the Options button.

    SQLWizard displays the Table Options dialog box.

  3. Click the Create button in the Aliases group box.

    SQLWizard displays the Create Alias dialog box.

  4. Type a name for the alias in the Alias Name field.
  5. Select target locations from the Target Location group box. These are the locations from which you want this alias to be accessible. Users in each of these locations can also use the alias to access the table.

    There are two ways to select location names:

    • Double click a location name on the Not Selected list to move it to the Selected list.
    • Click a location name on the Not Selected list; then click the right-arrow button to move it to the Selected list.
  6. Click OK to accept the information and return to the Table Options dialog box.

    Your new alias is now listed in the Aliases group box of the Table Options dialog box with a + sign preceding it.

  7. Click OK from the Table Options dialog box.
  8. Click OK from the Create Table or Alter Table dialog box to create the alias.
  9. Click OK to confirm altering the table.

    SQLWizard creates the new alias.

Parent topic: Manage Databases


Dropping and Altering Aliases

An alias is not dropped until you exit the Alter Table dialog box. Before you exit this window, be sure you have made all appropriate changes and wish to save the table specifications.

To drop an alias:

  1. Display the Alter Table dialog box for the table on which the alias is defined.
  2. Click the Options button from the Aliases group box to display the Table Options dialog box.
  3. Highlight an alias in the Aliases group box and click the Drop button. The Table Options dialog box displays the alias with a - sign preceding it to indicate that it will be dropped. Only aliases created in the same location as the table they are associated with will appear in the Aliases group box.
    Note:

    If you mark an alias name and then realize you want to keep it, before exiting the Create/Alter Table dialog box, double click the name of the alias to display the Drop Alias dialog box. Then click the Undo button. The - sign will be removed, and the original alias will remain intact.

  4. Click OK from the Table Options dialog box and click OK in the Alter Table dialog box to drop the alias.
  5. Click OK to confirm altering the table.
Parent topic: Manage Databases


Query Databases

  • Creating a Query
  • To create a query
  • Viewing Queries in SQL Edit Mode
  • Saving a Query
  • Opening a Saved Query
  • Running a Query
  • Viewing Results
  • Closing a Result Window
  • Example
  • Example
  • Setting Query Options
  • Choosing Columns
  • Moving Columns
  • Hiding Columns
  • Defining Conditions for a Single Column
  • Matching a Range of Values
  • Using AND and OR on One Column
  • Using AND and OR on Different Columns
  • Referring to Other Columns in Conditions
  • Including Calculations in Conditions
  • Selecting From a List of Values
  • Defining Computed Columns
  • Renaming Fields
  • Finding Distinct Values
  • Adding Extended Conditions (And and Where)
  • Specifying Sort Order
  • Retrieving Data From Two or More Tables
  • Displaying Table Names
  • Avoiding Cartesian Products
  • Prohibiting Cartesian Products
  • Manual Joins
  • Preventing Cartesian Products with Auto Joins
  • Non-equijoins
  • Outer Joins
  • Creating a Summary Query
  • Searching for Duplicate Values
  • Creating a Union
  • Creating a View
  • Creating a DELETE Statement
  • Creating an UPDATE Statement
  • Creating an INSERT Statement
Parent topic: SQL Wizard


Creating a Query

In this topic, you will learn to write a simple prompted query that retrieves everything in a table - all of the columns and rows. For this example, the Query Design window that produces a prompted query is used.

To create a new query:

  1. Open a new Query Design window.

    SQLWizard displays the Add Table dialog box.

  2. Click one of the tables from the Table Name list box. If you do not see the table you want to use, you may have to change the Location or AuthID.
  3. Once you have highlighted a table, click the Add button to copy the table to the Query Design window. Notice that the columns in the selected table are shown in a Column Selection List.
    Note: When adding tables to a Query Design window, you can pick more than one table. A query that gets data from more than one table is called a join. For now, just select a single table.
  4. Click the Done button to close the Add Table dialog box. If you click the Done button before you add a table to the query, you will need to use the Add Table command from the Query menu.
    Note:

    Catalog Browser button

    Add button
    Click the Add button on the toolbar or, from the Catalog Browser dialog box, drag a table to the Table Display Area.

  5. Examine the Column Selection List in the Table Display Area of the Query Design window. The table name is shown in the title bar. Beneath the title bar is a list box containing all column names in the selected table. You can select one column to be added in your query or you can use the asterisk (*) to select all columns in the table.
  6. Click the asterisk in the Column Selection List to add all of the columns in the table to the query.

    Notice that the columns are added to the Query Conditions Grid in the order they appear in the Column Selection List.

Parent topic: Query Databases


To create a query

  1. From the main menu, click > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click Catalog Browser icon to open it.
  3. On the Catalog Browser window, ensure the Query tab is selected.
  4. Click New.
  5. Click the table names that you are interested in and click Add.
  6. When you have added all the required tables, click Done.
  7. In each table, click the fields that you are interested in.
  8. Under each field, type any conditions you require.
  9. Click Save As on the file menu to save your query.
  10. Close the Query Design window.
  11. Click Refresh, to see your new query listed.
Note: To execute your query, click on the query and click Batch.
Parent topic: Query Databases


Viewing Queries in SQL Edit Mode

You can examine the SQL statements generated by the Query Design window by switching to the SQL Edit window.

To switch to the SQL Edit window:

  1. Click the SQL command from the View menu.
    Note:

    SQL Edit button
    Click the SQL Edit button on the toolbar

    While in the SQL Edit view, you can make changes to your query that would be difficult to make through the prompted Query Design window. You can also edit other types of commands that are not currently supported by the Query Design window.

  2. Click the Design command from the View menu to return to the Query Design window.
    Note:

    Query Design button
    Click the Query Design button for Query Design mode.

Note:

If you make changes to the SQL statement while in the SQL Edit window, you will not be able to go back to the Query Design window without discarding those changes. You can, however, first save the prompted query in Query Design mode, switch to SQL Edit mode, and save the modified SQL statement as an SQL script file.

Parent topic: Query Databases


Saving a Query

If you think you will want to use a query, save the query before you try to run it. Saving a query places the information in the system catalog tables, where it can be accessed later by you (and others if you save it as a shared query).

To save a query that has never been named before, or to save a query under a different name:

  1. From the File menu, click the Save As command.
    Note:

    Save button
    Click the Save button on the toolbar

    SQLWizard displays the Save As dialog box.

  2. Type a name for the query. You may want to change the location and AuthID for the query before you save it.
  3. Click the Options button to display the Set Query Options dialog box and type a comment or description for your query. This description will appear in the list of queries on the Catalog Browser dialog box.
  4. In the Query Type group box, choose to save your query as a Prompted Query (to be retrieved later into the Query Design window) or as an SQL Edit Query (to be retrieved later into the SQL Edit window or run as a batch SQL script file).
    Note:

    If you are saving a query from the SQL Edit window, and that query has been changed so that it no longer can be used in the Query Design window, you will only be able to save it as an SQL Edit Query, and not as a Prompted Query.

  5. In the Access group box, choose to make the query Private (available only to you) or Shared (available to other users on the XDB Server). With a Shared Query, the other users must have appropriate access authority to read the tables that the query uses.
  6. Click OK to exit back to the Save As dialog box.
  7. Click OK to save the query.

To resave a query:

Once a query is saved, you can use the Save command on the File menu or the Save button on the toolbar to resave any changes. The Save command does not prompt for a query name and does not provide access to the Set Query Options dialog box if the query has already been saved with a name.

Parent topic: Query Databases


Opening a Saved Query

There are several ways to open a saved query.

To open a saved query from the menu:

  1. From the File menu, click the Open command.

    SQLWizard displays the Open dialog box.

  2. Click the down-arrow button for the List Objects Of Type field to display the object types drop-down list; click Queries.
  3. Click the desired query to open. Note that you may have to change the Location or AuthID to find the query you want to open.
  4. Click OK.
Note:

Open button on menu

Open button on Catalog Browser
Click the Open button on the toolbar and choose the desired query or, from the Catalog Browser dialog box, click the Query tab, a query, and the Open button.

Parent topic: Query Databases


Running a Query

Running a query causes the SQL command to be sent to the XDB Server where the desired columns and rows are retrieved and sent back to SQLWizard to display in a Result window. Before you can run a query, you must have specified at least one table and one column.

To run an open query from a Query Design window:

  1. Click the Query Design window to make it the current window.
  2. From the Query menu, click the Run command
Note:

Run button

Batch button
Click the Run button on the toolbar or, from the Catalog Browser dialog box, click the Query tab, a query, and the Batch button.

Related Topics

Parent topic: Query Databases


Viewing Results

When you run a query, the results of the query are displayed in a Result window. There are two result views: Result Table and Result Form. These are available from the View menu after a query is run.

A Result Table shows the rows of the result in a spreadsheet-like format. You can scroll in any direction to see the columns and rows of the result.

A Result Form shows the result one record at a time, with the fields displayed one beneath another. You move between records much like you turn the pages of a book. You can have multiple Query Result windows open at the same time.

To switch between Result Table and Result Form views:

  1. Click the Result Table command from the View menu, or click the window to make it active.
  2. Click the Result Form command from the View menu, or click the window to make it active.
Note:

Result Table button

Result Form button
Click the Result Table or Result Form button on the toolbar.

Parent topic: Query Databases


Closing a Result Window

To close the current Result window, click the Close command from the File menu, or double click the Window Control Menu box at the upper left corner of the Result window.

Parent topic: Query Databases


Example

The following example returns a list of all customer companies located in California. Even though the state column, St, appears in the Query Conditions Grid, it does not appear in the result.

  1. Open a new query.
  2. Add the CUSTOMER table and click Done to close the Add Table dialog box.
  3. Click the COMPANY column in the Column Selection List to add it to the Query Conditions Grid.
  4. Click the ST column to add it to the grid.
  5. Move down to the Query Conditions Grid and enter the string CA in the Conditions row under the ST column name.
  6. Click the ST column to select it.
  7. Click the Hide Column button on the toolbar (or use the Hide Column command from the Column menu).
  8. Run the query. Only the COMPANY column is shown in the Result window, displaying the names of only those companies in California.
  9. Close the Result window.
  10. Examine the SQL code generated for this command by clicking on the SQL button on the toolbar. Notice that the ST column does not appear in the SELECT clause of the query, but it is mentioned in the WHERE clause.
  11. Click the Query Design button on the toolbar to switch back to Query Design mode. Save the query if you want to keep it, and close the Query Design window.
Parent topic: Query Databases


Example

This example creates a query that shows all of the cities that employees live in, and summarizes employee information into a column containing the count of employees living in each city. There will be one row returned for each city, regardless of how many employees live in that city.

  1. Open a new query and select the table of interest. In this case, open the EMPLOYEE table. Add it to the query and then click the Done button.
  2. Click the columns you want displayed in the query. Do not include the columns that contain data that you want to summarize yet. For this example, add the CITY and STATE columns.

  3. Create Computer Column
    Click the Create Computed Column button on the toolbar (or the Create Computed Column command from the Column menu) to display the Create Computed Column dialog box.
  4. From the Aggregate Function drop-down list, double-click Count.
  5. From the Table/Column drop-down list, double-click E_NO.

    It is a good idea, when generating a count, to choose a column that uniquely identifies the records that you want to count. You could also use an asterisk, which indicates that you want a count of all the records. The column name should be positioned inside the parentheses that appear after the count function.

  6. A column name is provided for the column, but you may want to change it to something more meaningful. Click the Column Name field and type in EmployeeCount.
    Note:

    Column names must satisfy the rules for a long identifier, discussed in the SQL Reference. That is, they may be up to 18 characters long and must begin with a letter. They cannot contain spaces.

  7. Click OK to accept the Computed Column.
  8. Now examine the Query Conditions Grid. You will notice that a new column called EMPLOYEECOUNT has been added at the end of the column list. The Order/Group row has also been added to the grid. You first saw this row when you defined a sort order for a query. Now it contains some new icons. The
    Computed Column symbol
    symbol indicates that the column is a computed column. If you click this symbol, the Modify Computed Column dialog box for this column is displayed so that you can modify the column definition.
  9. In addition, a
    Aggregate Function symbol
    symbol appears in the STATE and CITY columns. Whenever an aggregate function appears in a query, all other columns must be grouped. SQLWizard does this for you automatically. Click the
    Grouped Column symbol
    symbol.

    The Group By dialog box is displayed. Notice that there are two lists. The UnGrouped Columns includes the computed column EMPLOYEECOUNT, which SQLWizard will not allow you to group. The Grouped Columns include the CITY and STATE columns, which SQLWizard will not allow you to ungroup unless you delete the EMPLOYEECOUNT column.

  10. The order in which columns appear in the GROUP BY clause is important. SQLWizard places the columns in the list in the order in which they appear on the Query Conditions Grid. If this is not the correct order for your query, you should rearrange them. To do so, click a column to select it, and then use the Up and Down buttons to reposition the column. When positioning the columns, keep in mind that a column that contains a subset of the rows of another column should appear later in the list. In this example, the CITY column should appear after the STATE column, because there are a number of cities in each state. Move the STATE column to the top of the list.
  11. Once you have ordered the columns correctly, click OK to close the Group By dialog box. Notice the number that appears to the right of the GROUP symbol shows that STATE is the first grouped column, and CITY is the second grouped column.

  12. SQL button
    You have now created a query containing summary rows. Use the SQL button on the toolbar to examine the SELECT statement generated for this command. Notice the COUNT function and the GROUP BY clause.

  13. Query Design button
    Use the Query Design button on the toolbar to return to the Query Design window.
  14. Save the query if you would like to keep it.

  15. Run button
    Click the Run button to run the SQL command. When the result appears you will see a row for every city in the EMPLOYEE table. The number of EMPLOYEE records that have a matching CITY value will appear in the EMPLOYEECOUNT column.
  16. Exit from the Result window
Parent topic: Query Databases


Setting Query Options

SQLWizard provides options for designing and running your queries. You can set the defaults for all queries using the Options utility, as well as set specific options for a currently open Query Design or SQL Edit window.

To set options for the current query:

  1. From the Query menu, click the Current Query Options command.

    SQLWizard displays the Query Options dialog box.

  2. Make changes to the available items as desired.
  3. Click OK to accept the changes.
Parent topic: Query Databases


Choosing Columns

There may be times when you do not want to show all of the columns in a table in your result. You can specify which columns to show, and the order in which they will appear in the Result window.

To add a single column to the Query Conditions Grid:

  1. Open or create a new query.
  2. Scroll through the list in the Column Selection List to find the column you want to add.
  3. Click the column to add it to the Query Conditions Grid. The column will be highlighted in the Column Selection List to show that it is added to the grid.
  4. Continue adding columns by clicking on them. As you click the names, they appear in the Query Conditions Grid. If you click a name by mistake, click it again to remove it.

    Notice that as you add a column to the query, it is added at the end of the set of columns in the Query Conditions Grid.

Note: If you decide you do not like your current column selection, you can easily start over by clicking once on the asterisk in the Column Selection List to select all columns, and a second time to remove all columns from the Query Conditions Grid.
Parent topic: Query Databases


Moving Columns

The order in which columns appear in the Query Conditions Grid determines the order they appear in your result window.

To change the order of columns:

  1. Click a column name in the Query Conditions Grid to select it.
  2. Click and drag the column to a new location on the grid.
  3. Drop the column over the divider between two columns. The selected column will be repositioned between these two columns.

    You can also wait and rearrange the columns after the query is run.

Note: You can select and move more than one column at a time. Simply hold down Ctrl while you click a collection of column names. Or hold down Shift while you click a second column name to pick all columns between (and including) the first and second selection.
Parent topic: Query Databases


Hiding Columns

If you want to specify a condition on a column in one of your tables, but you do not want the column to appear in your result, you can hide the column. There are several ways to hide a column that appears in the Query Conditions Grid:

  • Double click the column title to toggle the selected column between visible and hidden states. A column is visible if the title appears as a button. A column is hidden if it appears as a pressed button.
  • Click the column to select it, and use the Hide Column command from the Column menu to hide the column.
  • Click the Select Hidden Column command from the Column menu. The Select Hidden Column(s) dialog box allows you to move columns between a Visible and Hidden list by selecting and using the buttons between the lists. Click OK to accept the column specification on the dialog box.
Parent topic: Query Databases


Defining Conditions for a Single Column

Usually when you define a Select command, you want to add filter conditions to restrict the rows retrieved.

To add simple search conditions on the columns in a query:

  1. Open the query.
  2. Click the Conditions row of one of the columns.
  3. Type in a value that the column should match. For example, under the ST column, enter the values DC, MD, and VA on separate rows. Quotes appear around the values if they are needed. The three values are treated as OR conditions.
Note: If you want to compare a column with another field, you will use the join mechanism.
Parent topic: Query Databases


Matching a Range of Values

You can specify a range of values that a column should satisfy using the BETWEEN predicate. Type the condition BETWEEN followed by a number, then the keyword AND, then another number. For example:

Between 2 and 8
Parent topic: Query Databases


Using AND and OR on One Column

You can enter a compound condition containing an AND or an OR in a single cell of the Query Conditions Grid. This condition will be enclosed in parentheses in the SQL statement. For example, you could enter the following condition in the LNAME column of the EMPLOYEE table:

"Hurwood" OR "Kerin"
Parent topic: Query Databases


Using AND and OR on Different Columns

Values in different columns on the same row are treated as AND conditions. Values in different rows are treated as OR conditions. Look at the following Query Conditions Grid example.

This yields the following SELECT statement:

SELECT  E1.e_no, E1.lname, E1.payrate, E1.st, E1.com
FROM    TUTORIAL.TUTORIAL.EMPLOYEE E1
WHERE    ((E1.e_no Between 2 and 8)
        OR (E1.lname like ""hur%"")
        OR ((E1.payrate >4
            AND E1.payrate < 15)
            AND (E1.com is null))
            OR (E1.st <> "MD"))
Parent topic: Query Databases


Referring to Other Columns in Conditions

You can refer to another column in the query from within a cell. For example, you type the following condition into the LNAME column of the EMPLOYEE table to test for a last name equal to a first name:

=fname
Parent topic: Query Databases


Including Calculations in Conditions

If you want to include an expression in a condition, simply type it in. For example, you could include the following condition in the COM column of the EMPLOYEE table:

> (payrate*1.25)
Parent topic: Query Databases


Selecting From a List of Values

You can use the IN predicate to check for a records having values that match a member of a list of values. For example, you could type the following into a cell of the EMPLOYEE table's ST column:

IN ('MD', 'VA', 'DC', 'NY')
Parent topic: Query Databases


Defining Computed Columns

You can create a computed column that compares two or more columns in a table and produces aggregate and/or scalar results.

To create a computed column:

  1. Computed Column button
    Click the Create Computed Column command from the Column menu, or click the Computed Column button on the toolbar.
  2. In the Computed Column dialog box, type or pick from the function and column lists to create a calculated field. For example, the following uses the string concatenation operator to combine last and first names into a single name.
      lname||","||fname
Parent topic: Query Databases


Renaming Fields

If you want to rename the columns that appear in your result, you can create a computed column that contains, as an expression, just the name of the column you want to rename. Type in a new name in the Computed Column Name field. Your result column is automatically renamed. If you do not provide a name, a default (Column 1) is used.

Note:

This option is not supported by DB2 version 3.x and earlier. Therefore, it is not available in DB2 mode.

Parent topic: Query Databases


Finding Distinct Values

You can create a computed column using the DISTINCT keyword to try to find all unique values in a column. When the DISTINCT keyword is used (instead of the default ALL), duplicate values are discarded. For example, querying the EMPLOYEE table enter the formula:

DISTINCT lname

and the computed column and resulting query do not show two rows with the LNAME Hurwood.

Parent topic: Query Databases


Adding Extended Conditions (And and Where)

Some of the conditions on columns that can be added to a query cannot be expressed easily using the Query Conditions Grid. In these cases, you have two alternatives:

  • Edit the SQL statement, in which case you can include any valid condition (including nested SELECTS).
  • Include an extended search condition.

An extended search condition is simply another set of conditions that are appended to the Query Conditions Grid as AND conditions.

To define an extended search condition:

  1. Open a new or existing query.
  2. Click the Where (?) button on the toolbar.

    SQLWizard displays the Search Condition dialog box. You compose a series of extended search conditions at the top of this dialog box, one per row.

  3. On the first row, the first drop-down list contains only the NOT qualifier. You should use this if you want to negate the condition you create on this row.
  4. The next field is used to specify the left-hand side of the expression. Move to this field and type in the expression, or compose it using the tools at the bottom of the dialog box. There are drop-down lists containing functions, as well as operators and column names that are used to build the expression.
  5. The next control is a drop-down list containing comparison operators, including SQL predicates such as BETWEEN and IN. Select an operator from this list.
  6. The next field is used to specify the right-hand side of the expression. Move to this field and complete the expression.
  7. The last control on the row is a button to add another condition row to the dialog box. Click it to add another condition row.
  8. Move to the next row and click the down-arrow button on the first drop-down list. While in the first row, the drop-down list only contains the NOT option, in the second and subsequent rows, this list contains connection operators AND and OR, with or without the NOT qualifier. Choose one of the connection operators.
  9. Complete the expression on this row as you did for the previous row.
  10. When you are finished with the extended search condition, click OK to accept the changes.
  11. Examine the Query Conditions Grid. You will see that a new area labeled AND has been added, showing the conditions that you just defined. If you want to make changes to the conditions, double click the area to redisplay the Search Condition dialog box.

If you want to add conditions that cannot be expressed through the Query Conditions Grid columns or the Search Condition dialog box, switch to the SQL view and edit the SQL statement directly. Note that once you have made changes to the statement in the SQL Edit window, you will not be able to switch back to the Query Design window without discarding the changes. Therefore, you should save your query in the Query Design window before switching to the SQL Edit window, and save it from the SQL Edit window using a different name if you make changes.

Parent topic: Query Databases


Specifying Sort Order

Often you will want to make data easier to understand by presenting it in a particular order. You can sort the result at the time the query is executed by creating an ORDER BY clause for the SELECT statement, or you can sort columns after the result is returned.

The advantages of sorting the query results using an ORDER BY clause are:

  • You can sort on columns that you do not retrieve.
  • Because the sort criteria are stored as part of the query, the query will always be properly sorted each time you run it.

The disadvantages of sorting the result using an ORDER BY clause are:

  • You are asking the database server to do additional work, which may affect the speed of other applications that are trying to use the database server.
  • If you are creating an ad hoc query, and don't know if you need all of the rows of the result, you still need to wait until they are retrieved and sorted before you can see any of the rows of the result.

This topic teaches you how to use SQLWizard's Query Design window to add an ORDER BY clause to your query.

To create an ORDER BY clause on a single column:

  1. Add the column you want to sort on to the Query Conditions Grid. If you do not want to see the column in the result, still add it to the grid, and then double click the title to hide it in the result.
  2. Click the title of the column to select the column.
  3. Click the Sort Column command from the Column menu.
  4. Choose Ascending or Descending from the Sort Column submenu. Ascending means the columns are sorted from 0 to 9 and A to Z (or as appropriate for international versions). Descending means the columns are sorted from 9 to 0 and Z to A (or as appropriate for international versions).
    Note: You can repeat the process above as many times as you like. Each time you add another column, it is appended to the ORDER BY clause. To see or modify all of the columns in the ORDER BY clause, switch to the SQL view, or follow the instructions for creating an ORDER BY clause on multiple columns.

To create an ORDER BY clause on multiple columns:

  1. Add all of the columns that you want to see in the result to the Query Conditions Grid.
  2. If there are columns that you do not want to see in the result, but that you want to use for ordering the result, add them to the Query Conditions Grid as well. For these columns, double click the column name to exclude the column from the columns displayed in the query result.
  3. Click the Sort command from the Query menu or use the Sort button on the toolbar.

    SQLWizard displays the Order By dialog box. This dialog box contains two lists: one containing all of the columns in the Query Conditions Grid, and the other containing the columns that will be included in the ORDER BY clause used to sort the result records. When you display the Order By dialog box for the first time, the list of Sorted columns is empty.

  4. To add a column to the ORDER BY clause, locate the column in the Unsorted Columns list and click it to select it. Then click the > button to move the name from the Unsorted Columns list to the Sorted Columns list. You can remove a column from the Sort Columns list by selecting it and using the < key. The >> button moves all columns in the Unsorted Columns list to the Sorted Columns list, while the << button moves all columns from the Sorted Columns list to the Unsorted Columns list.
  5. Once you have picked the columns you want to use for ordering the result, you can rearrange the order in which they appear in the ORDER BY clause. The first column in the ORDER BY clause is the primary sort column. Each additional column sorts the records in the group defined by the previous column. To move a column up in the list, click it and use the Up or Down buttons.
    Note: The first column in the list is the most significant column. Data is first sorted by this column, and each of the other columns are applied to the sorted rows in turn.
  6. You can also specify whether an ascending or descending sort sequence is to be used in sorting by a particular field. Ascending sorts go from 0-9 and A-Z (or as appropriate for international versions). Descending sort sequences go from 9-0 and Z-A (or as appropriate for international versions). To toggle between Ascending and Descending, click the arrow buttons beside a column name in the Sorted Columns list.

    Ascending Order button
    indicates ascending order.

    Desscending Order button
    indicates descending order.

  7. Once you are satisfied with the Sorted Columns list, click OK to close the dialog box.
  8. Now examine the Query Conditions Grid. You now see a new row labeled ORDER/GROUP, containing numbers and icons. The number indicates the order of the column in the ORDER BY clause, and the
    Ascending Order symbol
    or
    Descending Order symbol
    symbol indicates whether the column is to be sorted in ascending or descending sequence.
  9. You can change the ORDER BY clause by redisplaying the Order By dialog box and modifying the Sorted Columns list as described above. Or you can click the ORDER/GROUP row and change the number and ascending/descending specification.
Parent topic: Query Databases


Retrieving Data From Two or More Tables

In order to create a join, you need to have two or more tables visible in the Table Display Area.

To add more tables to create a join:

  1. From the Query Design window, click the Add Table button on the toolbar or the Add Table command from the Query menu.

    SQLWizard displays the Add Table dialog box.

  2. Click on the table you want to add.
    Note:

    Attempting to run a query involving tables from different locations will generate an error.

  3. Click the Add button to copy the table to the Table Display Area.
  4. Continue to add tables in this way until you have added all of the tables you want to join.
  5. When you are finished adding tables, click the Done button.
    Note:

    There is a limit of 15 tables in a FROM clause when running against XDB Server or DB2. Adding more than this number of tables will generate an error when you attempt to run the query.

    You can create nested SELECT statements that access many more tables than this limit. The limit applies to a single FROM clause.

Parent topic: Query Databases


Displaying Table Names

When you are creating queries involving multiple tables, it is often useful to see the names of the table from which a column comes in the Query Conditions Grid. To add a row containing table names, click the Show Table Names button in the toolbar, or use the Show Table Names item in the Query menu.

Parent topic: Query Databases


Avoiding Cartesian Products

The following method may be used to avoid Cartesian products when you create a join.

  • Usually you should have at least t-1 join conditions for a join between t tables.
  • If there are multi-column primary keys on a referenced table, there should be as many join conditions between the child table and the referenced table as there are columns in the primary key of the referenced table.
  • Turn on the Prohibit Cartesian Products option.
Parent topic: Query Databases


Prohibiting Cartesian Products

If you do not want to rely solely on your own tests for avoiding Cartesian products, you can set an option to prohibit Cartesian products. With this option set, each time you run a query, it is tested to determine whether or not there are join conditions between the tables. If there are no join conditions, an error results.

The test does not determine whether or not the join conditions are logical or correct for your application. However, by blocking Cartesian products in this way, you will reduce the chance that you will forget to put any join conditions on your query.

Note:

This test is only effective for queries run from within the SQLWizard. Queries embedded in host programs or executed from other programs are not affected. You may want to test your queries in SQLWizard before running them in other programs.

Another way to minimize the chance that you will generate a Cartesian product is to make use of SQLWizard's Auto Join facilities.

To prohibit (block) Cartesian products:

  1. From the Query menu, click the Current Query Options command (or, in the Micro Focus Program Group or Folder, click the Options icon).
  2. If using Options to set this item as your default, click the Query tab to access the Query options.
  3. Click the Prohibit Cartesian Products checkbox to select it.
  4. Close the Query Options dialog box (or Options window, as appropriate).

    Now when you run an SQL query in SQLWizard, it will be tested to determine if it might return a Cartesian product.

Parent topic: Query Databases


Manual Joins

When you put more than one table into the Schema View of a prompted query, you should define a join condition. SQLWizard provides several methods for doing this, including Auto Join capabilities.

The following are steps to define a join on your own:

To define a join manually:

  1. Click the New Query button, or click the New command from the File menu followed by the Query command from the submenu.

    SQLWizard displays the Add Table dialog box.

  2. Click the EMPLOYEE and DEPT tables and click the Add button to add them to the query.
  3. Click the Done button to close the Add Table dialog box. When the Query Design window is displayed, you will see both tables side by side in the Table Display Area.
  4. Select some columns from each table by clicking on them. You now have a join, but it is the type of join known as a Cartesian product, which is a combination of all the rows in one table with all of the rows in the other table.

    To prevent the occurrence of a Cartesian product, you need to define a join condition, which relates a column in one table to a column in another table. The EMPLOYEE and DEPT tables are joined on the DEPT field. Scroll through the EMPLOYEE table's Column Selection List until you see the DEPT field. Click it, and drag to the DEPT field in the DEPT table. A line representing the join will appear.

Parent topic: Query Databases


Preventing Cartesian Products with Auto Joins

When you select from more than one table without defining a join condition that maps the rows of one table to the rows of another table, you create a Cartesian product, which is generally an expensive result that includes every combination of records between the tables, and usually has no real meaning.

SQLWizard supports automatic joining of columns in three cases. Note that the third case is not usually a very good method for automatically joining tables. Frequently, there are like column names that have no join relationship with each other. It is recommended that you use the first two options whenever possible, or manually define joins.

To define an automatic join, click the Current Query Options command from the Query menu to display the Query Options dialog box, and check the desired auto join methods. Alternatively, click the Auto Join command from the Query menu to display a submenu of the desired methods. Note that if you change the auto join options after having selected your tables, you are asked if you want to apply the join criteria after the fact.

The three cases on which automatic joins can be performed between the columns of two tables are when:

  • There exists a foreign menu key relationship between two tables.
  • There exists a primary key column in one table, and a column with the same name in another table.
  • There is a column in one table that has a name that matches a column in the other table.
Parent topic: Query Databases


Non-equijoins

An equijoin is the most common kind of join condition. It tests whether the two sides of the condition are equal. A non-equijoin uses a comparison operator other than =. You can test if a column from one table contains values that are >, ?, <, ? or < > values in another column.

To create a non-equijoin condition:

  1. Define a regular equijoin using the auto join facilities, or by dragging from one column to another.
  2. Double click the = operator in the small box on the join line.

    SQLWizard displays the Join Options dialog box.

  3. Select a comparison operator from the drop-down list in the center of the dialog box. The operators that contain a + are for defining outer joins.
  4. Click OK. The new comparison operator appears in the join condition.

    When the Join Options dialog box closes, the new operator appears on the join line between the joined tables.

Parent topic: Query Databases


Outer Joins

Suppose you wanted to display information about all suppliers and the parts they supply. Joining the SUPPLIER and PARTSUPP tables will retrieve this information for every supplier that has provided parts. But you would not see any information for suppliers that have not yet supplied parts. You would have no indication that such a supplier even existed.

An outer join is a special kind of join that solves this problem by finding all of the matches between the joined columns, just like a regular join. However, unlike a regular join, those records in one table that have no match at all in the second table are identified.

An outer join is designated by a plus sign in parentheses on the side of the child table. The parent table is the one for which you want rows even if there are no matching child records in the other table.

To create an outer join condition:

  1. Define a regular equijoin using the auto join facilities, or by dragging from one column to another.
  2. Double click the = operator in the small box on the join line.

    SQLWizard displays the Join Options dialog box.

  3. Select a comparison operator from the drop-down list in the center of the dialog box. Make sure the operator includes the (+) on the child side - that is, on the side where you expect to see null values.
  4. Click OK. The new comparison operator appears in the join condition.
  5. When you run the command you should see some rows with values for the parent table fields, but only null values for the child rows.
    Note:

    Outer joins are not supported against all database systems. For example, outer joins are not supported against XDB Server in DB2 mode, or when running against DB2.

Parent topic: Query Databases


Creating a Summary Query

There may be times when you want to generate rows of data that summarize data in your tables. For example, you may want to find a sum or an average for the values in a column. To do this, you create a computed column that includes aggregate (column) functions.

If a computed column involving an aggregate function is added to a query, the system automatically defines a GROUP BY clause for you. If you want to modify this system-defined GROUP BY clause, or if you want to add a GROUP BY clause for a query that does not require one, use the Group command from the Query menu or the Group button on the toolbar.

To add a column to the GROUP BY clause, move it from the left list box to the right list box using the arrow buttons. To change the relative order of columns within the GROUP BY clause, use the Up and Down buttons.

Note:

When including aggregate functions in queries, SQLWizard requires that non-aggregate columns be grouped. SQLWizard automatically performs this grouping for you, and will not allow you to make illegal moves between boxes. You can, however, change the order of the columns in the GROUP BY list.

Uses for summary queries include:

  • Finding the total number of records in a query.
  • Finding the number of records in a group.
  • Finding the sum of a column for the set of records in a group.
  • Finding the sum of a column for all records in a query.
  • Finding the min or max of a set of values.
  • Finding the min or max for all records in a query.
  • Finding the average for all records in a query.
  • Finding the average of a column for all records in a group.
  • Finding rows that contain duplicate values.
  • Finding rows that contain unique values.
  • Finding rows that match the average, min, or max value in a column.
Parent topic: Query Databases


Searching for Duplicate Values

Before you can create a unique index on a column, you must make certain that there are no duplicate values in the column. An easy way to do this is to use a summary query that groups records based on the index fields, and include a HAVING condition that tests to see if the count of records in any group is greater than 1.

To search for duplicate values:

  1. Open or create a query that includes just the columns on which you want to build a unique index. These are the columns you need to test for duplicates.
  2. Open the Group By dialog box using the Group button on the toolbar or select the Group command from the Query menu.
  3. Move all columns to the Grouped Columns list by clicking the >> button.
  4. The order of the columns in the GROUP BY clause is not important in this particular query. However, it is always a good idea to list the columns in hierarchical order. For example, City should come after State, because each state can contain many cities.
  5. Click the OK button to accept the Group specification.
  6. Click the Having command on the Query menu .
  7. Enter the expression Count(*) > 1, as shown below.
  8. Click OK to accept the Having specifications.
  9. The query is now ready to run or save. When you run the query, you see the list of records that have duplicate values in the candidate index columns.
Parent topic: Query Databases


Creating a Union

A union is a set of SELECT statements pasted together with a UNION clause. The union returns the combined result sets from both queries. You can use SQLWizard to help you build a union .

Note:

SQLWizard allows you to combine up to approximately 33 query results using the UNION operator (the maximum number will depend upon the complexity of your query). You must make certain when writing these queries that the data types of the columns in the SELECT clause match.

To create a union:

  1. Create the first query using the Query Design window.
  2. Create the second query using another Query Design window. Make certain that there is a one-to-one correspondence between the columns in each SELECT clause.
  3. Now switch to SQL view by clicking on the SQL button on the toolbar.
  4. Copy the SELECT statement to the clipboard by selecting it and then clicking the Copy command from the Edit menu.
  5. Click the other Query Design window, and switch it to the SQL view.
  6. Go to the end of the second SELECT statement and type the keyword UNION.
  7. Now paste the query from the clipboard after the UNION keyword to complete the union. You are ready to save or run.
Note:

When you save, you must save from the SQL view because UNION is not supported by the Query Design window. When you save the query, you will be warned that you will lose your prompted SQL changes.

Parent topic: Query Databases


Creating a View

A view is a virtual table that is logically defined over one or more tables. Its definition includes a SELECT statement that determines the fields as well as the values it can contain at any point in time. Views permit you to query subsets of data or joins of multiple tables as though they are an actual table. Only the view definitions are stored - not the data retrieved by the view. Some views can be updated. An update of a view affects the underlying table. Views may make it easier to access data by organizing it in more meaningful ways, or by restricting the rows retrieved to those that pertain to the needs of a particular application. Views can also be used for security reasons, since privileges can be granted on a view instead of on the underlying table.

You can use a SELECT command generated through the Query Design window as the basis of a CREATE VIEW statement.

To create a view from a SELECT statement:

  1. Create a new query or open a saved query. It is a good idea to run the query to see if it was correctly designed, and that it retrieves the rows you expected it would.
  2. Switch to SQL view using the SQL button on the toolbar.
  3. Position the cursor in front of the SELECT clause of your query.
  4. To create a view called TodaysOrders, type the clause CREATE VIEW TodaysOrders AS in front of the SELECT statement.
    Note:

    You cannot create a view using a SELECT statement that contains an ORDER BY or UNION.

    The simplest way to determine whether or not a view is updatable is to try to create it with the WITH CHECK OPTION clause. If the view cannot be updated, an error will occur when you try to create it.

Parent topic: Query Databases


Creating a DELETE Statement

The easiest way to delete individual records is to run a query and switch to ALLOW EDIT mode. However, if you want to perform a batch delete, you can use the WHERE condition generated for a query as the WHERE condition for a DELETE statement.

To convert a SELECT command to a DELETE command:

  1. Create a query that retrieves the rows that you want to delete. You may want to test the query to make certain it retrieves the correct rows. You should also save the query before proceeding if you want to access it again in the Query Design window. You must include at least one column in this query.
  2. Switch to SQL view.
  3. Block the SELECT clause and click the DEL key to delete it.
  4. In place of the SELECT clause, type the keyword DELETE.
  5. Run or save the SQL statement from the SQL Edit window.
Parent topic: Query Databases


Creating an UPDATE Statement

The easiest way to update individual records is to run a query, and switch to ALLOW EDIT mode. However, if you want to perform a batch update, you can use the WHERE condition generated for a query as the WHERE condition for an UPDATE statement.

To convert a SELECT command to an UPDATE statement:

  1. Create a query that retrieves the columns and rows that you want to update. You may want to test the query to make certain it retrieves the correct rows. You should also save the query before proceeding if you want to access it again in the Query Design window.
  2. Switch to SQL view.
  3. Replace the keyword SELECT with the keyword UPDATE.
  4. Enter the name of the table you are updating, and follow it with the keyword SET.
  5. After each of the column names, enter an = and an expression. If you decide you do not want to update the column, delete it from the list.
  6. Run or save the SQL statement from the SQL Edit window.
    Note: You cannot update a join or a query that contains DISTINCT, ORDER BY, GROUP BY, UNION, or Computed Columns.
Parent topic: Query Databases


Creating an INSERT Statement

The easiest way to insert individual records is to run a query, and switch to ALLOW EDIT mode. However, if you want to perform a batch insert, you can use a query as the basis for an INSERT with SELECT statement.

To convert a SELECT statement to an INSERT statement :

  1. Create a query that retrieves the columns and rows from one table that you want to insert in another table. You may want to test the query to make certain it retrieves the correct rows. You should also save the query before proceeding if you want to access it again in the Query Design window.
  2. Switch to SQL view.
  3. In front of the SELECT keyword, enter the keywords INSERT INTO followed by the name of the table into which you want to insert rows.
  4. If the order of the columns in your SELECT clause does not match the order of the target columns in the table you are adding records to, you will have to create a comma-separated list of columns inside of parentheses. This list should be placed immediately after the name of the target table, and before the SELECT clause. You can drag the column names from the Catalog Browser so you don't have to type them.
  5. Run or save the SQL Statement from the SQL Edit window.
    Note: Insert Into is an XDB Server SQL extension. It is not available when running against non-XDB Server databases or when running in DB2 mode.
Parent topic: Query Databases


Work with Query Results

  • Working with Columns Overview
  • Fixing a Column in Place
  • Rearranging Result Columns
  • Hiding Columns
  • Printing a Result
  • Changing the Result View
  • Saving a Result to a File
Parent topic: SQL Wizard


Working with Columns Overview

The Column menu commands are available only if a Result window is active and data is displayed in Result Table view. These commands operate on the currently selected column(s).

To select a column, double click the column name.

Parent topic: Work with Query Results


Fixing a Column in Place

You can lock one or more columns against the left edge of the Result window to use for reference while you horizontally scroll the other columns.

To fix a column in place:

  1. Double click a column name to highlight the column.
  2. Click the Fix command from the Column menu.

    The column will be locked against the left edge of the window (if you selected a non-edge column, it will automatically be moved to the left edge). Note that when you scroll the Result window horizontally, the fixed column remains in place, while the other columns scroll by.

  3. Repeat steps 1 and 2 for each column you want to lock to the left side of the window. The columns will appear in the order in which you fixed them.

To free a fixed column:

  1. Click the Free command in the Column menu.

    The right-most fixed column is released. The scroll bar is readjusted to allow horizontal scrolling of this column.

  2. Repeat step 1 for each column you want to release.
    Note: Fixed columns that had initially occupied a non-edge position in the table are not returned to their original position when they are freed. If you want to return a column to its original position, you may do so by dragging it back into place.
Parent topic: Work with Query Results


Rearranging Result Columns

When you are in the Result Table view, you can rearrange the columns on your Result window by dragging them to a new position. Changes you make to the result by rearranging the columns only affects the current Result window. The next time you run the query, the columns will be in the order designated by the query. You can change the order of columns in the SELECT clause of the query if you want them to always appear in a specific order. Regardless of the order in which columns are shown in a result, the order of columns stored in the database is not changed.

To move columns in a Result Table view:

  1. Click the name of a column and hold down the left mouse button.

    SQLWizard displays a phantom outline the size of the column title.

  2. Keeping the mouse button pressed, drag the outline right or left to a position between two other columns. Release the mouse button to drop the column in the new position.

    SQLWizard rearranges the columns to move the dragged column between the other two columns.

Parent topic: Work with Query Results


Hiding Columns

You may find times when it would be easier to examine your result if you could temporarily exclude one or more columns from the Result window. SQLWizard allows you to do this in two ways.

To temporarily remove a single column from the result table view:

  1. Double click a column name to select the column you want to hide.
  2. Click the Hide Column command from the Column menu. The selected column will be removed from the Result window.
    Note:

    You cannot hide fixed columns. You must free a fixed column before you can hide it.

To temporarily remove or redisplay several columns on a result table view:

  1. Click the Select Hidden Column command on the Column menu to display the Select Hidden Column(s) dialog box.
  2. Move each column name to the desired list. The columns listed in the Displayed Columns list will be displayed on the Result Table when the dialog box is closed; those in the Hidden Columns list will be temporarily removed from the Result table.

    To move a column from one list to the other, click its name to highlight it; then click the appropriate arrow button to move it to the other list. Alternatively, double click a field name to move it to the other list.

    To select multiple contiguous names on a list, hold down the Shift key while clicking on the first and last entry of the desired list of names. To select multiple non-contiguous names, hold down the Ctrl key while clicking on each name you want to select.

    When the selected names are highlighted, click the appropriate arrow button to move the highlighted names to the other list.

  3. When the columns are in the desired lists, click the OK button to return to the Result window.

    When the Result window redisplays, you will be able to scroll to see all of the columns you placed in the Displayed Columns list, but those in the Hidden Columns list will not be shown.

Parent topic: Work with Query Results


Printing a Result

To print the contents of a Result window:

  1. Be sure that the Result window you want to print is the active window.
  2. Click the Print command from the File menu to display the Print dialog box.
  3. Specify your desired print options.
  4. Click OK to send the results to the printer or print queue.
Parent topic: Work with Query Results


Changing the Result View

When you successfully run a query or open a table, SQLWizard displays the results in the view you specify. You specify the desired views in any of the following ways:

  • You can set a default view using the Options utility.
  • You can set a default view for the session using the Current Query Options command from the Query menu.
  • You can select a result view before you run the query, using the Result Table View or Result Form View command on the Query menu.
  • After a Result window is displayed, you can switch between Table and Form views using either the Result Table or Result Form command from the Query menu, or by clicking on the Table View or Form View button on the toolbar.
Parent topic: Work with Query Results


Saving a Result to a File

To output the contents of a Result window to a file rather than to the printer, choose the Output command from the File menu.

To save the contents of a Result window to a file:

  1. Make certain that the Result window you want to save is the active window.
  2. Click the Output command from the File menu to display the Output File (Save As) dialog box.
  3. Specify a file name.
  4. Click OK to save the results to a file.
Parent topic: Work with Query Results


Use the Result Window for Data Entry

  • Enabling Edit Mode
  • Updating Records
  • Inserting New Records
  • Deleting Records
  • Undeleting a Deleted Record
Parent topic: SQL Wizard


Enabling Edit Mode

Because there is additional overhead in preparing a query result for Edit mode, the default is to disable Edit mode when a query is run. If you want to make Edit mode the default for all queries that you run, use the Query Run tab in the Options utility to set Allow Editing on.

Note: Certain query results are not editable. For example, a join cannot be edited. Also, if you are running against a database other than XDB Server, and the Check Unique Key option is enabled, your tables must have a primary key or unique index defined before you will be allowed to enable Edit mode.

To enable Edit mode:

  • To enable Edit mode before you run a query, click the Allow Editing command on the Query menu.
  • To enable Edit mode after you run a query (a Result window is active), click the Allow Editing command on the Record menu.
Parent topic: Use the Result Window for Data Entry


Updating Records

When you are in Edit mode, you can type in changes directly on the Result Table or Result Form. As you make the changes, they will be reflected in the Result window.

You can use the clipboard features of your operating environment to copy data from records and paste it into other applications. When you are in Edit mode you can copy data from one field and paste it into another field in the Result window.

Note: You can only cut, copy, or paste the data from one field at a time. You cannot copy an entire record or set of records to the clipboard.
Note: When cutting, copying, or pasting large amounts of data (such as in a varchar or longvarchar field), it may be faster to open a zoom window instead of working in the cell of the Result window. To open a zoom window, double click the desired field in the Result window, or place your cursor in the field and click Zoom from the View menu.
Parent topic: Use the Result Window for Data Entry


Inserting New Records

SQLWizard allows you to type in the values for a new record by moving to the blank record provided at the end of every Result window or by using Data Entry mode. If you are working with a large result set, and do not want to take the time to move to the end of the result set, you can switch to Data Entry mode, which shows only newly inserted records.

To insert a record in a result window:

  1. Make certain you are in Edit mode by checking the Allow Editing command in the Record menu.
  2. Click the New command from the Record menu. This will move the cursor to a blank record at the end of the result set, marked with an @ symbol.
  3. Begin typing the data for the new record. As you type, a new blank record is appended at the end of the result set, so that you will be ready to insert the next record.
  4. Move out of the current record to insert it into the database.

To insert records in Data Entry mode:

Data Entry mode provides you with a special view of a Result window that only shows newly inserted records. All existing records are temporarily hidden from view.

  1. Make certain that you are in Edit mode by checking the Allow Editing command on the Record menu.
  2. Click the Data Entry command from the Record menu. The Result window will be redisplayed. Initially you will only see a blank record into which you enter data for a new record.
  3. Enter data into the new record. A new blank record will appear at the bottom of the result set.
  4. As you enter the data for each record and move to the next record, the new record is inserted into the database.
Parent topic: Use the Result Window for Data Entry


Deleting Records

You can delete a single record from the Result window. If you want to delete many records at once, you should write an SQL DELETE statement.

To delete a record:

  1. Click the record number in the left column to select the record.
  2. From the Record menu, click the Delete command.
  3. At the confirmation dialog box, click OK to confirm the delete action.
Parent topic: Use the Result Window for Data Entry


Undeleting a Deleted Record

After you delete a record, you can undo the delete operation using the Undo Delete command on the Record menu. The record will be marked undeleted and will reappear in the Result window.

To undo a delete:

  1. Open the Record menu.
  2. Click the Undo Delete command, if it is enabled.

    If the Undo Delete command is not enabled, the record cannot be undeleted from the Result window. If you are working with Autocommit turned off, you may still be able to rollback the operation.

Parent topic: Use the Result Window for Data Entry


Import Files

  • Accessing the Import Utility
  • To import data downloaded from a mainframe
  • To import data from a PC application
  • Choosing a File Format and Source File
  • Choosing an Existing Table to Receive Your Data
  • Creating a New Table to Receive Your Data
  • Saving an Import Specification
  • Opening an Import Specification
  • Clearing Specifications from the Import Window
  • Resolving Import Errors
  • Viewing Your Source File
  • Viewing Your Batch Command File
  • Setting Import Options
  • Setting Import Defaults
  • Constructing a Batch Import File
  • Running a Batch Import File
  • Running Batch Import from the Command Line
Parent topic: SQL Wizard


Accessing the Import Utility

The SQLWizard Import utility is accessed using the New command on the File menu.

To access the Import window:

  1. From the File menu, click the New command.
  2. Click Import from the submenu.

    SQLWizard displays the Import window.

    Notice that the name in the title bar remains untitled until you save the specifications to an import batch file. This is accomplished using the Save As command from the File menu or by exiting the Import window. When you exit the Import window without saving, you are prompted to save the Import file. This will save an import batch file to the path and file name you specify.

Parent topic: Import Files


To import data downloaded from a mainframe

  1. From the main menu, click > Client > SQL Wizard.
  2. Click New on the File menu.
  3. Click Import.
  4. On the Import window, select the type of file from the Format list.
  5. Change the settings as appropriate for the type of file you are importing.
  6. Click Browse to find the file you want to import (or type its location and name and press Enter).

    The data structure appears in the XDB Table Information group.

  7. Make any changes you require to the data types and other table structure information.
  8. Select Create Table if you want to create a new table.
  9. Select Replace Data if the table already exists and you want to replace its data with the imported data.
  10. Click Browse to specify the table's location and name (or type the location and name in the Table field and press Enter).
  11. Click Run on the Import menu.

    A new table is created or an existing table is updated with the imported data.

Parent topic: Import Files


To import data from a PC application

  1. From the main menu, click > Client > SQL Wizard.
  2. Click New on the File menu.
  3. Click Import.
  4. On the Import window, select the type of file from the Format list.
  5. Change the settings as appropriate for the type of file you are importing:
    • Delimited (Free-Format) ASCII Files - fields are delimited by a fixed character, usually a comma or a tab
    • Columnar (Fixed-format) ASCII Files - fields and records have fixed lengths
  6. Click Browse to find the file you want to import (or type its location and name and press Enter).

    The data structure appears in the XDB Table Information group.

  7. Make any changes you require to the data types and other table structure information.
  8. Select Create Table if you want to create a new table.
  9. Select Replace Data if the table already exists and you want to replace its data with the imported data.
  10. Click Browse to specify the table's location and name (or type the location and name in the Table field and press Enter).
  11. Click Run on the Import menu.

    A new table is created or an existing table is updated with the imported data.

Parent topic: Import Files
Related information
Delimited (Free-Format) ASCII Files
Columnar (Fixed-format) ASCII Files


Choosing a File Format and Source File

The first step when importing a file into an XDB Server table is to choose a source file and specify the format of that source file. Some source file formats require you to specify additional parameters. The following steps are required when importing most source file types.

To specify a source file:

  1. Choose a format that reflects the type of file you want to import from the drop-down list.
  2. Specify the format items required for the selected format. As you choose different formats, the requirements displayed in the Source File Information section vary.
  3. Click the Browse button in the Source File Information section to display the Open Import dialog box. Use the List Files Of Type drop-down list to select the type of files to display.
  4. Choose the path and name of a source file. The default path is the application path. Click OK.

    SQLWizard examines the source file, creates a suggested table definition for the table (if not DSNTIAUL) and displays it in the XDB Table Information section of the window.

    Note:

    If importing large files, use the Options command from the Import menu to limit the number of records that will be read to determine the suggested table definition.

  5. At this point, you have two options for the destination of your imported data.
    • You can specify an existing XDB Server table as the destination for your data. In this case, you can choose to overwrite or append the import data.
    • You can create a new table to receive the imported data. You can use the suggested table format or modify the format as desired.
Parent topic: Import Files


Choosing an Existing Table to Receive Your Data

The following steps are required when choosing an existing XDB Server table into which you want to insert the imported data.

To choose a table to receive your imported data:

  1. Specify the file whose contents you want to import.
  2. Click the Browse button in the XDB Table Information section on the Import window.

    SQLWizard displays the Open dialog box.

  3. Choose the desired location, AuthID, and table name of the destination table and click OK.

    The selected location, AuthID, and table name appear in the Table field on the Import window. Also, SQLWizard retrieves the table definition from the system catalog and displays it in the Table Definition Grid at the bottom of the Import window.

    Note:

    Catalog Browser button
    Instead of selecting a destination table as described in steps 2 and 3, click the Table tab in the Catalog Browser dialog box, and drag a table name to the Table field on the Import window.

  4. You can now choose whether to append or replace data. If you wish to replace (overwrite) the data that exists in the selected table, click the Replace Data checkbox. Otherwise, new data from the file will be appended to the existing data in the table.
  5. Click the Run button or click the Run command from the Import menu to import the data.

    The status of the import operation is displayed in the status bar across the bottom of the window. When the import completes, this line indicates that the import is complete and lists the number of records imported.

Parent topic: Import Files


Creating a New Table to Receive Your Data

You can use SQLWizard Import to create a table to hold the data you are importing.

To create a new table to receive your imported data:

  1. Specify the file whose contents you want to import.
  2. Review the suggested table definition and decide if you need to change it. There are two ways to change the table definition:
    • Revise specifications on the Table Definition Grid on the Import window, as explained in Step 3.
    • Use the definition of an existing XDB Server table as a template for creating the new table. To do this, choose an existing table using the Browse button in the XDB Server Table Information section or drag a table from the Catalog Browser dialog box. Then change the name of the table. The Create Table checkbox will automatically be checked. You can make any desired changes to this new table's definition as described in Step 3.
  3. You can modify any of the non-gray fields in the Table Definition Grid. To make a change, click the desired field and change any information. If there are multiple entries for the selected field, a drop-down list appears as shown below. Otherwise, type the desired information.
    Note: If you need to restore the XDB Server-suggested table definition (based on the source file), use the Recalculate command on the Import menu. This command will reread the source file and recalculate a table definition from it.

  4. Run button
    When you have finished entering your specifications, click the Run command on the Import menu or click the Run button on the toolbar.

    The status of the import operation appears in the status bar at the bottom of the window. When the import completes, a completion message appears and the number of imported records is listed.

Parent topic: Import Files


Saving an Import Specification

You save an import specification in the same manner as you would save any file. You can save an import specification before or after you run it.

To save an import specification:

  1. Save button
    Click the Save button on the toolbar, or click the Save or Save As command from the File menu. If you click Save As, or if you click Save and this file has never been saved before, the standard Save dialog box is displayed.
  2. Choose a destination drive and path where you want to store the Batch Import file. Enter or select a file name. The default path is the current Application Path. The default file extension is .imp.
Parent topic: Import Files


Opening an Import Specification

An import specification that has been saved can be opened and reused to save time respecifying the import options.

To open an import specification:

  1. Open button
    Click the Open button on the toolbar or click the Open command from the File menu.

    SQLWizard displays the Open dialog box. If an Import window is active, the List Objects Of Type field shows the *.imp extension and all files with that extension are listed. If an Import window is not active, click the down-arrow button for the List Objects Of Type field to display the drop-down list; select the *.imp extension.

  2. Choose the name of the import file you want to open to display its specifications in the Import window.
    Note:

    Only batch files containing one import transaction can be opened into an Import window. To run a Batch Import file containing more than one transaction, use the Run Batch command from the File menu.

Parent topic: Import Files


Clearing Specifications from the Import Window

After an import process completes, you can clear the contents of the Import window before entering specifications for the next file you want to import.

To clear current import specifications from the Import window, click the Clear Form command from the Import menu. The current specifications are removed from the Import window and are replaced with default settings where appropriate. Defaults are based on your settings in the Import Options dialog box and the Default Settings dialog box

Parent topic: Import Files


Resolving Import Errors

SQLWizard Import allows you to set error handling options on the Import Options dialog box. You can specify the action to be taken when an error is encountered, and you can have Import generate two different kinds of log files.

If you encounter errors, use the Source File command from the View menu to compare the source file against selections made on the Import window. This is most effective with free- and fixed-format ASCII files.

Parent topic: Import Files


Viewing Your Source File

The Import utility allows you to view the contents of your source file. If the file has delimiters, this feature allows you to see what the delimiter characters are. For fixed column files, you can use this feature to check the column lengths and starting positions.

To view the contents of a source file:

  1. Click the Source File command from the View menu.

    SQLWizard displays the Open Source File dialog box.

  2. Choose the source file you want to view.
  3. Click OK.

    The contents of your source file are displayed in a scrollable, sizable window. You can view source files of any format. However, this feature is most effective with ASCII files (see note regarding binary files, below).

    A ruler is provided so that you can quickly assess the column positions in your source file. Use the cursor keys to navigate through the source file contents.

    Note:

    If you are viewing a binary file, you may find that the viewer stops displaying data before it reaches the end of your file. This will occur if your data contains a null character (00 hex), which to the viewer, signals the end of data.

Parent topic: Import Files


Viewing Your Batch Command File

The Import utility allows you to view the current import specifications as they would appear if they were saved to a Batch Import file. You can copy these commands to any text editor. This allows you to use SQLWizard to create any number of Batch Import transactions, and copy/append them in a file in your text editor. Later, you can use SQLWizard to run the series of import transactions as a batch file.

To view import specifications in Batch Import file format:

  1. Enter your import specifications.
  2. Click Batch Import Commands from the View menu.

    The import specifications are displayed in a scrollable and sizable window. Use the cursor keys to navigate through the import specifications. Use the Save As command from the File menu to save the import command as a Batch Import file.

Parent topic: Import Files


Setting Import Options

Options you select on the Import Options dialog box remain in effect for the duration of the current session or until you change them. In this case, a session is defined as an open occurrence of the Import window. You can have multiple Import windows open at the same time and each Import window can be using a different set of values for the options.

Instructions for how to set import options are provided below.

To set import options:

  1. Click the Options command from the Import menu.

    SQLWizard displays the Import Options dialog box.

  2. Click to choose an Insert Mode.
    Note:

    Be aware of the limitations of using Engine Direct Write.

  3. Click to choose an On Error option to control error handling.
  4. For the Recalculate option, choose All or specify the number of records to be examined when SQLWizard suggests a table definition for the file you are importing.
  5. To specify a Commit Interval, click the checkbox in this section and enter a value to indicate how many records should be imported between each commit.
  6. To convert data from one code page to another, select an entry from the ASCII Conversion box. Leave the field set to (None) if no conversion is required.
  7. Click to choose the desired Logging methods. To track overall import errors, select the Errors checkbox and provide a file name. To track bad records and have them inserted in a file, select the Records checkbox and provide a file name.
  8. Click OK.
Parent topic: Import Files


Setting Import Defaults

The Default Settings dialog box allows you to specify your preferred settings for import options. Choosing your own defaults means that each time you open a new Import window, your preferred settings will be in effect automatically. You can revert to SQLWizard's suggested default values at any time by clicking the Defaults button.

Default values can be set for Free-format ASCII, Fixed-format ASCII, and DSNTIAUL formats. In addition, you can set default values for the insert mode, commit interval, existing table append/replace option, and number of records to be read for the recalculate table function.

Instructions for how to set import options are provided below.

To set default parameters for Import:

  1. Click the Defaults command from the Import menu.

    SQLWizard displays the Default Settings dialog box.

  2. Select the desired defaults in each section of the dialog box. To revert to SQLWizard's suggested defaults, click the Defaults button.
  3. Click OK. The new defaults are available the next time you open a new Import window.
Parent topic: Import Files


Constructing a Batch Import File

A Batch Import file may include many transactions to import many files of the same or different types, as necessary. A complete transaction must be defined for each file being imported. Collectively, the batch commands for a given transaction are a set of parameters that describe the source file and the destination table.

Perhaps the easiest way to construct a Batch Import file containing multiple imports is to let SQLWizard create the batch commands for you. For each file you want to include in your Batch Import file, fill in the required information on an Import window. Then use the Save As command from the File menu to save the Batch Import specifications. After you have created these individual Batch Import files, use any text editor to copy and paste all of the batch commands into one file. Add comments as desired.

When constructing a Batch Import file, keep in mind the following:

  • Each transaction in a Batch Import file must begin with a name or label in square brackets to separate each set of batch commands. For example, you might want to enter the name of the table to identify the transaction, such as [EmployeeTable].
  • Each Batch Import command must end with a semicolon (;).
  • You may include spaces and blank lines as needed to improve readability. The spaces and blank lines are ignored by SQLWizard.
  • C-style comments can be used in the specifications. For example: /* comment */.
  • All commands are case-insensitive. You may use any combination of upper and lower case letters (for example, INSERT_MODE is the same as Insert_Mode).

Not all Batch Import commands are required for all file types. For instance, the field and record delimiter (FLD_DELIMITER and REC_DELIMITER, respectively) commands are required only for importing delimited, free-format ASCII files. Likewise, the OFFSETS command is required only for importing from columnar, fixed-format ASCII files.

Parent topic: Import Files


Running a Batch Import File

Saved Batch Import files have a file name extension of *.imp and are typically saved in the current application path. You can specify a different path for your batch file when you save it.

To run a Batch Import session:

  1. From the File menu, click the Run Batch command.
  2. Choose the desired Batch Import file.
  3. Click OK. If you choose an old-format batch file, import will prompt you to convert the file so that SQLWizard can run it.
    Note:

    If you are running under Windows, you can start a batch session by double clicking the .imp file name in the File Manager.

    Commands initiated from the .imp file begin to run in batch mode. If any bad data is found, error messages will be displayed depending on the way you set up your import options. (To set import options, use the Options command from the Import menu.)

    Import processing messages are displayed across the bottom of the SQLWizard window in the status bar.

Parent topic: Import Files


Running Batch Import from the Command Line

In addition to running Batch Import from within SQLWizard, you can run it directly from the development environment's command prompt.

To run an import from the development environment's command prompt, call the xwiz40n program file, and pass it the name of your Batch Import file as shown below:

xwiz40n [-iiniFile] filename.IMP

where:

iniFile | specifies which .ini file Wizard should use when it runs the import. If you do not specify an .ini file, xdb.ini in the working directory is used.
filename | is the name of your Batch Import file. The filename must include the extension .imp in its name (such as imfile.imp). If you do not specify the path to filename, the .imp file must be in the current application path (the application path is specified on the PATHS tab).

The following example shows how a Batch Import file called "iempfile" would be run. In this example, the contents of file emp.ini is used to establish SQLWizard's operating configuration.

xwiz40n -ic:\emp.ini iempfile.imp
Parent topic: Import Files


Export Files

  • Accessing the Export Utility
  • To export data for uploading to a mainframe
  • To export data to a PC application
  • To export DDL commands
  • Choosing a Target File and File Format
  • Specifying the Source Table in Design Mode
  • Specifying the Source Table in SQL Mode
  • Saving an Export Specification
  • Opening Export Specifications
  • Clearing Specifications from the Export Window
  • Resolving Export Errors
  • Viewing Your Target File
  • Viewing Batch Command Files
  • Setting Export Options
  • Setting Export Defaults
  • Constructing a Batch Export File
  • Running a Batch Export Session
  • Running Batch Export From the Command Line
Parent topic: SQL Wizard


Accessing the Export Utility

The SQLWizard Export utility is accessed using the New command on the File menu.

To access the Export window:

  1. From the File menu, click the New command.
  2. Click Export from the submenu.

    SQLWizard displays the Export window.

    When you access the Export window, notice that the name in the title bar remains untitled until you save the specifications to a Batch Export file. This is accomplished using the Save As command from the File menu or by exiting the Export window. If you exit the Export window without saving, you are prompted to save the Export file specification. You can save the specification to a batch import or Batch Export file.

Parent topic: Export Files


To export data for uploading to a mainframe

  1. From the main menu, click > Client > SQL Wizard.
  2. In SQL Wizard, click New > Export on the File menu.
  3. On the Export window, in the Source Table Information group, click Browse to specify the table's location and name (or type the location and name in the Table Name field and press Enter).

    The names of all columns in the table appear in the Included list.

  4. Remove the names of any columns you don't want to export by clicking them in the list and clicking <<.
  5. Optionally, change the order of columns in the table by selecting a column name and clicking Up or Down to change its position in the list.
  6. Optionally, type a condition (in SQL syntax) in the Where Condition field to export a subset of rows in the table. For example: CUST_NO < 12850
  7. In the Target File Information group, select the type of file from the Format list.
  8. Change the settings as appropriate for the type of file you want to create.
  9. Click Browse to specify a location and name for the file you want to create (or type a location and name and press Enter).
  10. Click Run on the Export menu.

    A new file is created containing the data you specified.

Parent topic: Export Files


To export data to a PC application

  1. From the main menu, click > Client > SQL Wizard.
  2. In SQL Wizard, click New > Export on the File menu.
  3. On the Export window, in the Source Table Information group, click Browse to specify the table's location and name (or type the location and name in the Table Name field and press Enter).

    The names of all columns in the table appear in the Included list.

  4. Remove the names of any columns you don't want to export by clicking them in the list and clicking <<.
  5. Optionally, change the order of columns in the table by selecting a column name and clicking Up or Down to change its position in the list.
  6. Optionally, type a condition (in SQL syntax) in the Where Condition field to export a subset of rows in the table. For example: CUST_NO < 12850
  7. In the Target File Information group, select the type of file from the Format list.
  8. Change the settings as appropriate for the type of file you are importing:
    • Delimited (Free-Format) ASCII Files - fields are delimited by a fixed character, usually a comma or a tab
    • Columnar (Fixed-format) ASCII Files - fields and records have fixed lengths
  9. Click Browse to specify a location and name for the file you want to create (or type a location and name and press Enter).
  10. Click Run on the Export menu.

    A new file is created containing the data you have specified.

Parent topic: Export Files
Related information
Delimited (Free-Format) ASCII Files
Columnar (Fixed-format) ASCII Files


To export DDL commands

  1. From the main menu, click > Client > SQL Wizard.
  2. In SQL Wizard, click New > Export on the File menu.
  3. On the Export window, in the Source Table Information group, click Browse to specify the table's location and name (or type the location and name in the Table Name field and press Enter).

    The names of all columns in the table appear in the Included list.

  4. Remove the names of any columns you don't want to export by clicking them in the list and clicking <<.
  5. Optionally, change the order of columns in the table by selecting a column name and clicking Up or Down to change its position in the list.
  6. Optionally, type a condition (in SQL syntax) in the Where Condition field to export a subset of rows in the table. For example: CUST_NO < 12850
  7. In the Target File Information group, select SQL Statements from the Format list.
  8. Check any options you want to include.
  9. Click Browse to specify a location and name for the file you want to create (or type a location and name and press Enter).
  10. Click Run on the Export menu.

    A new file is created containing the DDL corresponding to the options you selected.

Parent topic: Export Files


Choosing a Target File and File Format

The first step in exporting table data to a file is to specify a file to receive the data and the format for that file. Some file formats require you to specify additional parameters. Instructions for defining the Target File are provided below.

To specify a target file to receive data:

  1. Click the Browse button to display the Open Export File dialog box and select an existing file. Alternatively, you can type a path and file name in the File Name field.
  2. Choose a format for the selected target file. Click the down-arrow button from the Format field to display a drop-down list. Notice that as you choose different formats, the requirements displayed in the Target File Information section vary.
  3. Specify the format items required for the selected format.
  4. At this point, you have two options for how to specify the source table from which you will be exporting data. You can use Design mode or SQL mode to specify this information.
    • Export Design mode allows you to select a table to export and specify a WHERE condition to limit the number of records that will be exported. In addition, you can select specific fields to export and change the order of the fields exported. Design mode is the default export display for the Export window unless you change your default to SQL mode using the Defaults command from the Export menu. See Specifying the Source Table in Design ModeSpecifyingtheSourceTableinDesignMode.307 to continue setting up your export specifications.
      Note:

      Export Design button
      Click the Export Design button on the toolbar to switch to Design Mode.

    • Export SQL mode allows you to specify export criteria using an SQL SELECT statement.
      Note:

      Export SQL button
      Click the Export SQL button on the toolbar to switch to SQL Mode.

    Note:

    If you switch from Design mode to SQL mode after specifying table, column, and WHERE clause information, all of these specifications will be shown as an SQL SELECT statement in the SQL Query section of the Export window.

Parent topic: Export Files


Specifying the Source Table in Design Mode

In Design mode, you choose an XDB Server table and the fields you want to include or exclude in the Source Table Information section of the Export window. You can add a WHERE condition to limit the data that will be exported from the table. If you do not specify a WHERE condition, all rows in the table will be exported.

Note: XDB Server indexes are not exported with the table. One exception to this rule is that if the table uses indexes and you export the table specifications and data to SQL Statements format, you can choose to have Export generate the SQL statement to re-create the indexes.

Instructions on how to choose a source table using Design mode are provided below.

To specify source table information and export using Design Mode:

  1. Click the Browse button in the Source Table Information section on the Export window.

    SQLWizard displays the Open dialog box. (Alternatively, you can type a fully qualified table name and skip to Step 3.)

  2. Choose the desired location, AuthID, and table; then click OK.

    The selected table name appears in the Table field as a three-part name. If you have not already entered a destination file name in the Source File Information area at the top of the Export window, a default target file name is entered for you. The default name uses the first eight characters of the table name and the extension for the format that has been specified.

    Note:

    Catalog Browser icon
    From the Catalog Browser dialog box, click the Table tab and drag a table name to the Table field on the Export window.

  3. Choose which columns you want to export by moving them to the Included and Not Included lists as desired. The default is to export all columns.

    To move a column from one list to the other, click its name to highlight it, then click the appropriate arrow button to move it to the other list. Alternatively, double click a column name to move it to the other list.

    To select multiple contiguous items on a list, hold down the Shift key while clicking on the first and last entry of the desired list of items. To select multiple non-contiguous items, hold down the Ctrl key while clicking on each name you want to select. When the selected items are highlighted, click the appropriate arrow button to move the highlighted items to the other list. To move all columns from one list to the other, click the appropriate double-arrow button.

  4. If desired, you can re-arrange the order of the columns. Your exported data can list the columns of information in a different order than the original table.

    To move a column within the Selected list, click its name to highlight it, then click the Up or Down button as desired.

  5. If desired, you can limit the number of records to be exported by specifying a WHERE condition. This allows you to export only those records that meet the condition. If you do not specify a WHERE condition, all rows in the specified XDB Server table will be exported.

    To specify a WHERE condition, type a standard SQL WHERE clause. You do not need to type the word where.

  6. Click the Run command from the Export menu to start the export process.
    Note:

    Run button
    Click the Run button on the toolbar to start the export process.

    SQLWizard displays the progress of the export operation in the status bar. When the export is complete, the status bar reports the number of records exported.

Parent topic: Export Files


Specifying the Source Table in SQL Mode

When in SQL mode, the Export window permits direct entry of an SQL SELECT statement in the Query area to specify the table and columns to be exported. You can include a WHERE condition to limit the number of records that are selected for export.

Note:

SQL Mode button
Click the SQL Mode button on the toolbar to change from Design Mode to SQL Mode.

If you enter table, column, or WHERE condition information while in Design Mode, and then switch to SQL Mode, the SELECT statement will be generated for you. You can modify it as desired and export the table, or copy the SQL statement to a text editor.

Likewise, you can copy an SQL statement from the SQL Edit window or your text editor and paste it into the Query field on the Export window.

Note:

If you modify the SELECT statement in certain ways (add a JOIN, for example) you will not be able to switch to Design Mode.

Instructions on how to choose a source table using SQL mode are provided below.

To specify and export a source table using SQL mode:

  1. Click in the Query display area of the Export window to position your cursor in the text entry box.
  2. Type an SQL SELECT statement. Enter a WHERE clause if desired. Alternatively, you can copy a select statement from another SQLWizard window or from a text editor, and paste it into the Query display area of the Export window.
  3. Click the Run command from the Export menu.
    Note:

    Run button
    Click the Run button on the toolbar to start the export process.

    SQLWizard displays the progress of the export operation in the status bar. When the export is complete, the status bar reports the number of records exported.

Parent topic: Export Files


Saving an Export Specification

You save an export specification in the same manner as you would save any file. You can save the export specification before or after you run it.

To save an export specification:

  1. Select the Save or Save As command from the File menu.
    Note:

    Save button
    Click the Save button on the toolbar.

    If you select the Save As command, or if save and this file has never been saved before, SQLWizard displays the standard Save As dialog box.

  2. Choose a destination drive and path, and enter or select a name for the export specification. The default paths are the current application path. The default file extension is .exp.
Parent topic: Export Files


Opening Export Specifications

You can retrieve an Export specification that you previously saved with SQLWizard, and display it in an Export window.

To open an export specification:

  1. Click the Open command from the File menu.
    Note:

    Open button
    Click the Open button on the toolbar.

    SQLWizard displays the Open dialog box. If an Export window is active, the List Objects Of Type field shows the *.exp extension and all files with that extension are listed. If an Export window is not active, you may need to click the List Files Of Type drop-down menu to select the *.exp extension.

  2. Choose the name of the export file you want to open. Once selected, the specifications will display in the Export window.
    Note:

    Only batch files containing one export transaction can be opened into an Export window. To run a Batch Export file containing more than one transaction, use the Run Batch command from the File menu.

Parent topic: Export Files


Clearing Specifications from the Export Window

After completing an export process, you can clear the contents of the Export window before entering specifications for the next table you want to export.

To clear current export specifications from the Export window, click the Clear Form command from the Export menu. The current specifications are removed from the Export window and are replaced with default settings where appropriate. Defaults are based on your settings in the Export Options dialog box and the Default Settings dialog box.

Parent topic: Export Files


Resolving Export Errors

SQLWizard Export allows you to set error handling options on the Export Options dialog box. You can specify the action to be taken when an error is encountered, and you can have Export generate a log file.

If you encounter errors , use the Target File command from the View menu to compare the file containing the exported data against selections made on the Export window. This is most effective with free- and fixed-format ASCII files.

Parent topic: Export Files


Viewing Your Target File

After you export a table, you can view the contents of the target file.

To view the contents of a target file:

  1. Click the Target File command from the View menu.

    SQLWizard displays the File Open dialog box.

  2. Choose the target file you want to view.
  3. Click OK.

    SQLWizard displays the contents of your target file in a scrollable and sizable window. You can view target files of any format. A ruler is provided so that you can quickly assess information about your target file.

Parent topic: Export Files


Viewing Batch Command Files

The Export utility allows you to view the current export specifications as that would appear if they were saved to a Batch Export file.

Likewise, you can view the Batch Import commands that would be generated from the information currently appearing on the Export window. This is the SQL that would be saved if you use the Save or Save As command and saved the file as an Import (*.IMP) file.

Generating a batch import file at the time you are exporting data can help you when you plan to import the data onto another XDB Server. You would take the exported data file and the corresponding batch import file to the other XDB Server. Then use batch import on that machine to transfer the data onto that XDB Server.

To view export specifications in batch file formats:

  1. Enter specifications on the Export window.
  2. Click Batch Export Commands from the View menu to display the Batch Export form of the specifications in a scrollable, sizable window.
  3. Click Batch Import Commands from the View menu to display the batch import form of the specifications.
  4. If you plan to reuse this specification, click the Save As command from the File menu to save the batch file.
Parent topic: Export Files


Setting Export Options

Options you select on the Export Options dialog box remain in effect for the duration of the current session or until you change them. In this case, a session is defined as an open occurrence of an Export window. You can have multiple Export windows open at the same time, and each Export window can be using a different set of values for the options.

Instructions for how to set export options are provided below.

To set export options:

  1. Click the Options command from the Export menu.

    SQLWizard displays the Export Options dialog box.

  2. Click to choose an On Error option to control error handling.
  3. To convert data from one code page to another, select an entry from the ASCII Conversion box. Leave the field set to (None) if no conversion is required.
  4. If you want to log errors that may be encountered during an export process, click the On checkbox in the Error Logging section and type a fully qualified file name. To choose an existing file for logging errors, click the Browse button to display the File Open dialog box.
  5. Click OK to save your preferences.
Parent topic: Export Files


Setting Export Defaults

The Default Settings dialog box allows you to specify your preferred settings for exporting to Free ASCII, Fixed ASCII, and DSNTIAUL formats. In addition, you can specify which view of the Export window you would rather use: Design Mode or SQL Mode. Choosing your own defaults means that each time you open a new Export window, your preferred settings will be in effect automatically. You can revert to XDB Server's suggested default values at any time by clicking the Defaults button.

Instructions for how to set export defaults are provided below.

To set default format parameters for Export:

  1. Click the Defaults command from the Export menu.

    SQLWizard displays the Default Settings dialog box.

  2. Type your own defaults to use for each format.
  3. Click OK to save your defaults. These defaults will be used each time you open a new Export window.
Parent topic: Export Files


Constructing a Batch Export File

A Batch Export command file can include many transactions to export many tables of the same or different types. A complete transaction must be defined for each table being exported. Collectively, the batch commands for a given transaction are composed of a set of parameters that describe the source table and the destination file.

Perhaps the easiest way to construct a Batch Export file containing multiple exports is to let SQLWizard create the batch commands for you. For each file you want to include in your Batch Export file, fill in the required information on an Export window. Then use the Save As command from the File menu to save the Batch Export specifications. After you have created these individual Batch Export files, use any text editor to copy and paste all of the batch commands into one file. Add comments as desired.

When construction a Batch Export file, keep in mind the following:

  • Each transaction in a Batch Export file must begin with a name or label in square brackets to separate each set of batch commands. For example, you might want to enter the name of the table to identify the transaction, such as [EmployeeTable].
  • Each Batch Export command must end with a semicolon ( ; ).
  • You may include spaces and blank lines as needed to improve readability. The spaces and blank lines are ignored by SQLWizard.
  • C-style comments (/*  comment  */) can be used in the specifications.
  • All commands are case-insensitive. You may use any combination of upper and lower case letters. (For example, FORMAT= FIXASC; is the same as Format = FIXasc.)

Not all commands are required for all file types. For instance, the FLD_DELIMITER and REC_DELIMITER commands are required only for exporting to free-format ASCII files. The SPACE command is required only for fixed-format ASCII files.

Parent topic: Export Files


Running a Batch Export Session

Saved Batch Export files have a file name extension of .exp and are typically saved in the current application path. You can specify a different path for your batch file when you save it.

To run the Batch Export session:

  1. Click the Run Batch command from the File menu.
  2. Choose the desired Batch Export file.
  3. Click OK. If you choose an old-format batch file, Export will prompt you to convert the file so that SQLWizard can run it.
    Note:

    If you are running under Windows, you can start a batch session by double clicking the .exp file in the File Manager.

Commands initiated from the .exp file begin to run in batch mode. If any bad data is found, error messages will be displayed depending on the way you set up your Export Options. (To set Export options, use the Options command from the Export menu.)

Export processing messages are displayed across the bottom of the SQLWizard window in the status bar.

Parent topic: Export Files


Running Batch Export From the Command Line

In addition to running Batch Export from within SQLWizard, you can run it directly from the development environment's command prompt.

To run an export from the development environment's command prompt, call the xwiz40n program file, and pass it the name of your Batch Export file as shown below:

xwiz40n [-iiniFile] filename.EXP

where:

iniFile | specifies which .ini file Wizard should use when it runs the export. If you don't specify an .ini file, xdb.ini in the working directory is used.
filename | is the name of your Batch Export file. The filename must include the extension exp in its name (for example, xfile.exp). If you do not specify the path to filename, the .exp file must be in the current application path (the application path is specified on the PATHS tab.

In following example, a Batch Export file called "xempfile" would be run. In this example, the contents of file emp.ini is used to establish SQLWizard's operating configuration.

xwiz40n -ic:\xdb\emp.ini xempfile.exp
Parent topic: Export Files


Use Batch SQL Scripts

  • Creating a Script File
  • Saving and Reusing a Script
  • Running a Script
  • Running in Step Mode
  • Running From the Command Line
  • Using Host Variables
  • Changing Host Variable Values
Parent topic: SQL Wizard


Creating a Script File

A script file is generally created by saving SQL statements from the SQL Edit window. For example, you can create a script by performing a query, then switch to the Edit window to incorporate additional SQL commands. You can also incorporate any of the special batch SQL commands, which functionality specific to batch operation.

SQLWizard's Export facility provides another way to create a script file. When you export data from XDB Server, you can optionally include SQL statements with it. This process creates a script file that, when run, automatically recreates the table from the exported data.

If you prefer, you can create a script by typing your SQL statements directly into a file using any ASCII text editor. Regardless of how you create your script file, the following script-file syntax must be observed:

  • Commands can be placed on separate lines terminated by a semicolon (;) or on the same line terminated by a semicolon (;).
  • Commands may be typed in upper or lower case.
  • Spaces and blank lines can be included to improve readability. Spaces and blank lines are ignored by SQLWizard.
  • Spaces are not required before and after an equal sign ( = ), however they can be included to improve readability.
  • Comments can be inserted by bracketing them in comment characters (e.g., /*comment text */), or by prefixing them with two hyphens.

    Both comment types are shown below.

      /* Get customer list with company & state   */
  /* List customers with balance over $2,000. */
  SELECT company, state, balance  --retrieve columns
  FROM customer             --from customer table
  WHERE balance>$2,000;        --show records with
  --balance over $2000
Parent topic: Use Batch SQL Scripts


Saving and Reusing a Script

You can save the contents of an SQL Edit window to a .SQL file and retrieve it later to edit or run.

To save an SQL script from an active SQL Edit window:

  1. From the File menu, click the Save As command.

    SQLWizard displays the Save As dialog box.

  2. Choose SQL Scripts (*.SQL) from the list of Object Types.
  3. Provide a name for the file.
  4. Click OK to save the file.

To open an SQL script from an active SQL Edit window:

  1. From the File menu, click the Open command.
  2. Choose SQL Scripts (*.SQL) from the list of Object Types.
  3. Locate and select the file you want to open; then click OK.

    The script is opened in an SQL Edit window.

  4. Edit the file adding and deleting the necessary SQL commands. You can also incorporate batch commands.
Parent topic: Use Batch SQL Scripts


Running a Script

You can run a batch script from within SQLWizard, with or without opening the script file in an SQL Edit window. You can also execute a script without opening SQLWizard, by calling the file from your development environment's command prompt.

To run a batch SQL script from an active SQL Edit window:

  1. From the File menu, click the Run Batch command.
  2. When the Run Batch dialog box appears, select the .SQL script file you want to run.
  3. Click OK. The batch SQL script is loaded and immediately begins to execute.

    After execution, a message box is displayed telling you that you will not be able to edit the contents of the selected batch SQL script in the current SQL Edit window. To edit the script, reopen it in a separate SQL Edit window.

  4. Click Continue.

    The results are displayed in the Result window.

Parent topic: Use Batch SQL Scripts


Running in Step Mode

Use "step mode" to execute your batch SQL script one SQL command at a time.

To use the Step Mode feature:

  1. From the Query menu, click the Current Query Options command.

    SQLWizard displays the Query Options dialog box.

  2. Select the All Commands option in the Execute group box. This option ensures that the entire script is executed at run time.
  3. Click OK.
  4. From the Query menu, click Step Mode.
  5. Follow the steps described in Running a Script to run your batch SQL script.

    SQLWizard steps through the script one SQL command at a time, and displays the results of each command in a separate Result window.

Parent topic: Use Batch SQL Scripts


Running From the Command Line

In addition to running a SQL script from SQLWizard, you can run it directly from your development environment's command prompt.

Note: You can run a script file by double clicking the SQL file name in the Windows File Manager.

To run a script from the development environment's command prompt, call the xwiz40n program file, and pass it the name of your script file as shown below:

xwiz40n [-iiniFile] filename.SQL

where:

iniFile | is the initialization file that SQLWizard uses when it runs the script. If you don't specify an initialization file, XDB.INI in the working directory is used.
filename | is the name of your SQL script file. If you do not specify the path to filename the script file must be in the current application path (the application path is specified on the Paths tab. Note: The filename must include the extension "SQL" in its name (for example, sfile.sql).

The following example shows how a script called "newmember" would be called. In this example, the contents of file member.ini will establish SQLWizard's operating configuration.

xwiz40n -ic:\member.ini newmember.sql
Parent topic: Use Batch SQL Scripts


Using Host Variables

When you include host variables in batch SQL scripts, you are prompted for values. You can also specify values for host variables by using the Parameters command from the Query menu so that you will not be prompted at run time for values.

To run a batch SQL script that uses host variables:

  1. Select the Run Batch command from the File menu.

    SQLWizard displays the Run Batch dialog box.

  2. Choose the .SQL file you want to run; then click OK.

    The selected batch SQL script is loaded and it begins to execute.

  3. When prompted for host variables, type in the value.
  4. Click the Quotes checkbox if the value needs to be enclosed in quotes.

    Results of the batch SQL script are displayed in the Result window.

Parent topic: Use Batch SQL Scripts


Changing Host Variable Values

After a query containing host variables has run (you have entered values for the host variables when prompted), the host variable values are saved. This allows you to re-run the query without being prompted each time.

It you need to change the values of the host variables, use the Parameters command from the Query menu. You can also use this command to preset the values for the host variables so that you are not prompted at run time.

To change or preset host variable values:

  1. From the Query menu, click the Parameters command.

    The Enter Host Variable Values dialog box is displayed containing all of the host variables for the current query, if previously run or previously specified.

  2. Make changes as needed.
  3. Click OK.
Parent topic: Use Batch SQL Scripts


Administer XDB Users and Groups

  • Adding Users to the System
  • Deleting an AuthID
  • Updating an Existing User Specification
  • Adding a New Group and Assigning Users
  • Deleting a Group
  • Updating Your Group Information
  • Adding Priorities
  • Deleting Priorities
  • Updating Priorities
Parent topic: SQL Wizard


Adding Users to the System

Add button
The Add button on the Add/Modify User dialog box allows you to add a new AuthID and its associated specification into the appropriate XDB Server system tables using the information currently displayed on the dialog box. Once information for a user has been inserted, it remains on the dialog box. You can type another new AuthID (using the previous AuthID's information as a template) to add more users.

When connecting to an XDB Server, the AuthID is checked against values in XDB Server System tables on the XDBACF database in the SYSTEM location to determine if there are any SecondaryIDs or groups associated with it. All available groups are displayed in a scrollable list. Groups to which a particular AuthID is assigned (if any) are highlighted.

Instructions for adding new users to an XDB Server's list of AuthIDs are provided below. See the description of the Add/Modify User dialog box for information about each item on that dialog box.

To add a new AuthID and privileges for a new user:

  1. Click the Users command from the Admin menu to display the Add/Modify User dialog box.
  2. Type a new AuthID in the User ID field or click the User ID drop-down arrow and select an existing user. You can use an existing user's specifications for a new user by typing a new AuthID over the old one.
  3. In the Security Options group:
    • Select Password Required if this user will be required to enter a password when connecting to the XDB Server.
    • Select Access Authority to enable this user to access the XDB Server. You can temporarily disable an existing AuthID by deselecting the Access Authority box, leaving all other AuthID information intact.
  4. If you checked Password Required, type a Password according to the required Enforcement Level setting at the bottom of the dialog box. Retype the same password in the Verification field. Be sure to tell the user the password you have assigned, and explain how the user can change it.
  5. In the User Types section, click User or Super User. A super user has special system-wide privileges as explained in the description of the Add/Modify User dialog box. Super-user status is usually reserved for XDB Server Administrators and their assistants.
  6. Specify optional items: Comments, Groups, and Priorities.

    If desired, type a comment in the User Comments field.

    If you have created groups, they will be displayed in the Group Membership list. Assign the user to one or more groups by clicking on the desired group name(s). (You can also assign users to groups when you create the groups.

    If you have created priorities, they will be displayed in the Priorities list. Assign the user to one or more priorities by clicking on the desired priority name(s).

    Note: To select multiple, contiguous names on a list, hold down Shift while clicking on the first and last entry of the desired list of names. To select multiple non-contiguous names, hold down Ctrl while clicking on each name you want to select.
  7. Click the Add button to insert this user's information to SQLWizard security tables.
  8. Add, delete or update other users if desired. When done, click the Close button to exit the Add/Modify User dialog box.
Parent topic: Administer XDB Users and Groups


Deleting an AuthID

Delete button
The Delete button allows you to remove an AuthID from the system based on the AuthID displayed. Confirmation is required before an AuthID is removed.

Note: You can temporarily deny a user's access to the system without deleting the AuthID or changing any specifications. To deny access, de-select the Access Authority checkbox, then click the Update button.

Instructions for deleting AuthIDs from an XDB Server's list of AuthIDs are provided below. See the description of the Add/Modify User dialog box for information about each item on that dialog box.

To delete an AuthID:

  1. Click the Users command from the Admin menu to display the Add/Modify User dialog box.
  2. Use the User Name drop-down list to choose the AuthID to be removed.
  3. Click the Delete button. SQLWizard prompts you to confirm the removal of the selected AuthID.
  4. Add, delete, or update other users if desired. When done, click the Close button to exit the Add/Modify User dialog box.
Parent topic: Administer XDB Users and Groups


Updating an Existing User Specification

U button
The Update button changes information for an existing AuthID. Any modifications you make for an AuthID on the Add/Modify User dialog box are not saved to the system tables until you click the Update button.

Instructions for modifying AuthID specifications are provided below. See the description of the Add/Modify User dialog box for information about each item on that dialog box.

To update modified specifications for an existing AuthID:

  1. Click the Users command from the Admin menu to display the Add/Modify User dialog box.
  2. Use the User Name drop-down list to choose the AuthID to be changed.
  3. Modify the desired specifications for the selected AuthID.
  4. Click the Update button to save your changes to the XDB Server security database.
  5. Add, delete or update other users if desired. When done, click the Close button to exit the Add/Modify User dialog box.
Parent topic: Administer XDB Users and Groups


Adding a New Group and Assigning Users

Add button
Groups provide a method for controlling location, database, and table level access according to GroupID (GROUP NAME). Users with certain system needs can be given the required access by being in a group that has been granted privileges. When you grant an authority or privilege to a GroupID (using the SQL GRANT command), all users who are members of that group will have the privilege assigned to the group.

Instructions for how to create a new group and assign users to it are provided below. (If a group already exists, you also have the option to assign users to the group by using the Add/Modify User dialog box.

To add a new group and assign users:

  1. Click the Groups command from the Admin menu to display the Groups dialog box.
  2. Type a name in the Group Name (GroupID) field. The GroupID can be up to eight characters long and must follow the rules for a short identifier.
  3. If desired, type a comment about the new GroupID or its purpose in the Comments field. You can enter up to 254 characters.
  4. While you are still viewing the Groups dialog box, you can assign users to the group you are now creating by moving their AuthIDs from the User ID list to the Member Of list. AuthIDs remaining on the User ID list will not be members of the group. You can also assign a user to a group from the Add/Modify User dialog box.

    To move an AuthID from one list to the other, click its name to highlight it and then click the appropriate arrow button to move it to the other list. Alternatively, double click an AuthID to move it to the other list. Use a double-arrow button to move all AuthIDs to the other list.

    To select multiple contiguous names on a list, hold down Shift while clicking on the first and last entry of the desired list of names. To select multiple non-contiguous names, hold down Ctrl while clicking on each name you want to select. When the selected AuthIDs are highlighted, click the appropriate arrow button to move the highlighted AuthIDs to the other list.

  5. Click the Add button to create the group and its assigned members.
  6. Add, delete, or update other groups if desired. When done, click the Close button to exit the Groups dialog box.
Parent topic: Administer XDB Users and Groups


Deleting a Group

Delete button
When you delete a GroupID, all privileges associated with that group are deleted and all members of the deleted group are dissociated from that group.

Instructions for how to delete a group are provided below. See the description of the Groups dialog box for information about each item on that dialog box.

To delete a group:

  1. Click the Groups command from the Admin menu to display the Groups dialog box.
  2. Click the Group Name drop-down list to select the GroupID you want to delete.
  3. Click the Delete button. You are prompted to confirm deletion of the selected group.
  4. Add, delete, or update other groups if desired. When done, click the Close button to exit the Groups dialog box.
Parent topic: Administer XDB Users and Groups


Updating Your Group Information

Update button
There are two items of information you can change in a group definition. You can modify the comment that describes the group or its purpose and you can change the list of users who are members of the group. (Another way to change group membership is by accessing an AuthID using the Add/Modify User dialog box.

Instructions for how to change items in a group definition are provided below. See the description of the Groups dialog box for information about each item on the that dialog box.

To modify an existing GroupID's comment and/or membership:

  1. Click the Groups command from the Admin menu to display the Groups dialog box.
  2. Click the Group Name drop-down list to select the GroupID you want to change.
  3. Change the comment or memberships as desired.
  4. Click the Update button. A message box is displayed giving you a summary of the modifications you made.
  5. Add, delete, or update other groups if desired. When done, click the Close button to exit the Groups dialog box.
Parent topic: Administer XDB Users and Groups


Adding Priorities

Add button
Instructions for defining a new priority are provided below. See the description of the Define Priority dialog box for information about each item on that dialog box.

To add a new set of priorities:

  1. Click the Priorities command from the Admin menu to display the Define Priority dialog box.
  2. Click in the Priority Name field and type a name for the new priority set. (Click the Priority Name drop-down list to view the names of existing priorities.)
  3. Click in each field on the dialog and type the desired setting. (You can use Tab to move from field to field.
  4. Click the Add button to add the new priority and its specifications.

    As soon as a priority is defined, it can be assigned to an AuthID (use the Users command from the Admin menu.). However, it will not take effect until the XDB Server has been shut down and restarted.

  5. Add, delete or update other priorities if desired. When done, click the Close button to exit the Define Priority dialog box.
Parent topic: Administer XDB Users and Groups


Deleting Priorities

Delete button
When you delete a priority, all users who were assigned that priority are no longer restricted by any Governor limitations.

Instructions for deleting a priority are provided below. See the description of the Define Priority dialog box for information about each item on that dialog box.

To remove a priority from the system:

  1. Click the Priorities command from the Admin menu to display the Define Priority dialog box.
  2. Click the Priority Name drop-down list and select the priority you want to drop.
  3. Click the Delete button. A message box is displayed asking you to confirm deleting the currently displayed Priority.
  4. Add, delete or update other priorities if desired. When done, click the Close button to exit the Define Priority dialog box.
Parent topic: Administer XDB Users and Groups


Updating Priorities

Update button
You can change any of the fields on the Define Priority dialog box, and update the system tables to reflect the new restrictions. Any user who has been assigned that priority will be under the new restrictions the next time the XDB Server is shut down and restarted.

Instructions for updating a priority are provided below. See the description of the Define Priority dialog box for information about each item on that dialog box.

To change an existing priority:

  1. Click the Priorities command from the Admin menu to display the Define Priority dialog box.
  2. Click the Priority Name drop-down list and select the priority you want to change.
  3. Click in each field on the dialog that you want to change and type the desired setting. (You can use Tab to move from field to field.)
  4. Click the Update button. A message box is displayed stating that the priority has been updated.
  5. Add, delete, or update other priorities if desired. When done, click the Close button to exit the Define Priority dialog box.
Parent topic: Administer XDB Users and Groups


Implement Security and Authority

  • Setting Up Security
Parent topic: SQL Wizard


Setting Up Security

The following is an overview of the process used to set up and activate security on an XDB Server. This procedure must be performed by someone with super-user authority.

Note: The following procedure assumes a single-server environment. If you are working in a multi-server environment or you are using a "global" security server, see your SQL Option Server Administration Guide for additional setup procedures.
  1. From the main menu, click > Configuration > Server Configuration.
  2. From the XDB Server or from any client workstation attached to the XDB Server, use Options to select the XDB Server, specify your super-user ID, and enable security. Set the options as follows:
    • On the Connect tab, select the XDB Server on which you want to set up security.
    • On the Connect tab, specify your super-user ID (e.g., INSTALL).
    • On the Security tab, enable the Client Security option.
  3. Use SQLWizard to create a "user ID" and password for each user of this XDB Server. Only the users that you define during this step will be allowed to log on to the Server, and they must present the proper user ID/password combination when they do so.
    Note: Apart from permitting access to an XDB Server, the user ID you create in this step 2 also serves as a user's default AuthID. You can override this default assignment by assigning a Secondary ID to the user, or the user can change it using the SET CURRENT SQLID command.

    When you create a user ID, you must also specify whether that user will have user or super user privileges. A super user can access any table on the Server and can perform operations such as creating and dropping locations. An XDB Server is shipped with one super user called INSTALL. You can create others at your discretion. However, super-user privileges should be limited to a few trusted users with database administration expertise. There are other classes of privileges you can assign to other users using the GRANT command. For details, see your SQL Option Server Administration Guide and topics for the GRANT command.

  4. When you are finished creating users, run the Options utility at each user's workstation and turn on the Client Security option. You must also inform your users of the user ID and password you assigned to them in step 3. Once they log on, they can change their password using SQLWizard's Change Password command.
Parent topic: Implement Security and Authority


SQL Option Server Administration

  • To start the XDB Service Controller
  • To start the XDB Server Configuration Utility
  • To start the XDB Server
  • To start the XDB Server in blue screen mode
  • To stop the XDB Server
Parent topic: How to...


To start the XDB Service Controller

  • From the main menu, click > Server > XDB Server Control.
Parent topic: SQL Option Server Administration


To start the XDB Server Configuration Utility

Do one of the following:

  • From the main menu, click > Configuration > Server Configuration.
  • From the XDB Service Controller, click Configure.
Parent topic: SQL Option Server Administration
Related information
To start the XDB Service Controller


To start the XDB Server

  1. From the main menu, click > Servers > Server Control.
  2. Click Start.
  3. Once started, click Close.
Parent topic: SQL Option Server Administration
Related information
To start the XDB Service Controller
To shut down the XDB Server
To log on to an XDB Server
To log off an XDB Server


To start the XDB Server in blue screen mode

  • From the main menu, click > Server > XDB Server Monitor.
Parent topic: SQL Option Server Administration


To stop the XDB Server

  1. From the main menu, click > Servers > Server Control.
  2. Click Stop.
  3. Once stopped, click Close.
Parent topic: SQL Option Server Administration
Related information
To start the XDB Service Controller
To start the XDB Server
To log on to an XDB Server
To log off an XDB Server


Reference

  • SQL Reference
  • XDB Directive Options
  • Batch SQL Commands
  • Batch Import Commands
  • Batch Export Commands
  • SQL Option for DB2 Error Messages
  • User Interface Reference
Parent topic: SQL Option for DB2


SQL Reference

  • Overview
  • SQL Commands
  • Syntax Notation
  • DB2 Support
  • SQL Statements
  • Clauses
  • Functions Overview
  • System Table Overview
  • Overview of XDB Server Specifications
  • XDB Server Reserved Words
  • SQL Communications Area (SQLCA)
  • SQL Descriptor Area (SQLDA)
  • SQL Option Server TUTORIAL Location
  • Objects Used by the SQL Option Server
Parent topic: Reference


Overview

In the relational model, data are logically presented in two dimensional tables made up of rows and columns, as shown in the figure below. The intersection of a row and a column is known as a field. Fields contain individual data items called field values. The rows of a table, also known as records, are made up of a sequence of values that describes an occurrence of an entity (for example, a set of values that describes a particular employee). The columns of a table consist of a collection of attributes, which are characteristics of an entity. For example, each employee has an employee ID and a name.

When creating database objects, you must follow certain conventions. For example, every table must have a unique name, and within a table, every column must have a unique column name and a data type. When you ask the XDB Server to retrieve or modify data, it performs the job on the set of rows and columns you specify. An action may affect rows, columns or fields.

Colums and Rows

There exists no universally accepted standard for database terminology. Throughout this reference and other XDB Server documentation, we use a number of relational terms that have specific meanings that may differ from normal usage.

  • Database
  • Data Objects
  • Language Elements
  • Naming Conventions
  • Three-Part Names
  • Code Page Support
  • Data Types
  • Other Data Types
  • Assignment And Comparison
  • Constants
  • Special Registers
  • Labeled Duration
Parent topic: SQL Reference


Database

The use of the term database varies widely in the industry. The term database, as used in XDB Server documentation, has two meanings:

  • Relational Database

    In the generic sense, a database is an entire collection of data managed by a database management system. It is in this sense that the term database is used most often in XDB Server documentation.

  • XDB Server Database

    In a more specialized sense, a database is a named object created using the CREATE DATABASE command. A database consists of a collection of tables or a collection of table spaces and index spaces. Generally, if used in this sense, the term database is followed by the database name (if it is not clear from the context that an XDB Server database object is being discussed).

Parent topic: Overview


Data Objects

Most of the following terms are named data elements or objects that together allow you to organize data to best suit your needs. Both simple data models and complex systems that mirror mainframe configurations can be constructed with the building blocks provided. Except for records (rows), all database objects are created using one of the forms of the CREATE statement.

  • Alias
  • AuthID
  • Catalog
  • Column
  • Database
  • Index
  • Index Space
  • Key
  • Location
  • Query
  • Record
  • Storage Group
  • Synonym
  • Table
  • Table Space
  • View
Parent topic: Overview


Alias

An alias is an alternate one-part name for the three-part name of a table or view. An alias can be assigned to a table in the current location or in a remote location. This differs from a synonym, which can rename an object only in the current location. Aliases can be used by anyone, while synonyms can only be used by the AuthID that created them.

For example, the one-part name, EMPLOYEE, can be created as an alias for the three-part name, TUTORIAL.TUTORIAL.EMPLOYEE. Thereafter, the alias, EMPLOYEE , can be used to reference TUTORIAL.TUTORIAL.EMPLOYEE.

Parent topic: Data Objects


AuthID

An authorization ID, or AuthID, is a name associated with a user or process for auditing, monitoring and security purposes. An AuthID is also the second part of a three part name.

Parent topic: Data Objects


Catalog

The system catalog is a collection of special system defined tables that contain information about objects in the system. Most of the system tables are automatically maintained by the system when administrative tasks are performed, but there are some that must be updated manually. The XDB Server catalog consists of DB2-compatible tables (created with AuthID SYSIBM) and XDB Server-specific tables (created with AuthID SYSXDB.)

Parent topic: Data Objects


Column

A column is an attribute (or characteristic) of the entities described by the rows of a database table or result table. Each column is associated with a column name and a data type. Although the terms field and column are frequently used interchangeably in discussions of SQL programming; when we use the term field in the context of relational tables, we are referring to the intersection of a row and a column in a table or query result.

Parent topic: Data Objects


Database

An XDB Server database is a collection of tables, indexes and table spaces. Each database definition occupies a separate directory. A database consists of a number of files that may span several directories and disks if stogroups are used. Database names are stored in the system table SYSIBM.SYSDATABASE. A database is created using the CREATE DATABASE statement. Every location contains a default database (DSNDB04) and a system catalog database (DSNDB06). In addition a location may include a number of user-defined databases. The SYSTEM location includes two additional databases: XDBACF (stores information on security and access) and DSNDDF (stores information on other locations.)

Parent topic: Data Objects


Index

An index is an optional data structure used to speed retrieval of data or enforce certain constraints (such as uniqueness) on the records in a table. When you create an index on a column (or columns), the XDB Server stores an appropriately ordered list of all the values in that column as a separate index file. While this can greatly improve the performance of queries, maintaining an index slows down DML update operations (such as INSERT and DELETE) somewhat, and the index itself takes up memory. You must make a decision about creating indexes each time you create a table.

Parent topic: Data Objects


Index Space

An index space is a defined area of mainframe disk storage that is used to store the entries of an index. The XDB Server currently provides only syntactical support for index spaces. No entries are made into the system catalog when index space commands are executed.

Parent topic: Data Objects


Key

A key is one or more columns used to identify a row, or to establish a constraint such as uniqueness or referential integrity relationships. When you create or alter a table, you can establish keys which place constraints on the values that can be entered into that table's columns. Establishing a Foreign Key, for example, causes the XDB Server to reject any column values that violate the criteria defined for that Foreign Key constraint. The XDB Server supports three types of keys: primary, candidate and foreign.

Parent topic: Data Objects


Location

A location is a collection of tables, databases and related objects organized in a structured fashion. An XDB Server database system can have multiple locations, all managed by the same XDB Server. Through the use of a three-part naming scheme and other security measures, users can access more than one location at a time, as well as access remote locations, which are managed by other copies of an XDB Server, or by DB2 (accessed through XDB Link). The current location is set using the SET LOCATION TO or the CONNECT statement.

In order to operate, the XDB Server requires a SYSTEM location, which contains information on other locations, as well as security information. It is strongly recommended that you store your own data in a location other than the SYSTEM location.

Parent topic: Data Objects


Query

A query is a SELECT command that generates a result table or an intermediate result table. A query may be a subcomponent of another type of SQL statement, such as an INSERT or CREATE VIEW command. A nested query may also be part of a search condition. There are three forms of a query: subselect, fullselect and select-statement. For more information on these three query forms (as well as the SELECT INTO statement), see the SELECT command in SQL Commands. See also SELECT Clause, FROM Clause, and WHERE Clause. Queries are not named data objects, however XDB Server provides special facilities for saving and recalling queries as though they were named objects. Also, when writing programs containing embedded SQL, queries are usually associated with a cursor, which can be equated with a query name in the scope of the program.

Parent topic: Data Objects


Record

A record is a row of a table that presents information about a particular object, event or relationship. The words row and record are used interchangeably in this reference. A record is identified by the values contained in its fields. Note that a record is not a named data object. It is uniquely identified by the data it holds.

Parent topic: Data Objects


Storage Group

A storage group (stogroup) is a name assigned to a specific drive and directory used for physical storage. When using XDB Link to access DB2, a stogroup refers to a set of DASD volumes on which data is stored.

Parent topic: Data Objects


Synonym

A synonym is another name given to an existing table or view. Usually a synonym is used to define a more meaningful name for use by a particular application, or by a particular set of users. Synonyms are frequently used to replace two or three-part object names with one-part names (synonyms themselves can only be defined as one-part names). Synonyms can only be used to refer to a data objects in the current location, and can only be used by the AuthID that created them. This differs from aliases, which can rename objects in other locations, and can be used by anyone.

Parent topic: Data Objects


Table

A table is named data object that consists of a collection of homogeneously defined rows, all with consistent column names and data types. A table is the data object that actually stores the data that describes an entity or relationship. A result table is the output of a query (SELECT command). A result table also presents data in a two-dimensional format consisting of rows and columns. However, a result table is unnamed and transient.

Parent topic: Data Objects


Table Space

A table space is a physical area of disk space that holds a table. The table space object is provided for compatibility with DB2, and its use is optional when running against an XDB Server database. The XDB Server records all information about table spaces in the system catalog, but does not actually create table spaces.

Parent topic: Data Objects


View

A view is a virtual table that is logically defined over one or more tables in a location. Its definition includes a SELECT statement that determines the columns displayed, as well as the values it contains at any point in time. Views permit you to query subsets of data or joins of multiple tables as though they are an actual table. Only the view definition is stored in the location -- not the data retrieved by a view. Some views are updatable. Update commands performed on views actually affect the underlying table(s). Views may make it easier to access data by organizing it in more meaningful ways, or by restricting the rows retrieved to those that pertain to the needs of a particular application. Views can also be used for security reasons. For example, a user might be given access to only a specified set of records or columns.

Parent topic: Data Objects


Language Elements

This topic describes the basic syntax elements used to construct SQL keywords, command statements and object names.

More:

  • Characters
  • Tokens
  • Identifiers
  • NULL Value
  • Characters
  • Tokens
  • Identifiers
  • NULL Value
Parent topic: Overview


Characters

The elementary symbols of the SQL language are ASCII characters -- which may be classified as letters, digits and special characters -- plus non-English characters (or extended character sets) provided by IBM standard code pages.

  • Letters

    These are the letters of the alphabet (A-z). Letters are stored as entered by the user, however the sort sequence used for ordering and comparing data (including case sensitivity) is set by the XDB Server administrator for a particular location. A user can use the location default or define a special sort sequence.

  • Digits

    These are the numeric characters between 0 and 9.

  • Special Characters

    These are all characters other than letters and digits.

  • Extended Character Sets

    These are non-English characters.

Parent topic: Language Elements


Tokens

The syntactical elements of the SQL language are called tokens. Tokens are divided into two types:

  • Ordinary Tokens

    These are numeric constants, ordinary identifiers, or keywords. Ordinary tokens cannot include spaces, and must be followed by either delimiter tokens or spaces.

  • Delimiter Tokens

    These are string constants, delimited identifiers, operators (=, <=, <, >=, >, !=, ^=), or special characters identified in command syntax.

When a command extends to more than one line, tokens cannot be broken in the middle.

Parent topic: Language Elements


Identifiers

Identifiers are tokens used to form names. They fall into two categories:

  • Ordinary Identifiers

    These must begin with a letter (A-z), and may include letters (including standard IBM code page extended characters), digits and the special characters #$%&{}. The maximum length of ordinary identifiers depends on the object they name, as shown below. See XDB Server Specifications for a complete list of identifier limits.

    Short Identifiers. These are up to 8 characters long. Examples are database names and AuthIDs.

    Long Identifiers. These are up to 18 characters long (except location names are up to 16 characters.) Examples are column and table names.

    Follow the character selection rules below when naming short or long identifiers:

    • The first character can be chosen only from the letters of the alphabet (A-z) if using XDB mode.
    • If using DB2 mode, the letters of the alphabet (A-z), the special characters @#$, and IBM Code Page extended characters can be chosen for the first character position.
    • All following characters can follow the rules for Ordinary Identifiers defined above (which apply equally to XDB mode and DB2 mode).
  • Delimited Identifiers

    These consist of one or more characters enclosed within double (") or single quotes ('). A delimited identifier may contain either double quotes or apostrophes (or single quotes), in which case the identifier is usually delimited by the other type of quote. For example, the string Joe's Place can be used as a delimited identifier when written as:

    "Joe's Place"

    You can place both " and ' characters within the same string by using "" for " if you are using " as the string delimiter, or '' for ' if you are using ' as the string delimiter. For example, to enter the string value 5'11" into a character field, use a command like:

    UPDATE patient
SET height='5''11"'
WHERE name="o'HARA"
Parent topic: Language Elements


NULL Value

A NULL value is an undefined value for a field, indicating there is no data available. For sorting purposes, the NULL value's ordinal value depends on its location's definition. The XDB server considers NULL values to be the smallest possible value in all non-EBCDIC environments and with sensitive EBCDIC locations. In all other EBCDIC locations, NULL is sorted as the highest possible value.

Note that NULL values are not the same as blank or zero. NULL values are treated as undefined in mathematical operations, with the result that many expressions involving NULL are in turn resolved as NULL, or undefined.

Parent topic: Language Elements


Naming Conventions

On an XDB Server, database objects are assigned names, or identifiers, made up of ASCII characters (with the option of specifying extended character sets). Naming conventions depend on the object being named. The following list defines the terms used for certain types of database object names. Keep in mind that a short identifier is up to 8 characters long, while a long identifier is up to 18 characters long.

More:

  • AuthID
  • Column Name
  • Database Name
  • Index Name
  • Location Name
  • Table Name
  • Table Space Name
  • View Name
  • AuthID
  • Column Name
  • Database Name
  • Index Name
  • Location Name
  • Table Name
  • Table Space Name
  • View Name
Parent topic: Overview


AuthID

A short identifier that is associated with a user or process for auditing, monitoring and security purposes. AuthIDs must be unique within the system. However, an AuthID can be used by more than one individual or session.

Parent topic: Naming Conventions


Column Name

A long identifier that designates a table, view or result column. A column-name may be qualified or unqualified. A qualified column-name is prefixed with a qualifier followed by a period. A qualifier may be a table-name, view-name, correlation-name, or query-name.

The column name can be used to:

  • Define the name of the column in a table or view, as in a CREATE TABLE command.
  • Identify a column in a table or view, as in a CREATE INDEX or a COMMENT ON command.
  • Specify values of a column or intermediate result, as in a function, expression, GROUP BY clause, ORDER BY clause, or search condition.

In the above contexts only, column names may be qualified by prefixing them with a table name, view name or correlation name, followed by a period. Qualification is used to express correlated references, or to resolve ambiguous references. It can also be used simply as a matter of convenience.

Note that column names must be qualified when appearing in COMMENT ON commands.

Parent topic: Naming Conventions


Database Name

A short identifier that designates a database. Database-names must be unique within a location.

Parent topic: Naming Conventions


Index Name

A long identifier that designates an index. An index-name qualified by an AuthID must be unique within a location.

Parent topic: Naming Conventions


Location Name

An identifier that designates a subsystem. For compatibility with DB2, a location-name is limited to 16 characters in length, but otherwise follows the rules for a long identifier. Location-name must be unique within all locations to be accessed by a particular copy of the XDB Server.

Parent topic: Naming Conventions


Table Name

A long identifier that designates a table. A table name may be qualified or unqualified. A qualified table name is prefixed with a qualifier followed by a period. Table names that are qualified by location name and AuthID are known as three-part-names. A table name must be unique within all locations when it is qualified by location name and AuthID. An unqualified table name must be unique among all tables within a location that have the same owner.

Parent topic: Naming Conventions


Table Space Name

A short identifier that designates a table space. A table space name must be unique within a physical XDB Server database.

Parent topic: Naming Conventions


View Name

A long identifier that designates a view. It must satisfy the same rules as a table name, and must be unique among table names.

Parent topic: Naming Conventions


Three-Part Names

A data object name can be partially or fully qualified, or unqualified -- consisting of the table-identifier alone. Three-part names are provided by the XDB Server to support the concept of distributed units of work (DUW), which allows an application to access data at different servers and locations.

More:

  • Fully Qualified Table Names
  • Partially Qualified Table Names
  • Fully Qualified Table Names
  • Partially Qualified Table Names
Parent topic: Overview


Fully Qualified Table Names

A fully qualified (or three-part) table name consists of three distinct elements separated by periods:

location-name.authid.table-identifier

The first qualifier, location-name, indicates which location should be searched for the table. On an XDB Server, there can be multiple locations per server, while in DB2 the location name designates the DBMS (or subsystem) at which the table is stored. The SYSTEM.SYSIBM.SYSLOCATIONS table catalogs all locations accessible to the XDB Server.

The second qualifier, authid, is the Authorization ID (AuthID) that designates the owner of the table.

Parent topic: Three-Part Names


Partially Qualified Table Names

Partially qualified table names can be one-part or two-part names. A two-part table name consists of the table-identifier qualified by the authid, and implicitly qualified by the location-name of the current location.

A one-part table name consists of the table-identifier only, which is implicitly qualified by the location-name of the current location, and the Current SQLID special register. The value of the Current SQLID special register is determined by the following rules:

  • For static SQL statements, the Current SQLID is the identifier specified in the QUALIFIER option of the BIND command used to bind the SQL statements, or the owner of the plan or package.
  • For dynamic SQL statements, the Current SQLID is the identifier contained in the Current SQLID special register -- initially the same as USER, but changing to reflect execution of a SET CURRENT SQLID command. The Current SQLID can also be influenced by security exits and SecondaryID specifications.
Note:

Aliases and synonyms can be used for alternative names for a table or view. Aliases can be used to assign alternative names for tables and views that are not in the current location. Synonyms can only be used to rename tables or views in the current location.

Parent topic: Three-Part Names


Code Page Support

The character set used for naming database objects includes code page support for several standard IBM Code Pages. Code pages allow you to choose from a wide range of non-English characters when naming database objects. The XDB Server supports several IBM standard code pages that provide an extended character set when naming database objects, and when typing data into tables. The code pages supported and their character set definitions are shown in Code Page Character Sets.

The code page characters are in addition to the base character set. The base character set depends on the SQL Compatibility Mode under which you are running:

  • In XDB mode, the base character set includes: a-z, A-Z, 0-9, and the special characters # $ % & { } and _.
  • In DB2 mode, the base character set includes: a-z, A-Z, 0-9, and the special characters # @ $ and _. (Do not use an underscore (_) in an AuthID.)

The SQL Compatibility Mode is set in the Options Utility. For more information on the SQL Compatibility Mode, see the Options User's Guide. Characters from the selected code page may be used in:

Alias Names | Index Space Names
AuthIDs | Stogroup Names
Collection Names | Synonyms
Column Names | Table Names
Constraint Names | Table Space Names
Data Entry | View Names
Index Names |

Do not use any code page characters in a database name or location name. To maintain consistency with DB2, database and location names are restricted to the characters in the base character set.

Parent topic: Overview


Data Types

A column can contain any of the data types discussed in this topic. The following table lists the limits (minimum and maximum values) for each data type in XDB mode. The limits of XDB Server and DB2 data types are identical, except in the cases of float and char types. (See the footnotes in the table). The system rejects, or truncates (depending on the data type) values that fail to satisfy the rules for a data type.

Type | Minimum | Maximum | Storage
Smallint | -32,768 | 32,767 | 2 bytes
Int[eger] | -2,147,483,648 | 2,147,483,647 | 4 bytes
float (single) (See note 1.) | 1.2E-38 | 3.4E+38 | 4 bytes
float (double) (See note 1.) | 2.2E-308 | 1.8E+308 | 8 bytes
Dec[imal] | 1-10E+31 | 10E+31 | (precision/2)+1
Money | -10E+12 | 10E+12 | 8 bytes
DATE | 1/1/0001 | 12/31/9999 | 6 bytes
TIME | 00:00:01 | 24:00:00 | 6 bytes
Timestamp | 0001-1-01- 00.00.000000 | 9999-12-31- 24.00.000000 | 12 bytes
Char(See note 2.) | 1 byte | 254/4056 bytes (See note 3.) | n bytes
varchar (See note 2.) | 1 byte | 32706 | >= n bytes
long varchar (See note 2.) | 1 byte | 32706 | <= n bytes
Graphic | 2 bytes | 127 bytes | <= n bytes
Vargraphic | 2 bytes | 16353 | <= n bytes
Long Vargraphic | 2 bytes | 16353 | <= n bytes
BLOB(See note 4.) | zero bytes | 2 GB | separate file

Table Notes:

  1. The DB2 limits are 5.4E-79 to 7.2E+75 and 5.4E-79 to 7.2E+75 for single and double precision floating point values respectively.
  2. Can be defined as FOR BIT DATA, which means the column's fields contain a stream of bits that are not to be interpreted as ASCII (or EBCDIC) character codes.
  3. Character fields can store up to 4056 bytes in XDB mode, but only 254 bytes in DB2 mode.
  4. Includes image, binary, varbinary, and long varbinary data types.

More:

  • Smallint
  • Int[eger]
  • Float
  • Dec[imal]
  • Money
  • Date
  • Time
  • Timestamp
  • Char
  • Varchar
  • Long Varchar
  • Graphic
  • Vargraphic
  • Long Vargraphic
  • BLOB
  • Smallint
  • Int[eger]
  • Float
  • Dec[imal]
  • Money
  • Date
  • Time
  • Timestamp
  • Char
  • Varchar
  • Long Varchar
  • Graphic
  • Vargraphic
  • Long Vargraphic
  • BLOB
Parent topic: Overview


Smallint

This data type defines a field that holds whole numbers between -32,768 and 32,767. Smallint fields require 2 bytes of storage. Fractional values inserted into a small integer field are truncated. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Int[eger]

Defines a field containing a whole number between -2,147,483,648 and 2,147,483,647. Fractional values inserted into an integer field are truncated. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Float

FLOAT [(integer)]

This data type defines an IEEE standard 754 floating-point field. Floating-point fields can be defined as single or double (default) precision based on the value of integer. If the value of integer is between 1 and 21, the type is single precision floating-point, which requires 4 bytes of storage. If the value of integer is between 22 and 53 inclusive, the type is double precision floating-point, which requires 8 bytes of storage. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Dec[imal]

DEC[IMAL][(precision[,scale])]

This type of field holds fixed decimal point numbers between approximately 1-10E+31 and 10E+31. Precision is the total allowed number of digits including decimal places. The maximum precision is 31. The default precision is 5. Scale is the number of fractional digits (or decimal places.) The default scale is 0. Scale cannot be greater than precision. If only one parameter is given, it is treated as precision, and the default scale 0 is used. To estimate the storage requirement for decimal fields, round up the result of precision divided by two. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Money

This data type contains a dollar amount between -10E+12 and 10E+12. Money fields are stored as decimal (15,2) fields, and are displayed in a user-defined format. To specify special money formats (for example, foreign currencies), see the Options User's Guide. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Date

Dates designate a point in time according to the Gregorian calendar. Historical dates may not follow this calendar. Arithmetic may be performed on dates within the range shown in the table under Data Types. The standard input format for this data type is mm/dd/yy or mm/dd/yyyy (automatic conversion is performed between these two formats). Character representations of other date formats shown in the following table are permitted in SQL commands. When included in SQL commands, these special date formats must be enclosed in quotes.

When the XDB Server encounters a string in a location where it expects a date, it determines which of the formats is being used, and performs the internal conversion required. For more information on date formats, see the Options User's Guide. Dates are stored as three 2-byte integers. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by current date.

Format | Name | Date Format | Example
ISO | International Standards Organization | yyyy-mm-dd | 1992-03-20
USA | IBM USA Standard | mm/dd/yyyy | 03/20/1992
EUR | IBM European Standard | dd.mm.yyyy | 20.03.1992
JIS | Japanese Industrial Standard Christian Era | yyyy-mm-dd | 1992-03-20
LOCAL | Installation-defined | any defined format |
Parent topic: Data Types


Time

The time field data type is defined by the standard input format of hh:mm:ss, using a 24-hour clock. Character representations of other time formats shown in the following table are permitted in SQL commands. Note that when included in SQL commands, these special time formats must be enclosed in quotes. When the XDB Server encounters a string in a location where it expects a time, it determines which of the formats is being used, and performs the internal conversion required. Time requires 3 bytes of storage. If a time field is specified as NOT NULL WITH DEFAULT, null values will be replaced by the current time.

Format | Name | Date Format | Example
ISO | International Standards Organization | hh.mm.ss | 14:30:05
USA | IBM USA Standard | hh:mm AM or PM | 2:30 PM
EUR | IBM European Standard | hh.mm.ss | 14.30.05
JIS | Japanese Industrial Standard Christian Era | hh.mm.ss | 14.30.05
LOCAL | Installation-defined | Any defined format |
Parent topic: Data Types


Timestamp

This combination date and time data type is displayed in the format yyyy-mm-dd-hh.mm.ss.nnnnnn. The following table describes the various components of this field. As an example, the timestamp for 7:45:34pm on June 18, 1992 would be 1992-06-18-19.45.34.000000. When including a timestamp value in an SQL command, enclose it in quotes. Timestamp requires 12 bytes of storage. If the column is specified as NOT NULL WITH DEFAULT, null values will be replaced by the current timestamp.

Format | Description
YYYY | An integer from 0001 to 9999, representing a year.
MM | An integer from 1 to 12 representing a month.
DD | An integer from 1 to 31 (maximum depends on the month and year) representing the day of the month.
hh | An integer from 0 to 24, representing the hour.
mm | An integer from 0 to 59, representing minutes.
ss | An integer from 0 to 59 representing seconds (default 0).
nnnnnn | An integer (up to 6 digits) representing microseconds. If any trailing digit is omitted, 0 is assumed.
Parent topic: Data Types


Char

CHAR (field-length)

A data type containing a fixed length alphanumeric string with a maximum length of field-length characters. The field-length must be a positive number not exceeding 4056 in XDB mode (254 in DB2 mode). This data type can be defined as FOR BIT DATA. If the column is specified as NOT NULL WITH DEFAULT, null values will be replaced by spaces.

Parent topic: Data Types


Varchar

VARCHAR (field-length)

This data type consists of variable length alphanumeric string values with a maximum length of field-length characters. field-length must be a positive number not exceeding 32,706. See the CREATE TABLE command for more information on determining lengths of VARCHAR and LONG VARCHAR variables. Can be defined as FOR BIT DATA. If the column is specified as NOT NULL WITH DEFAULT, null values will be replaced by spaces.

Note: Currently all varchar and vargraphic fields are stored as fixed length fields. In future releases the storage required for these field types will vary according to the data to be stored.
Parent topic: Data Types


Long Varchar

A data type containing variable length alphanumeric strings (maximum length of 32,706 characters). See the CREATE TABLE command for more information on determining lengths of LONG VARCHAR and VARCHAR variables. The storage required depends on the actual length of the value stored. Can be defined as FOR BIT DATA. If the field is specified as NOT NULL WITH DEFAULT, null values are replaced by spaces.

Parent topic: Data Types


Graphic

GRAPHIC (field-length)

Fields of this data type contain fixed length strings (field-length characters long), intended for storing double byte data. The field-length must be a positive number not exceeding 127.

Parent topic: Data Types


Vargraphic

VARGRAPHIC (field-length)

This data type holds variable length strings (maximum length of 2028 characters), intended for storing double byte data. The amount of storage required depends on the actual length of the value stored.

Parent topic: Data Types


Long Vargraphic

This data type contains variable length strings (maximum length of 2028 characters), intended for storing double byte data. The amount of storage required depends on the actual length of the value stored.

Parent topic: Data Types


BLOB

BLOB is a generic term describing any arbitrarily sized block of data. This data type can also be referred to as image, binary or bitdata. A BLOB can be created using one of four syntaxes -- all of which are functionally equivalent. Various syntaxes are provided for compatibility with industry standards and different vendors. The available BLOB data type syntaxes are:

  • image[BLOCK SIZE n]
  • binary(x)
  • varbinary(x)
  • long varbinary

where n is the size of the block used for storage. The x parameter for the binary, varbinary and long varbinary syntaxes is not currently used. The minimum size of a BLOB data type is zero bytes. BLOB data types do not have NULLs. Since BLOB fields can not be used in WHERE clauses or aggregate functions, there is no need for NULLs. However, any BLOB can have a length of zero, which can only be determined by using an API call from a host application.

The BLOB data type allows you to save and manage binary disk files, such as image and sound files. Unlike char, int, and decimal, which have defined purposes and semantics, BLOB data is considered to be "unstructured" and "anonymous" and is not interpreted in any way by the database. Apart from certain limitations, BLOB fields can be accessed and manipulated like any other column in a table.

Tables can have more than one BLOB field; and tables with BLOB fields can be joined in any fashion. There is no maximum size for a BLOB data type. Data stored as a BLOB data type is not stored in the XDB Server table (.TAB) file as other data types are. Instead, each BLOB field is stored as a separate file in the same storage group as the XDB Server table file. Each BLOB file name has the same root file name as the .TAB file.

Each BLOB field in a table is stored in a separate file. The files are partitioned into blocks, and each BLOB record is stored as a linked-list of blocks. The default block size is 2K, and can be set (using the BLOCK SIZE clause) to any value between 64 bytes and 32K during table creation. A free list of blocks is maintained and blocks are reused.

Note:

BLOB data types are not supported with the DOS single-user engine.

Parent topic: Data Types


Other Data Types

For ANSI compatibility, the XDB Server allows you to issue commands to create or alter tables using the following data types. These data types are converted to appropriate XDB Server data types, as shown.

More:

  • Double Precision
  • Numeric
  • Real
  • Double Precision
  • Numeric
  • Real
Parent topic: Overview


Double Precision

When creating or altering a column as a DOUBLE or DOUBLE PRECISION data type, the column is created as (or modified to) a double precision FLOAT type.

Parent topic: Other Data Types


Numeric

NUMERIC[(precision[, scale])]

If the data type NUMERIC is used when creating or altering a table, the column is created as (or modified to) a data type DECIMAL, with the specified precision and scale.

Parent topic: Other Data Types


Real

When creating or altering a column as a REAL data type, the column is created as (or modified to) a single precision FLOAT type.

Parent topic: Other Data Types


Assignment And Comparison

When running against an XDB Server, character strings, dates, times and numbers are not compatible. That is, one type of value cannot always be compared or assigned to an object of another type. NULL values can be assigned to any type of column, except those defined as NOT NULL.

More:

  • Assignment
  • Comparison
  • Assignment
  • Comparison
Parent topic: Overview


Assignment

If an attempt is made to assign a numeric value to a column not large enough to hold it, the fractional part may be truncated. If the integer portion cannot be assigned to a column, an error message is displayed. If an attempt is made to assign a character string to a target field that is too short, the value will be truncated on the right.

Parent topic: Assignment And Comparison


Comparison

Numeric values are compared according to their algebraic values. Character strings are compared by comparing the two strings according to the sort sequence specified for the location, beginning with the leftmost characters. For more information on specifying a sort sequence, see the Options User's Guide and the SQLWizard User's Guide. The default sort sequence is a modified ASCII sequence that does not distinguish between upper and lower case letters.

Parent topic: Assignment And Comparison


Constants

Constants are specific values. Constants may be classified as character string, date, time, timestamp or numeric constants. Character string constants appear inside quotes (single or double) in SQL commands. Numeric constants are subdivided into integer (including both integer and smallint), float, and money constants, according to the data type into which they fall. In SQL commands, date constants should be in the form mm/dd/yy or mm/dd/yyyy (the slash ( / ) is not interpreted as a division operator if the value is determined to be a date). If another date format is used, the date string must be enclosed in quotes. In SQL commands, time constants should be of the format hh:mm:ss. If another time format is used, the date string must be enclosed in quotes. Timestamp constants should be in the format yyyy-mm-dd-hh.mm.ss.nnnnnn.

Parent topic: Overview


Special Registers

The XDB Server supports a set of special keywords that refer to the contents of system variables, which can be referenced in SQL commands.

More:

  • BOTTOM
  • CURRENT DATE
  • CURRENT DEGREE
  • CURRENT PACKAGESET
  • CURRENT RULES
  • CURRENT SERVER
  • CURRENT SQLID
  • CURRENT TIME
  • CURRENT TIMESTAMP
  • CURRENT TIMEZONE
  • LEVEL
  • NULL
  • ROWID
  • BOTTOM
  • CURRENT DATE
  • CURRENT DEGREE
  • CURRENT PACKAGESET
  • CURRENT RULES
  • CURRENT SERVER
  • CURRENT SQLID
  • CURRENT TIME
  • CURRENT TIMESTAMP
  • CURRENT TIMEZONE
  • LEVEL
  • NULL
  • ROWID
Parent topic: Overview


BOTTOM

Lowest recursion level (used with PREVIOUS function). The Data type is smallint.

Parent topic: Special Registers


CURRENT DATE

Today's date, read from system clock. (Also TODAY in XDB mode.) The data type is date. XDB Server also recognizes CURRENT_DATE as a synonym for the CURRENT DATE special register.

Parent topic: Special Registers


CURRENT DEGREE

This special register is supported functionally in that it returns the default value or a value specified with the SET CURRENT DEGREE command. This value does not actually reflect the "degree of parallelism."

Parent topic: Special Registers


CURRENT PACKAGESET

This special register is syntactically supported by the XDB Server for the SET CURRENT PACKAGESET command and the SET Host Variable command. On mainframe DB2 systems, CURRENT PACKAGESET is used to specify the Collection ID of a package that will be used to execute subsequent SQL statements. The data type is CHAR(18) and is padded with blanks to fill out the field. The initial value is blanks.

Parent topic: Special Registers


CURRENT RULES

The new special register CURRENT RULES allows you to specify the SQL rules that apply to the execution of SQL statements. The value in CURRENT RULES also effects the enforcement of table check constraints. See the SET CURRENT RULES statement for further information.

Parent topic: Special Registers


CURRENT SERVER

This special register is similar to the CURRENT SERVER in DB2. The Current Server special register identifies the DBMS to which your application is actively connected.

When running against an XDB Server, this is the name of the current location to which you are connected.

Parent topic: Special Registers


CURRENT SQLID

The CURRENT SQLID is initially the same as USER. The value changes to reflect execution of a SET CURRENT SQLID command. The data type is char(8). CURRENT SQLID can also be influenced by security exits and SecondaryID specifications.

Parent topic: Special Registers


CURRENT TIME

The CURRENT TIME register value is read from the system clock. The data type is time. (Also XTIME in XDB mode.) The XDB Server also recognizes CURRENT_TIME as a synonym for the CURRENT TIME special register.

Parent topic: Special Registers


CURRENT TIMESTAMP

The CURRENT TIMESTAMP register value consists of the current date and time, both of which are read from the system clock. The data type is timestamp. The XDB Server also recognizes CURRENT_TIMESTAMP as a synonym for the CURRENT TIMESTAMP special register.

Parent topic: Special Registers


CURRENT TIMEZONE

A time duration between -24 and 24 hours representing difference in hours between local time and Greenwich Mean Time (GMT). The data type is decimal(6,0). The default returned by CURRENT TIMEZONE is 0.

Parent topic: Special Registers


LEVEL

Recursion level (number of times the PREVIOUS function's recursion algorithm is applied). The data type is smallint.

Parent topic: Special Registers


NULL

Absence of a value. NULL can be used for any data type.

Parent topic: Special Registers


ROWID

DB2 mode only. Data type is integer. Contains the physical row number of the current record. The XDB Server reports this value when a referential integrity error occurs or when a duplicate value is detected in a unique index. You can use ROWID anywhere an expression can be used. For example:

SELECT * FROM CUSTOMER WHERE ROWID = 22;

gets the record in physical row 22. And,

SELECT ROWID,NAME,ADDRESS, FROM CUSTOMER;

gets the row numbers along with other fields in the CUSTOMER table.

When ROWID is used with a join, it represents the row number of the first table in the join.

Parent topic: Special Registers


Labeled Duration

The following table contains keywords known as labeled durations. Each labeled duration keyword corresponds to a specific time unit, interpreted as it normally would be against a calendar or clock. A labeled duration can only be used in an arithmetic expression having date, time or timestamp expressions (or columns) as one of the operands. The expression must resolve to the proper data type. For example, DATE("1993-12-12") + DAY is a valid expression, as is BIRTHDATE + 15 YEARS + 8 MONTHS.

The expression BIRTHDATE + (15 YEARS + 8 MONTHS), on the other hand, cannot be resolved because the system would attempt to add the expression in parentheses first, which contains no date or time operand.

A labeled duration is converted into a decimal (15,0) number before it is applied. If present, decimal places are truncated. All of the keywords listed in the following table can also be used in singular form as labeled durations (for example, YEAR is the same as YEARS, MONTH is the same as MONTHS, etc.)

Duration | Example
YEARS | goldenanniv = weddingdate + 50 years
MONTHS | eligibledate = hiredate + 6 months
DAYS | nextcall = current date + 14 days
HOURS | endshift = beginshift + 8 hours
MINUTES | sampletime = current time + 10 minutes
SECONDS | eta = depart + second(travel) seconds
MICROSECONDS | adjustedtime=recordedtime - 200 microseconds
Parent topic: Overview


SQL Commands

  • SQL Command Category Overview
  • Data Definition Language (DDL)
  • Data Manipulation Language (DML)
  • Data Control Language (DCL)
  • Utility Commands
  • Embedded and Dynamic SQL
Parent topic: SQL Reference


SQL Command Category Overview

Standard SQL statements supported by the XDB Server can be divided into three functional command categories:

  • Data Definition Language (DDL) statements create, alter and drop relational database objects such as databases, tables and indexes.
  • Data Manipulation Language (DML) statements select, update, insert, and delete data values within relational database tables.
  • Data Control Language (DCL) statements establish system security by controlling access to data objects, plus regulating concurrency and transaction processing.

In addition, there are utility commands (that perform administrative functions on the XDB Server) and embedded and dynamic SQL commands.

Parent topic: SQL Commands


Data Definition Language (DDL)

Data Definition Language (or DDL) includes those SQL statements that create and drop locations, databases and database objects such as tables and indexes. DDL also includes statements to alter database objects and impose integrity constraints on tables. All DDL statements automatically update the appropriate system catalog tables.

  • ALTER DATABASE

    Changes information parameters for a database under the currently set XDB Server location.

  • ALTER INDEX

    Changes the configuration of an existing index (DB2). This command is supported syntactically by the XDB Server to maintain compatibility with DB2.

  • ALTER LOCATION

    Converts a location to DB2 Version 4 or DB2 Version 5 compatibility.

  • ALTER SEQUENCE

    Changes the attributes of a sequence at the current server.

  • ALTER STOGROUP

    Changes the specifications of an existing storage group (stogroup) defined within the current XDB Server location.

  • ALTER TABLE

    Adds, removes or renames table columns, or changes the data types of columns. In XDB mode, the ALTER TABLE command can create or drop UNIQUE, PRIMARY, FOREIGN KEY and CHECK constraints used to enforce referential and domain integrity, plus uniqueness (the DB2-specific syntax of the ALTER TABLE statement is supported in DB2 mode).

  • ALTER TABLESPACE

    Changes the specifications of a table space within the currently set XDB Server location.

  • ALTER VIEW

    Regenerates a view using an existing view definition at the current server.

  • COMMENT ON

    Places a remark about an object in the catalog tables at the currently set location.

  • CREATE ALIAS

    The CREATE ALIAS command defines an alias for an existing table or view, and records the alias definition in the catalog tables at the currently set location. It is not required that the table or view be described under the same location as the alias.

  • CREATE DATABASE

    Defines a logical database, which under default operating conditions consists of a subdirectory of the same name, under the active location root directory. The database directory, normally under the location root directory, holds the physical table and index files that are logically associated with the database. By using stogroups (described in the Server Administration Guide), users have the option of implicitly specifying different storage directories for individual database objects (or groups of objects).

  • CREATE GLOBAL TEMPORARY TABLE

    Creates a description of a temporary table at the current server.

  • CREATE INDEX

    Creates an index on one or more columns of a table. Indexes speed data retrieval and can enforce uniqueness constraints.

  • CREATE LOCATION

    Creates a new XDB Server location in a subdirectory path specified by the user. A location on an XDB Server is similar to a DB2 subsystem. In addition to a SYSTEM location (used for overall system administration and security), the XDB Server allows additional user-defined locations to be created.

  • CREATE SEQUENCE

    Creates a sequence at the application server.

  • CREATE STOGROUP

    Creates a DB2 style storage group (stogroup) that can be associated with a directory path. Stogroups are used to define a physical directory area for storing database objects.

  • CREATE SYNONYM

    Creates an alternate name for a table or view within the currently set location.

  • CREATE TABLE

    Creates a table by defining all columns in the table, including the data type and field length of each column. Primary and Foreign keys for the table also can be created using this command.

  • CREATE TABLESPACE

    Creates a DB2 style table space that can be used with a stogroup to store tables from the same logical database in different directory paths.

  • CREATE VIEW

    Defines a virtual table that usually restricts data retrieval and updating to a subset of columns and rows from one or more base tables.

  • DROP ALIAS

    Deletes an alternate name for a table or view from the location's system catalog.

  • DROP DATABASE

    Deletes a database defined within the current location. Also deletes all objects logically associated with the database, and then deletes the database subdirectory. If the database subdirectory is empty (with no objects logically associated with that database), then this command removes the empty subdirectory.

  • DROP INDEX

    Deletes an index existing at the current location. Note that an index created as the result of a UNIQUE, PRIMARY or FOREIGN KEY constraint can only be dropped by first dropping the existing constraint with the ALTER command.

  • DROP LOCATION

    Removes a user-defined XDB Server location, along with accompanying catalog tables and directory structure. Also deletes all objects associated with the location.

  • DROP STOGROUP

    Deletes a stogroup defined within the currently set location. This action severs the logical connection between any data objects that were defined using the stogroup, and the directory path specified in the deleted stogroup definition (does not delete objects associated with the stogroup) -- USE WITH CAUTION.

  • DROP SYNONYM

    Deletes an alternate name for a table or view from the location's system catalog.

  • DROP TABLE

    Deletes a table created under the current location, along with all associated indexes, views and synonyms built on that table.

  • DROP TABLESPACE

    Deletes a table space defined within the current location, along with all tables logically associated within that table space.

  • DROP VIEW

    Deletes a view from the system catalog of the current location. In addition, all other views defined on the dropped view are dropped also.

  • LABEL ON

    Replaces or adds descriptive text labels to the catalog tables of the currently set location. These text labels describe tables, views, aliases, or columns existing at the current location.

  • RENAME

    Changes a table name.

Parent topic: SQL Commands


Data Manipulation Language (DML)

Data Manipulation Language (or DML) consists of SQL statements used to retrieve, insert, update and delete records from database tables. DML statements are the only statements that can be rolled back or recovered.

  • DELETE

    Deletes specified rows from a table. Also has a special format (DELETE WHERE CURRENT OF) for embedded SQL.

  • INSERT

    Inserts a specified number of rows into a table.

  • SELECT

    Retrieves data from one or more tables. Also has a special format (SELECT INTO) for embedded SQL.

  • UPDATE

    Modifies data in specified rows of a table. Also has a special format (UPDATE WHERE CURRENT OF) for embedded SQL.

Parent topic: SQL Commands


Data Control Language (DCL)

Data Control Language (or DCL) consists of statements that control security and concurrent access to table data.

  • COMMIT

    Instructs the XDB Server to make permanent all data changes resulting from DML statements executed by a transaction.

  • CONNECT

    Connects the application process (or user) to a designated XDB Server or DB2 location. This location becomes the current location for the application process or user.

  • GRANT (Database Privileges)

    Assigns access privileges to XDB Server users or applications.

  • GRANT (Sequence Privileges)

    Grants privileges on a user-defined sequence.

  • LOCK TABLE

    Extends XDB Server's automatic record and table level locking functions (in a multi-user system) by acquiring explicit locks on a particular table.

  • REVOKE (Database Privileges)

    Cancels access privileges for XDB Server users or applications.

  • REVOKE (Sequence Privileges)

    Revokes the privileges on a user-defined sequence.

  • ROLLBACK

    Instructs the XDB Server to reverse the effect of any DML commands executed on a database by a transaction. Information recorded in a backward log is used to restore the database to a state existing before the transaction.

  • UNLOCK TABLE

    Removes table locks (in a multi-user system) acquired with the LOCK TABLE command.

Parent topic: SQL Commands


Utility Commands

Utility commands perform administrative functions on the XDB Server.

  • ALTER PASSWORD

    Enables you to change passwords.

  • BACKUP LOCATION

    Makes a backup copy of an entire XDB Server location to a specified directory path.

  • BULK [ON | OFF]

    BULK ON turns the Bulk Upload feature on for all subsequent transactions. Bulk uploading allows data to be transferred to the client in bulk, instead of one row at a time (used with XDB Link). BULK OFF turns the Bulk Upload feature off.

  • CHECKPOINT

    Flushes the entire logging system cache buffer to disk and flushes database cache buffer.

  • COMPACT

    Recycles unused disk space by packing tables, rebuilding indexes and reorganizing directory files.

  • CREATE USER

    Creates additional XDB user accounts.

  • DISABLE LOGIN

    Prevents additional users from logging on to the server.

  • ENABLE LOGIN

    Permits users to log on to the server again after a DISABLE LOGIN command has been issued.

  • EXPLAIN

    Acquires access path selection information about an "explainable" SQL statement, and inserts the information into a special table (automatically created by the XDB Server) named PLAN_TABLE. Users have the option of creating their own plan_table structure.

  • HALT QUERY FROM

    Terminates a specific query.

  • REFRESH LOCATIONS

    Directs the XDB Server to re-read the information contained in the SYSIBM.SYSLOCATIONS catalog table. REFRESH LOCATIONS is typically issued after information in this table has been manually updated by the user.

  • REFRESH TABLE

    Refreshes the data in a materialized query table.

  • ROLLFORWARD

    Applies all DML changes recorded in a forward log file to a location backup copy. The ROLLFORWARD command restores the information in a location to the condition existing before the last location backup.

  • SET AUTOCOMMIT

    Sets the autocommit feature on or off. Setting autocommit to "on" causes a commit to be automatically generated after any DML command.

  • SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION

    Changes the value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register.

  • SET CURRENT PACKAGE PATH

    Assigns a value to the CURRENT PACKAGE PATH special register.

  • SET CURRENT PACKAGESET

    Assigns a value to the CURRENT PACKAGESET special register.

    Note: This command is supported only syntactically by the XDB Server, where packages are bound with a particular qualifier.
  • SET CURRENT REFRESH AGE

    Changes the value of the CURRENT REFRESH AGE special register.

  • SET CURRENT RULES

    Assigns a value to the CURRENT RULES special register.

  • SET CURRENT SQLID

    Changes the AuthID value stored in the CURRENT SQLID special register.

  • SET ISOLATION

    Defines the isolation level used to determine appropriate lock acquiring and lock releasing procedures for an executing transaction.

  • SET LOCATION location-name OFFLINE/ONLINE

    Lets the system administrator prevent or permit access to a specific location.

  • SET LOCATION TO

    Logs a user onto a new location, creating an implied connection between the user's current session and the specified location. The value of the CURRENT LOCATION special register is temporarily updated to reflect the new active location. The user's default location is not changed.

  • SET LOG

    Allows database administrators (with SYSADM authority or higher) to suspend logging system operation during an administrative session, and change the path where location log files are stored.

  • SET SCHEMA

    Assigns a value to the CURRENT SCHEMA special register.

  • SET SORTSPACE

    Changes the size of the sort space while the XDB Server is running.

  • SHUTDOWN

    Stops an XDB Server from a remote client.

  • START DATABASE

    Allows users to have access to the contents of the named database.

  • STOP DATABASE

    Restricts all access to the named database.

  • TRUNCATE TABLE

    Deletes records from a table much like the DELETE command, but proceeds much faster since the deleted data is not logged.

Parent topic: SQL Commands


Embedded and Dynamic SQL

XDB Server statements that are used in embedded and dynamic SQL programming are summarized below. While most SQL commands can be embedded in host programming languages (for example, COBOL, C and PL/I), the following commands can only appear as embedded or dynamic SQL statements.

  • ALLOCATE CURSOR

    Defines a cursor and associates it with a result set locator variable.

  • ASSOCIATE LOCATORS

    Gets the result set locator value for each result set returned by a stored procedure.

  • BEGIN DECLARE SECTION

    Marks the beginning of declarations for host variables to be used by SQL commands (optional in COBOL).

  • CALL

    Runs stored procedures on the mainframe (through XDB Link), or procedures on an XDB Server, from an application.

  • CLOSE

    Closes a previously opened cursor (OPEN command).

  • DECLARE CURSOR

    Defines a cursor.

  • DECLARE STATEMENT

    Identifies prepared SQL statements for later use in application programs.

  • DECLARE TABLE

    Provides the precompiler with information for checking embedded SQL statements. DECLARE TABLE is also used for application program documentation.

  • DESCRIBE

    Obtains information about either a prepared statement (PREPARE command), or an existing table or view.

  • DESCRIBE CURSOR

    Obtains information about the result set that is associated with the cursor and places the information into a descriptor.

  • DESCRIBE PROCEDURE

    Obtains information about the result sets returned by a stored procedure, and places the information into a descriptor.

  • END DECLARE SECTION

    Marks the end of declarations for host variables to be used by SQL commands (required if BEGIN DECLARE SECTION statement is used).

  • EXECUTE

    Executes a prepared (PREPARE command) SQL statement.

  • EXECUTE IMMEDIATE

    Prepares (PREPARE command) and executes (EXECUTE command) an SQL statement in one step.

  • FETCH

    Positions a cursor on the next row of a result, and assigns the values of that row to host program variables.

  • GET DIAGNOSTICS

    Provides diagnostic information about the last SQL statement (other than a GET DIAGNOSTICS statement) that was executed.

  • INCLUDE

    Inserts declarations or code into a source program for use by SQL, as well as the host language.

  • OPEN

    Opens a previously prepared (PREPARE command) cursor prior to fetching (FETCH command) result rows.

  • PREPARE

    Prepares an SQL statement for execution.

  • SELECT INTO

    Retrieves one row of values from a table or view, and then assigns these values to one or more host variables specified in the SELECT INTO command statement.

  • SET Host Variable

    Assigns special register values to host variables.

  • WHENEVER

    Specifies the host language statement to be executed whenever a specified exception condition takes place.

Parent topic: SQL Commands


Syntax Notation

The SQL statement syntax in this reference shows all the clauses, object types and predicates that can be incorporated into a particular statement. The following standard notation conventions are used in the statement syntax:

  • Italics are used to distinguish general parameter information and data object categories in a statement syntax. The clause "PASSWORD password," for example, contains the keyword PASSWORD, and the parameter password (indicating that the user should supply a password).
  • Square brackets ( [ ] ) enclose optional items in a command statement. Do not type the brackets. For example, the statement "COMMIT [WORK]" indicates that the keyword COMMIT must be used, but the keyword WORK is optional.
  • Ellipses ( ... ) indicate that the preceding item may be repeated one or more times. Do not type the ellipses.
  • Ellipses are sometimes preceded with a comma ( ,... ) indicating that the preceding item may be repeated one or more times, with each repeated item separated from the last by a comma. For example, the clause "column-name [,...]" indicates that at least one column name must be specified, with an option to add any number of other column names (with each column name separated from the last by a comma).
  • Vertical bars ( | ) indicate that whatever item precedes the bar can be replaced by the item following the bar. This character operates as an OR conjunction, offering a choice between the item appearing before and after. Do not type the vertical bar.
  • Braces ( { } ) group items to be selected as a single element of the command statement. One item within the braces must be chosen. For example, "{A | B}" means choose either A or B. Do not type the braces.
  • Parentheses appearing within the statement syntax are part of the statement syntax and need to be typed as shown.
  • Underlined items indicate a default option. For example, "PRIQTY {3 | integer}" indicates that the PRIQTY clause has a default value of three. The statement "SELECT [ALL | DISTINCT]" indicates that SELECT (by itself) is interpreted the same as SELECT ALL.

More:

  • Syntax Support Only
  • Case Sensitivity
  • Comments
  • Line Continuation
  • Syntax Support Only
  • Case Sensitivity
  • Comments
  • Line Continuation
Parent topic: SQL Reference


Syntax Support Only

A DB2-mainframe statement that has no functional equivalent on the XDB Server. It is fully supported only when running against a DB2-mainframe location using XDB Link. If running against an XDB Server location, only the syntax of these clauses is checked. An error message is returned to the user if a spelling or syntax error is found. Refer to the appropriate DB2 documentation for full explanations of these commands.

Parent topic: Syntax Notation


Case Sensitivity

To enhance readability in this reference, command keywords always appear in capital letters. For actual database operations, however, XDB Server keywords are not case sensitive and may be entered in either all upper case, all lower case, or any combination of upper and lower case letters.

The character sort sequence for each XDB Server location defaults to case insensitive -- which can be changed to standard ASCII, standard EBCDIC or a user defined sorting scheme. XDB Server Administrators can change the sort sequence for an XDB Server location. Users can choose to use the default location sort or specify their own sort through client configuration, described in your client tools documentation.

Parent topic: Syntax Notation


Comments

The XDB Server receives and processes SQL commands as continuous, nondelimited strings. Comments can be included anywhere in an SQL command, provided they are bracketed by the characters /* and */. The XDB Server ignores all characters enclosed between these special characters. For example, the following command statement has the comment string "info on parts & suppliers" attached:

SELECT *
    FROM partsupp /* info on parts & suppliers */

An alternative means of entering comments is provided in SQLWizard, where users may place comments at the end of a statement line, separating them from the statement text by a double hyphen (--). Anything on the line after the double hyphen is ignored by the system.

Parent topic: Syntax Notation


Line Continuation

Although the XDB Server requires that an SQL commands be processed as a single string of text characters, in most XDB Server environments you can split commands over several lines without requiring special line continuation marks. A semicolon generally indicates the end of a complete command statement.

Parent topic: Syntax Notation


DB2 Support

When running in DB2-mode, the XDB Server provides either full or partial DB2-mainframe support for all SQL statements and clauses. When running against a mainframe location using XDB Link, XDB Link effectively becomes the DB2 subsystem, providing complete DB2-mainframe support for all SQL statements issued by the user.

However, when running against an XDB Server location in a non-mainframe environment, some combination of the following three categories of DB2-mainframe support applies to each SQL statement and clause:

  • Functionally Supported

    These clauses actually perform some function within the XDB Server. This implementation may not exactly mirror the DB2-mainframe implementation, but is functional in some respect.

  • Syntactically Supported

    None of the information contained within these clauses has a functional purpose within the XDB Server. XDB technology does, however, check the spelling and syntax of these clauses, returning an error to the user if the syntax deviates from correct DB2-mainframe usage. It is also possible that some clause information may be recorded within XDB Server catalog tables. These clauses appear as bold text in syntax statements.

Parent topic: SQL Reference


SQL Statements

  • ALLOCATE CURSOR
    The ALLOCATE CURSOR statement defines a cursor and associates it with a result set locator variable.
  • ALTER DATABASE
    The ALTER DATABASE statement changes the description of the specified database under the currently set XDB Server location.
  • ALTER FUNCTION
    The ALTER FUNCTION statement changes the description of an external scalar or external table function at the current server.
  • ALTER FUNCTION (SQL)
    The ALTER FUNCTION (SQL) statement changes the description of a user-defined SQL scalar function at the current server.
  • ALTER INDEX
    On a mainframe DB2 subsystem, this statement changes the configuration of an existing index. See the ALTER TABLE command for information on altering indexes that result from UNIQUE, PRIMARY and FOREIGN keys. In some cases, it may be necessary to drop an index and re-create it using the DROP INDEX and CREATE INDEX commands.
  • ALTER LOCATION
    The ALTER LOCATION statement converts (upgrades) a location to DB2 Version 6, 7 or 8 compatibility.
  • ALTER PASSWORD
    The ALTER PASSWORD statement enables you to change passwords.
  • ALTER PROCEDURE (external)
    The ALTER PROCEDURE statement changes the description of a stored procedure at the current server.
  • ALTER PROCEDURE (SQL)
    The XDB Server operating environment only provides syntax support for external Procedures (SQL) at this time.
  • ALTER SEQUENCE
    The ALTER SEQUENCE statement changes the attributes of a sequence at the current server. Only future values of the sequence are affected by the ALTER SEQUENCE statement.
  • ALTER STOGROUP
    The ALTER STOGROUP statement changes the specifications of an existing storage group (stogroup) defined within the current XDB Server location.
  • ALTER TABLE
    The ALTER TABLE statement changes the description of a table at the current server.
  • ALTER TABLESPACE
    The ALTER TABLESPACE statement changes the specifications of a table space within the currently set XDB Server location.
  • ALTER VIEW
    The ALTER VIEW statement regenerates a view using an existing view definition at the current server.
  • ASSOCIATE LOCATORS
    The ASSOCIATE LOCATORS statement gets the result set locator value for each result set returned by a stored procedure.
  • BACKUP LOCATION
    This XDB Server utility command copies the entire contents of an XDB Server location to the specified drive and path while the XDB Server location is still generally available.
  • BEGIN DECLARE SECTION
    The BEGIN DECLARE SECTION statement (embedded SQL only) marks the beginning of a host variable declare section in an application program.
  • BULK
    The BULK ON command activates the Bulk Upload feature which increases the efficiency of your transactions between the mainframe and XDB Link. The BULK OFF command turns off the Bulk Upload feature.
  • CALL
    The XDB Server can run a stored procedure on the mainframe (through XDB Link) or on an XDB Server through use of the CALL statement.
  • CHECKPOINT
    CHECKPOINT is an SQL command which flushes the database and log files.
  • CLOSE
    The CLOSE command (embedded SQL only) closes a cursor previously opened by a DECLARE CURSOR command. If a temporary table is created as a result of the cursor, that table is deleted when the cursor is closed.
  • COMMENT ON
    The COMMENT ON statement adds or replaces descriptive text comments for aliases, columns, distinct types (currently not supported), stored procedures, tables, triggers, user-defined functions, and views located within the current XDB Server location. All comments are stored in the catalog tables belonging to that location.
  • COMMIT
    The COMMIT statement is used to mark the end of a transaction (unit of work) and preserve all of the database changes made by the transaction.
  • COMPACT
    Use the COMPACT command to pack table, index and dictionary files in order to reuse disk storage space.
  • CONNECT
    The CONNECT statement (embedded SQL only) connects the application process to the specified XDB Server or DB2 (through XDB Link) location. This location becomes the current location for the application process.
  • CREATE ALIAS
    The CREATE ALIAS command defines an alternate name for an existing table or view, and records the alias definition in the XDB Server system catalog at the currently set location. It is not required that the table or view be in the current location.
  • CREATE AUXILIARY TABLE
    The CREATE AUXILIARY TABLE statement creates an auxiliary table at the current server for storing LOB data.
  • CREATE DATABASE
    The CREATE DATABASE command creates a logical database structure at the currently set XDB Server location.
  • CREATE DISTINCT TYPE
    The CREATE DISTINCT TYPE statement defines a distinct type, which is a data type that a user defines. A distinct type must be sourced on one of the built-in data types. Successful execution of the statement also generates:
  • CREATE FUNCTION
    The CREATE FUNCTION statement registers a user-defined function with an application server. You can register three different types of functions with this statement, each of which is described separately.
  • CREATE FUNCTION (external scalar)
    This CREATE FUNCTION statement registers a user-defined external scalar function with an application server.
  • CREATE FUNCTION (external table)
    This CREATE FUNCTION statement registers a user-defined external table function with an application server.
  • CREATE FUNCTION (sourced)
    This CREATE FUNCTION statement registers a user-defined function that is based on an existing scalar or column function with an application server.
  • CREATE FUNCTION (SQL Scalar)
    This statement is used to define a user-defined SQL scalar function. A scalar function returns a single value each time it is invoked. Specifying a function is generally valid wherever an SQL expression is valid.
  • CREATE GLOBAL TEMPORARY TABLE
    Create a temporary table to store the intermediate results of SQL transactions. The CREATE GLOBAL TEMPORARY TABLE statement creates a description of a temporary table at the current server.
  • CREATE INDEX
    Creates an index on one or more columns of a table at the current location.
  • CREATE LOCATION
    The CREATE LOCATION command allows you to define multiple XDB Server locations under the same XDB Server. Each XDB Server location contains a set of catalog tables for that location.
  • CREATE PROCEDURE
    The CREATE PROCEDURE command defines a Stored Procedure to the SQL engine. You can then embed an SQL CALL statement in a program to invoke the stored procedure.
  • CREATE PROCEDURE
    The CREATE PROCEDURE statement defines an SQL procedure at the current server and specifies the source statements for the procedure.
  • CREATE SEQUENCE
    The CREATE SEQUENCE statement creates a sequence at the application server.
  • CREATE STOGROUP
    The CREATE STOGROUP command creates an XDB Server stogroup which associates a user-specified directory path with the named stogroup. Once the SYSIBM.SYSVOLUMES catalog table has been updated to reflect this path assignment, newly created objects can be physically stored in this directory path by designating the named stogroup when creating the objects.
  • CREATE SYNONYM
    The CREATE SYNONYM command is used to define alternate names for tables or views within the currently set location.
  • CREATE TABLE
    The CREATE TABLE statement defines a table. The definition must include its name and the names and attributes of its columns. The definition can include other attributes of the table, such as its primary key and its table space.
  • CREATE TABLESPACE
    This statement defines a table space in the current location. A table space in the XDB Server system architecture is logically compatible with DB2 table spaces. However, an XDB Server table space does not physically store XDB Server table (.TAB) files. This XDB Server interpretation of table spaces differs from a DB2 subsystem, where a table space can physically store multiple tables. Refer to the appropriate DB2 documentation for details on the mainframe implementation of table spaces.
  • CREATE TRIGGER
    The CREATE TRIGGER statement defines a trigger in a schema and builds a trigger package at the current server.
  • CREATE USER
    The CREATE USER statement enables you to create additional XDB user accounts.
  • CREATE VIEW
    The CREATE VIEW command is used to define a view or virtual table that is based on one or more tables or views. The view definition is stored at the current location. While a view does not actually contain data, it provides indirect access to data contained in the tables upon which the view is based. Views may be used to define subsets of tables, or to combine data from several tables into a logical view. Views may contain expressions that are computed from other columns, including aggregate functions such as averages, totals, etc.
  • DECLARE CURSOR
    The DECLARE CURSOR command (embedded SQL only) is used to define a cursor, which is a named control structure that points to a row in a set of records defined by a query.
  • DECLARE GLOBAL TEMPORARY TABLE
    The DECLARE GLOBAL TEMPORARY TABLE statement defines a declared temporary table for the current application process and instantiates an empty instance of the table for the process.
  • DECLARE STATEMENT
    The DECLARE STATEMENT command (embedded SQL only) identifies prepared SQL statements for later use in application programs.
  • DECLARE TABLE
    The DECLARE TABLE statement (embedded SQL only) is used for application program documentation and providing the precompiler with information for checking embedded SQL statements.
  • DELETE (Positioned)
    The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).
  • DELETE (Searched)
    The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).
  • DESCRIBE
    The DESCRIBE statement (embedded SQL only) obtains information about a previously prepared (PREPARE command) SQL statement and places this information inside an SQL Descriptor Area (SQLDA). This information is needed in dynamic SQL queries that utilize a varying-list SELECT statement. A varying-list SELECT statement is a SELECT statement where the number of columns retrieved is not known before run time. Alternatively, the DESCRIBE statement can provide information about a specified table or view.
  • DESCRIBE CURSOR
    The DESCRIBE CURSOR statement gets information about the result set that is associated with the cursor. The information, such as column information, is put into a descriptor. Use DESCRIBE CURSOR for result set cursors from stored procedures. The cursor must be defined with the ALLOCATE CURSOR statement.
  • DESCRIBE INPUT Example
  • DESCRIBE PROCEDURE
    The DESCRIBE PROCEDURE statement gets information about the result sets returned by a stored procedure. The information, such as the number of result sets, is put into a descriptor.
  • DISABLE LOGIN
    Use this command to prevent all users, except those with SYSADM privileges, from logging on to the XDB Server. This command does not affect users who are already logged on.
  • DROP
    The DROP statement removes (erases) an object from the current location. When an object is deleted, its description is also deleted from the system catalog at the current location.
  • ENABLE LOGIN
    Use this command to return a server to service after it has been taken out of service with the DISABLE LOGIN command.
  • END DECLARE SECTION
    The END DECLARE SECTION statement (embedded SQL only) marks the end of a host variable declaration block in an application program.
  • END DECLARE SECTION Example
  • EXECUTE
    The EXECUTE command (embedded SQL only) executes a previously prepared nonquery statement. To prepare and execute in one step, see the EXECUTE IMMEDIATE command.
  • EXECUTE IMMEDIATE
    The EXECUTE IMMEDIATE statement (embedded SQL only) prepares an executable statement from a character string and then immediately executes the statement.
  • EXPLAIN
    The EXPLAIN statement uses the optimizer to acquire access path selection information about SELECT, INSERT (and the searched form of UPDATE or DELETE) statements. This information is placed by the XDB Server into a table named PLAN_TABLE. The XDB Server creates this table automatically if it has not already been created by the user.
  • FETCH
    The FETCH command (embedded SQL only) positions a cursor on a row of its result table. It can return zero, one, or multiple rows and assigns the values of the rows to host variables if there is a target specification.
  • FREE LOCATOR
    The FREE LOCATOR statement removes the association between a LOB locator variable and its value.
  • GET DIAGNOSTICS
    The GET DIAGNOSTICS statement provides diagnostic information about the last SQL statement (other than a GET DIAGNOSTICS statement) that was executed. This diagnostic information is gathered as the previous SQL statement is executed. Some of the information available through the GET DIAGNOSTICS statement is also available in the SQLCA.
  • GRANT (Database Privileges)
    The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
  • GRANT (Function or Procedure Privileges)
    This form of the GRANT statement grants privileges on user-defined functions, cast functions that are generated for distinct types, and stored procedures.
  • GRANT (Table or View Privileges)
    The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
  • GRANT (Sequence Privileges)
    This form of the GRANT statement grants privileges on a user-defined sequence.
  • GRANT (System Privileges)
    The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
  • HALT QUERY FROM
    Use the HALT QUERY FROM command to terminate a running query. You can specify the query by user ID or by node name. This command is useful for canceling a query operation that is monopolizing the server computer.
  • HOLD LOCATOR
    The HOLD LOCATOR statement allows a LOB locator variable to retain its association with a value beyond a unit of work. The XDB operating environment does not support the LOB data type at this time.
  • INCLUDE
    The INCLUDE statement (embedded SQL only) inserts declarations or code into source programs from external files.
  • INSERT
    The INSERT command is an SQL command used to insert zero or more rows of data values (or records) into an existing table or view. The table or view receiving the new rows can be at the current location or any other location accessible to the XDB Server. Inserting a row into a view also inserts the row into that view's underlying table (if the view is updatable).
  • LABEL ON
    The LABEL ON statement adds or replaces descriptive text labels in the system catalog for the current location. These text labels describe tables, views, aliases, or columns existing at the current location.
  • LOCK TABLE
    The LOCK TABLE statement is used to acquire a shared or exclusive lock on a table at the current location.
  • OPEN
    The OPEN command (embedded SQL only) opens a previously declared cursor creating a result table containing row data.
  • PREPARE
    The PREPARE statement (embedded SQL only) transforms a character string form of an SQL statement into an executable form of the same statement. The resulting executable statement is known as a prepared statement, while the original character string is known as the statement string.
  • REFRESH LOCATIONS
    REFRESH LOCATIONS is an XDB Server utility command (not supported in DB2 mode) that re-reads the SYSIBM.SYSLOCATIONS catalog table and updates the system with any new location changes. The REFRESH LOCATIONS command is necessary only if a location has been manually inserted into SYSIBM.SYSLOCATIONS. If a new location is created using the CREATE LOCATION command, the system is automatically reset (and the catalog tables updated) to include the new location information.
  • REFRESH TABLE
    The REFRESH TABLE statement refreshes the data in a materialized query table. The statement deletes all rows in the materialized query table, executes the fullselect in the table definition to recalculate the data from the tables specified in the fullselect, inserts the calculated result into the materialized query table, and updates the catalog for the refresh timestamp and cardinality of the table. The table can exist at the current server or at any DB2 subsystem with which the current server can establish a connection.
  • RELEASE (connection)
    The RELEASE statement places one or more connections in the release pending state.
  • RELEASE SAVEPOINT
    The RELEASE SAVEPOINT statement releases the identified savepoint and any subsequently established savepoints within a unit of recovery.
  • RENAME
    The RENAME statement renames an existing table.
  • REVOKE (Database Privileges)
    The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
  • REVOKE (Function or Procedure Privileges)
    This form of the REVOKE statement revokes privileges on user-defined functions, cast functions that were generated for distinct types, and stored procedures.
  • REVOKE (Sequence Privileges)
    This form of the REVOKE statement revokes the privileges on a user-defined sequence.
  • REVOKE (System Privileges)
    The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
  • REVOKE (Table or View Privileges)
    The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
  • ROLLBACK
    ROLLBACK is used to mark the end of a transaction and back out of all changes made by the transaction at the current location. The XDB Server does not rollback data definition language (DDL) commands such as CREATE, DROP, ALTER; data control language (DCL) commands such as GRANT, and REVOKE; or utility commands such as SET and COPY. When working in a production environment, it is recommended that you backup your location before and after such commands.
  • ROLLFORWARD
    ROLLFORWARD allows users to roll forward the transactions stored in supplied log files to a specified location. This command must be run while in exclusive use mode.
  • SAVEPOINT
    The SAVEPOINT statement sets a savepoint within a unit of recovery to identify a point in time within the unit of recovery to which relational database changes can be rolled back.
  • SELECT
    SELECT commands (or queries) all retrieve information from data tables and display this information in a results table. For purposes of classification, SELECT commands can be subdivided into three general categories including, subselects (and subqueries), fullselects and select statements.
  • SELECT INTO
    The SELECT INTO command (embedded SQL only) retrieves one row of values from a table or view, and then assigns these values to one or more host variables specified in the SELECT INTO command statement.
  • SET AUTOCOMMIT
    The SET AUTOCOMMIT command is used to turn autocommit on or off. When autocommit is on, a command is automatically committed as soon as it is successfully executed.
  • SET COMPATIBILITY
    The SET COMPATIBILITY command is used to specify a mode of operation. When a particular mode is in effect, SQL commands must adhere to the syntax of that mode.
  • SET CONNECTION
    The SET CONNECTION statement establishes the application server of the process by identifying one of its existing connections.
  • SET CURRENT DEGREE
    This command is supported only syntactically by the XDB Server.
  • SET CURRENT LOCALE LC_CTYPE
    The SET CURRENT LOCALE LC_CTYPE statement assigns a value to the CURRENT LOCALE LC_CTYPE special register. The special register allows control over the LC_CTYPE locale for statements that use a function that refers to a locale, such as LCASE, UCASE, and TRANSLATE (with a single argument).
  • SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION
    The SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION statement changes the value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register.
  • SET CURRENT OPTIMIZATION HINT
    The SET CURRENT OPTIMIZATION HINT statement assigns a value to the CURRENT OPTIMIZATION HINT special register.
  • SET CURRENT PACKAGE PATH
    The SET CURRENT PACKAGE PATH assigns a value to the CURRENT PACKAGE PATH special register.
  • SET CURRENT PACKAGESET
    On mainframe DB2 and XDB Servers, this command assigns a value to the CURRENT PACKAGESET special register. This command is partially supported by the XDB Server, which adopts the CURRENT SQLID as the qualifier for the package.
  • SET CURRENT PATH
    The SET CURRENT PATH statement assigns a value to the CURRENT PATH special register.
  • SET CURRENT REFRESH AGE
    The SET CURRENT REFRESH AGE statement changes the value of the CURRENT REFRESH AGE special register.
  • SET CURRENT RULES
    The SET CURRENT RULES statement assigns a value to the CURRENT RULES special register.
  • SET CURRENT SQLID
    The SET CURRENT SQLID statement changes the AuthID value stored in the CURRENT SQLID special register.
  • SET Host Variable
    The SET host-variable assignment statement assigns values, either of expressions or NULL values, to host variables.
  • SET Transitional Variable
    The SET transition-variable assignment statement assigns values, either of expressions or NULL values, to transition variables.
  • SET ISOLATION
    The SET ISOLATION command is used to set the isolation level for locking in multi-user versions.
  • SET LOCATION TO
    The SET LOCATION command logs a user onto a new location, creating an implied connection between the user's sessions and the specified location. The value of the CURRENT SERVER special register is also updated to reflect the new active location.
  • SET LOCATION
    Use this command to prevent all users, except for those with SYSADM privileges, from logging on to a location on the XDB Server. This command does not affect users who are already using the location.
  • SET LOG
    The SET LOG command allows Database Administrators (with SYSADM authority or higher) to suspend logging system operation during an administrative session, and change the path where location log files are stored.
  • SET SCHEMA
    The SET SCHEMA statement assigns a value to the CURRENT SCHEMA special register. If the package is bound with the DYNAMICRULES BIND option, this statement does not affect the qualifier that is used for unqualified database object references.
  • SET SORTSPACE
    Use this command to dynamically reset the size of the sort space on the XDB Server. Active sorts are not affected by this command.
  • SHUTDOWN
    Use the SHUTDOWN command to close the XDB Server program at a specified time. You can also use a variant of this command to cancel a SHUTDOWN request that you have issued.
  • SIGNAL SQLSTATE
    The SIGNAL SQLSTATE statement is used to signal an error. It causes an error to be returned with the specified SQLSTATE and error description.
  • START DATABASE
    The START DATABASE command allows users access to the contents of a named database.
  • START PROCEDURE
    The START PROCEDURE command checks the argument list for a stored procedure already defined to the SQL engine. If the stored procedure meta-data has been imported from another system, this command can be used to check that the argument list is compatible with XDB syntax rules.
  • STOP DATABASE
    The STOP DATABASE command restricts all access to the named database.
  • TRUNCATE TABLE
    The TRUNCATE TABLE command performs the same function as the DELETE command, except TRUNCATE TABLE removes all records from a table without recording the changes in the Forward and Backward Log files.
  • UNLOCK TABLE
    UNLOCK TABLE is used in multi-user versions to release table locks acquired using the LOCK TABLE command.
  • UPDATE (Searched)
    The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.
  • UPDATE (Positioned)
    The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.
  • VALUES
    The VALUES statement provides a method for invoking a user-defined function from a trigger. Transition variables and transition tables can be passed to the user-defined function.
  • VALUES INTO
    The VALUES INTO statement assigns one or more values to host variables.
  • WHENEVER
    The WHENEVER statement (embedded SQL only) has three different forms, each of which changes the execution of a host language program according to the occurrence of specified exception conditions.
Parent topic: SQL Reference


ALLOCATE CURSOR

The ALLOCATE CURSOR statement defines a cursor and associates it with a result set locator variable.

Invocation

This statement can be embedded in an application program. It is an executable statement that can be dynamically prepared. It cannot be issued interactively.

Authorization

No authorization is required for this statement.

Syntax

ALLOCATE CURSOR cursor-name
CURSOR FOR RESULT SET rs-locator-variable

Parameters:

cursor-name | Names the cursor. The name must not identify a cursor that has already been declared in the source program.
rs-locator-variable | Names a result set locator variable that has been declared in the application program. The result set locator variable must contain a valid result set locator value, as returned by the ASSOCIATE LOCATORS or DESCRIBE PROCEDURE statements. In the ALLOCATE CURSOR statement, rs-locator-variable is always a host variable.

Description

When an ALLOCATE CURSOR statement is dynamically prepared, the EXECUTE statement with the USING clause must be used to execute the prepared statement. As with all dynamically prepared statements, parameter markers (question marks) must appear where the host variables would appear in the prepared statement. The USING clause of the EXECUTE statement should specify the host variables for which the values are to be substituted for the parameter markers in the dynamically prepared ALLOCATE CURSOR statement.

You cannot use a statement identifier for an ALLOCATE CURSOR statement if the same statement identifier has been used for a DECLARE CURSOR statement.

The following rules apply when you use an allocated cursor:

  • For this statement to be successful, an application must be currently connected to the site where the stored procedure was executed.
  • You cannot open an allocated cursor by using the SQL OPEN cursor statement.
  • You can close an allocated cursor by using the SQL CLOSE cursor statement. This closes the cursor in the stored procedure as well.
  • You can allocate only one cursor to each result set.

Rollback, and an implicit and explicit close destroy allocated cursors. A commit destroys allocated cursors that are not defined WITH HOLD by the stored procedure. Destroying an allocated cursor closes the associated cursor in the stored procedure.

Parent topic: SQL Statements


ALTER DATABASE

The ALTER DATABASE statement changes the description of the specified database under the currently set XDB Server location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER DATABASE command, users must possess either DBADM or DBCTRL authority for the database, DROP privilege on the database, overall SYSADM or SYSCTRL authority for the location, or be the owner of the database affected.

Syntax

ALTER DATABASE database-name

[BUFFERPOOL bpname]
    [INDEXBP bpname]
    [STOGROUP stogroup-name]
    [CCSID ccsid-value]

Parameters:

database-name | Identifies the database to be altered. The database must exist within the currently set location.
BUFFERPOOL bpname | Identifies the default buffer pool for the table spaces within the database. It does not apply to table spaces that already exist within the database. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9 If the database is a work file database, 8KB and 16KB buffer pools cannot be specified.
INDEXBP bpname | Identifies the default buffer pool for the indexes within the database. It does not apply to indexes that already exist within the database. The name must identify a 4KB buffer pool. INDEXBP cannot be specified for a work file database.
stogroup-name | Identifies an optional stogroup for this database, if stogroups are used.
ccsid-value | Identifies the default CCSID for table spaces within the database. It does not apply to existing table spaces in the database. ccsid-value must identify a CCSID value that is compatible with the current value of the CCSID for the database. CCSID cannot be specified for a work file data base or a TEMP database.

Description

The ALTER DATABASE command offers users the option of assigning a stogroup designation to a logical database. This command can also specify whether or not the database is used as a Read-Only Shared database.

BUFFERPOOL

This clause has no functional equivalent in the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, BP32K, BPK1...BPK9). The first fifty bufferpools are for tables with 4K page sizes, while the last ten are for tables with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server catalog tables.

CCSID

This clause has no functional equivalent in the XDB Server operating environment.

STOGROUP

This clause allows the user to change the default stogroup to which all objects created under this database will be physically stored. This clause does not affect the storage locations of tables and indexes already created under the database. On an XDB Server, a stogroup designates a particular drive (and/or directory) on which all objects created under a logical database are physically stored. A stogroup is usually assigned to a database, or table space within a database, when these objects are created.

Example:

Change the default buffer pool for both table spaces and indexes within database ABCDE to BP2.

ALTER DATABASE ABCDE
    BUFFERPOOL BP2
    INDEXBP BP2;
Parent topic: SQL Statements


ALTER FUNCTION

The ALTER FUNCTION statement changes the description of an external scalar or external table function at the current server.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER FUNCTION command, users must possess either overall SYSADM or SYSCTRL authority for the location, or be the owner of the function affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER FUNCTION function-name [(parameter-type[,...])] |
SPECIFIC FUNCTION specific-name
    [EXTERNAL NAME {'string' | identifier}]
    [LANGUAGE {ASSEMBLE | C | COBOL | PLI}]
    [[NOT] DETERMINISTIC]
    [{RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT}]
    [{CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA | NO SQL}]
    [[NO] EXTERNAL ACTION]
    [{NO SCRATCHPAD | SCRATCHPAD length}]
    [[NO] FINAL CALL]
    [{ALLOW PARALLEL | DISALLOW PARALLEL}]
    [[NO] DBINFO]
    [CARDINALITY integer]
    [{NO COLLID | COLLID collection-id}]
    [WLM ENVIRONMENT {name | (name,*)}]
    [ASUTIME {NO LIMIT | LIMIT integer}]
    [STAY RESIDENT {NO | YES}]
    [PROGRAM TYPE {SUB | MAIN}]
    [SECURITY {DB2 | USER | DEFINER}]
    [STOP AFTER SYSTEM DEFAULT FAILURES |
      STOP AFTER integer FAILURES |
      CONTINUE AFTER FAILURE]
    [RUN OPTIONS run-time-options]

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE table-name as LOCATOR}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

[SMALLINT]
[INTEGER | INT]
[{DECIMAL | DEC | NUMERIC} [(integer[,...])]
[{FLOAT [(integer)] | REAL [PRECISION] | DOUBLE}]
[{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) } [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | I} |[{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
    {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] }]
[{BINARY LARGE OBJECT | BLOB} [(integer [K|M|G])]]
[{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB [(integer [K|M|G])] } [CCSID {EBCDIC | ASCII}]]
[DATE | TIME | TIMESTAMP]
[ROWID]

Description

One of the following three clauses identifies the function to be changed.

FUNCTION function-name

Identifies the external function by its function name. The name is implicitly or explicitly qualified with a schema name. If the name is not explicitly qualified, it is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is prepared dynamically, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The identified function must be an external function. There must be exactly one function with function-name in the schema. The function can have any number of input parameters. If the schema does not contain a function with function-name or contains more than one function with this name, an error occurs.

FUNCTION function-name (parameter-type,...)

Identifies the external function by its function signature, which uniquely identifies the function.

function-name | gives the function name of the external function. If the function name is not qualified, it is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.
(parameter-type,...) | identifies the number of input parameters of the function and their data types.

The data type of each parameter must match the data type that was specified in the CREATE FUNCTION statement for the parameter in the corresponding position. The number of data types and the logical concatenation of the data types are used to uniquely identify the function. Therefore, you cannot change the number of parameters or the data types of the parameters.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match.FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).
  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.
  • The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:
    CHAR | CHAR(1)
    GRAPHIC | GRAPHIC(1)
    DECIMAL | DECIMAL(5,0)
    FLOAT | DOUBLE (length of 8)

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement

For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that XDB ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

A function with the function signature must exist in the explicitly or implicitly specified schema; otherwise, an error occurs.

SPECIFIC FUNCTION specific-name

Identifies the external function by its specific name. The name is implicitly or explicitly qualified with a schema name. A function with the specific name must exist in the schema; otherwise, an error occurs.

If the specific name is not qualified, it is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.

The following clauses change the description of the function that has been identified to be changed.

EXTERNAL NAME 'string' or identifier

Identifies the name of the module that contains the user-written code that implements the logic of the function. The external program name can be a string constant that is no longer than 8 characters or a short identifier.

The module is created when the program that contains the function body is compile . The module does not need to exist when the ALTER FUNCTION statement is executed. However, it must exist and be accessible by the current server when the function is invoked.

LANGUAGE

Specifies the application programming language in which the function is written. All programs must be designed to run in IBM's Language Environment environment .

ASSEMBLE | The function is written in Assembler. (Not currently available with XDB Server)
C | The function is written in C or C++. (Not currently available with XDB Server)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PL/I | The function is written in PL/I. (Not currently available with XDB Server)

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the function returns the same results for identical input arguments.

NOT DETERMINISTIC The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements.

Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.

If a view or a materialized query table definition refers to the function, the function cannot be changed to NOT DETERMINISTIC. To change the function, drop any views or materialized query tables that refer to the function first.

DETERMINISTIC The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input.

XDB does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

RETURNS NULL ON NULL INPUT or CALLED ON NULL INPUT

Specifies whether the function is called if any of the input arguments is null at execution time.

RETURNS NULL ON NULL INPUT | The function is not called if any of the input arguments is null. For an external scalar function, the result is the null value. For an external table function, the result is an empty table, which is a table with no rows.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. For an external scalar function, the function can return a null or nonnull value. For an external table function, the function can return an empty table, depending on its logic.

NO SQL, MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL

Indicates whether the function issues any SQL statements and, if so, what type.

NO SQL | The function cannot execute any SQL statements.
MODIFIES SQL DATA | The function can execute any SQL statement except those statements that are not supported in any function. Do not specify MODIFIES SQL DATA for external table functions or with ALLOW PARALLEL.
READS SQL DATA | The function cannot execute SQL statements that modify data. SQL statements that are not supported in any function return a different error.
CONTAINS SQL | The function cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.

NO EXTERNAL ACTION or EXTERNAL ACTION

This clause has no functional equivalent in the XDB Server operating environment.

NO SCRATCHPAD or SCRATCHPAD

Specifies whether XDB provides a scratchpad for the function. It is strongly recommended that external functions be reentrant, and a scratchpad provides an area for the function to save information from one invocation to the next.

NO SCRATCHPAD A scratchpad is not allocated and passed to the function.
SCRATCHPAD When the function is invoked for the first time, XDB allocates memory for a scratchpad. A scratchpad has the following characteristics:
  • Length must be between 1 and 32767. The default value is 100 bytes.
  • XDB initializes the scratchpad to all binary zeros (X'00's).
  • The scope of a scratchpad is the SQL statement. For each reference to the function in an SQL statement, there is one scratchpad. For example, assuming that function UDFX was defined with the SCRATCHPAD keyword, three scratchpads are allocated for the three references to UDFX in the following SQL statement:
    SELECT A, UDFX(A) FROM TABLEB WHERE UDFX(A) > 103 OR UDFX(A) < 19;

    If the function is run under parallel tasks, one scratchpad is allocated for each parallel task of each reference to the function in the SQL statement. This can lead to unpredictable results. For example, if a function uses the scratchpad to count the number of times that it is invoked, the count reflects the number of invocations done by the parallel task and not the SQL statement. Specify the DISALLOW PARALLEL clause for functions that do not work correctly with parallelism.

  • The scratchpad is persistent. XDB preserves its content from one invocation of the function to the next. Any changes that the function makes to the scratchpad on one call are still there on the next call. XDB initializes the scratchpads when it begins to execute an SQL statement. XDB does not reset scratchpads when a correlated subquery begins to execute.
  • The scratchpad can be a central point for the system resources that the function acquires. If the function acquires system resources, specify FINAL CALL to ensure that XDB calls the function one more time so that the function can free those system resources.

Each time that the function is invoked, XDB passes an additional argument to the function that contains the address of the scratchpad.

NO FINAL CALL or FINAL CALL

Specifies whether a final call is made to the function. A final call enables the function to free any system resources that it has acquired. A final call is useful when the function has been defined with the SCRATCHPAD keyword and the function acquires system resource and anchors them in the scratchpad.

The effect of NO FINAL CALL or FINAL call depends on whether the external function is a scalar function or a table function.

For an external scalar function:

NO FINAL CALL

A final call is not made to the external scalar function. The function does not receive an additional argument that specifies the type of call.

FINAL CALL

A final call is made to the external scalar function. See the following description of call types for the characteristics of a final call. When FINAL CALL is specified, the function receives an additional argument that specifies the type of call to enable the function to differentiate between a final call and another type of call.

For an external table function:

NO FINAL CALL

A first and final call are not made to the external table function.

FINAL CALL

A first call and final call are made to the external table function in addition to one or more other types of calls.

ALLOW or DISALLOW PARALLEL

This clause has no functional equivalent in the XDB Server operating environment.

NO DBINFO or DBINFO

Specifies whether specific information that XDB knows is passed to the function when it is invoked.

NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function. For details about the argument and its structure, see your DB2 Application Programming and SQL Guide.

CARDINALITY integer

Specifies an estimate of the expected number of rows that the function returns. The number is used for optimization purposes. The value of integer must range from 0 to 2147483647.

If a function has an infinite cardinality--the function never returns the "end-of-table" condition and always returns a row, then a query that requires the "end-of-table" to work correctly, will need to be interrupted. Thus, avoid using such functions in queries that involve GROUP BY and ORDER BY.

Do not specify CARDINALITY for external scalar functions.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the function is executed.

NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of the function can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a function, setting a limit can be helpful if the function gets caught in a loop.

NO LIMIT | There is no limit on the service units.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the load module for the function remains resident in memory when the function ends.

NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the function program runs as a main routine or a subroutine.

SUB | The function runs as a subroutine.
MAIN | The function runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures. The following options must not be specified for SQL functions or sourced functions.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

Note:

Changes are immediate: Any changes that the ALTER FUNCTION statement causes to the definition of an external function take effect immediately. The changed definition is used the next time that the function is invoked.

Examples:

Assume that there are two functions CENTER in the PELLOW schema. The first function has two input parameters with INTEGER and FLOAT data types, respectively. The specific name for the first function is FOCUS1. The second function has three parameters with CHAR(25), DEC(5,2), and INTEGER data types.

Using the specific name to identify the function, change the WLM environment in which the first function runs from WLMENVNAME1 to WLMENVNAME2.

ALTER SPECIFIC FUNCTION PELLOW.FOCUS1 WLM ENVIRONMENT WLMENVNAME2;

Change the second function that is described above so that it is not invoked when any of the arguments are null. Use the function signature to identify the function,

 ALTER FUNCTION PELLOW.CENTER (CHAR(25), DEC(5,2), INTEGER)
     RETURNS NULL ON NULL INPUT;

You can also code the ALTER FUNCTION statement without the exact values for the CHAR and DEC data types:

 ALTER FUNCTION PELLOW.CENTER (CHAR(), DEC(), INTEGER)
     RETURNS NULL ON NULL INPUT;

If you use empty parentheses, XDB ignores the length, precision, and scale attributes when looking for matching data types to find the function.

Parent topic: SQL Statements


ALTER FUNCTION (SQL)

The ALTER FUNCTION (SQL) statement changes the description of a user-defined SQL scalar function at the current server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set defined below must include at least one of the following:

  • Ownership of the function
  • The ALTERIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the ALTERIN privilege on the schema.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the authorization IDs of the process. The specified function name can include a schema name (a qualifier). However, if the schema name is not the same as one of these authorization IDs, one of the following conditions must be met:

  • The privilege set includes SYSADM or SYSCTRL authority.
  • An authorization ID of the process has the ALTERIN privilege on the schema.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER {FUNCTION function-name [(parameter-type[,...])] |
    SPECIFIC FUNCTION specific-name}
    option-list

parameter-type

{data-type [AS LOCATOR] | TABLE LIKE table-name AS LOCATOR}

data-type

{built-in-type | distinct-type-name}

built-in-type

[SMALLINT]
[INTEGER | INT]
[DECIMAL | DEC | NUMERIC} [(5,0) | (integer [,integer])]
[FLOAT [(53) | (integer)] | REAL [PRECISION] | DOUBLE}]
[{{CHARACTER | CHAR} [(1) | (integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] |
    {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(1M) | (integer [K | M | G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] }]
[{GRAPHIC [(1) | (integer)] | VARGRAPHIC (integer) | DBCLOB [(1M) | (integer [K | M | G])]}
    [CCSID {ASCII | EBCDIC | UNICODE}]]
[{BINARY LARGE OBJECT | BLOB} [(1M) | (integer [K | M | G])]]
[DATE | TIME | TIMESTAMP]
[ROWID]

option-list

LANGUAGE SQL
    [DETERMINISTIC | NOT DETERMINISTIC]
    [EXTERNAL ACTION | NO EXTERNAL ACTION]
    [CONTAINS SQL | READS SQL DATA]
    [STATIC DISPATCH CALLED ON NULL INPUT]
Parent topic: SQL Statements


ALTER INDEX

On a mainframe DB2 subsystem, this statement changes the configuration of an existing index. See the ALTER TABLE command for information on altering indexes that result from UNIQUE, PRIMARY and FOREIGN keys. In some cases, it may be necessary to drop an index and re-create it using the DROP INDEX and CREATE INDEX commands.

Invocation

When issued against an XDB Server, this statement only supports the ADD COLUMN clause, but is fully supported when issued against a DB2 database through XDB Link.

Syntax

ALTER INDEX index-name
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [COPY {YES | NO}]
    [DSETPASS password]
    [PART integer]
    [FREEPAGE integer]
    [PCTFREE integer]
    [USING {VCAT catalog-name
            | STOGROUP stogroup-name}]
    [PRIQTY {3 | integer}]
    [SECQTY {3 | integer}]
    [ERASE {YES | NO}] [GBPCACHE {CHANGED | ALL}]
    [CONVERT TO {TYPE 1 [SUBPAGES {4 | 1 | 2 | 8 | 16}] | TYPE 2}]
    [PIECESIZE integer {K | M | G}]
    [PART integer [VALUES (constant[,...])]
        [[using-block | free-block | gbpcache-block][...]][,...]]
    [{CLUSTER | NOT CLUSTER}]
    [{PADDED | NOT PADDED}]
    [ADD COLUMN (column-name [{ASC | DESC}] )]

Parameters:

bpname A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.

Description

index-name

Identifies the index to be altered. The name must identify a user-created index that exists at the current server. The name must not identify an index that is defined on a declared temporary table.

BUFFERPOOL

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, BP32K, BPK1...BPK9). The first fifty bufferpools are for indexes with 4K page sizes, while the last ten are for indexes with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server catalog tables.

COPY

Indicates whether the COPY utility is allowed for the index.

NO | Does not allow full image or concurrent copies or the use of the RECOVER utility on the index.
YES | Allows full image or concurrent copies and the use the RECOVER utility on the index.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

PIECESIZE integer

Specifies the maximum addressability of each piece (data set) for a nonpartitioning index. Be very aware that when you alter the PIECESIZE value, the index is placed into REBUILD-pending (PSRBD) status and the entire index space becomes inaccessible. You must run the REBUILD INDEX or the REORG TABLESPACE utility to remove that status.

The subsequent keyword K, M, or G, indicates the units of the value specified in integer.

K | Indicates that the integer value is to be multiplied by 1 024 to specify the maximum piece size in bytes. The integer must be a power of two between 256 and 67 108 864.
M | Indicates that the integer value is to be multiplied by 1 048 576 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 65 536.
G | Indicates that the integer value is to be multiplied by 1 073 741 824 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 64

The piece size limit for partitioned table spaces with more than 254 partitions is 4096.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

Using Block for Nonpartitioning Indexes

For nonpartitioning indexes, the USING clause specifies whether the data sets for the index are to be managed by the user or managed by DB2. The USING clause applies to every data set that can be used for the index. (A nonpartitioning index can have more than one data set if PRIQTY+118 * SECQTY is at least 2 gigabytes.)

If you specify USING, the index must be in the stopped state when the ALTER INDEX statement is executed.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

USING Block for Partitioning Indexes:

For a partitioning index, there is an optional PART clause for each partition. A using-block can be specified at the global level or at the partition level. A using-block within a PART clause applies only to that partition. A using-block specified before any PART clauses applies to every partition except those with a PART clause with a using-block.

For DB2-managed data sets, the values of PRIQTY, SECQTY, and ERASE for each partition are given by the first of these choices that applies:

  • The values of PRIQTY, SECQTY, and ERASE given in the using-block within the PART clause for the partition. Do not use more than one using-block in any PART clause.
  • The values of PRIQTY, SECQTY, and ERASE given in a using-block before any PART clauses
  • The current values of PRIQTY, SECQTY, and ERASE

For data sets that are being changed from user-managed to DB2-managed, the values of PRIQTY, SECQTY, and ERASE for each partition are given by the first of these choices that applies:

  • The values of PRIQTY, SECQTY, and ERASE given in the using-block within the PART clause for the partition. Do not use more than one using-block in any PART clause.
  • The values of PRIQTY, SECQTY, and ERASE given in a using-block before any PART clauses
  • The default values of PRIQTY, SECQTY, and ERASE, which are:

    PRIQTY 12

    SECQTY 12, if PRIQTY is not specified in either using-block, or 10% of PRIQTY or 3 times the index page size (whichever is larger) when PRIQTY is specified

    ERASE NO

Any partition for which USING or ERASE is specified (either explicitly at the partition level or implicitly at the global level) must be in the stopped state when the ALTER INDEX statement is executed.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

VCAT catalog-name

Specifies a user-managed data set with a name that starts with the specified catalog name. You must specify the catalog name in the form of a short identifier. Thus, you must specify an alias if the name of the integrated catalog facility catalog is longer than eight characters.

If n is the number of the partition, the identified integrated catalog facility catalog must already contain an entry for the nth data set of the index. Refer to appropriate DB2 documentation for a full explanation of DB2 naming conventions for data sets.

One or more DB2 subsystems could share integrated catalog facility catalogs with the current server. To avoid the chance of having one of those subsystems attempt to assign the same name to different data sets, select a value for catalog-name that is not used by the other DB2 subsystems.

DB2 assumes one and only one data set for each partition.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

STOGROUP stogroup-name

If USING STOGROUP is used, stogroup-name must identify a storage group that exists at the current server and the privilege set must include SYSADM authority, SYSCTRL authority, or the USE privilege for the storage group.

DB2 assumes one and only one data set for each partition.

Omitting or specifying -1 for the PRIQTY or SECQTY clause implicitly specifies the default value for that clause. For more information on the PRIQTY, SECQTY, and ERASE clauses, see the description of those clauses for nonpartitioning indexes.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

FREEPAGE integer

Specifies how often to leave a page of free space when index entries are created as the result of executing a DB2 utility. One free page is left for every integer pages. The value of integer can range from 0 to 255. The change to the description of the index or partition has no effect until it is loaded or reorganized using a DB2 utility.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

PCTFREE integer

Determines the percentage of free space to leave in each nonleaf page and leaf page when entries are added to the index or partition as the result of executing a DB2 utility. The first entry in a page is loaded without restriction. When additional entries are placed in a nonleaf or leaf page, the percentage of free space is at least as great as integer.

The value of integer can range from 0 to 99, however, if a value greater than 10 is specified, only 10 percent of free space will be left in nonleaf pages. The change to the description of the index or partition has no effect until it is loaded or reorganized using a DB2 utility.

If the index is partitioning, the values of FREEPAGE and PCTFREE for a particular partition are given by the first of these choices that applies:

  • The values of FREEPAGE and PCTFREE given in the PART clause for that partition. Do not use more than one free-block in any PART clause.
  • The values given in a free-block before any PART clauses.
  • The current values of FREEPAGE and PCTFREE for that partition.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

GBPCACHE

Specifies what index pages are written to the group buffer pool in a data sharing environment. In a non-data-sharing environment, you can specify this option, but it is ignored.

CHANGED | When there is inter-DB2 R/W interest on the index or partition, updated pages are written to the group buffer pool. When there is no inter-DB2 R/W interest, the group buffer pool is not used. Inter-DB2 R/W interest exists when more than one member in the data sharing group has the index or partition open, and at least one member has it open for update. If the index is in a group buffer pool that is defined as GBPCACHE(NO), CHANGED is ignored and no pages are cached to the group buffer pool.
ALL | Indicates that pages are to be cached to the group buffer pool as they are read in from DASD, with one exception. When the page set is not GBP-dependent and one DB2 data sharing member has exclusive R/W interest in that page set (no other group members have any interest in the page set), no pages are cached in the group buffer pool. Hiperpools are not used for indexes or partitions that are defined with GBPCACHE ALL. If the index is in a group buffer pool that is defined as GBPCACHE(NO), ALL is ignored and no pages are cached to the group buffer pool.
NONE | Indicates that no pages are to be cached to the group buffer pool. DB2 uses the group buffer pool only for cross-invalidation. If you specify NONE, the index or partition must not be in group buffer pool recover pending (GRECP) status.

If the index is partitioned, the value of GBPCACHE for a particular partition is given by the first of these choices that applies:

  1. The value of GBPCACHE given in the PART clause for that partition. Do not use more than one gbpcache-block in any PART clause.
  2. The value given in a gbpcache-block before any PART clauses.
  3. The current value of GBPCACHE for that partition.

If you specify GBPCACHE in a data sharing environment, the index or partition must be in the stopped state when the ALTER INDEX statement is executed. You cannot alter the GBPCACHE value for the following indexes on catalog table SYSIBM.SYSINDEXES: DSNDXX01, DSNDXX02, DSNDXX03.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

PART integer

Identifies a partition of the index. For an index that has n partitions, you must specify an integer in the range 1 to n. You must not use this clause if the index is nonpartitioned. You must use this clause if the index is partitioned and you specify the VALUES clause.

VALUES(constant,...) Specifies the highest value of the index key for the identified partition of the partitioning index. In this context, highest means highest in the sorting sequences of the index columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC), the lowest actual value is highest in the sorting sequence.

You must use at least one constant after VALUES in each PART clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition of the index. The length of each highest key value (also called the limit key) is the same as the length of the partitioning index.

The use of the constants to define key values is subject to these rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must have the same data type as its corresponding column.
  • If a key includes a ROWID column (or a column with a distinct type that is sourced on a ROWID data type), the values of the ROWID column are assumed to be in the range of X'000...00' to X'FFF...FF'. Only the first 17 bytes of the constant that is specified for the corresponding ROWID column are considered.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'; if the column is descending, the padding character is X'00'.
  • Using fewer constants than there are columns in the key has the same effect as using the highest possible values for all omitted columns for an ascending index. For a descending index, it has the same effect as using the lowest possible values for all omitted columns.
  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition.
  • The highest value of the key in the last partition depends on how the table space was defined. For table spaces created without the LARGE or DSSIZE option, the constants you specify after VALUES are not enforced. The highest value of the key that can be placed in the table is the highest possible value of the key.For table spaces created with the LARGE or DSSIZE options, the constants you specify after VALUES are enforced. The value specified by the constants is the highest value of the key that can be placed in the table. Any keys that are made invalid after the ALTER statement is executed are placed in a discard data set when you run REORG. If the last partition is in REORG pending, regardless of whether you changed its limiting key values, you must specify a discard data set when you run REORG.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

CLUSTER or NOT CLUSTER

Specifies whether the index is the clustering index for the table.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

CLUSTER

The index is used as the clustering index for the table. This change takes effect immediately. Any subsequent INSERT statements will use the new clustering index. Existing data remains clustered by the previous clustering index until the table space is reorganized.

The implicit or explicit clustering index is ignored when data is inserted into a table space that is defined with MEMBER CLUSTER. Instead of using cluster order, DB2 chooses where to locate the data based on available space. The MEMBER CLUSTER attribute affects only data that is inserted with the INSERT statement; data is always loaded and reorganized in cluster order.

Do not specify CLUSTER if the table is an auxiliary table or if CLUSTER was used already for a different index on the table.

NOT CLUSTER

The index is not used as the clustering index of the table. If the index is already defined as the clustering index, it continues to be used as the clustering index by DB2 and the REORG utility until clustering is explicitly changed by specifying CLUSTER for a different index.

Specifying NOT CLUSTER for an index that is not a clustering index is ignored.

If the index is the partitioning index for a table that uses index-controlled partitioning, the table is converted to use table-controlled partitioning. The high limit key for the last partition is set to the highest possible value for ascending key columns or the lowest possible value for descending key columns.

NOT PADDED or PADDED

Specifies how varying-length string columns are to be stored in the index. If the index contains no varying-length columns, this option is ignored, and a warning message is returned.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

NOT PADDED

Specifies that varying-length string columns are not to be padded to their maximum length in the index. The length information for a varying-length column is stored with the key.

NOT PADDED is ignored and has no effect if the index is on an auxiliary table. Indexes on auxiliary tables are always padded.

When PADDED is changed to NOT PADDED, the index key length is recalculated with the varying-length formula (2000 - n - 2m, where n is the number of columns that can contain null values and m is the number of varying-length columns in the key). If it is possible that the index key length may exceed the maximum length (because before when it was padded, the formula 2000 - n was used), an error occurs.

PADDED

Specifies that varying-length string columns within the index are always padded with the default pad character to their maximum length.

When an index with at least one varying-length column is changed from PADDED to NOT PADDED, or vice versa, the index is placed in restricted REBUILD-pending status (RBDP). The index cannot be accessed until it is rebuilt from the table (REBUILD INDEX, REORG TABLESPACE, or LOAD REPLACE utility). For nonpartitioned secondary indexes (NPSIs), the index is placed in page set REBUILD-pending status (PSRBD), and the entire index must be rebuilt. In addition, plans and packages that are dependent on the table are quiesced, and dynamically cached statements that are dependent on the index are invalidated.

ADD COLUMN column-name

Adds column-name to the index. column-name must be unqualified, must identify a column of the table, must not be one of the existing columns of the index, and must not be a LOB column or a distinct type column based on a LOB data type. The total number of columns for the index cannot exceed 64.

For PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000 - n, where n is the number of columns that can contain null values.

For NOT PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000 - n -2m, where n is the number of nullable columns and m is the number of varying-length columns.

The index cannot be any of the following types of indexes:

  • A system-defined catalog index
  • An index that enforces a primary key, unique key, or referential constraint
  • A partitioning index when index-controlled partitioning is being used
  • A unique index required for a ROWID column defined as GENERATED BY DEFAULT
  • An auxiliary index

If the column is added to the table and that same column is added to an associated index within the same commit scope and within that commit scope no data rows were inserted, the index is left in advisory REORG-pending (AREO*) state; otherwise, the index is left in REBUILD-pending (RBDP) state.

  • ASC - Index entries are put in ascending order by the column.
  • DESC - Index entries are put in descending order by the column.

Examples:

Alter the index DSN8610.XEMP1. Indicate that XDB is not to close the data sets that support the index when there are no current users of the index.

 ALTER INDEX DSN8610.XEMP1
     CLOSE NO;

Alter the index DSN8610.XPROJ1. Use BP1 as the buffer pool that is to be associated with the index, indicate that full image or concurrent copies on the index are allowed, and change the maximum size of each data set to 8 megabytes.

 ALTER INDEX DSN8610.XPROJ1
     BUFFERPOOL BP1
     COPY YES
     PIECESIZE 8M;
Parent topic: SQL Statements


ALTER LOCATION

The ALTER LOCATION statement converts (upgrades) a location to DB2 Version 6, 7 or 8 compatibility.

Note:

By default, XDB Server creates locations that are compatible with DB2 Version 6, 7 or 8.

Invocation

ALTER LOCATION is an executable command that can be issued interactively, embedded in a host language or dynamically prepared.

Authorization

To execute the ALTER LOCATION command, users must have INSTALL or SYSADM privileges.

Syntax

ALTER LOCATION location-name TO {VERSION {V41 | V51 | V60 | V71 | V80} | SORT SEQUENCE language-name EBCDIC}

Parameters:

location-name

Identifies the location to be converted.

  • swedish
  • classic
  • dutch
  • french
  • spanish
  • italian
  • uk
  • danish
  • norwegian
  • finnish
  • german
  • austrian
  • portuguese
  • us
  • international
  • turkish

Description

You can use most DB2 Version 7.0 and Version 8.0 features without converting your existing XDB Server locations. However, you cannot use new DDL-related features without upgrading. Once you convert a location to DB2 Version 7.0 and Version 8.0 compatibility, you cannot use it with an earlier version of the XDB Server.

Example:

alter location jbl to sort sequence german ebcdic;
Parent topic: SQL Statements


ALTER PASSWORD

The ALTER PASSWORD statement enables you to change passwords.

Syntax

ALTER PASSWORD old_password TO new_password
Parent topic: SQL Statements


ALTER PROCEDURE (external)

The ALTER PROCEDURE statement changes the description of a stored procedure at the current server.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER PROCEDURE command, users must possess either overall SYSADM or SYSCTRL authority for the location, or be the owner of the stored procedure affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER PROCEDURE procedure-name
    [DYNAMIC RESULT {SET | SETS} integer]
    [EXTERNAL NAME {'string' | indentifier}]
    [LANGUAGE {ASSEMBLE | C | COBOL | COMPJAVA | PLI | REXX}]
    [PARAMETER STYLE {DB2SQL | GENERAL | GENERAL WITH NULLS | JAVA}]
    [{DETERMINISTIC | NOT DETERMINISTIC}]
    [{CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA | NO SQL}]
    [{DBINFO | NODBINFO}]
    [{NO COLLID | COLLID collection-id}]
    [{WLM ENVIRONMENT {name | (name,*)}} | NO WLM ENVIRONMENT}]
    [ASUTIME {NO LIMIT | LIMIT integer}]
    [STAY RESIDENT {NO | YES}]
    [PROGRAM TYPE {SUB | MAIN}]
    [SECURITY {DB2 | USER | DEFINER}]
    [RUN OPTIONS run-time-options]
    [COMMIT ON RETURN {NO | YES}]
    [CALLED ON NULL INPUT]
    [{STOP AFTER SYSTEM DEFAULT FAILURES |
     STOP AFTER integer FAILURES |
     CONTINUE AFTER FAILURE}]

Description

procedure-name

Identifies the stored procedure to be altered. The name is implicitly or explicitly qualified by a schema name. If the name is not explicitly qualified, it is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

DYNAMIC RESULT SET integer or DYNAMIC RESULT SETS integer

Specifies the maximum number of query result sets that the stored procedure can return. The value must be between 0 and 32767.

EXTERNAL NAME 'string' or identifier

Identifies the program that runs when the procedure name is specified in a CALL statement.

The name can be a string constant that is no longer than 8 characters or a short identifier.

The program does not need to exist when the ALTER PROCEDURE statement is executed. However, it must exist and be accessible by the current server when a CALL statement for the stored procedure is issued.

LANGUAGE

Specifies the application programming language in which the stored procedure is written. Assembler, C, COBOL, and PL/I programs must be designed to run in IBM's Language Environment.

ASSEMBLE | The stored procedure is written in Assembler. (Not currently available with XDB Server.)
C | The stored procedure is written in C or C++. (Not currently available with XDB Server.)
COBOL | The stored procedure is written in COBOL, including the OO-COBOL language extensions.
COMPJAVA | The stored procedure is written in Java and is a compiled program. (Not currently available with XDB Server.)
PL/I | The stored procedure is written in PL/I. (Not currently available with XDB Server.)
REXX | The stored procedure is written in REXX. Do not specify LANGUAGE REXX when PARAMETER STYLE DB2SQL or NO WLM ENVIRONMENT is in effect. (Not currently available with XDB Server.)

PARAMETER STYLE

Identifies the linkage convention used to pass parameters to the stored procedure. All of the linkage conventions provide arguments to the stored procedure that contain the parameters specified on the CALL statement. Some of the linkage conventions pass additional arguments to the stored procedure that provide more information to the stored procedure. For more information on linkage conventions, refer to appropriate DB2 documentation for a full explanation.

DB2SQL In addition to the parameters on the CALL statement, the following arguments are also passed to the stored procedure:
  • A null indicator for each parameter on the CALL statement
  • The SQLSTATE to be returned to DB2
  • The qualified name of the stored procedure
  • The specific name of the stored procedure
  • The SQL diagnostic string to be returned to DB2

If DBINFO is specified, an additional parameter, the DB2INFO structure, might also be passed. Do not specify DB2 SQL when LANGUAGE REXX is in effect.

GENERAL | Only the parameters on the CALL statement are passed to the stored procedure. The parameters cannot be null.
GENERAL WITH NULLS | In addition to the parameters on the CALL statement, another argument is also passed to the stored procedure. The additional argument contains a vector of null indicators for each of the parameters on the CALL statement that enables the stored procedure to accept or return null parameter values.
JAVA | The stored procedure uses a convention for passing parameters that conforms to the Java and SQLJ specifications. INOUT and OUT parameters are passed as single-entry arrays. The DBINFO structure is not passed. JAVA can be specified only if LANGUAGE is COMPJAVA. For REXX stored procedures (LANGUAGE REXX), GENERAL and GENERAL WITH NULLS are the only valid values for PARAMETER STYLE. For LANGUAGE COMPJAVA, JAVA is the only valid value.

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the stored procedure returns the same result from successive calls with identical input arguments.

NOT DETERMINISTIC | The stored procedure might not return the same result from successive calls with identical input arguments.
DETERMINISTIC | The stored procedure returns the same result from successive calls with identical input arguments. XDB does not verify that the stored procedure code is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

NO SQL, MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL DATA

Indicates whether the stored procedure issues any SQL statements and, if so, what type.

NO SQL | The stored procedure cannot execute any SQL statements.
MODIFIES SQL DATA | The stored procedure can execute any SQL statement except those statements that are not supported in any stored procedure.
READS SQL DATA | The stored procedure cannot execute SQL statements that modify data. SQL statements that are not supported in any stored procedure return a different error.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any stored procedure return a different error.

NO DBINFO or DBINFO

Specifies whether specific information known by XDB is passed to the stored procedure when it is invoked.

NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the stored procedure is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the procedure might be inserting into or updating, and identification of the database server that invoked the procedure.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the stored procedure is executed.

NO COLLID | The package collection for the stored procedure is the same as the package collection of the program that invokes the stored procedure. If a trigger invokes the stored procedure, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

NO WLM ENVIRONMENT

Indicates that the stored procedure is to run in the XDB-established stored procedure address space.

Do not specify NO WLM ENVIRONMENT if the definition of the stored procedure implicitly or explicitly includes the following clauses or parameters:

  • The PROGRAM TYPE SUB clause
  • The SECURITY USER or SECURITY DEFINER clause
  • The LANGUAGE REXX clause
  • Parameters with a LOB data type or a distinct type based on a LOB data type

To change the procedure to run in the XDB-established stored procedure address space, you must have appropriate authority for the XDB-established stored procedure address space.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of a stored procedure can run. The value is unrelated to the ASUTIME column in the resource limit specification table.

When you are debugging a stored procedure, setting a limit can be helpful in case the stored procedure gets caught in a loop.

NO LIMIT | There is no limit on the service units.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the stored procedure uses more service units than the specified value, the stored procedure is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the stored procedure load module remains resident in memory when the stored procedure ends.

NO | The load module is deleted from memory after the stored procedure ends. Use NO for non-reentrant stored procedures.
YES | The load module remains resident in memory after the stored procedure ends.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the stored procedure runs as a main routine or a subroutine.

SUB | The stored procedure runs as a subroutine.
MAIN | The stored procedure runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

COMMIT ON RETURN

Indicates whether XDB commits the transaction immediately on return from the stored procedure.

NO XDB does not issue a commit when the stored procedure returns.
YES XDB issues a commit when the stored procedure returns if the following statements are true:
  • The SQLCODE that is returned by the CALL statement is not negative.
  • The stored procedure is not in a must abort state.

The commit operation includes the work that is performed by the calling application process and the stored procedure.

If the stored procedure returns result sets, the cursors that are associated with the result sets must have been defined WITH HOLD to be usable after the commit.

CALLED ON NULL INPUT

Specifices that the stored procedure will be called even if any of the input arguments is null, making the procedure responsible for testing for null argument values. The result is the null value.

Note:

Changes are immediate: Any changes that the ALTER PROCEDURE statement cause to the definition of a procedure take effect immediately.

The changed definition is used the next time that the procedure is called.

Restrictions for nested stored procedures: A stored procedure, user-defined function, or trigger cannot call a stored procedure that is defined with the COMMIT ON RETURN clause.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

Example:

Assume that stored procedure SYSPROC.MYPROC is currently defined to run in WLM environment PARTSA and that you have appropriate authority on that WLM environment and WLM environment PARTSEC. Change the definition of the stored procedure so that it runs in PARTSEC.

ALTER PROCEDURE SYSPROC.MYPROC WLM ENVIRONMENT PARTSEC;
Parent topic: SQL Statements


ALTER PROCEDURE (SQL)

The XDB Server operating environment only provides syntax support for external Procedures (SQL) at this time.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER PROCEDURE command, users must possess either overall SYSADM or SYSCTRL authority for the location, or be the owner of the stored procedure affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER PROCEDURE procedure-name
    [DYNAMIC RESULT {SET | SETS} integer]
    [EXTERNAL NAME {'string' | identifier}]
    [{DETERMINISTIC | NOT DETERMINISTIC}]
    [{CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA}]
    [{NO COLLID | COLLID collection-id}]
    [{WLM ENVIRONMENT {name | (name,*)}} | NO WLM ENVIRONMENT}]
    [ASUTIME {NO LIMIT | LIMIT integer}]
    [STAY RESIDENT {NO | YES}]
    [PROGRAM TYPE {SUB | MAIN}]
    [SECURITY {DB2 | USER | DEFINER}]
    [RUN OPTIONS run-time-options]
    [COMMIT ON RETURN {NO | YES}]
    [INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
    [{STOP AFTER SYSTEM DEFAULT FAILURES |
     STOP AFTER integer FAILURES |
     CONTINUE AFTER FAILURE}]

Description

procedure-name

Identifies the stored procedure to be altered. The name is implicitly or explicitly qualified by a schema name. If the name is not explicitly qualified, it is implicitly qualified with a schema name according to the following rules.

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

DYNAMIC RESULT SET integer or DYNAMIC RESULT SETS integer

Specifies the maximum number of query result sets that the stored procedure can return. The value must be between 0 and 32767.

EXTERNAL NAME 'string' or identifier

Specifies the name of the MVS load module for the program that runs when the procedure name is specified in an SQL CALL statement. The value must conform to the naming conventions for MVS load modules: the value must be less than or equal to 8 bytes, and it must conform to the rules for an ordinary identifier with the exception that it must not contain an underscore.

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the stored procedure returns the same result from successive calls with identical input arguments.

NOT DETERMINISTIC | The stored procedure might not return the same result from successive calls with identical input arguments.
DETERMINISTIC | The stored procedure returns the same result from successive calls with identical input arguments. XDB does not verify that the stored procedure code is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL DATA

Indicates whether the stored procedure can execute any SQL statements and, if so, what type.

MODIFIES SQL DATA | The stored procedure can execute any SQL statement except those statements that are not supported in any stored procedure.
READS SQL DATA | The stored procedure cannot execute SQL statements that modify data. SQL statements that are not supported in any stored procedure return a different error.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any stored procedure return a different error

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the stored procedure is executed.

NO COLLID | The package collection for the stored procedure is the same as the package collection of the program that invokes the stored procedure. If a trigger invokes the stored procedure, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the stored procedure is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of a stored procedure can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a stored procedure, setting a limit can be helpful in case the stored procedure gets caught in a loop.

NO LIMIT | There is no limit on the service units.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2 GB. If the stored procedure uses more service units than the specified value, the stored procedure is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the stored procedure load module remains resident in memory when the stored procedure ends.

NO | The load module is deleted from memory after the stored procedure ends.
YES | The load module remains resident in memory after the stored procedure ends.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the stored procedure runs as a main routine or a subroutine.

SUB | The stored procedure runs as a subroutine.
MAIN | The stored procedure runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

COMMIT ON RETURN

Indicates whether XDB commits the transaction immediately on return from the stored procedure.

NO XDB does not issue a commit when the stored procedure returns.
YES XDB issues a commit when the stored procedure returns if the following statements are true:
  • The SQLCODE that is returned by the CALL statement is not negative.
  • The stored procedure is not in a must abort state.

The commit operation includes the work that is performed by the calling application process and the stored procedure.

If the stored procedure returns result sets, the cursors that are associated with the result sets must have been defined as WITH HOLD to be usable after the commit.

Note:

Any changes that the ALTER PROCEDURE statement cause to the definition of a procedure take effect immediately.

The changed definition is used the next time that the procedure is called.

A stored procedure, user-defined function, or trigger cannot call a stored procedure that is defined with the COMMIT ON RETURN clause.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

Example:

Modify the definition for an SQL procedure so that SQL changes are committed on return from the SQL procedure and the SQL procedure runs in the WLM environment named WLMSQLP.

 ALTER PROCEDURE UPDATE_SALARY_1
    COMMIT ON RETURN YES
    WLM ENVIRONMENT WLMSQLP;
Parent topic: SQL Statements


ALTER SEQUENCE

The ALTER SEQUENCE statement changes the attributes of a sequence at the current server. Only future values of the sequence are affected by the ALTER SEQUENCE statement.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

  • Ownership of the sequence
  • The ALTER privilege for the sequence
  • The ALTERIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the ALTERIN privilege on the schema.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process.

Syntax

ALTER SEQUENCE sequence-name {RESTART [WITH numeric-constant] |
     INCREMENT BY numeric-constant |
     {MINVALUE numeric-constant | NO MINVALUE} |
     {MAXVALUE numeric-constant | NO MAXVALUE} |
     {CYCLE | NO CYCLE} |
     {CACHE integer-constant | NO CACHE} |
     {ORDER | NO ORDER}
     } [...]

Description

SEQUENCE sequence-name
Identifies the sequence. The combination of sequence name and the implicit or explicit qualifier must identify an existing sequence at the current server. sequence-name must not identify a sequence that is generated by the system for an identity column.
RESTART
Restarts the sequence. If numeric-constant is not specified, the sequence is restarted at the value specified implicitly or explicitly as the starting value on the CREATE SEQUENCE statement that originally created the sequence.
WITH numeric-constant
Specifies the value at which to restart the sequence. The value can be any positive or negative value that could be assigned to a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point.

If RESTART is not specified, the sequence is not restarted. Instead, it resumes with the current values in effect for all the options after the ALTER statement is issued.

After a sequence is restarted or changed to allow cycling, sequence numbers may be duplicates of values generated by the sequence previously.

INCREMENT BY numeric-constant
Specifies the interval between consecutive values of the sequence. The value can be any positive or negative value (including 0) that could be assigned to a column of the data type that is associated with the sequence without any non-zero digits existing to the right of the decimal point. The default is 1.

If INCREMENT BY numeric-constant is positive, the sequence ascends. If INCREMENT BY numeric-constant is negative, the sequence descends. If INCREMENT BY numeric-constant is 0, the sequence is treated as an ascending sequence.

The absolute value of INCREMENT BY can be greater than the difference between MAXVALUE and MINVALUE.

NO MINVALUE
Specifies that the minimum end point of the range of values for the sequence has not been specified explicitly. In such a case, the value for MINVALUE becomes one of the following:
  • For an ascending sequence, the value is the original starting value.
  • For a descending sequence, the value is the minimum of the data type that is associated with the sequence.
MINVALUE MINVALUEnumeric-constant
Specifies the minimum value at which a descending sequence either cycles or stops generating values, or an ascending sequence cycles to after reaching the maximum value. The last value that is generated for a cycle of a descending sequence will be equal to or greater than this value. MINVALUE is the value to which an ascending sequence cycles to after reaching the maximum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

NO MAXVALUE
Specifies either explicitly or implicitly that the minimum end point of the range of values for the sequence has not be set. In such a case, the default value for MAXVALUE becomes one of the following:
  • For an ascending sequence, the value is the maximum value of the data type that is associated with the sequence
  • For a descending sequence, the value is the original starting value.

If NO MAXVALUE is explicitly specified in the ALTER SEQUENCE statement, the value of the MAXVALUE column in the catalog table is reset to the maximum value of the data type associated with the sequence if the sequence is ascending or the value stored in the START column of the catalog table if the sequence is descending. Whether the sequence is ascending or descending depends on whether or not the INCREMENT BY option is reset. If it is, the new INCREMENT BY VALUE determines if the sequence is ascending or descending. If it is not explicitly reset, the value stored in the INCREMENT column of the catalog table determines if the sequence is ascending or descending.

MAXVALUE numeric-constant
Specifies the maximum value at which an ascending sequence either cycles or stops generating values or a descending sequence cycles to after reaching the minimum value. The last value that is generated for a cycle of an ascending sequence will be less than or equal to this value. MAXVALUE is the value to which a descending sequence cycles to after reaching the minimum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

CYCLE

Specifies that the sequence continue to generate values after either the maximum or minimum value has been reached. If this option is used, after an ascending sequence reaches its maximum value, it generates its minimum value. After a descending sequence reaches its minimum value, it generates its maximum value. The maximum and minimum values for the sequence defined by the MINVALUE and MAXVALUE options determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by the sequence. When a sequence is defined with CYCLE, any application conversion tools for converting applications from other vendor platforms to DB2 should also explicitly specify MINVALUE, MAXVALUE, and START WITH values.

NO CYCLE
Specifies that the sequence cannot generate more values once the maximum or minimum value for the sequence has been reached.
NO CACHE
Specifies that values of the sequence are not to be preallocated. This option ensures that there is not a loss of values in the case of a system failure. When NO CACHE is specified, the values of the sequence are not stored in the cache. In this case, every request for a new value for the sequence results in synchronous I/O.
CACHE integer-constant
Specifies the maximum number of sequence values that XDB can preallocate and keep in memory. Preallocating values in the cache reduces synchronous I/O when values are generated for the sequence. The actual number of values that XDB caches is always the lesser of the number in effect for the CACHE option and the number of remaining values within the logical range. Thus, the CACHE value is essentially an upper limit for the size of the cache.

In the event of a system failure, all cached sequence values that have not been used in committed statements are lost (that is, they will never be used). The value specified for the CACHE option is the maximum number of sequence values that could be lost in case of system failure.

The minimum value is 2.

In a data sharing environment, you can use the CACHE and NO ORDER options to allow multiple XDB members to cache sequence values simultaneously.

NO ORDER
Specifies that the sequence numbers do not need to be generated in order of request.
ORDER
Specifies that the sequence numbers are generated in order of request. Specifying ORDER may disable the caching of values. There is no guarantee that values are assigned in order across the entire server unless NO CACHE is also specified. ORDER applies only to a single-application process.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for next value assignments from different members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the same sequence, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested for next value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that sequence numbers are generated in strict numeric order among multiple members using the same sequence concurrently, specify the ORDER option.

Comments:

  • The changes to the attributes of a sequence take effect after the ALTER SEQUENCE statement is committed. If the ALTER SEQUENCE request results in an error or is rolled back, nothing is changed; however, unused cache values may be lost. You cannot use the ALTER SEQUENCE statement to change the data type of a sequence. To change the data type, drop the sequence and recreate it. Altering a sequence may cause unused cache values to be lost.
  • To provide compatibility with previous releases, XDB supports the following keywords:
    • NOCACHE (single key word) as a synonym for NO CACHE
    • NOCYCLE (single key word) as a synonym for NO CYCLE
    • NOMINVALUE (single key word) as a synonym for NO MINVALUE
    • NOMAXVALUE (single key word) as a synonym for NO MAXVALUE
    • NOORDER (single key word) as a synonym for NO ORDER
Parent topic: SQL Statements


ALTER STOGROUP

The ALTER STOGROUP statement changes the specifications of an existing storage group (stogroup) defined within the current XDB Server location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute this command, users must either be the owner of the referenced stogroup, or possess SYSADM or SYSCTRL authority for the location.

Syntax

ALTER STOGROUP stogroup-name
    [PASSWORD password]
    [ADD VOLUMES (volume-id[,...])]
    [REMOVE VOLUMES (volume-id[,...])]

Parameters:

stogroup-name | Identifies the stogroup to be altered. The stogroup identified must exist within the currently set XDB Server location.
volume-id | Refers to the volume serial number of a mainframe storage volume.

Description

ALTER STOGROUP allows users to add and remove logical volume ID designations from an existing stogroup. The XDB Server also records any mainframe assigned password in the location catalog tables (DB2 mode).

PASSWORD

This option is utilized in the mainframe-DB2 environment. Any password parameter values are recorded in the catalog tables for the current XDB Server location.

ADD VOLUMES (volume-id,...) or ADD VOLUMES('*',...)

XDB records the volumes added to a stogroup in the catalog tables for that location. One or more volume-id numbers (corresponding to volume serial numbers) can be specified in this clause, each with a maximum of six characters (specified as an identifier or a string constant).

A volume-id must not be specified if any volume of the storage group is designated by an asterisk (*). An asterisk must not be specified if any volume of the storage group is designated by a volume-id.

You cannot add a volume that is already in the storage group unless you first remove it with REMOVE VOLUMES.

REMOVE VOLUMES (volume-id,...) or REMOVE VOLUMES('*',...)

XDB Server can associate up to 133 volumes with one stogroup. The REMOVE VOLUMES option removes one or more volumes (identified by volume-id) associated with the storage group. The XDB Server applies the REMOVE VOLUMES clause to the current list of stogroup volumes, before applying any ADD VOLUMES clauses.

Parent topic: SQL Statements


ALTER TABLE

The ALTER TABLE statement changes the description of a table at the current server.

Altering the structure of a table may require a time consuming reorganization of the table. The original table is not recoverable; take care when using this command. ALTER TABLE (in XDB mode and DB2 mode) alters the structure of an existing table. Use ALTER TABLE to add new columns, and create and drop integrity constraints.

In XDB mode, the ALTER TABLE command includes the following additional options: delete, rename and modify existing columns, add and drop unique keys and check conditions, and specify any parent table unique key (also called a candidate key) when adding a foreign key reference.

ALTER TABLE clauses can add and drop check constraints, along with WITH RESTRICT ON DROP clauses. Columns with user-defined defaults or check constraints can also be added.

Invocation

This statement can be embedded in an application program or issued interactively.

The ALTER TABLE command can be dynamically prepared (PREPARE command).

Authorization

To execute an ALTER TABLE statement, users must possess either DBADM authority on the database, the ALTER privilege on the table being altered, overall SYSADM or SYSCTRL authority for the location, or ownership of the table affected. If a FOREIGN KEY clause is included in the ALTER TABLE statement, the user must possess the ALTER privilege on the parent table.

Additional privileges might be required in the following cases:

  • FOREIGN KEY, DROP PRIMARY KEY, DROP FOREIGN KEY, or DROP CONSTRAINT is specified
  • the data type of a column that is added to the table is a distinct type
  • A fullselect is specified
  • A column is defined as a security label column

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER TABLE table-name
    [ALTER [COLUMN] column-alteration | partition-alteration]
                ROTATE partition-rotation

    [ADD column-definition]
                [VALIDPROC {program-name | NULL}]
    [AUDIT {NONE | CHANGES | ALL}]
    [[ADD] PRIMARY KEY key-name (column-list)]
    [ADD check-constraint]
                [ADD add-partition]
                [ADD partitioning-clause]
    [DROP CHECK constraint-name]
    [[ADD] referential-constraint]
    [DATA CAPTURE {NONE | CHANGES}]
                [{VOLATILE | NOT VOLATILE} [CARDINALITY]]
    [DROP PRIMARY KEY]
    [DROP FOREIGN KEY constraint-name]
    [DROP CONSTRAINT constraint-name]
    [{ADD | DROP} RESTRICT ON DROP]
{
    | DELETE column-name[,...]
    | RENAME old-column-name new-column-name[,...]
    | MODIFY column-name column-type [FOR BIT DATA]
        [NOT NULL [WITH DEFAULT]] [,...]
    | UNIQUE KEY key-name (column-list)
    | FOREIGN KEY [constraint-name] (column-list)
        REFERENCES referenced-table [key-name]
        [ON UPDATE {RESTRICT | CASCADE| SET NULL}]
    | DROP KEY key-name
    | CHECK (search-condition)
    | DROP CHECK
    | ADD [[MATERIALIZED] QUERY] materialized-query-definition
    | DROP [MATERIALIZED] QUERY
    | ALTER [MATERIALIZED] QUERY materialized-query-definition
                }

column-alteration:

[COLUMN] column-name
 {SET DATA TYPE altered-data-type |
                generation-alteration |
  [generation-alteration] identity-alteration}

altered-data-type

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...] | (5,0)] |
{FLOAT [integer | 53] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer) | (1)] |
  {CHARACTER | CHAR} VARYING (integer) |
  VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA]  |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G]) | (1M)] }
[FOR {SBCS | MIXED} DATA] } |
{GRAPHIC [(integer) | (1M)] | VARGRAPHIC (integer)

generation-alteration

SET GENERATED {ALWAYS | BY DEFAULT}

partition-rotation:

PARTITION FIRST TO LAST ENDING [AT] (constant[,...]) [INCLUSIVE] RESET

materialized-query-definition:

(fullselect) refreshable-table-options

refreshable-table-options:

DATA INITIALLY DEFERRED REFRESH DEFERRED
[MAINTAINED BY SYSTEM | MAINTAINED BY USER]
[ENABLE QUERY OPTIMIZATION | DISABLE QUERY OPTIMIZATION]

referential-constraint:

FOREIGN KEY [constraint-name] (column-name[,...]
REFERENCES referenced-table [column-name ,...]
[ON DELETE {RESTRICT | CASCADE | SET NULL | NO ACTION}]

references-clause:

REFERENCES referenced-table
    [column-name ,...]
    [ON DELETE {RESTRICT | CASCADE | SET NULL | NO ACTION}]
    [ENFORCED | NOT ENFORCED]
    [ENABLE QUERY OPTIMIZATION]

check-constraint:

[CONSTRAINT constraint-name] CHECK (check-condition)

add-partition:

PARTITION ENDING [AT] (constant) [,...] [INCLUSIVE]

partitioning-clause:

PARTITION BY [RANGE] (partition-expression[,...]) (partition-element[,...])

partition-expresion:

                column-name [NULLS LAST] [ASC | DESC]

partition-element:

PARTITION integer ENDING [AT] (constant[,...]) [INCLUSIVE]

partition-alteration:

PARTITION integer ENDING [AT] (constant[,...]) [INCLUSIVE]

column-definition:

column-name data-type
    [NOT NULL]
    [FOR {BIT | SBCS | MIXED} DATA]
    [default-clause]
    [GENERATED {ALWAYS | BY DEFAULT} [as-identity-clause]]
    [references-clause]
    [check-constraint]
                [FIELDPROC program-name [(constant[,...])]]
    [AS SECURITY LABEL]

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT | {INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
                {BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

default-clause:

[WITH] DEFAULT [{constant | USER | CURRENT SQLID | NULL | cast-function-name ({constant |
   USER | CURRENT SQLID | NULL})}]

as-identity-clause:

AS IDENTITY
    [({START WITH {numeric-constant | 1}
     | INCREMENT BY {numeric-constant | 1}
     | {MINVALUE numeric-constant | NO MINVALUE} |
     | {MAXVALUE numeric-constant | NO MAXVALUE} |
     | {CYCLE | NO CYCLE} |
     | {CACHE 20 | NO CACHE | CACHE integer}}
     | [ORDER | NO ORDER] ])[,..]]

Parameters

table-name | Identifies the table to be altered. The name must identify a table that exists at the current server. The name must not identify an auxiliary table, declared temporary table, or view. If the name identifies a catalog table, DATA CAPTURE CHANGES is the only clause that can be specified.
column-name | Identifies a column in the table.
column-type Identifies a valid XDB Server column data type. Valid data types are detailed in Basic Concepts. If the column data type is CHAR or VARCHAR, and no character length is specified when altering (or creating) the table, a default character length of one becomes part of the column type specification. If the column type is DECIMAL, precision and scale may also be specified (default is 5,0).

FOR BIT DATA is an optional keyword for CHAR, VARCHAR, and LONG VARCHAR data columns. The presence of these keywords indicates that the contents of the column data values are to be treated as bit (binary) data. This option is important for COBOL programming that uses character and variable character fields to store integers, structures, etc. If not specified as FOR BIT DATA, the column is assumed (by default) to contain ASCII characters. Default character modes (such as EBCDIC) are set using the CREATE LOCATION statement. Note that the FOR BIT DATA keywords must precede any NULL specification for that column.

NOT NULL is an optional instruction that prevents the column from containing null values.

NOT NULL WITH DEFAULT prevents columns from containing null values. When an attempt is made to place a NULL value in a column field, a default value depending on the data type is inserted instead.

key-name | Designates an original name for a UNIQUE KEY.
column-list Identifies one or more columns (separated by commas) on which the key is created. Up to 64 columns can be included in a key constraint. For information on the total character (or byte) limitations of an XDB Server key constraint (or index), see the CREATE INDEX statement.

When establishing a PRIMARY KEY, a unique index must already be created on the table. The PRIMARY KEY constraint must contain the same column names, in the same order, as the unique index. If these requirements are met, the unique index is transformed into the PRIMARY KEY for that table.

constraint-name Identifies a FOREIGN KEY constraint. If a constraint name is not specified in the command, the system generates a constraint name by taking the first eight characters of the first column name, and checking for uniqueness. If these characters are not unique, the XDB Server adds a number to the first seven characters of the first column name. If still not unique, then two numbers are added to the first six characters, etc. -- until the new constraint name becomes unique among all constraint names for that table.

Also defines a table CHECK constraint within the CONSTRAINT...CHECK clause, and constraints within the DROP FOREIGN KEY, DROP CONSTRAINT and DROP CHECK clauses. The constraint-name is an SQL long identifier. A constraint-name cannot be specified more than once for the same table. (See the CONSTRAINT, DROP CONSTRAINT, DROP CHECK, and DROP keywords.)

check-condition | Can consist of a single predicate, or two or more predicates joined by AND or OR. The first operand of each predicate must be the name of a column of the table. The second operand can be a column name or a constant. A check-condition can evaluate to unknown if a column that is an operand of the predicate is null. A check-condition that evaluates to unknown does not violate the check constraint (see CHECK clause).
referenced-table Identifies the parent table referenced by the FOREIGN KEY clause. ON DELETE tells the XDB Server how to handle dependent records in the referencing table when an attempt is made to delete a referenced record in the parent table. The RESTRICT option (default) prevents the referenced record from being deleted from the parent table.

The CASCADE option deletes the dependent records from the referencing table, and also deletes the parent record. The SET NULL option causes the FOREIGN KEY data values in the dependent records to be set to NULL before the parent record is deleted.

search-condition | Represents any search condition, except a join condition or a subselect.

Description

In XDB mode, only one optional clause can be included in any ALTER TABLE statement. For example, one ALTER TABLE command might ADD one or more columns, while another ALTER TABLE command could DELETE one or more columns. In DB2 mode, multiple clauses can be included in each ALTER TABLE statement, as long as the same clause is not specified more than once. Information contained in the VALIDPROC, AUDIT and DATA CAPTURE clauses is recorded in the XDB Server catalog tables for the current location, but is not otherwise used by the XDB Server. These clauses are operational when used against a DB2 database through XDB Link.

ALTER COLUMN column-alteration

Alters the definition of an existing column, including the attributes of an existing identity column. Only the attributes specified are altered. Other attributes remain unchanged. Only future values of the column are affected by the changes made with an ALTER TABLE ALTER COLUMN statement.

The table being altered must not be in an incomplete state because of a missing unique index on a unique constraint (primary or unique key). A column can only be referenced once in an ALTER COLUMN clause in a single ALTER TABLE statement. However, that same column can be referenced multiple times for adding or dropping constraints in the same ALTER TABLE statement. An ALTER TABLE ALTER COLUMN statement may not be processed in the same unit of work as an INSERT, DELETE, or UPDATE statement. A column cannot be altered if the table is used in a materialized query table definition or if the table is a materialized query table.

You can modify all the attributes of an existing identity column, except for the data type of the column. To change the data type of an identity column, drop the table containing the column and recreate it.

column-name Identifies the column to be altered. The name must not be qualified and must identify an existing column in the table being altered when the ALTER statement is processed. The column must not be part of a referential constraint or have a field procedure. The column must not be defined as a security label column. When the attributes of an identity column are altered, the column of the specified column-name must exist in the specified table and must have been defined with the IDENTITY attribute.
SET DATA TYPE (altered-data-type) Specifies the new data type of the column to be altered. For a character or CLOB column, you can also use the clause to change the definition of the subtype that is stored in the XDB catalog and OBD.The column cannot be an identity column. The new data type must be compatible with the existing data type of the column. The existing data type of the column cannot be a ROWID, LOB, date, time, timestamp, or distinct type.

If the data type is a character or graphic string, the new length attribute must be at least as large as the existing length attribute of the column. If the data type is a numeric data type, the specified precision and scale must be at least as large as the existing precision and scale. If a decimal fraction is being converted to floating point, the ALTER statement will fail if there is a unique index or a unique constraint on the column.

If the specified column has a default value, the existing default value must represent a value that could be assigned to a column with the new data type in accordance with the rules for assignment. The default value is updated to reflect the new data type.

If the column is specified in a unique constraint (unique key or primary key) or unique index, the new column length must not exceed the limit on an index size. For PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000-n, where n is the number of columns that can contain null values. For NOT PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000-n-2m, where n is the number of nullable columns and m is the number of varying length columns.

The total byte count of columns after the alteration must not exceed the maximum row size. If the column is in the partitioning key, the new partitioning key cannot exceed 255-n.

The following numeric data type alterations are supported for SET DATA TYPE:

The following character data type alterations are supported for SET DATA TYPE:

When columns are converted from CHAR to VARCHAR, normal assignment rules apply, which means that trailing blanks are kept instead of being stripped out. If you want varying length character strings without trailing blanks, use the STRIP function for data in the column after changing the data type to VARCHAR.

If the table being altered has an edit procedure or valid procedure, an error occurs. If a materialized query table is defined on this table or if this table is defined as being a materialized query table, then an error also occurs.

The table space that contains the table being altered is left in an advisory REORG-pending (AREO) status. If the column being altered is part of an index, an exception state may be set for the index as shown in the table below:

The length of more than one column can be changed in a single ALTER TABLE statement if each ALTER COLUMN clause identifies a unique column of the table. The ALTER COLUMN clause and ADD CHECK CONSTRAINT clause can identify the same column.

ADD column-definition

Adds a column to the table. Except for a ROWID column and an identity column, all values of the column in existing rows are set to its default value. If the table has n columns, the ordinality of the new column is n+1. The value of n cannot be greater than 749. For a dependent table, n cannot be greater than 748.

The column cannot be added if the increase in the total byte count of the columns exceeds the maximum row size. The maximum row size for the table is eight less than the maximum record size. A column also cannot be added to a table that has an edit procedure.

If you add a LOB column and the table does not already have a ROWID column, XDB creates a hidden ROWID column. You cannot add a LOB or ROWID column to a created temporary table.

You cannot add an identity column to a table that has an identity column or to a created temporary table.

column-name | Is the name of the column you want to add to the table. Do not use the name of an existing column of the table. Do not qualify column-name.
built-in-data-type | Specifies the data type of the column is one of the built-in data types.
distinct-type-name | Specifies the distinct type (user-defined data type) of the column. User-defined data types are not yet supported by the XDB Server operating environment.

NOT NULL

Prevents the column from containing null values. If NOT NULL is specified, the DEFAULT clause must be used to specify a nonnull default value for the column unless the column has a row ID data type or is an identity column. For a ROWID column, NOT NULL must be specified, and DEFAULT must not be specified. For an identity column, although NOT NULL can be specified, DEFAULT must not be specified

For example, the ALTER statement below adds three new data columns to the SUPPLIER table:

ALTER TABLE supplier
    ADD state CHAR 2, zip CHAR 5,
        founded DATE NOT NULL WITH DEFAULT

To disallow NULL values in a new column, first add data to the column, and then issue another ALTER TABLE statement with the MODIFY clause to specify the column as NOT NULL.

DEFAULT

The default value assigned to the column in the absence of a value specified on INSERT or LOAD. Do not specify DEFAULT for a ROWID column, an identity column (a column that is defined AS IDENTITY) or a security label column (a column that is defined AS SECURITY LABEL); XDB generates default values. If a value is not specified after the DEFAULT keyword and the column is not nullable, the default value depends on the data type of the column.

Data Type | Default Value
numeric | 0
date | current date
time | current time
timestamp | current date and time
character | Blanks
Varchar | Blanks
graphic | Blanks

For example, if you want to record the identity of anyone inserting rows into a table, define the table with two additional columns:

PRIMARY_ID

CHAR(8)

WITH DEFAULT USER,

SQL_ID

CHAR(8)

WITH DEFAULT CURRENT SQLID,

You can allow updates and inserts to the table only through a view that omits those columns. Then, the primary authorization ID and the SQLID of the process are added by default.

constant

Specifies a constant as the default value for the column. The value of the constant must conform to the rules for assigning that value to the column.

A character or string constant must be short enough so that its UTF-8 representation requires no more than 1536 bytes. In addition, a hexadecimal graphic string (GX) constant cannot be specified.

USER

Specifies the value of the USER special register at the time of INSERT or LOAD as the default for the column. If USER is specified, the data type of the column must be a character string with a length greater than or equal to the length attribute of the USER special register. For existing rows, the value is that of the USER special register at the time the ALTER TABLE statement is processed.

CURRENT SQLID

Specifies the value of the SQL authorization ID of the process at the time of INSERT or LOAD as the default for the column. If CURRENT SQLID is specified, the data type of the column must be a character string with a length greater than or equal to the length attribute of the CURRENT SQLID special register. For existing rows, the value is the SQL authorization ID of the process at the time the ALTER TABLE statement is processed.

NULL

Specifies null as the default value for the column.

cast-function-name

The XDB Server operating environment does not currently provide this functionality.

GENERATED

Indicates that XDB generates values for the column. GENERATED is applicable only to ROWID columns and identity columns. If the data type of the column is a ROWID (or a distinct type that is based on a ROWID), the default is GENERATED ALWAYS.

ALWAYS Indicates that XDB will generate a value for the column when a row is inserted into the table. ALWAYS is the recommended value unless you are using data propagation.

If you specify ALWAYS, you must not specify a value for the column when a row is inserted into the table. Also, you cannot update the value of the column

BY DEFAULT Indicates that XDB will generate a value for the column when a row is inserted unless a value is specified.into the table only if a value is not specified. Otherwise, XDB uses the value that you specify.

For a ROWID column, XDB uses a specified value only if it is a valid row ID value that was previously generated by XDB and the column has a unique, single-column index. Until this index is created on the ROWID column, the SQL INSERT statement and the LOAD utility cannot be used to add rows to the table. If the value of special register CURRENT RULES is 'STD' when the ALTER TABLE statement is processed, XDB implicitly creates the index on the ROWID column. The name of this index is 'I' followed by the first ten characters of the column name followed by seven randomly generated characters. If the column name is less than ten characters, XDB adds underscore characters to the end of the name until it has ten characters. The implicitly created index has the COPY NO attribute.

For an identity column, XDB inserts a specified value but does not verify that it is a unique value for the column unless the identity column has a unique, single-column index; without a unique index, XDB can guarantee unique values only among the set of system-generated values.

BY DEFAULT is the recommended value only when you are using data propagation.

AS SECURITY LABEL

Indicates that the table is defined with multilevel security with row level granularity and specifies that the column will contain the security label values. A table can have only one security label column. To define a table with a security label column, the primary authorization ID of the statement must have a valid security label, and the RACF SECLABEL class must be active. In addition, the following conditions are also required:

  • The data type of the column must be CHAR(8).
  • The subtype of the column must be SBCS.
  • The column does not have any field procedures, check constraints, or referential constraints.
  • The column must be defined as NOT NULL and WITH DEFAULT clauses.
  • The table does not have an edit procedure.
  • The table is not the source table for a materialized query table.
  • You are using z/OS Version 1 Release 5 or later.

For existing rows in the table, the value of the security label column defaults to the security label of the user at the time the ALTER statement is executed.

AS IDENTITY

Specifies that the column is an identity column for the table. A table can have only one identity column. AS IDENTITY can be specified only if the data type for the column is an exact numeric type with a scale of zero (SMALLINT, INTEGER, DECIMAL with a scale of zero, or a distinct type based on one of these types). Separator commas between identity column attribute specifications are optional when the identity column is defined.

An identity column is implicitly NOT NULL. When adding an identity column to a table, you must also specify GENERATED ALWAYS or GENERATED BY DEFAULT.

START WITH numeric-constant | Specifies the first value for the identity column. The value can be any positive or negative value that could be assigned to the column without non-zero digits exisitng to the right of the decimal point. The default is 1.
INCREMENT BY numeric-constant | Specifies the interval between consecutive values of the identity column. The value can be any positive or negative value (including 0) that does not exceed the value of a large integer constant and could be assigned to the column without any non-zero digits existing to the right of the decimal point. The default is 1. If the value is positive, the sequence of values for the identity column ascends. If the value is negative, the sequence of values descends.

MINVALUE or NO MINVALUE

Specifies the minimum value at which a descending identity column either cycles or stops generating values or an ascending identity column cycles to after reaching the maximum value.

NO MINVALUE

Specifies that the minimum end point of the range of values for the identity column has not been specified explicitly. In such a case, the value for MINVALUE becomes one of the following:

  • For an ascending identity column, the value is the START WITH value or 1 if START WITH was not specified.
  • For a descending identity column, the value is the minimum value of the data type of the column.

MINVALUE numeric-constant

Specifies the numeric constant that is the minimum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

MAXVALUE or NO MAXVALUE

Specifies the maximum value at which a ascending identity column either cycles or stops generating values or a descending identity column cycles to after reaching the minimum value.

NO MAXVALUE

Specifies that the minimum end point of the range of values for the identity column has not be set. In such a case, the default value for MAXVALUE becomes one of the following:

  • For an ascending identity column, the value is the maximum value of the data type of the column.
  • For a descending identity column, the value is the START WITH value or -1 if START WITH is not specified.

MAXVALUE numeric-constant

Specifies the numeric constant that is the maximum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

NO CYCLE or CYCLE

Specifies whether this identity column should continue to generate values after reaching either its maximum or minimum value.

NO CYCLE

Specifies that values will not be generated for the identity column after the maximum or minimum value has been reached. This is the default.

CYCLE

Specifies that values continue to be generated for this column after the maximum or minimum value has been reached. If this option is used, after an ascending identity column reaches the maximum value, it generates its minimum value. After a descending identity column reaches its minimum value, it generates its maximum value. The maximum and minimum values for the identity column determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by XDB for an identity column. However, if a unique index exists on the identity column and a non-unique value is generated for it, an error occurs.

CACHE or NO CACHE

This clause has no functional equivalent in the XDB Server operating environment.

NO ORDER or ORDER

Specifies whether the sequence numbers must be generated in order of request.

NO ORDER

Specifies that the values do not need to be generated in order of request.

ORDER

Specifies that the values are generated in order of request. Specifying ORDER may disable the caching of values. ORDER applies only to a single-application process.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for identity values from different XDB members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the identity column, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested a value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that identity values are generated in strict numeric order among multiple XDB members using the same identity column, specify the ORDER option.

REFERENCES

The references portion of the referential-constraint clause is a separate clause. A single column can be identified as a foreign key of a referential constraint by using the references-clause in a column definition.

Do not specify references-clause in the definition of a LOB, ROWID column, or security label column because a LOB, ROWID, or security label column cannot be a foreign key.

The parent key of the referential constraint is composed of the identified columns. The identified column cannot be a LOB, ROWID, or security label column. The same column must not be identified more than once.

Define a key that consists of more than one column by listing the column names. A foreign key can reference a unique key or a primary key. When a foreign key refers to a nonprimary unique key, you must specify the columns of the key.

If the foreign key includes a column defined as a distinct type, the corresponding column of the nominated parent key must be the same distinct type. If a column of the foreign key has a field procedure, the corresponding column of the nominated parent key must have the same field procedure and an identical field description. A field description is a description of the encoded value as it is stored in the database for a column that has been defined to have an associated field procedure.

ENFORCED or NOT ENFORCED

Indicates whether or not the referential constraint is enforced by the database manager during normal operations, such as insert, update, or delete.

ENFORCED

Specifies that the referential constraint is enforced by the database manager during normal operations (such as insert, update, or delete) and that it is guaranteed to be correct. This is the default.

NOT ENFORCED

Specifies that the referential constraint is not enforced by the database manager during normal operations, such as insert, update, or delete. This option should only be used when the data that is stored in the table is verified to conform to the constraint by some other method than relying on the database manager.

ENABLE QUERY OPTIMIZATION

Specifies that the constraint can be used for query optimization. XDB uses the information in query optimization using materialized query tables with the assumption that the constraint is correct. This is the default.

ADD RESTRICT ON DROP

Indicates that the table cannot be dropped. Also, the database and table space that contain the table cannot be dropped.

DROP RESTRICT ON DROP

Removes the restriction on dropping the table and the database and table space that contain the table.

CONSTRAINT

Names a table check constraint. If a constraint-name is not specified, a unique constraint name is derived from the name of the first column in the check-condition specified in the definition of the table check constraint.

Do not specify a check constraint in the definition of a LOB, ROWID, or security label column.

DROP CONSTRAINT

Drops the constraint constraint-name. The constraint-name must identify an existing check constraint or referential constraint defined on the table.

CHECK

Table check constraints can be defined on individual columns within both the CREATE TABLE and ALTER TABLE command statements. The check constraint is the check condition that defines the values that designated columns of the table can contain.

Do not specify a table check constraint in the definition of a ROWID column.

ADD PARTITION

Specifies that a partition is added to the table and each partitioned index on the table. The new partition is the next physical partition not being used until the maximum for the table space has been reached. ADD PARTITION must not be specified for nonpartitioned tables. If the table uses index-controlled partitioning, it is converted to use table-controlled partitioning.

The maximum number of partitions allowed depends on how the table space was originally created. If DSSIZE was specified when the table space was created, it is non-zero in the catalog. The maximum number of partitions allowed is shown in the following table.

DSSIZE | Page size 4Kb | Page size 8 Kb | Page size 16 Kb | Page size 32 Kb
1-4 Gb | 4096 | 4096 | 4096 | 4096
8 Gb | 2048 | 4096 | 4096 | 4096
16 Gb | 1024 | 2048 | 4096 | 4096
32 Gb | 512 | 1024 | 2048 | 4096
64 Gb | 256 | 512 | 1024 | 4096

If LARGE was specified when the table space was created, the maximum number of partitions is shown in the fourth row of the following table. For more than 254 partitions when LARGE or DSSIZE is not specified, the maximum number of partitions is determined by the page size of the table space.

Type of table space | Number of existing partitions | Maximum partitions
non-large | 1-16 | 16
non-large | 17-32 | 32
non-large | 33-64 | 64
large | N/A | 4096

The existing table space PRIQTY and SECQTY attributes of the previous logical partition are used for the space attributes of the new partition. For each partitioned index, the existing PRIQTY and SECQTY attributes of the previous partition are used.

To specify specific space attributes for the new partition, use additional ALTER TABLESPACE and ALTER INDEX statements.

Adding a partition is not allowed if the table is a materialized query table or a materialized query table is defined on the table. A partition cannot be added if the table space definition is incomplete because a partitioning key or partitioning index is missing.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant, ...)

Specifies the high key limit for the new partition. The new partition's key limit must be higher when partitioning is ascending and lower when it is descending. Specify at least one constant after ENDING AT in the PARTITION clause. You can use as many values as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition of the index. The use of constants to define key values is subject to the following rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must have the same data type as its corresponding column. A hexadecimal graphic string constant (GX) cannot be specified.

    Using fewer constants than there are columns in the key has the same effect as using the highest or lowest values for the omitted columns, depending on whether they are ascending or descending.

  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition.
  • The constants specified for the last partition are enforced. The value specified for the last partition is the highest value of the key that can be placed in the table. If the limit was not previously enforced, any existing key values greater than the value specified for the added partition are placed into the discard data set when REORG is run.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'. If the column is descending, the padding character is X'00'.
  • If a key includes a ROWID column or a column with a distinct type that is based on a ROWID data type, then 17 bytes of the constant that is specified for the corresponding ROWID column are considered.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

ADD PARTITION BY RANGE

Specifies the range partitioning scheme for the table (the columns used to partition the data). When this clause is specified, the table uses table-controlled partitioning. The number of partitions specified in the ADD PARTITION BY RANGE clause has to be the same as the number of partitions defined in the table space.

This clause applies only to tables in a partitioned table space. If the table is already complete by having established either table-controlled partitioning or index-controlled partitioning, the ADD PARTITION BY RANGE clause is not allowed. If this clause is used, then the ENDING AT clause cannot be used on a subsequent CREATE INDEX statement for this table.

This clause is only implemented syntactically in the XDB Server operating environment.

partition-expression

Specifies the key data over which the range is defined to determine the target data partition of the data.

column-name

Specifies the columns of the key. Each column-name must identify a column of the table. Do not specify more than 64 columns, the same column more than once, a LOB column, a column with a distinct type that is based on a LOB data type, or a qualified column name. The sum of length attributes of the columns must not be greater than 255 - n, where n is the number of columns that can contain null values.

NULLS LAST

Specifies that null values are treated as positive infinity for purposes of comparison.

ASC

Puts the entries in ascending order by the column. ASC is the default.

DESC

Puts the entries in descending order by the column.

partition-element

Specifies ranges for a data partitioning key and the table space where rows of the table in the range will be stored.

PARTITION integer

Identifies the partition to apply the boundary specified in the subsequent ENDING AT clause. It must be in the range of 1 to n where n is the number of partitions in the table.

ENDING AT(constant, ...)

Specifies the highest value of the partitioning key for the new partition. Specify at least one constant after ENDING AT in each PARTITION clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition. The length of each highest key value (the limit key) is the same as the length of the partitioning key. The use of constants to define key values is subject to the rules listed for the ENDING AT clause for a partition definition.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

ALTER PARTITION

Specifies that the partitioning limit key for the identified partition is to be altered. Specify ALTER PARTITION only if the table is partitioned.

This clause applies only to tables in a partitioned table space. If the table is already complete by having established either table-controlled partitioning or index-controlled partitioning, the ADD PARTITION BY RANGE clause is not allowed. If this clause is used, then the ENDING AT clause cannot be used on a subsequent CREATE INDEX statement for this table.

This clause is only implemented syntactically in the XDB Server operating environment.

integer

If integer is specified, it must be in the range 1 to n, where n is the number of partitions in the table. Altering a partition boundary is not allowed if the table is a materialized query table or if a materialized query table is defined on this table. When this option is specified for any partition except for the last, both the identified partition and the partition following are placed in REORG-pending (REORP) status.

ENDING AT(constant, ...)

Specifies the highest value of the partitioning key for the identified partition.

In this context, highest means highest in the sorting sequences of the columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC) the lowest actual value is highest in the sorting sequence.

Specify at least one constant after ENDING AT in each ALTER PARTITION clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition. The length of each highest key value (the limit key) is the same as the length of the partitioning key. The use of constants to define key values is subject to the rules listed for the ENDING AT clause for a partition definition. The value that is specified must not be equal to or beyond the range of the partition boundaries of the adjacent partitions.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

If the table uses index-controlled partitioning, it is converted to use table-controlled partitioning. The high limit key for the last partition is set to the highest possible value for ascending key columns or the lowest possible value for descending key columns.

ROTATE PARTITION FIRST TO LAST

Specifies that the first logical partition should be rotated to become the last logical partition. This keyword must be followed by the ENDING AT clause, which specifies the new high key limit for this partition, which is now logically last. The new partitioning key value must be higher than the current high key limit if partition values are ascending. If partition values are descending, the new key limit must be lower than the current low key limit.

Rotating a partition occurs immediately. If there is a referential constraint with DELETE RESTRICT on the table, the ROTATE might fail. If the table uses index-controlled partitioning, it is converted to use table-controlled partitioning.

If the table has a security label column, the user must have a valid security label to rotate partitions. In addition, if write-down is in effect, the user must have the write-down privilege.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant, ...)

The ENDING AT clause specifies the new high key limit for the existing partition holding the oldest data.

In this context, highest means highest in the sorting sequences of the columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC) the lowest actual value is highest in the sorting sequence.

Specify at least one constant after ENDING AT. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition. The length of each highest key value (the limit key) is the same as the length of the partitioning key. The use of constants to define key values is subject to the rules listed for the ENDING AT clause for a partition definition.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

RESET

Specifies that the existing data in the oldest partition is deleted. In a partitioned table with limit values that are in ascending sequence, ALTER TABLE ALTER PARTITION ROTATE FIRST TO LAST logically operates as if the partition with the lowest high key limit were dropped and then a new partition was added with the specified high key limit. The partition's new key limit must be higher than any other partition in the table. For descending limit keys, the rotation operates as the partition with the highest limit values becomes the partition with the lowest limit values.

If the partition contains referential integrity parent relationships, has DATA CAPTURE logging enabled, or has a delete row trigger, then each data row in the partition must be deleted individually. If a table does not have any of these attribute settings, then the data rows are removed by deleting and redefining the underlying data sets.

SYSCOPY and SYSLGRNGX rows associated with the partition being reset are deleted. This includes the rows for the table space partition, partitioned index partitions, LOB table spaces, and auxiliary indexes.

This clause is only implemented syntactically in the XDB Server operating environment.

ADD MATERIALIZED QUERY materialized-query-definition

Changes a base table to a materialized query table. Supplies a definition for a regular table to make it a materialized query table. The table specified by table-name and the result columns of the fullselect must not have the following characteristics:

  • Be already defined as a materialized query table
  • Have any primary keys, unique constraints (unique indexes), referential constraints (foreign keys), check constraints, or triggers defined
  • Be referenced in the definition of another materialized query table
  • Be directly or indirectly referenced in the fullselect
  • Be in an incomplete state

If table-name does not meet these criteria, an error occurs. fullselect defines the query on which the table is based. The columns of the existing table must meet the following characteristics:

  • Have the same number of columns
  • Have exactly the same column definitions
  • Have the same column names in the same ordinal positions

If fullselect is specified, the owner of the table being altered must have the SELECT privilege on the tables or views referenced in the fullselect. Having SELECT privilege means that the owner has at least one of the following authorizations:

  • Ownership of the tables or views referenced in the fullselect
  • The SELECT privilege on the tables and views referenced in the fullselect
  • SYSADM authority
  • DBADM authority for the database in which the table of the fullselect reside

If the owner of the table does not have the SELECT privilege, the following authorization IDs must have SYSADM authority or DBADM authority for the database in which the tables of the fullselect reside:

  • For embedded statements, the authorization ID of the owner of the plan or package
  • For dynamically prepared statements, the SQL authorization ID of the process

Altering a table to change it from a base table to a materialized query table with REFRESH DEFERRED causes any plans and packages dependent on the table to be invalidated.

This clause is only implemented syntactically in the XDB Server operating environment.

refreshable-table-options

Specifies the materialized query table options for altering a regular table to a materialized query table.

DATA INITIALLY DEFERRED

Specifies that the data in the table is not validated as part of the ALTER TABLE statement. A REFRESH TABLE statement can be used to make sure the data in the materialized query table is the same as the result of the query in which the table is based.

REFRESH DEFERRED

Specifies that the data in the table can be refreshed at any time using the REFRESH TABLE statement. The data in the table only reflects the result of the query as a snapshot at the time when the REFRESH TABLE statement is processed or as updated by the user for a user-maintained materialized query table.

MAINTAINED BY SYSTEM or MAINTAINED BY USER

Specifies how the data in the materialized query table is maintained.

MAINTAINED BY SYSTEM

Specifies that the data in the materialized query table table-name is to be maintained by the system. Only the REFRESH TABLE statement is allowed on the table.

MAINTAINED BY USER

Specifies that the data in materialized query table table-name is to be maintained by the user, who can use LOAD utility or the INSERT, DELETE, UPDATE, and REFRESH TABLE statements on the table.

ENABLE QUERY OPTIMIZATION or DISABLE QUERY OPTIMIZATION

Specifies whether this materialized query table can be used for optimization.

ENABLE QUERY OPTIMIZATION

Specifies that the materialized query table can be used for query optimization. If the fullselect specified does not satisfy the restrictions for query optimization, an error occurs.

DISABLE QUERY OPTIMIZATION

Specifies that the materialized query table cannot be used for query optimization. The table can still be queried directly.

DROP MATERIALIZED QUERY

Changes a materialized query table so that it is no longer considered a materialized query table. The table specified by table-name must be defined as a materialized query table. The definition of columns and data of the name are not changed, but the table can no longer be used for query optimization and is no longer valid for use with the REFRESH TABLE statement.

Altering a table to change from a materialized query table to a base table with the DROP MATERIALIZED QUERY clause causes any plans and packages dependent on the table to be invalidated.

This clause is only implemented syntactically in the XDB Server operating environment.

ALTER MATERIALIZED QUERY materialized-query-table-alteration

Changes attributes of a materialized query table. The table-name must identify a materialized query table.

This clause is only implemented syntactically in the XDB Server operating environment.

SET refreshable-table-alteration

Changes how the table is maintained or whether the table can be used in query optimization.

MAINTAINED BY SYSTEM

Specifies that the data in a materialized query table table-name is to be maintained by the system.

MAINTAINED BY USER

Specifies that the data in the materialized query table table-name is to be maintained by the user.

ENABLE QUERY OPTIMIZATION

Specifies that materialized query table table-name can be used in query optimization. If the fullselect specified for the materialized query table does not satisfy the restrictions for automatic query optimization, an error occurs.

DISABLE QUERY OPTIMIZATION

Specifies that materialized query table table-namecannot be used for query optimization. The table can still be queried directly.

DROP CHECK

Drops the check constraint constraint-name. The constraint-name must identify an existing check constraint defined on the table.

DELETE

This clause (available in XDB mode only) deletes one or more data columns from an existing table, by listing the column names (separated by commas) after the DELETE keyword. The corresponding field values are actually removed from each record in the table; all data values in the deleted columns are lost. The ALTER TABLE statement below removes the three columns that were added in the ADD example shown above:

ALTER TABLE supplier
    DELETE state, zip, founded

RENAME

This clause (available in XDB mode only) renames one or more existing columns within an existing table. For each column to be renamed, list the old-column-name, a space, followed by the new-column-name. If more than one column needs renaming, separate the pairs of old and new names with commas.

For example:

ALTER TABLE supplier
    RENAME sno Supplier_No, sname Supplier_Name

MODIFY

This clause (available in XDB mode only) changes the data type or null permission for one or more existing table columns. The new data type must be compatible with the old data type, with conversion being performed whenever possible. The following example changes the character length of the STATUS and CITY columns:

ALTER TABLE supplier
    MODIFY status CHAR 2, city CHAR 15

If the conversion cannot be performed because of incompatible data field types or possible loss of data, an error message is displayed. If a character field is not long enough to hold a string value, the string is truncated on the right.

The following table defines the data conversions permitted. The "Y" values indicate that the intersecting data types are compatible (meaning one type can be switched to the other). The "N" values indicate that the intersecting data types are not compatible.

From/To | small- int | int | float | float4 | dec | Money | date | time | Time- stamp | char | vchar (See note 1) | graph | vgraph (See note 2)
smallint | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
integer | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
float | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
float(4) | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
decimal | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
money | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
date | N | N | N | N | N | N | Y | N | Y | Y | Y | Y | Y
time | N | N | N | N | N | N | N | Y | Y | Y | Y | Y | Y
timestamp | N | N | N | N | N | Y | Y | Y | Y | Y | Y | Y | Y
char | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
varchar | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
graphic | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
vargraph | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
image | This BLOB data type cannot be modified within SQL.
Note:
  • Varchar and Long Varchar are treated the same way for data type conversions.
  • Vargraphic and Long Vargraphic are treated the same way for data type conversions.

In addition to changing data types and null permissions, the MODIFY clause can change character string lengths, along with decimal scale and precision. For example, to change the length of the column named SNAME in the SUPPLIER table to ten characters, enter the following command:

ALTER TABLE supplier
    MODIFY sname CHAR 10

Note that the length of INT and MONEY column fields cannot be changed. To increase the length of a SMALLINT field, change it to INT type. You can also change numeric field types to DECIMAL or FLOAT if you need to accommodate larger numbers.

The MODIFY option can also specify whether or not null values are permitted in a column. The NULL or NOT NULL keywords should appear after the name and data type specifications of the data column. Use the NULL keyword to permit null values in the data column, and the NOT NULL keywords to restrict null values in the column. Use the NOT NULL WITH DEFAULT option to insert default data values in place of null values (current time, current date, zero, etc.).

An error message is displayed if a MODIFY clause attempts to change a data column containing NULL values to NOT NULL. If a null option is not specified in the ALTER TABLE command, no change is made to the null permission currently defined for that column. For example, if the SNO column in the SUPPLIER table was originally defined as "sno CHAR(4)," you can change the null permission to prevent entry of null values using the following command. Note that the data type must be specified, even though it is not changed:

ALTER TABLE supplier
    MODIFY sno char(4) NOT NULL

You can change both field length and null permission to permit nulls by entering:

ALTER TABLE supplier
    MODIFY sno CHAR(6) NULL

UNIQUE KEY

Defines a unique key composed of the identified columns with the specified constraint-name. If a constraint-name is not specified, a name is generated. Each column name must be an unqualified name that identifies a column of the table except a LOB or ROWID column, and the same column must not be identified more than once. Each identified column must be defined as NOT NULL. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 - n for padded indexes and 2000 - n - 2m for nonpadded indexes, where n is the number of columns that can contain null values and m is the number of varying-length columns in the key.

Note:

The various domain and referential constraints discussed in these paragraphs utilize indexes in the background to implement the checks efficiently.

When key-name refers to a unique index created on a parent table (other than the PRIMARY KEY), or when the key-name optionally appears after the referenced-table parameter in the REFERENCES clause of an ADD FOREIGN KEY clause (XDB mode only), that special type of unique index can also be referred to as a candidate-key.

The example below creates a unique index named pskey that constrains each row of the PARTSUPP table to contain a unique set of values in the PNO and SNO columns:

ALTER TABLE partsupp
    UNIQUE KEY pskey (pno, sno)

When the ALTER TABLE...UNIQUE command is issued, the system checks the table to verify whether there are duplicate values in the specified columns. The system creates and maintains a unique index called pskey on the named columns. The index created as a result of a uniqueness constraint cannot be dropped using the DROP INDEX command, since it is required to enforce the uniqueness constraint. To drop the index you must drop the uniqueness constraint.

PRIMARY KEY

The purpose of the primary key is to enforce entity integrity -- that is, to uniquely identify each row of a table. A PRIMARY KEY constraint is similar to a UNIQUE constraint, except that a table can have at most one constraint condition specified as a PRIMARY KEY.

Note that the fields in the primary key must be defined as NOT NULL. The column names must appear in the CREATE UNIQUE INDEX command in exactly the same order as in the PRIMARY KEY constraint. This index will be designated as the primary key of the table. If there is more than one index that satisfies the criteria for a primary key, one is selected arbitrarily as the primary key.

For example, to define columns PNO and SNO as the primary key of the PARTSUPP, use the command:

ALTER TABLE partsupp
    PRIMARY KEY (pno, sno)

To define the column SNO as the primary key of the SUPPLIER table, use a command like:

ALTER TABLE supplier
    PRIMARY KEY (sno)

Again, a unique index must exist on the SUPPLIER table SNO column.

Each column name must be an unqualified name that identifies a column of the table except a LOB or ROWID column, and the same column must not be identified more than once. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 -2m, where m is the number of varying-length columns in the key. The table must not have a primary key and the identified columns must be defined as NOT NULL.

FOREIGN KEY

A FOREIGN KEY constraint is used to enforce referential integrity -- the relationship between a referencing or dependent table and a referenced or parent table. The referential integrity rule requires that, for any value in the dependent column(s), there must exist a row in the parent table such that the value of the dependent column(s) equals the value of the corresponding column(s) in the primary key of the parent table. This is enforced as follows:

  1. When an update or insert is performed on the dependent table, the set of values placed in the referencing columns must match a set of values that exists in the parent table.
  2. If an attempt is made to delete or update a row of the parent table that contains values matching those in a dependent table, the system uses the ON DELETE (or ON UPDATE) clause to determine the delete rule to be used. The options are:
    • RESTRICT

      Prevents records from being deleted from the parent table if dependents exist. This is the default setting.

    • NO ACTION

      Prevents records from being deleted from the parent table (as in the RESTRICT option), except the referential constraint is enforced at the end of the statement. This is the default setting if the CURRENT RULES special register is STD (SQL standard).

    • CASCADE

      Deletes the dependent records from the current table and then deletes the parent records.

    • SET NULL

      Causes each nullable column in the foreign key of each dependent record to be set to NULL before the corresponding parent records are deleted.

Note that whenever a cyclical situation exists (for example a foreign key of table B references the primary key of table A, and a foreign key of table A references a primary key of table B), the delete rules should be the same for all foreign keys, and the SET NULL option should not be used.

To create a referential integrity constraint you must create a FOREIGN KEY constraint on the referencing table. The FOREIGN KEY constraint must reference the existing PRIMARY KEY or UNIQUE KEY of the referenced table.

FOREIGN KEY columns do not have to have the same names as the corresponding columns in the PRIMARY KEY of the referenced table, but the columns must match in type, number and order.

A constraint-name is used to uniquely identify the FOREIGN KEY constraint. The constraint-name should be a short identifier (up to eight characters) that is unique among all constraints built on the table. The constraint-name is stored in the RELNAME column of the SYSIBM.SYSFOREIGNKEYS catalog table, and is displayed in the error message generated when the constraint is violated.

It is a good practice to provide a meaningful constraint-name, however, if a constraint-name is not supplied, the system automatically generates one by first checking the first eight characters of the first column name (in the column list) for uniqueness. If these eight characters are not unique, the XDB Server truncates the last character and substitutes a number -- checking again for uniqueness. If necessary, one letter at a time is removed from the end of the constraint name and replaced with a number until the constraint name becomes unique among all constraint names that exist on the table.

The foreign key of the referential constraint is composed of the identified columns. Each column-name must be an unqualified name that identifies a column of T1 except a ROWID column or security label column, and the same column must not be identified more than once. The number of identified columns must not exceed 64 and the sum of their length attributes must not exceed 255 minus the number of columns that allow null values. The referential constraint is a duplicate if the FOREIGN KEY and the parent table are the same as the FOREIGN KEY and parent table of an existing referential constraint on T1. The specification of a duplicate referential constraint is ignored with a warning.

Indexes on Foreign Keys

The XDB Server automatically builds an index on your FOREIGN KEY columns. The system will generate the name of the index and store it in the REFKEYNAME column of theSYSIBM.SYSREF catalog table. DB2, in contrast, does not automatically create an index on FOREIGN KEY columns.

If you are using your DB2 data definition language (DDL) script, and this script contains CREATE INDEX commands on FOREIGN KEY columns, you can end up with redundant indexes. For optimal performance, you should modify your DB2 DDL script to remove any CREATE INDEX commands on FOREIGN KEY columns.

To demonstrate the use of a FOREIGN KEY constraint, consider the SUPPLIER and PARTSUPP tables (see XDB Server Tutorial Location). There should not be any values in the SNO column of the PARTSUPP table that do not appear in the SUPPLIER table, since you cannot order from a supplier that does not exist. To enforce this rule, a PRIMARY KEY is built on the SNO column of the SUPPLIER table. Next a FOREIGN KEY constraint is built on the SNO column of the PARTSUPP table. The PARTSUPP table is the referencing table and the SUPPLIER table is the referenced table. The example below adds a foreign key constraint named ps_fkey to the PARTSUPP table:

ALTER TABLE partsupp
    FOREIGN KEY ps_fkey (sno)
    REFERENCES supplier

If an attempt is made to remove a supplier from the SUPPLIER table, it will be permitted only if there are no matching records in the PARTSUPP table. It is possible, therefore, to delete the row where SNO equals S5, since supplier S5 supplies no parts. But the row where SNO equals S1 cannot be deleted, since supplier S1 supplies many parts. Each matching record in the PARTSUPP table must be deleted before the S1 record could be deleted from the SUPPLIER table.

If the command was specified using the ON DELETE CASCADE option, as shown below, the SUPPLIER record S5 could be deleted, but all PARTSUPP records for S5 would also be deleted.

ALTER TABLE partsupp
    FOREIGN KEY ps_fkey (sno)
    REFERENCES supplier
    ON DELETE CASCADE

CHECK

In XDB mode, you can also add a CHECK constraint to a table, consisting of a search condition that must be true for every row of the table. If an attempt is made to update or insert a row that does not satisfy the search condition, an error results. Any SQL search condition can be used. CHECK conditions are stored in the SYSIBM.SYSCHECK table (see XDB Server System Tables).

Note:

The system does not check the data currently in the table to verify whether it satisfies the CHECK constraint. You should delete or update the rows that violate the constraint before issuing the ALTER TABLE...CHECK statement.

For example, to impose the constraint that no part be supplied in quantities greater than 500, use the following ALTER TABLE statement:

ALTER TABLE partsupp
    CHECK qty <= 500

A CHECK constraint may be a compound condition. For example, you may issue the command:

ALTER TABLE employee
    CHECK (payrate <= 20
           AND hours <= 60
           AND dept = 2020)
           OR (payrate <= 25
               AND hours <= 40
               AND dept = 1050)

This constraint always checks to verify that employees in Department 2020 are not paid more than $20.00 an hour, and do not work more than 60 hours a week. On the other hand, employees in department 1050 cannot receive pay greater than $25.00 an hour or work more than 40 hours a week.

You may use nested queries and nested joins in the CHECK condition, if desired.

DROP

This option is used to drop uniqueness, referential or check constraints. If no constraint is found, the command has no effect.

For example, to drop the PRIMARY KEY on the employee table, issue the statement:

ALTER TABLE employee
    DROP PRIMARY KEY

To drop a UNIQUE KEY named ps_key on the PARTSUPP table columns SNO and PNO, issue the statement:

ALTER TABLE partsupp
    DROP KEY ps_key

To drop a FOREIGN KEY constraint called ps_fkey on the PARTSUPP table, issue the statement:

ALTER TABLE partsupp
    DROP FOREIGN KEY ps_fkey

To drop a CHECK constraint on the PARTSUPP table, issue the statement:

ALTER TABLE partsupp
    DROP CHECK
Note:

When using ALTER TABLE, there are restrictions for adding columns. You cannot add:

  • A column to a table that has an edit procedure
  • A ROWID column to a table that already has a ROWID column
  • An identity column to a table that already has an identity column
  • A ROWID, or identity column to a created temporary table

Adding a ROWID column

When you add a ROWID column to an existing table, XDB ensures that the same, unique row ID value is returned for a row whenever it is accessed. Reorganizing a table space has no effect on the values in a ROWID column.

Altering the length of a column

Only the length of VARCHAR columns can be changed. When changing the length of a column, be aware of the following information about indexes, limit keys, check constraints, and invalidation.

The length of a VARCHAR column cannot be changed if any of the following conditions are true:

  • The column is referenced in a referential constraint or view.
  • The column has a field procedure routine
  • The table has an edit or validation routine
  • The table is defined with DATA CAPTURE CHANGES
  • The table is a created temporary table

The XDB Server operating environment does not currently provide this functionality.

Indexes

After the ALTER TABLE statement is executed, each index on the table with a key that includes a column whose length was increased remains available. However, SQL operations against such an index are not allowed until the changes from the ALTER TABLE statement are committed.

The maximum number of distinct alters that increase the index key length is sixteen or less. If the maximum number of alters is exceeded, SQLCODE -148 is returned, and the index must be reorganized or rebuilt. An alter is considered distinct when it occurs in a different unit of work than the previous alter. For example, changing an index column length, committing database changes, and changing the column length of that index column or another index column counts as two distinct alters. Whereas, changing an index column length twice before committing any changes counts as one distinct alter; the second changes replace the first because it was in the same commit scope. Changing the length of two different index columns before committing the changes also counts as one distinct alter.

Check constraints

If a table check constraint refers to the column being altered, the length of the column is also changed in the check constraint.

Examples

Column DEPTNAME in table DSN8610.DEPT was created as a VARCHAR(36). Increase its length to 50 bytes. Also, add the column BLDG to the table DSN8610.DEPT. Describe the new column as a character string column that holds SBCS data.

 ALTER TABLE DSN8610.DEPT
   ALTER COLUMN DEPTNAME SET DATA TYPE VARCHAR(50)
   ADD BLDG CHAR(3) FOR SBCS DATA;

Assign a validation procedure named DSN8EAEM to the table DSN8610.EMP.

 ALTER TABLE DSN8610.EMP
   VALIDPROC DSN8EAEM;

Disassociate the current validation procedure from the table DSN8610.EMP. After the statement is executed, the table no longer has a validation procedure.

 ALTER TABLE DSN8610.EMP
   VALIDPROC NULL;

Define ADMRDEPT as the foreign key of a self-referencing constraint on DSN8610.DEPT.

 ALTER TABLE DSN8610.DEPT
   FOREIGN KEY(ADMRDEPT)
      REFERENCES DSN8610.DEPT ON DELETE CASCADE;

Add a check constraint to the table DSN8610.EMP which checks that the minimum salary an employee can have is $10,000.

 ALTER TABLE DSN8610.EMP
   ADD CHECK (SALARY >= 10000);

Alter the PRODINFO table to define a foreign key that references a non-primary unique key in the product version table (PRODVER_1). The columns of the unique key are VERNAME, RELNO.

 ALTER TABLE PRODINFO
   FOREIGN KEY (PRODNAME,PRODVERNO)
      REFERENCES PRODVER_1 (VERNAME,RELNO) ON DELETE RESTRICT;

The check pending status prevents further updating or reading by other SQL applications. It does not affect the application process that issues ALTER TABLE. However, we do not recommend that a process create or alter a permanent table and then access it.

Parent topic: SQL Statements


ALTER TABLESPACE

The ALTER TABLESPACE statement changes the specifications of a table space within the currently set XDB Server location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER TABLESPACE command, users must possess either DBADM authority for the database, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table space affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER TABLESPACE [database-name.]tablespace-name
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [DSETPASS password]
    [PART integer]
    [FREEPAGE integer]
    [PCTFREE integer]
    [USING {VCAT catalog-name | STOGROUP stogroup-name}]
    [PRIQTY integer]
    [SECQTY integer]
    [ERASE {YES | NO}]
    [COMPRESS {NO | YES}]
    [GBPCACHE {CHANGED | ALL | SYSTEM | NONE}]
    [LOCKMAX {SYSTEM | integer}]
    [LOCKSIZE {ANY | TABLESPACE | TABLE | PAGE | ROW | LOB}]
    [TRACKMOD {YES | NO}]
    [LOG {YES | NO}]
    [LOCKPART {NO | YES}]
    [MAXROWS integer]

Parameters:

database-name.tablespace-name | Identifies the table space to be altered. The table space must exist at the currently set XDB Server location. If the database-name qualifier is omitted, then the XDB Server assumes the table space is located in the default DSNDB04 database (within the current location).
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.
password | Consists of a short identifier.
integer | Specifies a whole number in the range of 1 to n.

Description

Although all of the information contained in the following ALTER TABLESPACE optional clauses is recorded in the XDB Server catalog tables, the XDB Server system architecture does not physically support many of these options. Refer to appropriate DB2 documentation for complete descriptions of these mainframe-specific options.

BUFFERPOOL

This clause has no functional equivalent withing the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for table spaces with 4K page sizes, while the last ten are for table spaces with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server catalog tables.

LOCKSIZE

Specifies the size of locks used within the table space and, in some cases, also the threshold at which lock escalation occurs. Do not specify LOCKSIZE for a table space in a work file database or a TEMP database.

In most cases, DB2 uses LOCKSIZE PAGE LOCKMAX SYSTEM for non-LOB table spaces and LOCKSIZE LOB LOCKMAX SYSTEM for LOB table spaces. However, when the number of locks acquired for the table space exceeds the maximum number of locks allowed for a table space (an installation parameter), the page or LOB locks are released and locking is set at the next higher level. If the table space is segmented, the next higher level is the table. If the table space is nonsegmented, the next higher level is the table space.

TABLESPACE | Specifies table space locks.
TABLE | Specifies table locks. Use TABLE only for a segmented table space.
PAGE | Specifies page locks. Do not use PAGE for a LOB table space.
ROW | Specifies row locks. Do not use ROW for a LOB table space.
LOB | Specifies LOB locks. Use LOB only for a LOB table space.

This option is semantically checked and recorded in the XDB Server system catalog tables. See DB2 documentation for a full discussion of keyword options.

TRACKMOD

Specifies whether DB2 tracks modified pages in the space map pages of the table space or partition. Do not specify TRACKMOD for a LOB table space. For a table space in a TEMP database, DB2 uses TRACKMOD NO regardless of the value specified.

YES | DB2 tracks changed pages in the space map pages to improve the performance of incremental image copy. For data sharing, changing TRACKMOD to YES causes additional SCA (shared communication area) storage to be used until after the next full or incremental image copy is taken or until TRACKMOD is set back to NO.
NO | DB2 does not track changed pages in the space map pages. It uses the LRSN value in each page to determine whether a page has been changed.

LOCKMAX

Specifies the maximum number of page, row, or LOB locks an application process can hold simultaneously in the table space. If a program requests more than that number, locks are escalated. The page, row, or LOB locks are released and the intent lock on the table space or segmented table is promoted to S or X mode. If you specify LOCKMAX a for table space in a TEMP database, DB2 ignores the value because these types of locks are not used.

For an application that uses Sysplex query parallelism, a lock count is maintained on each member.

Integer | Specifies the number of locks allowed before escalating, in the range 0 to 2 147 483 647. Zero (0) indicates that the number of locks on the table or table space are not counted and escalation does not occur.
SYSTEM | Indicates that the value of field LOCKS PER TABLE(SPACE) on installation panel DSNTIPJ specifies the maximum number of page, row, or LOB locks a program can hold simultaneously in the table or table space.

If you change LOCKSIZE and omit LOCKMAX, the following results occur:

LOCKSIZE | Resultant LOCKMAX
TABLESPACE or TABLE | 0
PAGE ROW, or LOB | Unchanged
ANY | SYSTEM

If the lock size is TABLESPACE or TABLE, LOCKMAX must be omitted, or its operand must be 0.

CLOSE

When the limit on the number of open data sets is reached, specifies the priority in which data sets are closed.

YES | Eligible for closing before CLOSE NO data sets. This is the default unless the table space is in a TEMP database.
NO | Eligible for closing after all eligible CLOSE YES data sets are closed.

For a table space in a TEMP database, DB2 uses CLOSE NO regardless of the value specified.

This option is semantically checked and recorded within the XDB Server system catalog tables. See DB2 documentation for a full discussion of keyword options.

DSETPASS

This option records a password for a DB2 subsystem dataset inside the XDB Server system catalog. To remove a password, specify a delimited string of blank characters as the password name. For example:

DSETPASS " "

PART

XDB does not physically support partitioned table spaces, however, this clause can be used to identify a table space partition number (integer) defined within a DB2 subsystem that is being accessed through XDB Link. Do not use this clause if the DB2 table space is not partitioned.

If the DB2 table space is partitioned, the PART clause must be used if the FREEPAGE, PCTFREE, USING, PRIQTY, SECQTY, or ERASE clause appears in the ALTER TABLESPACE statement. Under these circumstances, all alterations specified in the later clause options apply specifically to the table space partition identified in the PART clause.

FREEPAGE

This option specifies the number of pages left free within a segmented table space defined on a DB2 subsystem. The integer whole number value can range from 0 to 255, but must be less than the SEGSIZE value. In situations where the number of pages free is greater than or equal to the SEGSIZE, the number of pages free is corrected downward to the SEGSIZE value minus one.

PCTFREE

This option specifies a whole number value (integer) ranging from 0 to 99. This clause is semantically checked after which the values are recorded in the appropriate XDB Server catalog tables. See DB2 documentation for a full discussion of keyword options.

USING

This clause specifies either a user-managed or DB2-managed dataset for a table space or partition in a DB2 subsystem. For partitioned table spaces, the USING clause is applied only to the dataset within the partition identified in the PART clause. For nonpartitioned table spaces, the USING clause is applied to every dataset that is eligible for a particular table space.

VCAT catalog-name | Designates a user-managed dataset starting with catalog-name. The catalog-name must be a short identifier.
STOGROUP stogroup-name | Identifies a stogroup described in the DB2 catalog. Before applying a new description for a table space, the storage group description must include at least one volume serial number. This volume serial number is entered into the SYSIBM.SYSVOLUMES catalog table, and can be used to locate tables created in this table space on different physical paths (see CREATE STOGROUP).

If the current dataset for the table space or partition is DB2-managed and USING STOGROUP is specified, then omitting the PRIQTY clause implicitly defines the current PRIQTY value. Additionally, omitting the SECQTY clause implicitly defines the current SECQTY value, while omitting the ERASE clause implicitly specifies the current ERASE rule.

If the current dataset for the table space or partition is user-managed and USING STOGROUP is specified, then the omission of the various clauses below implicitly specifies the following:

  • PRIQTY values of 12 for a table space with 4K pages and 96 for a table space with 32K pages, when omitting the PRIQTY clause.
  • SECQTY values of 12 for a table space with 4K pages and 96 for a table space with 32K pages, when omitting the SECQTY clause.
  • Default value of ERASE NO, when omitting the ERASE clause.

PRIQTY

Indicates the replacement value for the last primary space allocation for the table space or partition dataset. This clause can be specified only under one of the following conditions:

  • USING STOGROUP is also specified.
  • The USING clause is not specified, and the table space or partition dataset is DB2-managed.

The value integer is the primary space allocation in kilobytes. Any whole number can be specified up to a limit of 4,194,304. Values greater than 4,194,304 are reduced to 4,194,304. When specifying a number less than 12 for a table space with a page size of 4K, the system increases the number to 12. When specifying a number less than 96 for a table space with a page size of 32K, the system increases the number to 96. If PRIQTY -1 is specified, DB2 uses a default value for the primary space allocation.

If PRIQTY is specified, the primary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

  • For 4KB page sizes, if integer is less than 12, n is 12.
  • For 8KB page sizes, if integer is less than 24, n is 24.
  • For 16KB page sizes, if integer is less than 48, n is 48.
  • For 32KB page sizes, if integer is less than 96, n is 96.
  • For any page size, if integer is greater than 4194304, n is 4194304.

For LOB table spaces, the exceptions are:

  • For 4KB pages sizes, if integer is less than 200, n is 200.
  • For 8KB pages sizes, if integer is less than 400, n is 400.
  • For 16KB pages sizes, if integer is less than 800, n is 800.
  • For 32KB pages sizes, if integer is less than 1600, n is 1600.
  • For any page size, if integer is greater than 4194304, n is 4194304.
  • Do not specify the PRIQTY clause for user-managed datasets.

SECQTY

Indicates the replacement value for the last secondary space allocation for the table space or partition dataset. This clause can be specified only under one of the following conditions:

  • USING STOGROUP is also specified.
  • The USING clause is not specified, and the table space or partition dataset is DB2-managed.

The value integer is the secondary space allocation in kilobytes. For a dataset or table space using 4K pages, any whole number can be specified up to a limit of 131,068. Values greater than 131,068 are reduced to 131,068. The maximum allowable secondary allocation for 32K page size datasets is 131,040. If a value of zero is specified, the dataset cannot be extended. If SECQTY -1 is specified, DB2 uses a default value for the secondary space allocation.

If SECQTY is specified, the secondary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

  • If integer is greater than 4194304, n is 4194304. A value of 0 for integer indicates that no data set can be extended.

For LOB table spaces the exceptions are:

  • For 4KB page sizes, if integer is greater than 0 and less than 200, n is 200.
  • For 8KB page sizes, if integer is greater than 0 and less than 400, n is 400.
  • For 16KB page sizes, if integer is greater than 0 and less than 800, n is 800.
  • For 32KB page sizes, if integer is greater than 0 and less than 1600, n is 1600.
  • For any page size, if integer is greater than 4194304, n is 4194304.

Do not specify the SECQTY clause for user-managed datasets.

ERASE

This clause can be specified only under one of the following conditions:

  • USING STOGROUP is also specified.
  • The USING clause is not specified, and the table space or partition dataset is DB2-managed.

Do not specify the ERASE clause for user-managed datasets.

COMPRESS

Specifies whether data compression applies to the rows of the table space or partition. Do not specify COMPRESS for a LOB table space.

Either the option specified or the default value is recorded in the SYSIBM.SYSTABLEPART system catalog table. This option does not compress data in any way.

GBPCACHE

In a data sharing environment, specifies what pages of the table space or partition are written to the group buffer pool in a data sharing environment. In a non-data-sharing environment, you can specify GBPCACHE for a table space other than one in a work file or TEMP database, but it is ignored. Do not specify GBPCAHCE for a table space in a work file database or in a TEMP database in either environment (data sharing or not).

CHANGED When there is inter-DB2 R/W interest on the table space or partition, updated pages are written to the group buffer pool. When there is no inter-DB2 R/W interest, the group buffer pool is not used. Inter-DB2 R/W interest exists when more than one member in the data sharing group has the table space or partition open, and at least one member has it open for update.

If the table space is in a group buffer pool that is defined to be used only for cross-invalidation (GBPCACHE NO), CHANGED is ignored and no pages are cached to the group buffer pool.

ALL Indicates that pages are to be cached in the group buffer pool as they are read in from DASD.

Exception: In the case of a single updating DB2 when no other DB2s have any interest in the page set, no pages are cached in the group buffer pool.

Hiperpools are not used for table spaces or partitions that are defined with GBPCACHE ALL.

If the table space is in a group buffer pool that is defined to be used only for cross-invalidation (GBPCACHE NO), ALL is ignored and no pages are cached to the group buffer pool.

SYSTEM Indicates that only changed system pages within the LOB table space are to be cached to the group buffer pool. A system page is a space map page or any other page that does not contain actual data values.

SYSTEM is the default for a LOB table space. Use SYSTEM only for a LOB table space.

NONE Indicates that no pages are to be cached to the group buffer pool. DB2 uses the group buffer pool only for cross-invalidation.

If you specify NONE, the table space or partition must not be in recover pending status.

If you specify GBPCACHE in a data sharing environment, the table space or partition must be in the stopped state when the ALTER TABLESPACE statement is executed. You cannot alter the GBPCACHE value for the following table spaces:

  • DSNDB06.SYSDBASE
  • DSNDB06.SYSDBAUT
  • DSNDB06.SYSPKAGE
  • DSNDB06.SYSPLAN
  • DSNDB06.SYSUSER (exception: the attribute can be altered if authorization includes installation SYSADM authority.)

LOG

Specifies whether changes to a LOB column in the table space are to be written to the log. Use LOG only for a LOB table space.

YES Indicates that changes to a LOB column are to be written to the log. You cannot use YES if the auxiliary table in the table space stores a LOB column that is greater than 1 gigabyte in length.

When you change the value of LOG to YES, the LOB table space is placed in copy pending status.

NO Indicates that changes to a LOB column are not to be written to the log.

LOG NO has no effect on a commit or rollback operation; the consistency of the database is maintained regardless of whether the LOB value is logged. All committed changes and changes that are rolled back reflect the expected results.

Even when LOG NO is specified, changes to system pages and to the auxiliary index are logged. During the log apply operation of the RECOVER utility, LPL recovery, or GPB recovery, all LOB values that were not logged are marked invalid and cannot be accessed by a SELECT or FETCH statement. Invalid LOB values can be updated or deleted.

LOCKPART

You can specify the LOCKPART clause, but it has no effect. Starting with Version 8, DB2 treats all partitioned table spaces as if they were defined as LOCKPART YES. LOCKPART YES specifies the use of selective partition locking. When all the conditions for selective partition locking are met, DB2 locks only the partitions that are accessed. When the conditions for selective partition locking are not met, DB2 locks every partition of the table space.

Running utilities

You cannot execute the ALTER TABLESPACE statement while a DB2 utility has control of the table space.

Altering more than one partition

To change FREEPAGE, PCTFREE, USING, PRIQTY, SECQTY, COMPRESS, ERASE, or GBPCACHE for more than one partition, you must use separate ALTER TABLESPACE statements.

Altering storage attributes

The USING, PRIQTY, SECQTY, and ERASE clauses define the storage attributes of the table space or partition. If you specify USING or ERASE when altering storage attributes, the table space or partition must be in the stopped state when the ALTER TABLESPACE statement is executed. You can use a STOP DATABASE...SPACENAM... command to stop the table space or partition.

If the catalog name changes, the changes take effect after you move the data and start the table space or partition using the START DATABASE...SPACENAM... command. The catalog name can be implicitly or explicitly changed by the ALTER TABLESPACE statement. The catalog name also changes when you move the data to a different device

Changes to the secondary space allocation (SECQTY) take effect the next time DB2 extends the data set; however, the new value is not Reflected in the integrated catalog until you use the REORG, RECOVER, or LOAD REPLACE utility on the table space or partition. The changes to the other storage attributes take effect the next time the page set is reset. For a non-LOB table space, the page set is reset when you use the REORG, RECOVER, or LOAD REPLACE utilities on the table space or partition. For a LOB table space, the page set is reset when RECOVER is run on the LOB table space or LOAD REPLACE is run on its associated base table space. If there is not enough storage to satisfy the primary space allocation, a REORG might fail. If you change the primary space allocation parameters or erase rule, you can have the changes take effect earlier if you move the data before you start the table space or partition

Examples:

Alter table space DSN8S61E in database DSN8D61A. CLOSE NO means that the data sets of the table space are not to be closed when there are no current users of the table space.

 ALTER TABLESPACE DSN8D61A.DSN8S61E
     CLOSE NO;

Alter table space DSN8S61D in database DSN8D61A. BP2 is the buffer pool associated with the table space. PAGE is the level at which locking is to take place.

 ALTER TABLESPACE DSN8D61A.DSN8S61D
     BUFFERPOOL BP2
     LOCKSIZE PAGE;
Parent topic: SQL Statements


ALTER VIEW

The ALTER VIEW statement regenerates a view using an existing view definition at the current server.

The XDB Server operating environment only provides syntax support for this statement at this time.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

  • Ownership of the view
  • SYSADM authority
  • SYSCTRL authority

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is the union of the privilege sets that are held by each authorization ID of the process.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER VIEW view-name REGENERATE

Description

view-name
Identifies the view to be regenerated. The name must identify a view that exists at the current server.
REGENERATE
Specifies that the view is to be regenerated. The view definition in the catalog is used, and existing authorizations and dependent views are retained. The catalog is updated with the regenerated view definition. If the view cannot be successfully regenerated, an error is returned.
Parent topic: SQL Statements


ASSOCIATE LOCATORS

The ASSOCIATE LOCATORS statement gets the result set locator value for each result set returned by a stored procedure.

Invocation

This statement can be embedded in an application program. It is an executable statement that can be dynamically prepared. It cannot be issued interactively.

Authorization

No authorization is required for this statement.

Syntax

ASSOCIATE [RESULT SET] {LOCATOR | LOCATORS}
    (rs-locator-variable ,...)
    WITH PROCEDURE {procedure-name | host-variable}

Parameters

RESULT SET
This optional item has no effect on the execution of the statement. Use it only to improve the readability of the statement.

More than one locator can be assigned to a result set. You can issue the same ASSOCIATE LOCATORS statement more than once with different result set locator variables.

If the number of result set locator variables that are listed in the ASSOCIATE LOCATORS statement is less than the number of locators returned by the stored procedure, all variables in the statement are assigned a value, and a warning is issued.

If the number of result set locator variables that are listed in the ASSOCIATE LOCATORS statement is greater than the number of locators returned by the stored procedure, the extra variables are assigned a value of 0.

The ASSOCIATE LOCATORS statement assigns result set locator values from the SQLVAR sections of the SQLDA to result set locator variables. For languages other than REXX, the first SQLDATA field is assigned to the first locator variable, the second SQLDATA field to the second locator variable, and so on. For REXX, the first SQLLOCATOR field is assigned to the first locator variables, the second SQLLOCATOR field to the second locator variable, and so on.

If a stored procedure is called more than once with a one-part name at the same location, only the most recent result sets are accessible.

LOCATOR | LOCATORS
Specifies the use of a locator or locators.
rs-locator-variable
Identifies a result set locator variable that has been declared according to the rules for declaring result set locator variables. One result set locator variable is required for each result set that is returned by the stored procedure. If the stored procedure returns fewer result sets than the number of result set locator variables specified, the extra variables are assigned a value of 0.
WITH PROCEDURE

Identifies the stored procedure that returned result set locators by the specified procedure name or the procedure name contained in the host variable.

A procedure name is a qualified or unqualified name. Each part of the name is a long SQL identifier that must be composed of SBCS characters:

  • A fully qualified procedure name is a three-part name. The first part is a location name that identifies the DBMS where the procedure is stored. The next two parts identify the stored procedure. A period must separate each of the parts. Any or all of the parts can be a delimited identifier.
  • An implicitly qualified procedure name is a two-part name that is qualified by the location name of the current server. The two parts identify the schema name and the name of the stored procedure. A period must separate the two parts. The first part identifies the stored procedure at the server. The location name of the first part depends on the application server.
  • An unqualified procedure name is a one-part name with two implicit qualifiers. The first implicit qualifier is the location name of the current server. The second implicit qualifier identifies the stored procedure at the server. The meaning of the second implicit qualifier depends on the application server (for MVS, it is SYSPROC). The name and its implicit qualifiers identifies a stored procedure.

    Successful execution of the ASSOCIATE LOCATOR statement only requires that the unqualified procedure name in the statement is the same as the procedure name in the most recently executed CALL statement that was specified with an unqualified procedure name. (The implicit schema name for the unqualified name in the CALL statement is not considered in the match.) The rules for how the procedure name must be specified are described below.

If a host variable is used:

  • It must be a character string variable with a length attribute that is not greater than 254.
  • It must be preceded by a colon and must not be followed by an indicator variable.
  • The value of the host variable is a specification that depends on the application server. Regardless of the application server, the specification must:
    • Be left justified within the host variable
    • Not contain embedded blanks
    • Be padded on the right with blanks if its length is less than that of the host variable

The procedure name in the ASSOCIATE LOCATORS statement must be specified the same way that it was specified on the CALL statement. For example, if a two-part name was specified on the CALL statement, you must use a two-part name in the ASSOCIATE LOCATORS statement. However, there is one condition under which the names do not have to match. If the CALL statement was made with a three-part name and the current server is the same as the location in the three-part name, you can omit the location name and specify a two-part name.

procedure-name
Identifies the stored procedure that returned result set locators by the specified procedure name.
host-variable
Identifies the stored procedure that returned result set locators by the procedure name contained in the host variable.

Description

The ASSOCIATE LOCATORS statement assigns result set locator values from the SQLVAR sections of the SQLDA to result set locator variables so that the first SQLDATA field is assigned to the first locator variable, the second SQLDATA field to the second locator variable, and so on.

More than one locator can be assigned to a result set. You can issue the same ASSOCIATE LOCATORS statement more than once with different result set locator variables.

If the number of result set locator variables listed in the ASSOCIATE LOCATORS statement is less than the number of locators returned by the stored procedure, all variables in the statement are assigned a value, and a warning is issued.

If the number of result set locator variables listed in the ASSOCIATE LOCATORS statement is greater than the number of locators returned by the stored procedure, the extra variables are assigned a value of 0.

When the ASSOCIATE LOCATORS statement is executed, the procedure name or specification must identify a stored procedure that the requestor has already invoked using the CALL statement.

Note: For this statement to be successful, the application must be currently connected to the site at which the stored procedure was executed.

Examples

The statements in the following examples are assumed to be in COBOL programs.

Use result set locator variables LOC1 and LOC2 to get the result set locator values for the two result sets returned by stored procedure P1. Assume that the stored procedure is called with a one-part name from current server SITE2.

 EXEC SQL CONNECT TO SITE2;
 EXEC SQL CALL P1;
 EXEC SQL ASSOCIATE RESULT SET LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE P1;

Repeat the scenario above, but use a two-part name to specify an explicit schema name for the stored procedure to ensure that stored procedure P1 in schema MYSCHEMA is used.

 EXEC SQL CONNECT TO SITE2;
 EXEC SQL CALL MYSCHEMA.P1;
 EXEC SQL ASSOCIATE RESULT SET LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE MYSCHEMA.P1;

Use result set locator variables LOC1 and LOC2 to get the result set locator values for the two result sets that are returned by the stored procedure named by host variable HV1. Assume that host variable HV1 contains the value SITE2.MYSCHEMA.P1 and the stored procedure is called with a three-part name.

 EXEC SQL CALL SITE2.MYSCHEMA.P1;
 EXEC SQL ASSOCIATE LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE :HV1;

The preceding example would be invalid if host variable HV1 had contained the value MYSCHEMA.P1, a two-part name. For the example to be valid with that two-part name in host variable HV1, the current server must be the same as the location name that is specified on the CALL statement as the following statements demonstrate. This is the only condition under which the names do not have to be specified the same way and a three-part name on the CALL statement can be used with a two-part name on the ASSOCIATE LOCATORS statement.

 EXEC SQL CONNECT TO SITE2;
 EXEC SQL CALL SITE2.MYSCHEMA.P1;
 EXEC SQL ASSOCIATE LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE :HV1;
Parent topic: SQL Statements


BACKUP LOCATION

This XDB Server utility command copies the entire contents of an XDB Server location to the specified drive and path while the XDB Server location is still generally available.

Invocation

BACKUP LOCATION can be executed interactively, embedded in a host language, or dynamically prepared.

Authorization

To use the BACKUP LOCATION command you must be a super user.

Syntax

BACKUP LOCATION location-name TO path-name
[INCREMENTAL]

Parameters:

location-name | Identifies the location to be backed up.
path-name | Specifies the parent target directory where backups are stored. Inside this directory, a subdirectory will be created that contains this backup’s contents. This subdirectory’s name is of the form xdbYYYYMMDDHHMMSSnnnnnn, where YYYYMMDDHHMMSS is the time of the backup, and nnnnnn is a relative sequence number.
INCREMENTAL | Indicates that you want to backup only your log files. Omitting this option results in your log files and your location’s database files being backed up.

Description

The BACKUP LOCATION command is used for backing up locations (including all associated databases, tables, catalog tables, and log files) to a secure device, such as a file server, or a different disk drive.

This is useful for avoiding losses due to media or machine failure. For instance, if the drive where your XDB location was located becomes inoperable, provided that you have issued a BACKUP LOCATION command that saved the entire contents of that location to another disk you can ROLLFORWARD that backup to recreate the corrupted location.

While the standard BACKUP LOCATION command copies both database and log files, in addition to creating a recovery script (xdbdata.bat), a BACKUP LOCATION INCREMENTAL backs up only the log files for your location.

After performing a standard backup (which is mandatory for all recovery scenarios), which type of backup you perform is up to you. Always performing standard backups takes longer than performing incremental backups but the recovery process from them is much easier and quicker. Performing incremental backups is quicker than performing standard backups but more ROLLFORWARD steps might be necessary to recreate your location.

Examples:

BACKUP LOCATION (Standard)
The following command creates a directory, such as d:\backuplocs\xdb20051017151315000001, that contains an xdbdata.bat script, database files and log files:
BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
BACKUP LOCATION (Incremental)
The following command creates a directory, such as d:\backuplocs\xdb20051017151315000002, that contains only log files:
BACKUP LOCATION MYLOC TO D:\BACKUPLOCS INCREMENTAL
Recovery with Standard Backups
The following sequence of events shows the typical steps in performing standard backups and subsequently recovering from a media failure:
  1. On Friday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  2. On Monday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  3. On Tuesday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  4. On Wednesday morning recover from a media failure using the following steps:
    1. Stop the XDB Server.
    2. Copy the contents of the current logs to another directory, such as d:\currlocs.
    3. Remove the contents of the original XDB location.
    4. Run the xdbdata.bat script in Tuesday afternoon’s d:\backuplocs subdirectory.
    5. Start the XDB Server in exclusive use mode.
    6. Issue the following ROLLFORWARD command:
      ROLLFORWARD MYLOC USING D:\CURRLOGS
    7. Stop the XDB Server.
    8. Restart the XDB Server for general availability.
Recovery with Incremental Backups
The following sequence of events shows the typical steps in performing incremental backups and subsequently recovering from a media failure:
  1. On Friday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  2. On Monday afternoon perform an incremental backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS INCREMENTAL

    This creates directory xdb20051015153015000002, for instance.

  3. On Tuesday afternoon perform an incremental backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS INCREMENTAL

    This creates directory xdb20051016144416000003, for instance.

  4. On Wednesday morning recover from a media failure using the following steps:
    1. Stop the XDB Server.
    2. Copy the contents of the current logs to another directory, such as d:\currlocs.
    3. Remove the contents of the original XDB location.
    4. Run the xdbdata.bat script in Friday afternoon’s d:\backuplocs subdirectory.
    5. Start the XDB Server in exclusive use mode.
    6. Issue the following ROLLFORWARD commands:
      ROLLFORWARD MYLOC USING D:\BACKUPLOCS\XDB20051015153015000002
ROLLFORWARD MYLOC USING D:\BACKUPLOCS\XDB20051016144416000003
ROLLFORWARD MYLOC USING D:\CURRLOGS
    7. Stop the XDB Server.
    8. Restart the XDB Server for general availability.
Parent topic: SQL Statements


BEGIN DECLARE SECTION

The BEGIN DECLARE SECTION statement (embedded SQL only) marks the beginning of a host variable declare section in an application program.

Invocation

BEGIN DECLARE SECTION is not an executable statement. It can only be embedded in a host language.

Authorization

No special authorization is required.

Syntax

BEGIN DECLARE SECTION

Description

BEGIN DECLARE SECTION may be used in an application program to mark the beginning of the section of code where host variables are declared. If a BEGIN DECLARE SECTION is used, the host variable declaration section must end with the END DECLARE SECTION statement.

When programming in C, or when the DECLARE or ANSI COBOL preprocessor directives are used, BEGIN and END DECLARE SECTION commands must surround the declarations for all host variables, to create host variable declaration blocks. As illustrated in the COBOL example below, a host variable declaration block can appear anywhere that the host language allows variable declarations:

EXEC SQL BEGIN DECLARE SECTION;
        short int cust_num = 28;
        char name[30];
EXEC SQL END DECLARE SECTION;

The following rules are enforced by the precompiler, only if C is the host language, or if the DECLARE or ANSI COBOL precompiler option is specified:

  • Variables referenced within SQL statements must be declared within the variable declaration section of the host program.
  • There must be a paired set of BEGIN DECLARE SECTION and END DECLARE SECTION statements.
Note:

Only if the DECLARE or the ANSI COBOL precompiler directive is specified or the host language is C, are host variable declaration sections required. Any source program, in any host language, can be made to conform to the SAA definition of SQL by specifying a declare section. If variable declaration sections are used when they are not required, all variables declared outside the declare section must have a name different from all variable names declared within the declare section.

Parent topic: SQL Statements


BULK

The BULK ON command activates the Bulk Upload feature which increases the efficiency of your transactions between the mainframe and XDB Link. The BULK OFF command turns off the Bulk Upload feature.

Invocation

BULK ON and BULK OFF are not executable statements. They can only be embedded in a host language.

Note:

To use the BULK ON and BULK OFF commands, you must include the XDBFUNCS directive as explained in your COBOL precompiler manual.

Authorization

No special authorization is required.

Syntax

BULK [ON | OFF]

Description

The BULK ON command optimizes communications between the mainframe and XDB Link. BULK ON sets internal indicators allowing XDB Link to operate in Bulk Upload mode -- whereby INSERT, UPDATE and DELETE statements are sent to the mainframe as usual, but the SQLCA response buffers are not sent back to the XDB Link until a bulk interval has been reached. This reduction in the number of SQLCA responses optimizes upload performance by reducing the number of LU6.2 line turn-around events associated with the upload procedure.

The bulk interval for the upload is determined by the Upload Pacing Limit value specified in the Location Configuration dialog box in the Gateway Profile Utility or by a COMMIT statement. If, for example, the interval is set to 10, then every tenth SQL upload statement (such as INSERT, UPDATE and DELETE) contains an active SQLCA indicating the true SQLCODE for the bulk process.

Bulk Upload mode can be deactivated by issuing a BULK OFF statement, which terminates Bulk Upload mode for all subsequent transactions. If an SQL error has occurred in the bulk upload interval, it is returned in the next live SQLCA. A live SQLCA (reporting the true status of the bulk interval) is returned either at the end of a bulk interval or with the next statement following a BULK OFF command.

Note:

A live SQLCA is also returned if a SELECT statement is inadvertently issued in the middle of a bulk upload process. It must be noted that this SQLCA is reporting the status of the bulk interval, and not the SELECT statement.

Error Handling

With any SQL error, a nonzero SQLCODE is returned. The SQLERRD[3] field of the SQLCA indicates the first statement to fail in the bulk interval. You can also terminate the interval with a COMMIT. The COMMIT in this case is not executed, and you can choose to re-issue the COMMIT (not recommended) or ROLLBACK the entire bulk upload interval.

SQLCA Status

SQLCA information is loaded after each SQL call. The status of the SQLCA is indicated by the SQLERRD[3] field:

SQLERRD[3] = -1

Inactive SQLCA. A pseudo-SQLCA is being sent to the client because the client application is in the middle of a bulk upload interval.

SQLERRD[3] = 0

Active SQLCA. Indicates a successful return of all SQLCAs for all SQL statements in the bulk upload interval. Along with the SQLCODE, shows the status of the bulk process.

SQLERRD[3] > 0

Active SQLCA. An error has occurred in this bulk interval. SQLERRD[3] is indicating the number of SQL statements that qualify for failure based on the first SQL statement failure. SQLCODE shows the SQL error for the failing SQL statement.

Examples:

In the following scenario the Bulk Interval is set to a value of 10, with the third SQL statement in error:

SQLERRD[3] = 8

Indicates that eight SQL statements (the third through the tenth) are in doubt (with the first two being all right).

SQLCODE = -551

Indicates that an authorization error occurred on the third (or failed) SQL statement.

You could choose to ROLLBACK this bulk process, and re-execute (using BULK OFF) to monitor each failure.

The following steps are recommended for turning off bulk upload mode, and checking for errors:

EXEC SQL BULK OFF
EXEC SQL COMMIT

Finally, test the SQLCODE value for errors. If errors are found, issue a ROLLBACK.

Parent topic: SQL Statements


CALL

The XDB Server can run a stored procedure on the mainframe (through XDB Link) or on an XDB Server through use of the CALL statement.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

The privileges required to execute the CALL statement are determined by the owner of the package or plan that contains the CALL statement. If the server is DB2 for MVS/ESA (or an XDB Server), that AuthID must have either the EXECUTE privilege on the package associated with the stored procedure, ownership of the package associated with the stored procedure, PACKADM authority for the package's collection, or SYSADM authority.

The authorization ID that must have the EXECUTE privilege on the stored procedure depends on the form of the CALL statement:

  • For static SQL programs that use the syntax CALL procedure, the owner of the plan or package that contains the CALL statement must have one of the following:
    • The EXECUTE privilege on the stored procedure
    • Ownership of the stored procedure
    • SYSADM authority
  • For static SQL programs that use the syntax CALL host variable (ODBC applications use this form of the CALL statement), the authorization ID of the plan or package that contains the CALL statement must have one of the following:
    • The EXECUTE privilege on the stored procedure
    • Ownership of the stored procedure
    • SYSADM authority

The authorization that is required to run the stored procedure package and any packages that are used under the stored procedure apply to any form of the CALL statement as follows:

Stored procedure package

One of the authorization IDs that are defined below under Set of authorization IDs must have at least one of the following on the stored procedure package:

  • The EXECUTE privilege on the package
  • Ownership of the package
  • PACKADM authority for the package's collection
  • SYSADM authority

A PKLIST entry is not required for the stored procedure package.

Syntax

CALL {procedure-name | host-variable}
[({expression | NULL | TABLE transition-table-name}[,...]) |
USING DESCRIPTOR descriptor-name]

Parameters:

procedure-name | A qualified or unqualified name that identifies the stored procedure. Procedure names can be three-part, two-part or unqualified one-part names. A fully qualified procedure name begins with a location name that identifies the DBMS at which the procedure is stored. The second and third parts identify the stored procedure. A period must separate each of the parts.
host-variable-1 | Character string variable with a maximum length of 254 bytes that identifies the stored procedure by the value of the specified host variable. This host variable must be preceded by a colon and must not be followed by an indicator variable.
host-variable-2 | Identifies a parameter of the CALL statement. The host variable must identify a host variable (not a structure) described in the program according to the rules for declaring host variables. The data type of the variable must be compatible with the data type of the corresponding parameter of the stored procedure.
constant | A parameter of the stored procedure expressed as a constant in the CALL statement. The data type of the constant must be compatible with the corresponding parameter of the stored procedure and that parameter must be defined as IN.
NULL | A parameter of the stored procedure expressed as a NULL value in the CALL statement. The corresponding parameter of the stored procedure must be defined as IN, and the description of the stored procedure must allow for null parameters.
descriptor-name | Identifies an SQLDA that must contain a valid description of host variables. In C, the descriptor-name can be a pointer to an SQLDA.

Description

A stored procedure is invoked by the CALL statement, which passes a list of parameters to the procedure. When the CALL statement is executed, the procedure name specified must identify a stored procedure that exists at the application server. If the server is DB2 for MVS/ESA (or an XDB Server), the last or only part of the name must be equal to some value of the NAME column of the SYSIBM.SYSROUTINES catalog table.

DB2 and the XDB Server use the information stored in SYSIBM.SYSROUTINES and SYSIBM.SYSPARMS to automatically activate a stored procedure definition, which includes identification of the parameter list used to implement the stored procedure. The parameters issued in your procedure's CALL statement must correspond to the parameters defined in SYSIBM.SYSPARMS.

procedure-name or host-variable

Identifies the stored procedure to call. The procedure name can be specified as a character string constant or within a host variable.

A procedure name is a qualified or unqualified name. Each part of the name must be composed of SBCS characters:

  • A fully qualified procedure name is a three-part name. The first part is a long identifier that contains the location name that identifies the DBMS at which the procedure is stored. The second part is a short identifier that contains the schema name of the stored procedure. The last part is a long identifier that contains the name of the stored procedure. A period must separate each of the parts. Any or all of the parts can be a delimited identifier.
  • A two-part procedure name has one implicit qualifier. The implicit qualifier is the location name of the current server. The two parts identify the schema name and the name of the stored procedure. A period must separate the two parts.
  • An unqualified procedure name is a one-part name with two implicit qualifiers. The first implicit qualifier is the location name of the current server. The second implicit qualifier depends on the application server. If the server is DB2 for OS/390, the implicit qualifier is the schema name. DB2 uses the SQL path to determine the value of the schema name.
  • If the procedure name is specified as a literal on the CALL statement (CALL procedure-name), the SQL path is the value of the PATH bind option that is associated with the calling package or plan.
  • If a host variable is specified for the procedure name on the CALL statement (CALL host-variable), the SQL path is the value of the CURRENT PATH special register.

DB2 searches the schema names in the SQL path from left to right until a stored procedure with the specified schema name is found in the DB2 catalog. When a matching schema.procedure-name is found, the search stops only if the following conditions are true:

  • The user is authorized to call the stored procedure.
  • The number of parameters in the definition of the stored procedure matches the number of parameters specified on the CALL statement.
  • The create timestamp for the stored procedure must be older than the bind timestamp for the package or plan in which the procedure is invoked.

If the list of schemas in the SQL path is exhausted before the procedure name is resolved, an error is returned.

If a host variable is used:

  • It must be a character string variable with a length attribute that is not greater than 255.
  • It must not be followed by an indicator variable.
  • The value of the host variable is a specification that depends on the application server. Regardless of the application server, the specification must:
    • Be left justified within the host variable
    • Not contain embedded blanks
    • Be padded on the right with blanks if its length is less than that of the host variable

In addition, the specification can:

  • Contain upper and lowercase characters. Lowercase characters are not folded to uppercase.
  • Use a delimited identifier for any part of a the three-part procedure name.

When the CALL statement is executed, the procedure name or specification must identify a stored procedure that exists at the application server.

When the package that contains the CALL statement is bound, the stored procedure that is invoked must be created if VALIDATE(BIND) is Specified. Although the stored procedure does not need to be created at bind time if VALIDATE(RUN) is specified, it must be created when the CALL statement is executed.

Parameters (Expression, Null, Table Transition-Table-Name)

Identifies a list of values to be passed as parameters to the stored procedure. If USING DESCRIPTOR is specified, each host variable described by the identified SQLDA is a parameter of the CALL statement. If host structures are not specified in the CALL statement, the nth parameter of the CALL statement corresponds to the nth parameter in the stored procedure, and the number of parameters in each must be the same. Otherwise, each reference to a host structure is replaced by a reference to each of the variables contained in that host structure, and the resulting number of parameters must be the same as the number of parameters defined for the stored procedure.

Each parameter of a stored procedure is described at the server. In addition to attributes such as data type and length, the description of each parameter indicates how the stored procedure uses it:

  • IN means as an input value
  • OUT means as an output value
  • INOUT means both as an input and an output value

When the CALL statement is executed, the value of each of its parameters is assigned to the corresponding parameter of the stored procedure. In cases where the parameters of the CALL statement are not an exact match to the data types of the parameters of the stored procedure, each parameter specified in the CALL statement is converted to the data type of the corresponding parameter of the stored procedure at execution. The conversion occurs according to the same rules as assignment to columns.

Conversion can occur when precision, scale, length, encoding scheme, or CCSID differ between the parameter specified in the CALL statement and the data type of the corresponding parameter of the stored procedure. Conversion might occur for a character string parameter specified in the CALL statement when the corresponding parameter of the stored procedure has a different encoding scheme or CCSID. For example, an error occurs when the CALL statement passes mixed data that actually contains DBCS characters as input to a parameter of the stored procedure that is declared with an SBCS subtype. Likewise, an error occurs when the stored procedure returns mixed data that actually contains DBCS characters in the parameter of the CALL statement that has an SBCS subtype.

expression

The parameter is the result of the specified expression, which is evaluated before the stored procedure is invoked.

If expression is a single host variable, the corresponding parameter of the procedure can be defined as IN, INOUT, or OUT. Otherwise, the corresponding parameter of the procedure must be defined as IN. In addition, the host variable can identify a structure. Any host variable or structure that is specified must be described in the application program according to the rules for declaring host structures and variables. A reference to a host structure is replaced by a reference to each of the variables contained in the host structure.

If the result of the expression can be the null value, either the description of the procedure must allow for null parameters or the corresponding parameter of the procedure must be defined as OUT.

The following additional rules apply depending on how the corresponding parameter was defined in the CREATE Procedure statement for the procedure:

  • expression can contain references to multiple host variables. expression cannot include a column name or column function or a user-defined function that is sourced on a column function.
  • INOUT or OUT expression can only be a single host variable.

NULL

The parameter is a null value. The corresponding parameter of the procedure must be defined as IN and the description of the procedure must allow for null parameters.

TABLE transition-table-name

The parameter is a transition table and it is passed to the procedure as a table locator. . You can use the CALL statement with the TABLE clause only within the definition of the triggered action of a trigger. The name of a transition table must be specified in the CALL statement if the corresponding parameter of the procedure was defined in the TABLE LIKE clause of the CREATE PROCEDURE statement.

The XDB Server operating environment does not currently provide this functionality.

USING DESCRIPTOR descriptor-name

Identifies an SQLDA that contains a valid description of the host variables that are to be passed as parameters to the stored procedure. If the stored procedure has no parameters, an SQLDA is ignored.

Before the CALL statement is processed, the user must set the following fields in the SQLDA:

  • SQLN to indicate the number of SQLVAR occurrences provided in the SQLDA. This number must not be less than SQLD. This field is not part of the REXX SQLDA and therefore does not need to be set for REXX programs.
  • SQLDABC to indicate the number of bytes of storage allocated for the SQLDA. This number must be not be less than SQLN*44+16. This field is not part of the REXX SQLDA and therefore does not need to be set for REXX programs.
  • SQLD to indicate the number of variables used in the SQLDA when processing the statement. This number must be the same as the number of parameters of the stored procedure.
  • SQLVAR occurrences to indicate the attributes of the variables.

Variable Usage

Each specification of a host-variable, constant or NULL is a parameter of the CALL statement. If USING DESCRIPTOR is specified, each host variable described by the identified SQLDA is a parameter of the CALL statement. The nth parameter of the CALL statement corresponds to the nth parameter of the stored procedure. When the CALL statement is executed, the number of parameters of the stored procedure and each pair of corresponding parameters must be consistent.

A description of each parameter describes how that parameter is used by the stored procedure. In addition to parameter attributes such as data type and length, the following information on each parameter is also stored in SYSIBM.SYSPROCEDURES:

  • IN: used only as an input value
  • OUT: used only as an output value
  • INOUT: used as both input and output value
Note:

When a trigger issues a CALL statement to invoke a stored procedure, the parameters that are specified in the CALL statement cannot be host variables and the USING DESCRIPTOR clause cannot be specified.

A program that is executing as a stored procedure, a user-defined function, or a trigger can issue a CALL statement. When a stored procedure, user-defined function, or trigger calls a stored procedure, user-defined function, or trigger, the call is considered to be nested. Stored procedures, user-defined functions, and triggers can be nested up to 16 levels deep on a single system. Nesting can occur within a single DB2 subsystem or when a stored procedure or user-defined function is invoked at a remote server.

If a stored procedure returns any query result sets, the result sets are returned to the caller of the stored procedure. If the SQL CALL statement is nested, the result sets are visible only to the program that is at the previous nesting level.

Some stored procedures cannot be nested. A stored procedure, user-defined function, or trigger cannot call a stored procedure that is defined with the COMMIT ON RETURN attribute. A stored procedure can call another stored procedure only if they execute in the same type of address space; they must both execute in a DB2-established address space or in a WLM-established address space.

Example:

The following CALL statement activates a stored procedure named alpha:

EXEC SQL CALL alpha (:P1, :A1, :ED1, :type, :code)
Parent topic: SQL Statements


CHECKPOINT

CHECKPOINT is an SQL command which flushes the database and log files.

Invocation

CHECKPOINT is an executable command that can be issued interactively or embedded in a host language.

Authorization

SYSADM or higher authority is required to use the CHECKPOINT command.

Syntax

CHECKPOINT

Description

Under normal operating conditions CHECKPOINT commands are issued automatically by the logging system at regular time intervals (see lCheckpointFreq Parameter below). Some occasions, however, warrant issuing a CHECKPOINT command within SQLWizard as a precautionary measure. If you know (or suspect) that the server must be taken down, and you can still access SQLWizard, then issue a CHECKPOINT. This action minimizes crash recovery time when the server is brought back up.

lCheckpointFreq Parameter

One of the factors affecting the length of time needed to return location data objects to a logically consistent state after a transient system failure (for example, power outage, operating system failure) is the value of the lCheckpointFreq configuration parameter. Changing the value of this parameter (set in the [XDBLogManager] section of thexdbsrvco.ini file) allows the user to increase or decrease the time interval between automatic checkpoints issued by the logging system.

lCheckpointFreq is defaulted to a value of 300 seconds, which means that the logging system automatically performs a checkpoint every five minutes. If this checkpoint interval is adjusted upward, more time could be necessary for log recovery after a transient system failure. Conversely, a shorter checkpoint interval could reduce average recovery time, but increase system overhead. See the Server Administration Guide for more information on the lCheckpointFreq parameter.

Parent topic: SQL Statements


CLOSE

The CLOSE command (embedded SQL only) closes a cursor previously opened by a DECLARE CURSOR command. If a temporary table is created as a result of the cursor, that table is deleted when the cursor is closed.

Invocation

CLOSE is an executable command that can only be embedded in a host language. CLOSE cannot be dynamically prepared.

Authorization

See Authorization under the DECLARE CURSOR command topic for the authorization required to use a cursor.

Syntax

CLOSE cursor-name

Parameters:

cursor-name: Identifies the cursor opened by a DECLARE CURSOR command.

Description

A CLOSE command is checked for all syntactical elements. The cursor must have been previously declared relative to the source program line in which CLOSE is encountered.

Example:

The following example (in the C language) declares a cursor named deptemp using the EMPLOYEE table, and then closes the cursor:

EXEC SQL
    DECLARE CURSOR deptemp FOR
        SELECT * FROM employee
            WHERE dept = :deptno
;....
EXEC SQL
    CLOSE deptemp;
Note: If the WITH HOLD option is not specified in the declaration of a cursor, then that cursor (when opened) is implicitly closed when a unit of work is terminated. Performance can be improved, however, by explicitly closing cursors as soon as possible. A CLOSE command does not necessarily commit or rollback system changes or updates (unless AUTOCOMMIT is on).
Parent topic: SQL Statements


COMMENT ON

The COMMENT ON statement adds or replaces descriptive text comments for aliases, columns, distinct types (currently not supported), stored procedures, tables, triggers, user-defined functions, and views located within the current XDB Server location. All comments are stored in the catalog tables belonging to that location.

Invocation

COMMENT ON is an executable command that can be issued interactively or embedded in a host language. COMMENT ON can be dynamically prepared.

Authorization

For a comment on a table, view, alias, index, or column, the privilege set that is defined below must include at least one of the following:

  • Ownership of the table, view, alias, or index
  • DBADM authority for its database (tables and indexes only)
  • SYSADM or SYSCTRL authority

For a comment on a distinct type, stored procedure, trigger, or user-defined function, the privilege set that is defined below must include at least one of the following:

  • Ownership of the distinct type, stored procedure, trigger, or user-defined function
  • The ALTERIN privilege on the schema (for the addition of comments)
  • SYSADM or SYSCTRL authority

For a comment on a plan or package, the privilege set that is defined below must include at least one of the following:

  • Ownership of the plan or package
  • SYSADM or SYSCTRL authority

For a comment on a sequence, the privilege set that is defined below must include at least one of the following:

  • Ownership of the sequence
  • The ALTER privilege for the sequence
  • The ALTERIN privilege on the schema
  • SYSADM or SYSCTRL authority

Syntax

COMMENT ON
{
TABLE {table-name | view-name}
    | COLUMN {table-name | view-name}.column-name
    | ALIAS alias-name
    | DISTINCT TYPE distinct-type-name
    | FUNCTION function-name [(parameter-type[,...])]
    | PROCEDURE procedure-name
    | SPECIFIC FUNCTION specific-name
    | TRIGGER trigger-name
    | PACKAGE collection-id.package-name [VERSION | version-id]
    | PLAN plan-name
    | PROCEDURE procedure-name
    | SEQUENCE sequence-name
}
IS string-constant

or:

COMMENT ON {table-name | view-name}
(column-name IS string-constant [,...])

Parameters:

table-name or view-name or alias-name | Identifies the table, view or alias affected.
column-name | Identifies the name of the column affected. When the COLUMN keyword is used, column names must be qualified with the name of the table or view that contains them.
string-constant | Specifies the comment you want to place in the system table. The string may be up to 254 characters in length, enclosed in double or single quotation marks.

Description

The COMMENT ON statement is used for adding a comment to, or replacing an existing comment in the REMARKS column of the SYSIBM.SYSCOLUMNS or SYSIBM.SYSTABLES table. These comments prove very useful in documenting the purpose of tables, views, columns and aliases, and may be selected using a SELECT command, and incorporated into application documentation. Remarks columns are defined as character fields, with a maximum length of 254 characters.

ALIAS alias-name

The ALIAS clause is used to comment on an alias. If you use the COMMENT ON ALIAS format, the comment is placed in the REMARKS column of the SYSIBM.SYSTABLES table, in the row describing the specified table or view.

COLUMN table-name.column-name or view-name.column-name

Identifies the column to which the comment applies. The name must identify a column of a table or view that exists at the current server. The name must not identify a column of a declared temporary table. The comment is placed into the REMARKS column of the SYSIBM.SYSCOLUMNS catalog table, for the row that describes the column.

Do not use TABLE or COLUMN to comment on more than one column in a table or view. Give the table or view name and then, in parentheses, a list in the form:

  • column-name IS string-constant,
  • column-name IS string-constant,...

The column names must not be qualified, each name must identify a column of the specified table or view, and that table or view must exist at the current server.

DISTINCT TYPE distinct-type-name

Identifies the distinct type to which the comment applies. distinct-type-name must identify a distinct type that exists at the current server.

The comment is placed in the REMARKS column of the SYSIBM.SYSDATATYPES catalog table for the row that describes the distinct type.

FUNCTION

Identifies the function to which the comment applies. The function must exist at the current server, and it must be a function that was defined with the CREATE FUNCTION statement or a cast function that was generated by a CREATE DISTINCT TYPE statement. The comment is placed in the REMARKS column of the SYSIBM.SYSROUTINES catalog table for the row that describes the function.

If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name

Identifies the particular function, and is valid only if there is exactly one function with function-name.

FUNCTION function-name (parameter-type,...)

Provides the function signature, which uniquely identifies the function.

function-name | Identifies the name of the function.
(parameter-type,...) | Identifies the parameters of the function.

The data types of the parameters must match the data types that were specified on the CREATE FUNCTION statement in the

corresponding position. The number of data types and the logical concatenation of the data types are used to identify the specific function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that DB2 ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

    CHAR CHAR(1)

    GRAPHIC GRAPHIC(1)

    DECIMAL DECIMAL(5,0)

    FLOAT DOUBLE (length of 8)

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that DB2 ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name

Identifies the particular function using the specific name either specified or defaulted to when the function was created.

PROCEDURE procedure-name

Identifies the stored procedure to which the comment applies. procedure-name must identify a stored procedure that has been defined with the CREATE PROCEDURE statement at the current server. The comment is placed in the REMARKS column of the SYSIBM.SYSROUTINES catalog table for the row that describes the stored procedure.

TABLE table-name or view-name

Identifies the table or view to which the comment applies. table-name or view-name must identify a table, auxiliary table, or view that exists at the current server. table-name must not identify a declared temporary table. The comment is placed in the REMARKS column of the SYSIBM.SYSTABLES catalog table for the row that describes the table or view.

TRIGGER trigger-name

Identifies the trigger to which the comment applies. trigger-name must identify a trigger that exists at the current server. The comment is placed in the REMARKS column of the SYSIBM.SYSTRIGGERS catalog table for the row that describes the trigger.

PACKAGE collection-id.package-name

Identifies the package to which the comment applies. You must qualify the package name with a collection ID. collection-id.package-name must identify a package that exists at the current server. The name plus the implicitly or explicitly specified version-id must identify a package that exists at the current server. Omitting version-id is an implicit specification of the null version.

PLAN plan-name

Identifies the plan to which the comment applies. plan-name must identify a plan that exists at the current server.

PROCEDURE procedure-name

Identifies the stored procedure to which the comment applies. procedure-name must identify a stored procedure that has been defined with the CREATE PROCEDURE statement at the current server. The comment is placed in the REMARKS column of the SYSIBM.SYSROUTINES catalog table for the row that describes the stored procedure.

SEQUENCE sequence-name

Identifies the sequence to which the comment applies. The combination of name and implicit or explicit schema name must identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs. sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column. The comment is placed in the REMARKS column of the SYSIBM.SYSSEQUENCES catalog table for the row that describes the sequence.

IS string-constant

Introduces the comment that you want to make. string-constant can be any SQL character string constant of up to 254 characters.

Examples:

To place a comment on the PART table, use a command like:

COMMENT ON TABLE part
    IS "Information on all parts in use."

To place a comment on a view named redparts use a command like:

COMMENT ON TABLE redparts
    IS "View of parts table containing info on all red parts in use."

To place a comment on the CITY column of the SUPPLIER table, use a command like:

COMMENT ON COLUMN supplier.city
    IS "City where supplier is headquartered."

To place a comment on both the COMPANY and BALANCE columns of the CUSTOMER table, use the command below:

COMMENT ON customer
    (company IS "Corporate name of the client",
     balance IS "Outstanding as of last billing")
Parent topic: SQL Statements


COMMIT

The COMMIT statement is used to mark the end of a transaction (unit of work) and preserve all of the database changes made by the transaction.

Invocation

COMMIT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared. COMMIT cannot be used in CICS or IMS environments.

Authorization

No special authorization is required.

Syntax

COMMIT [WORK]

Description

A transaction begins when a previous transaction ends or when logging begins (see the SET LOG command). A transaction is terminated by a COMMIT or ROLLBACK command.

Only the results of SQL commands executed within a single, uncommitted transaction are affected by the COMMIT command. When the COMMIT command is issued, all table changes caused by EXPLAIN, GRANT, REVOKE, COMMENT ON, LABEL ON, INSERT, UPDATE, and DELETE commands in the transaction are made permanent, and can no longer be rolled back (the CREATE, DROP and ALTER commands can never be rolled back).All savepoints that were set within the transaction are released

In DB2 mode, open cursors declared without the WITH HOLD option are closed and any statements prepared for those cursors are destroyed. All open cursors declared with the WITH HOLD option are preserved, along with any statements that were prepared for these cursors. In XDB mode, all cursors remain open at commit time.

For existing connections, all LOB locators are disassociated, except for those locators for which a HOLD LOCATOR statement has been issued without a corresponding FREE LOCATOR statement.

All implicitly acquired locks are released, except:

  • Locks that are required for the cursors that were not closed
  • Table and table space locks when the RELEASE parameter on the bind command was not RELEASE(COMMIT)
  • LOB locks and LOB table space locks that are required for held LOB locators

An implicit COMMIT is always performed when exiting from the current session. All locks acquired during a transaction are released by the COMMIT command.

All rows of every declared temporary table of the application process are deleted with these exceptions:

  • The rows of a declared temporary table that is defined with the ON COMMIT PRESERVE ROWS atttribute are not deleted.
  • The rows of a declared temporary table that is defined with the ON COMMIT DELETE ROWS attribute are not deleted if any program in the application process has an open WITH HOLD cursor that is dependent on that table.

The optional keyword WORK is provided for compatibility with the SAA definition of SQL, and is available in DB2. COMMIT and COMMIT WORK perform identically.

Parent topic: SQL Statements


COMPACT

Use the COMPACT command to pack table, index and dictionary files in order to reuse disk storage space.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

No special authorization is required.

Syntax

COMPACT
{
    LOCATION [AND INDEX] [NO CLUSTER] [NOSTOP] [RULES DB2]|
    DIRECTORIES |
    TABLE table-name [AND INDEXES] [NO CLUSTER] [RULES DB2]|
    TABLES [LIKE pattern] [IN DATABASE db-name] [NOSTOP] [CLUSTER BY INDEX index-name] [RULES DB2]|
    INDEXES [LIKE pattern] [IN DATABASE db-name] [NOSTOP]
}
Note:

Keyword order is significant. When used, keywords must appear in the order specified below.

Parameters:

table-name | Identifies the name of the table that you want to compact.
index-name | Identifies the name of a table index that determines the physical order of records in the table.
db-name | Identifies the name of the database that you want to compact.
pattern | Defines pattern-matching criteria for a 2-part table name (use same pattern-matching syntax as for the LIKE Operator). For example, SYS%.SYSC% and SALES%.%.

Description

XDB Server locations consist of table, index and dictionary files. When these object are altered or deleted, the files may become disorganized, increasing the amount of space occupied and the amount of time required to perform searches. To optimize table and dictionary file structures, you can pack specific location objects using the COMPACT command.

During processing, the COMPACT command must create a temporary copy of the specified file(s).. If the size of the largest file exceeds the free space on the storage device you are using, an error results, and the object being packed is restored to its original condition.

LOCATION

If the keyword LOCATION appears in the command syntax, the entire location is packed (including all tables and dictionary files), and all location indexes rebuilt. If a clustered index exists on a table, then the records in that table are also reclustered (swapped so they are arranged in the same physical order as the clustering index), unless the NO CLUSTER option is specified.

Use the RULES DB2 clause to pad char fields (non-FOR BIT DATA only) with blank characters during the compacting process. This option is useful for converting tables initially populated in XDB mode to standard DB2 format for character data.

Use the NOSTOP clause to enable the XDB Server to continue processing after an error. Without the NOSTOP clause, the server stops executing the COMPACT command as soon as it encounters the first error. With the NOSTOP clause, if the server encounters an error as it processes a table, it writes the error to a trace file then continues packing the next table. This option is useful for performing a COMPACT in unattended mode.

Note: We strongly recommend that you make a backup copy of the location to be compacted before executing the COMPACT LOCATION command.

DIRECTORIES

The keyword DIRECTORIES packs only location dictionary files to remove information about deleted data objects. Table and index files are not affected.

TABLE

The TABLE keyword is used to compact a single table. The optional AND INDEXES and NO CLUSTER clauses function the same on a single table as with multiple tables (when using the TABLES keyword).

The optional CLUSTER BY INDEX clause is used to physically reorder the table records according to the index-name specified. The CLUSTER BY INDEX and NO CLUSTER clauses are mutually exclusive. If you use both CLUSTER BY INDEX and NO CLUSTER, the NO CLUSTER clause is ignored.

Use the RULES DB2 clause to pad char fields (non-FOR BIT DATA only) with blank characters during the compacting process. This option is useful for converting tables initially populated in XDB mode to standard DB2 format for character data.

TABLES

If the keyword TABLES appears without the AND INDEXES clause, only the table files within the current location are compacted. Indexes are rebuilt only if a table contains deleted records. If a table contains deleted records and a clustered index, then the clustered index is rebuilt and the table records reordered (unless the NO CLUSTER clause is added).

Including the optional AND INDEXES clause forces all table indexes in the location (including all primary, unique and foreign keys) to be dropped and rebuilt. All tables with clustered indexes are therefore reclustered, unless the NO CLUSTER clause is specified.

Use the NOSTOP clause to enable the XDB Server to continue processing after an error. Without the NOSTOP clause, the server stops executing the COMPACT command as soon as it encounters the first error. With the NOSTOP clause, if the server encounters an error as it processes a table, it writes the error to a trace file then continues packing the next table. This option is useful for performing a COMPACT in unattended mode.

Use the RULES DB2 clause to pad char fields (non-FOR BIT DATA only) with blank characters during the compacting process. This option is useful for converting tables initially populated in XDB mode to standard DB2 format for character data.

INDEXES

The INDEXES keyword rebuilds location indexes only and leaves the tables alone. If clustered indexes exist on any tables, those tables are reclustered unless NO CLUSTER is specified.

Use the NOSTOP clause to tell the XDB Server to automatically continue to with the next index when an error occurs in the one it is processing. (If this option is not used, the entire process terminates immediately on error.) COMPACT writes the error to a trace file (XDBTRACE.OUT) before continuing to the next index. This option is useful for performing a COMPACT in unattended mode.

Example:

To compact the CUSTOMER table use the command:

COMPACT TABLE customer

To compact only the dictionary files of the current location, use the command:

COMPACT DIRECTORIES

To compact the entire current location, including the dictionary files and all tables, use the command:

COMPACT LOCATION

To compact the EMPLOYEE table, and physically reorder the records by PAYRATE column values (assuming the index payidx has already been built on the PAYRATE column of the EMPLOYEE table) use the following command:

COMPACT TABLE employee CLUSTER BY INDEX payidx

If the payidx index was built as a clustered index the command:

COMPACT TABLE employee

could be used without the explicit CLUSTER BY INDEX clause.

To rebuild all indexes that exist on the EMPLOYEE table, issue the command:

COMPACT TABLE employee AND INDEX

To compact all tables in the current location, issue the command:

COMPACT TABLES

To compact all indexes in the current log, issue the command:

COMPACT INDEXES

To compact all XDB Server system tables, issue the command:

COMPACT TABLES LIKE SYSXDB%.%
Parent topic: SQL Statements


CONNECT

The CONNECT statement (embedded SQL only) connects the application process to the specified XDB Server or DB2 (through XDB Link) location. This location becomes the current location for the application process.

Invocation

CONNECT is an executable statement that can only be embedded in an application program. It cannot be dynamically prepared.

Authorization

The primary AuthID for the application process must be authorized to connect to the specified location. The specific AuthID required is determined by that location, with the authorization check also performed by that location.

Syntax

CONNECT
    [TO {location-name | host-variable}]
    [RESET]

Parameters:

location-name | Identifies a specific XDB Server system location.
host-variable | Names a host variable name containing a location name.

Description

The CONNECT statement is the embedded SQL equivalent of the interactive SET LOCATION TO command. The CONNECT statement connects an application process to a designated location or a host-variable containing a location name. When the CONNECT statement is executed, the location name must be known to the local XDB Server running the application, or the location name must appear in the LOCATION column of the SYSIBM.SYSLOCATIONS catalog within the SYSTEM location.

Host variables must conform to the following requirements:

  • Must be a character string variable with a length attribute of at least 16 characters.
  • Must be preceded by a colon and not be followed by an indicator variable.
  • Within the host variable, the location name must be left-justified and conform to the rules for forming an ordinary location identifier.
  • If the location name length is less than the length of the host variable, the remainder of the host variable must be padded on the right with blanks.

If the CONNECT statement execution is successful:

  • The application process is connected to the identified location.
  • The CURRENT SERVER special register is updated to contain the specified location name.
  • The SQLERRP field of the SQLCA is set to contain information about the location. This information has the format pppvvrrN, where:
    ppp | identifies the product (for example, XDB or DB2)
    vv | contains a two-digit version identifier (for example, '04')
    rr | contains a two-digit release identifier (for example, '00')
    N | indicates the Windows operating system

Examples:

The following code excerpt connects the application process to the system location:

EXEC SQL
    CONNECT TO system;

To connect the application to a location named in the host variable nameloc, execute the following command:

EXEC SQL
    CONNECT TO :nameloc;

The XDB Server implements the CONNECT command identically to DB2, except that the XDB Server improves performance by leaving the old location open after connecting with the new location.

CONNECT RESET

The CONNECT RESET statement is equivalent to a CONNECT TO specifying the local XDB Server location.

Note: Issuing this command is the only way to get back to an XDB Server location after connecting to a DB2 subsystem through the XDB Link.

CONNECT

The keyword CONNECT by itself returns information about the currently set XDB Server location. This information is placed in the SQLERRP field of the application SQLCA.

Note: The initial server of an application process is the currently set XDB Server location. An explicit or implicit execution of a CONNECT [TO] statement can establish a different location. A CONNECT [TO] statement directed to the currently set location is treated like any other CONNECT [TO]. The CURRENT SQLID special register is not reinitialized when CONNECT [TO] is used to connect back to the currently set location.
Parent topic: SQL Statements


CREATE ALIAS

The CREATE ALIAS command defines an alternate name for an existing table or view, and records the alias definition in the XDB Server system catalog at the currently set location. It is not required that the table or view be in the current location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE ALIAS command, you must possess either the CREATEALIAS privilege, or overall SYSADM or SYSCTRL authority for the location. If the alias-name specified includes an authorization name qualifier that does not match the AuthID, the privilege set must include SYSADM or SYSCTRL authority for the location. When the specified alias-name includes an authorization name qualifier that does not match the process AuthID, any authorization name qualifier is valid, if the application process privilege set includes SYSADM or SYSCTRL authority.

Syntax

CREATE ALIAS alias-name
    FOR {table-name | view-name}

Parameters:

alias-name | Names the alias, and must not match the name of any table, view, alias, or synonym that already exists at the currently set location.
table-name or view-name | Identifies the table or view for which the alias is defined. If a table is identified, it must not be an auxiliary table or a declared temporary table. The table or view need not exist at the time the alias is defined. If it does exist, it can be at the current server or at another server. The name must not be the same as the alias name and must not identify an alias that exists at the current server.

Description

The alias name can be either a one-part, two-part or three-part qualified name (location-name.AuthID.alias-name). The AuthID qualifier within alias-name identifies the alias owner. If the CREATE ALIAS statement is dynamically prepared and the alias name is unqualified, the application process AuthID becomes the alias owner.

The table or view need not exist when the CREATE ALIAS statement is executed. Already defined tables or views can exist at either the currently set location or a different location. The table or view name must not match the alias name, and must not match any other alias names described in the catalog at the current XDB Server location.

An alias can be defined for a table, view or other alias whose name does not exist under the current XDB Server location. In this case, the existence of the referenced object is not verified by the XDB Server when the alias is created. The XDB Server can detect an alias specified for a location other than the current location. In these cases, the full three-part name that the alias references is substituted in the query for the alias name. The new query is then sent to the location specified in the three-part name.

Example:

The following example creates an alias called bob, and then uses that alias in a query:

CREATE ALIAS bob FOR tutorial.tutorial.customer

When the query shown below references bob, the three-part name value defined above is substituted, and the query sent to the TUTORIAL location.

SELECT * FROM bob
Parent topic: SQL Statements


CREATE AUXILIARY TABLE

The CREATE AUXILIARY TABLE statement creates an auxiliary table at the current server for storing LOB data.

Invocation

Do not use this statement if the value of special register CURRENT RULES is 'STD' when the statement is executed. When the register's value is 'STD' and a base table is created with LOB columns or altered such that LOB columns are added, DB2 automatically creates the LOB table space, auxiliary table, and index on the auxiliary table for each LOB column. DB2 chooses the names and characteristics of these objects.

This statement can be embedded in an application program or issued interactively if the value of special register CURRENT RULES is 'DB2' when the statement is executed.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATETAB privilege for the database implicitly or explicitly specified by the IN clause
  • DBADM, DBCTRL, or DBMAINT authority for the database
  • SYSADM or SYSCTRL authority

Privilege set

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the specified table name includes a qualifier that is not the same as this authorization ID, the privilege set must include SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process. However, if the specified table name includes a qualifier that is not the same as this authorization ID, the following rules apply:

  1. If the privilege set includes SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, any qualifier is valid.
  2. If the privilege set does not include any of the authorities listed in item 1 above, the qualifier is valid only if it is the same as one of the authorization IDs of the process and the privilege set that are held by that authorization ID includes all privileges needed to create the table.

Syntax

CREATE {AUXILIARY | AUX} TABLE aux-table-name
    IN [database-name] table-space-name STORES table-name
    COLUMN column-name [PART integer]

Parameters:

aux-table-name Names the auxiliary table. The name must not identify a table, view, alias, or synonym that exists at the current server.

If qualified, the name can be a two-part or three-part name. If a three-part name is used, the first part must match the value of field DB2 LOCATION NAME on installation panel DSNTIPR at the current server. (If the current server is not the local DB2, this name is not necessarily the name in the CURRENT SERVER special register.) Whether the name is two-part or three-part, the authorization ID that qualifies the name is the table's owner.

If the table name is unqualified and the statement is embedded in a program, the owner of the table is the authorization ID that serves as the implicit qualifier for unqualified object names. This is the authorization ID in the QUALIFIER operand when the plan or package was created or last rebound. If QUALIFIER was not used, the owner of the table is the owner of the package or plan.

If the table name is unqualified and the statement is dynamically prepared, the SQL authorization ID is the owner of the table.

IN database-name.table-space-name or IN table-space-name Identifies the table space in which the auxiliary table is created. The name must identify an empty LOB table space that currently exists at the current server.

If you specify a database and a table space, the table space must belong to the specified database. If you specify only a table space, it must belong to database DSNDB04.

Description

AUXILIARY or AUX

Specifies a table that is used to store the LOB data for a LOB column (or a column with a distinct type that is based on a LOB data type).

STORES table-name COLUMN column-name

Identifies the base table and the column of that table that is to be stored in the auxiliary table. If the base table is nonpartitioned, an auxiliary table must not already exist for the specified column. If the base table is partitioned, an auxiliary table must not already exist for the specified column and specified partition.

The encoding scheme for the LOB data stored in the auxiliary table is the same as the encoding scheme for the base table. It is either ASCII or EBCDIC depending on the value of the CCSID clause when the base table was created.

The auxiliary table can store a BLOB, CLOB, or DBCLOB value that is greater than 1 gigabyte in length only if the LOB table space for the auxiliary table was defined with LOG NO.

PART integer

Specifies the partition of the base table for which the auxiliary table is to store the specified column. You can specify PART only if the base table is defined in a partitioned table space, and no other auxiliary table exists for the same LOB column of the base table.

Note:

The number of auxiliary tables to create depends on the number of LOB columns in the base table and whether the base table is partitioned. If the base table is nonpartitioned, you need one LOB table space and one auxiliary table for each LOB column in the base table. If the base table is partitioned, you need one LOB table space and one auxiliary table for each partition for each LOB column. For example if the base table has four partitions and two LOB columns, you need to create a total of eight auxiliary tables in eight different LOB table spaces.

Example:

Assume that a column named EMP_PHOTO with a data type of BLOB(110K) has been added to sample employee table DSN8610.EMP for each employee's photo. Create auxiliary table EMP_PHOTO_ATAB to store the BLOB data for the BLOB column in LOB table space DSN8D61A.PHOTOLTS.

CREATE AUX TABLE EMP_PHOTO_ATAB
    IN DSN8D61A.PHOTOLTS
    STORES DSN8610.EMP
    COLUMN EMP_PHOTO;
Parent topic: SQL Statements


CREATE DATABASE

The CREATE DATABASE command creates a logical database structure at the currently set XDB Server location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE DATABASE command, you must possess either CREATEDBA or CREATEDBC privileges, or overall SYSADM or SYSCTRL authority for the location.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE DATABASE database-name
    [BUFFERPOOL bpname]
    [INDEXBP bpname]
    [ROSHARE {OWNER | READ}]
    [AS {WORKFILE | TEMP} [FOR member-name]]
    [STOGROUP stogroup-name]
    [CCSID {ASCII | EBCDIC | UNICODE}]

Parameters:

database-name | Names the new database, which must not already exist at the current location.
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.
member-name | The name of the DB2 subsystem that the database will become part of.
stogroup-name | Identifies a user-defined XDB Server stogroup (drive and path) where database files can be stored.

Description

The CREATE DATABASE command creates a logical database the current XDB Server location. If a subdirectory for the database does not exist and a stogroup is not specified, a new subdirectory is created under the current location path (with the subdirectory taking on the name of the newly created database). The creator of a database is given DBADM authority for the database.

The CREATE DATABASE command has been enhanced to reflect the new XDB Server system architecture. The BUFFERPOOL clause (DB2-mainframe only) along with the ROSHARE and STOGROUP clauses have been added. The ROSHARE clause is used to create XDB Server read-only shared (ROSHARE) databases, while the STOGROUP clause allows you to store database objects within a user defined XDB Server stogroup (or directory path).

With DB2 V7, XDB locations (either EBCDIC or ASCII) can now contain Unicode data. If you create a database with CCSID UNICODE, all character data in corresponding tables is stored in UTF-8 format and all graphic data is stored in UTF-16 format.

BUFFERPOOL bpname

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, The XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for tables with 4K page sizes, while the last ten are for tables with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server system catalog tables.

Specifies the default buffer pool name to be used for table spaces created within the database. If the database is a work file database, 8KB and 16KB buffer pools cannot be specified.

If you omit the BUFFERPOOL clause, the buffer pool specified for user data on installation panel DSNTIP1 is used. The default value for the user data field on that panel is BP0.

INDEXBP bpname

Specifies the default buffer pool name to be used for the indexes created within the database. The name must identify a 4KB buffer pool.If the database is a work file database, INDEXBP cannot be specified.

If you omit the INDEXBP clause, the buffer pool specified for user indexes on installation panel DSNTIP1 is used. The default value for the user indexes field on that panel is BP0.

AS WORKFILE or AS TEMP

Indicates that this is a work file database or a database for declared temporary tables (a TEMP database).

AS WORKFILE | Specifies the database is a work file database. AS WORKFILE can be specified only in a data sharing environment. Only one work file database can be created for each DB2 member.
AS TEMP | Specifies the database is for declared temporary tables only. AS TEMP must be specified to create a database that will be used for declared temporary tables; otherwise, the database will not be used for declared temporary tables. Only one TEMP database can be created for each DB2 subsystem or data sharing member. A TEMP database cannot be shared between DB2 subsystems or data sharing members. PUBLIC implicitly receives the CREATETAB privilege (without GRANT authority) to define a declared temporary table in the TEMP database. This implicit privilege is not recorded in the DB2 catalog and cannot be revoked.

FOR member-name

Specifies the member for which this database is to be created. Specify FOR member-name only in a data sharing environment.

If FOR member-name is not specified, the member is the DB2 subsystem on which the CREATE DATABASE statement is executed.

ROSHARE

This optional clause is used for the creation of read-only shared (or ROSHARE) databases. The OWNER keyword identifies the database as the owner created and controlled database, while the READ keyword identifies a reading (or dummy) database that can only read (or SELECT) data from the owner database.

STOGROUP

Identifies an optional XDB Server-created stogroup where database objects (tables, indexes, views, etc.) can be stored (stogroups allow you to define a path for storing data). To use the defined stogroup, first modify the special XDBPRIMEVOLPATH and XDBVOLPATH column values in the SYSIBM.SYSVOLUMES table to associate the stogroup's VOLID column value with the stogroup path (see CREATE STOGROUP command summary). If a stogroup is specified when creating the database, the XDB Server does not create a database subdirectory under the current location path, but uses the stogroup path instead.

If the optional STOGROUP clause is omitted, the stogroup associated with the new database defaults to SYSDEFLT -- a system default, not representing any physical storage entity on the XDB Server. This omission of a stogroup name causes the XDB Server to create a new database subdirectory under the currently set location directory path, with this information being recorded within the current location system tables.

CCSID

The CCSID clause is only syntactically supported for EBCDIC and ASCII. This is because the definition of the XDB location itself defines how character data is stored.

If you specify UNICODE, your character and graphic data is stored as UNICODE within the database.

Examples:

Create database DSN8D61P. Specify DSN8G610 as the default storage group to be used for the table spaces and indexes in the database. Specify 8KB buffer pool BP8K1 as the default buffer pool to be used for table spaces in the database, and BP2 as the default buffer pool to be used for indexes in the database.

CREATE DATABASE DSN8D61P
    STOGROUP DSN8G610
    BUFFERPOOL BP8K1
    INDEXBP BP2;

Create database DSN8TEMP. Use the defaults for the default storage group and default buffer pool names. Specify ASCII as the default encoding scheme for data stored in the database.

CREATE DATABASE DSN8TEMP
    CCSID ASCII;
Parent topic: SQL Statements


CREATE DISTINCT TYPE

The CREATE DISTINCT TYPE statement defines a distinct type, which is a data type that a user defines. A distinct type must be sourced on one of the built-in data types. Successful execution of the statement also generates:
  • A function to cast between the distinct type and its source type
  • A function to cast between the source type and its distinct type
  • As appropriate, support for the use of comparison operators with the distinct type

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Privilege set

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID

of the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process. The specified distinct type name can include a schema name (a qualifier). However, if the schema name is not the same as the SQL authorization ID, one of the following conditions must be met:

  • The privilege set includes SYSADM or SYSCTRL authority.
  • The SQL authorization ID of the process has the CREATEIN privilege on the schema.

Syntax

CREATE DISTINCT TYPE distinct-type-name AS source-data-type
    [WITH COMPARISONS]

source-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] |
  {CHARACTER | CHAR} VARYING (integer) |
  VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}]|
{DATE | TIME | TIMESTAMP} |
ROWID

Description

distinct-type-name

Names the distinct type. The name is implicitly or explicitly qualified by a schema name. The name, together with the implicit or explicit schema name, must not identify a distinct type that exists at the current server.

The unqualified form of distinct-type-name is a long SQL identifier.

distinct-type-name must not be the name of a built-in data type, BOOLEAN, or any of following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |

The unqualified name is implicitly qualified with a schema name according to the following rules:

  • If the CREATE DISTINCT TYPE statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the CREATE DISTINCT TYPE statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of distinct-type-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name can be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the distinct type is determined by how the CREATE DISTINCT TYPE statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

Although the information is not recorded in the catalog, the owner is given the USAGE privilege on the distinct type. The owner is also given the EXECUTE privilege with the GRANT option on each of the generated cast functions.

source-data-type

Specifies the data type that is used as the basis for the internal representation of the distinct type. The data type must be a built-in data type. You can use any of the built-in data types that are allowed for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead.

If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:

CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)

If the distinct type is sourced on a character string data type, the FOR clause indicates the subtype. If you do not specify the FOR clause, the distinct type is defined with the default subtype. The default is SBCS when the value of field MIXED DATA on installation panel DSNTIPF is NO. The default is MIXED when the value is YES.

If the distinct type is sourced on a string data type, the CCSID clause indicates whether the encoding scheme of the data is ASCII or EBCDIC. If you do not specify CCSID ASCII or CCSID EBCDIC, the encoding scheme is the value of field DEF ENCODING SCHEME on installation panel DSNTIPF.

WITH COMPARISONS

Specifies that system-generated comparison operators are to be created for comparing two instances of the distinct type. Do not specify WITH COMPARISONS if the source data type is BLOB, CLOB, or DBCLOB; otherwise, a warning occurs and the comparison operators are not generated. You must specify WITH COMPARISONS for all other source data types.

DB2 implicitly creates comparison functions for the following comparison operators for use with the distinct type:

BETWEEN | IS NULL | < | ¬<
NOT BETWEEN | IS NOT NULL | > | ¬>
IN | = | <= | >=
NOT IN | ¬= | <>

The name of the function is the same as the comparison operator. You cannot invoke the comparison functions using function notation syntax, for example, '<'(C1,C2). Instead, use the syntax C1 < C2.

You must not specify the comparison operations for distinct types that are sourced on a CLOB, BLOB, or DBCLOB, or that have a length greater than 255 bytes. (Distinct types that are sourced on a VARCHAR or VARGRAPHIC can have a length greater than 255 bytes).

Source data types with DBCS or mixed data

If you specify a GRAPHIC source type and the ASCII encoding scheme, or a string source type with a mixed data subtype (FOR MIXED DATA), the value of field FOR MIXED DATA on installation panel DSNTIPF must be YES; otherwise, an error occurs. In addition, to create a distinct type on a GRAPHIC data type, the corresponding CCSID must be defined for the implicitly or explicitly specified encoding scheme.

Generated cast functions

The successful execution of the CREATE DISTINCT TYPE statement causes DB2 to generate the following cast functions:

  • A function to convert from the distinct type to its source data type
  • A function to convert from the source data type to the distinct type
  • A function to cast from a data type A to distinct type DT, where A is promotable to the source data type S of distinct type DT

For some source data types, DB2 supports an additional function to convert from:

  • INTEGER to the distinct type if the source type is SMALLINT
  • VARCHAR to the distinct type if the source type is CHAR
  • VARGRAPHIC to the distinct type if the source type is GRAPHIC
  • DOUBLE to the distinct type if the source type is REAL

The cast functions are created as if the following statements were executed:

CREATE FUNCTION source-type-name (distinct-type-name)
    RETURNS source-type-name ...
CREATE FUNCTION distinct-type-name (source-type-name)
    RETURNS distinct-type-name ...

Even if you specified a length, precision, or scale for the source data type in the CREATE DISTINCT TYPE statement, the name of the cast function that converts from the distinct type to the source type is simply the name of the source data type. The data type of the value that the cast function returns includes any length, precision, or scale values that you specified for the source data type.

The name of the cast function that converts from the source type to the distinct type is the name of the distinct type. The input parameter of the cast function has the same data type as the source data type, including the length, precision, and scale.

For example, assume that a distinct type named T_SHOESIZE is created with the following statement:

CREATE DISTINCT TYPE CLAIRE.T_SHOESIZE AS VARCHAR(2) WITH COMPARISONS

When the statement is executed, DB2 also generates the following cast functions. VARCHAR converts from the distinct type to the source type, and T_SHOESIZE converts from the source type to the distinct type.

FUNCTION CLAIRE.VARCHAR (CLAIRE.T_SHOESIZE) RETURNS SYSIBM.VARCHAR (2)
FUNCTION CLAIRE.T_SHOESIZE (SYSIBM.VARCHAR (2)) RETURNS CLAIRE.T_SHOESIZE

Notice that function VARCHAR returns a value with a data type of VARCHAR(2) and that function T_SHOESIZE has an input parameter with a data type of VARCHAR(2).

The schema of the generated cast functions is the same as the schema of the distinct type. No other function with the same name and function signature must already exist in the database.

In the preceding example, if T_SHOESIZE had been sourced on a SMALLINT, CHAR, or GRAPHIC data type instead of a VARCHAR data type, another cast function would have been generated in addition to the two functions to cast between the distinct type and the source data type. For example, assume that T_SHOESIZE is created with this statement:

CREATE DISTINCT TYPE CLAIRE.T_SHOESIZE AS CHAR(2) WITH COMPARISONS

When the statement is executed, DB2 generates these cast functions:

FUNCTION CLAIRE.CHAR (CLAIRE.T_SHOESIZE) RETURNS SYSIBM.CHAR (2)
FUNCTION CLAIRE.T_SHOESIZE (SYSIBM.CHAR (2)) RETURNS CLAIRE.T_SHOESIZE
FUNCTION CLAIRE.T_SHOESIZE (SYSIBM.VARCHAR (2)) RETURNS CLAIRE.T_SHOESIZE

Notice that the third function enables the casting of a VARCHAR(2) to T_SHOESIZE. This additional function is created to enable casting a constant, such as 'AB', directly to the distinct type. Without the additional function, you would have to first cast 'AB', which has a data type of VARCHAR, to a data type of CHAR and then cast it to the distinct type.

You cannot explicitly drop a generated cast function. The cast functions that are generated for a distinct type are implicitly dropped when the distinct type is dropped with the DROP statement.

Built-in functions

When a distinct type is defined, the built-in functions (such as AVG, MAX, and LENGTH) are not automatically supported for the distinct type. You can use a built-in function on a distinct type only after a sourced user-defined function, which is based on the built-in function, has been created for the distinct type.

Example:

Create a distinct type named SHOESIZE that is sourced on an INTEGER data type.

CREATE DISTINCT TYPE SHOESIZE AS INTEGER WITH COMPARISONS;

The successful execution of this statement also generates two cast functions. Function INTEGER(SHOESIZE) returns a value with data type INTEGER, and function SHOESIZE(INTEGER) returns a value with distinct type SHOESIZE.

Create a distinct type named MILES that is sourced on a DOUBLE data type.

CREATE DISTINCT TYPE MILES AS DOUBLE WITH COMPARISONS;

The successful execution of this statement also generates two cast functions. Function DOUBLE(MILES) returns a value with data type DOUBLE, and function MILES(DOUBLE) returns a value with distinct type MILES.

Parent topic: SQL Statements


CREATE FUNCTION

The CREATE FUNCTION statement registers a user-defined function with an application server. You can register three different types of functions with this statement, each of which is described separately.

External Scalar

CREATE FUNCTION (external scalar)

The function is written in a programming language and returns a scalar value. The external executable is registered with an application server along with various attributes of the function.

External Table

CREATE FUNCTION (external table)

The function is written in a programming language and returns a complete table. The external executable is registered with an application server along with various attributes of the function.

Sourced

CREATE FUNCTION (sourced)

The function is implemented by invoking another function (either built-in, external, or sourced) that is already registered with an application server.

Parent topic: SQL Statements


CREATE FUNCTION (external scalar)

This CREATE FUNCTION statement registers a user-defined external scalar function with an application server.

A scalar function returns a single value each time it is invoked.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE FUNCTION function-name ([parameter-declaration[,...]])
RETURNS {data-type2 [AS LOCATOR] |
    data-type3 CAST FROM data-type4 [AS LOCATOR]} option-list

option-list:

[SPECIFIC specific-name]
[EXTERNAL [NAME {'string' | identifier}] LANGUAGE {ASSEMBLE | C | COBOL | PLI}]
[PARAMETER STYLE DB2SQL [DETERMINISTIC | NOT DETERMINISTIC] [FENCED]]
[RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT]
[READS SQL DATA | NO SQL | MODIFIES SQL DATA | CONTAINS SQL]
[EXTERNAL ACTION | NO EXTERNAL ACTION]
[NO SCRATCHPAD | SCRATCHPAD [100 | length]]
[FINAL CALL | NO FINAL CALL]
[ALLOW PARALLEL | DISALLOW PARALLEL]
[DBINFO | NODBINFO]
[NO COLLID | COLLID collection-id]
[WLM ENVIRONMENT {name | (name)}]
[ASUTIME NO LIMIT | ASUTIME LIMIT integer]
[STAY RESIDENT NO | STAY RESIDENT YES]
[PROGRAM TYPE SUB | PROGRAM TYPE MAIN]
[SECURITY DB2 | SECURITY {USER | DEFINED}]
[STOP AFTER SYSTEM DEFAULT FAILURES |
 STOP AFTER integer FAILURES |
 CONTINUE AFTER FAILURE]
[INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
[RUN OPTIONS run-time-options]

parameter-declaration:

[parameter-name] parameter-type

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] |
    {CHARACTER | CHAR} VARYING (integer)|
    VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] |
VARGRAPHIC (integer) |
DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

Description

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type of each parameter (without regard for any length, precision, scale, subtype or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

You can use the same name for more than one function if the function signature of each function is unique.

The unqualified form of function-name is a long SQL identifier. The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |

The unqualified function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of function-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name can be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Identifies the number of input parameters of the function, and specifies the data type of each parameter. All the parameters for a function are input parameters. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is a long SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |
built-in-data-type | The data type of the input parameter is a built-in data type. You can use the same built-in data types as for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead. If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
data-type2 | Specifies the data type of the output.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if data-type4 is a LOB data type or a distinct type based on a LOB data type.
data-type3 CAST FROM data-type4 Specifies the data type of the output of the function (data-type4) and the data type in which that output is returned to the invoking statement (data-type3). The two data types can be different For example, for the following definition, the function returns a DOUBLE value, which DB2 converts to a DECIMAL value and then passes to the statement that invoked the function:
CREATE FUNCTION SQRT(DECIMAL(15,0))
    RETURNS DECIMAL(15,0) CAST FROM DOUBLE
ASSEMBLE | The function is written in Assembler. (Not currently available with XDB Server.)
C | The function is written in C or C++. (Not currently available with XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available with XDB Server.)
NOT DETERMINISTIC The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements.

NOT DETERMINISTIC is the default.

Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.

DETERMINISTIC The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input.

DB2 does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is the null value.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return a null or nonnull value.
NO SQL | The function cannot execute any SQL statements.
MODIFIES SQL DATA | The function can execute any SQL statement except those statements that are not supported in any function. Do not specify MODIFIES SQL DATA when ALLOW PARALLEL is in effect.
READS SQL DATA The function cannot execute SQL statements that modify data. SQL statements that are not supported in any function return a different error.

READS SQL DATA is the default.

CONTAINS SQL | The function cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.
NO SCRATCHPAD

A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.

SCRATCHPAD length

When the function is invoked for the first time, XDB allocates memory for a scratchpad.

NO FINAL CALL | A final call is not made to the external scalar function. The function does not receive an additional argument that specifies the type of call.
FINAL CALL | A final call is made to the external scalar function. See the following description of call types for the characteristics of a final call. When FINAL CALL is specified, the function receives an additional argument that specifies the type of call to enable the function to differentiate between a final call and another type of call.
NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function. For details about the argument and its structure, see your DB2 Application Programming and SQL Guide.
NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.
NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.
NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.
SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.
  • A distinct type parameter is passed as the source type of the distinct type.

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB Server operating environment does not support the LOB data type at this time.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACES.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

XDB Server operating environment does not support transition table parameters at this time.

RETURNS

Identifies the output of the function. Consider this clause in conjunction with the optional CAST FROM clause.

data-type2 | Specifies the data type of the output.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if data-type4 is a LOB data type or a distinct type based on a LOB data type.
data-type3 CAST FROM data-type4 Specifies the data type of the output of the function (data-type4) and the data type in which that output is returned to the invoking statement (data-type3). The two data types can be different For example, for the following definition, the function returns a DOUBLE value, which DB2 converts to a DECIMAL value and then passes to the statement that invoked the function:
CREATE FUNCTION SQRT(DECIMAL(15,0))
    RETURNS DECIMAL(15,0) CAST FROM DOUBLE

The value of data-type4 must not be a distinct type and must be castable to data-type3. The value for data-type3 can be any built-in data type or distinct type.

SPECIFIC specific-name

Specifies a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is a long SQL identifier. The qualified form is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk , XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

EXTERNAL

Specifies that the function being registered is based on code that is written in an external programming language and adheres to the documented linkage conventions and interface of that language.

If you do not specify the NAME clause, 'NAME function-name' is implicit. In this case, function-name must not be longer than 8 characters.

NAME 'string' or identifier

Identifies the name of the MVS load module that contains the user-written code that implements the logic of the function. The name can be a string constant that is no longer than 8 characters or a short identifier, The name must conform to the naming conventions for MVS load modules.

DB2 loads the load module when the function is invoked. The load module is created when the program that contains the function body is compiled and link-edited. The load module does not need to exist when the CREATE FUNCTION statement is executed. However, it must exist and be accessible by the current server when the function is invoked.

You can specify the EXTERNAL clause in one of the following ways:

EXTERNAL
EXTERNAL NAME PKJVSP1
EXTERNAL NAME 'PKJVSP1'

If you specify an external program name, you must use the NAME keyword. For example, this syntax is not valid:

EXTERNAL PKJVSP1

LANGUAGE

Specifies the application programming language in which the function program is written. All programs must be designed to run in IBM's Language Environment environment.

ASSEMBLE | The function is written in Assembler. (Not currently available with XDB Server.)
C | The function is written in C or C++. (Not currently available with XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available with XDB Server.)

PARAMETER STYLE DB2SQL

Specifies the linkage convention that the function program uses to receive input parameters from and pass return values to the invoking SQL statement.

DB2SQL indicates that parameters for indicator variables are associated with each input and return value to allow for null values. The parameters that are passed between the invoking SQL statement and the function include:

  • The first n parameters are the input parameters that are specified for the function
  • A parameter for the result of the function
  • n parameters for the indicator variables for the input parameters
  • A parameter for the indicator variable for the result
  • The SQLSTATE to be returned to DB2
  • The qualified name of the function
  • The specific name of the function
  • The SQL diagnostic string to be returned to DB2

Zero to three additional parameters might also be passed:

  • The scratchpad, if SCRATCHPAD is specified
  • The call type, if NO FINAL CALL is specified
  • The DBINFO structure, if DBINFO is specified

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the function returns the same results for identical input arguments.

NOT DETERMINISTIC | The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements. NOT DETERMINISTIC is the default. Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.
DETERMINISTIC | The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input. DB2 does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

FENCED

This clause has no functional equivalent in the XDB Server operating environment.

RETURNS NULL ON NULL INPUT or CALLED ON NULL INPUT

Specifies whether the function is called if any of the input arguments is null at execution time.

RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is the null value.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return a null or nonnull value.

NO SQL, MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL

Indicates whether the function can execute any SQL statements and, if so, what type.

NO SQL | The function cannot execute any SQL statements.
MODIFIES SQL DATA | The function can execute any SQL statement except those statements that are not supported in any function. Do not specify MODIFIES SQL DATA when ALLOW PARALLEL is in effect.
READS SQL DATA | The function cannot execute SQL statements that modify data. SQL statements that are not supported in any function return a different error. READS SQL DATA is the default.
CONTAINS SQL | The function cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.

EXTERNAL ACTION or NO EXTERNAL ACTION

This clause has no functional equivalent in the XDB Server operating environment.

NO SCRATCHPAD or SCRATCHPAD

Specifies whether XDB provides a scratchpad for the function. It is strongly recommended that external functions be reentrant, and a scratchpad provides an area for the function to save information from one invocation to the next.

NO SCRATCHPAD | A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.
SCRATCHPAD length | When the function is invoked for the first time, XDB allocates memory for a scratchpad.

A scratchpad has the following characteristics:

  • length must be between 1 and 32767. The default value is 100 bytes.
  • XDB initializes the scratchpad to all binary zeros (X'00''s).
  • The scope of a scratchpad is the SQL statement. For each reference to the function in an SQL statement, there is one scratchpad. For example, assuming that function UDFX was defined with the SCRATCHPAD keyword, three scratchpads are allocated for the three references to UDFX in the following SQL statement:
    SELECT A, UDFX(A) FROM TABLEB
    WHERE UDFX(A) > 103 OR UDFX(A) < 19;

    If the function is run under parallel tasks, one scratchpad is allocated for each parallel task of each reference to the function in the SQL statement. This can lead to unpredictable results. For example, if a function uses the scratchpad to count the number of times that it is invoked, the count reflects the number of invocations done by the parallel task and not the SQL statement. Specify the DISALLOW PARALLEL clause for functions that will not work correctly with parallelism.

  • The scratchpad is persistent. XDB preserves its content from one invocation of the function to the next. Any changes that the function makes to the scratchpad on one call are still there on the next call. XDB initializes the scratchpads when it begins to execute an SQL statement. XDB does not reset scratchpads when a correlated subquery begins to execute.
  • The scratchpad can be a central point for the system resources that the function acquires. If the function acquires system resources, specify FINAL CALL to ensure that XDB calls the function one more time so that the function can free those system resources.

    Each time the function invoked, XDB passes an additional argument to the function that contains the address of the scratchpad.

NO FINAL CALL or FINAL CALL

NO FINAL CALL | A final call is not made to the external scalar function. The function does not receive an additional argument that specifies the type of call.
FINAL CALL | A final call is made to the external scalar function. See the following description of call types for the characteristics of a final call. When FINAL CALL is specified, the function receives an additional argument that specifies the type of call to enable the function to differentiate between a final call and another type of call.

ALLOW or DISALLOW PARALLEL

This clause has no functional equivalent in the XDB Server operating environment.

NO DBINFO or DBINFO

Specifies whether specific information that XDB knows is passed to the function when it is invoked.

NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function. For details about the argument and its structure, see your DB2 Application Programming and SQL Guide.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the function is executed.

NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of the function can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a function, setting a limit can be helpful if the function gets caught in a loop.

NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the load module for the function remains resident in memory when the function ends.

NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the function program runs as a main routine or a subroutine.

SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

Choosing data types for parameters

When you choose the data types of the input and output parameters for your function, consider the rules of promotion that can affect the values of the parameters. For example, a constant that is one of the input arguments to the function might have a built-in data type that is different from the data type that the function expects, and more significantly, might not be promotable to that expected data type. Based on the rules of promotion, using the following data types for parameters is recommended:

  • INTEGER instead of SMALLINT
  • DOUBLE instead of REAL
  • VARCHAR instead of CHAR
  • VARGRAPHIC instead of GRAPHIC

For portability of functions across platforms that are not DB2 for OS/390, do not use the following data types, which might have different representations on different platforms:

  • FLOAT. Use DOUBLE or REAL instead.
  • NUMERIC. Use DECIMAL instead.

Determining the uniqueness of functions in a schema

At the current server, the function signature of each function, which is the qualified function name combined with the number and data types of the input parameters, must be unique. If the function has more than 30 input parameters, only the data types of the first 30 are used to determine uniqueness. This means that two different schemas can each contain a function with the same name that have the same data types for all of their corresponding data types. However, a single schema must not contain multiple functions with the same name that have the same data types for all of their corresponding data types.

When determining whether corresponding data types match, XDB does not consider any length, precision, scale, subtype or encoding scheme attributes in the comparison. XDB considers the synonyms of data types (DECIMAL and NUMERIC, REAL and FLOAT, and DOUBLE and FLOAT) a match. Therefore, CHAR(8) and CHAR(35) are considered to be the same, as are DECIMAL(11,2), DECIMAL(4,3), and NUMERIC(4,2).

Assume that the following statements are executed to create four functions in the same schema. The second and fourth statements fail because they create functions that are duplicates of the functions that the first and third statements created.

CREATE FUNCTION PART (INT, CHAR(15)) ...
CREATE FUNCTION PART (INTEGER, CHAR(40)) ...
CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
CREATE FUNCTION ANGLE (DEC(10,7)) ...

Overriding a built-in function

Giving an external function the same name as a built-in function is not a recommended practice unless you are trying to change the functionality of the built-in function.

If you do intend to create an external function with the same name as a built-in function, be careful to maintain the uniqueness of its function signature. If your function has the same name and data types of the corresponding parameters of the built-in function but implements different logic, XDB might choose the wrong function when the function is invoked with an unqualified function name. Thus, the application might fail, or perhaps even worse, run successfully but provide an inappropriate result.

Example:

Assume that you want to write an external function program in C that implements the following logic:

output = 2 * input – 4

The function should return a null value if and only if one of the input arguments is null. The simplest way to avoid a function call and get a null result when an input value is null is to specify RETURNS NULL ON NULL INPUT on the CREATE FUNCTION statement or allow it to be the default.

Write the statement needed to register the function, using the specific name MINENULL1.

CREATE FUNCTION NTEST1 (SMALLINT)
    RETURNS SMALLINT
    EXTERNAL NAME 'NTESTMOD'
    SPECIFIC MINENULL1
    LANGUAGE C
    DETERMINISTIC
    NO SQL
    FENCED
    PARAMETER STYLE DB2SQL
    RETURNS NULL ON NULL INPUT
    NO EXTERNAL ACTION;

Assume that user Smith wants to register an external function named CENTER in schema SMITH. The function program will be written in C and will be reentrant. Write the statement that Smith needs to register the function, letting DB2 generate a specific name for the function.

CREATE FUNCTION CENTER (INTEGER, FLOAT)
    RETURNS FLOAT
    EXTERNAL NAME 'MIDDLE'
    LANGUAGE C
    DETERMINISTIC
    NO SQL
    FENCED
    PARAMETER STYLE DB2SQL
    NO EXTERNAL ACTION
    STAY RESIDENT YES;

Assume that user McBride (who has administrative authority) wants to register an external function named CENTER in the SMITH schema. McBride plans to give the function specific name FOCUS98. The function program uses a scratchpad to perform some one-time only initialization and save the results. The function program returns a value with a FLOAT data type. Write the statement McBride needs to register the function and ensure that when the function is invoked, it returns a value with a data type of DECIMAL(8,4).

CREATE FUNCTION SMITH.CENTER (FLOAT, FLOAT, FLOAT)
    RETURNS DECIMAL(8,4) CAST FROM FLOAT
    EXTERNAL NAME 'CMOD'
    SPECIFIC FOCUS98
    LANGUAGE C
    DETERMINISTIC
    NO SQLFENCED
    PARAMETER STYLE DB2SQL
    NO EXTERNAL ACTION
    SCRATCHPAD
    NO FINAL CALL;
Parent topic: SQL Statements


CREATE FUNCTION (external table)

This CREATE FUNCTION statement registers a user-defined external table function with an application server.

A scalar function returns a single value each time it is invoked.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE FUNCTION function-name ([parameter-declaration[,...]])
    RETURNS TABLE (column-name data-type [AS LOCATOR] [,...]) option-list

option-list:

    [SPECIFIC specific-name]
    [EXTERNAL [NAME {'string' | identifier}] LANGUAGE {ASSEMBLE | C | COBOL | PLI}]
    [PARAMETER STYLE DB2SQL [DETERMINISTIC | NOT DETERMINISTIC]
    [FENCED]]
    [RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT]
    [READS SQL DATA | NO SQL | MODIFIES SQL DATA | CONTAINS SQL]
    [EXTERNAL ACTION | NO EXTERNAL ACTION]
    [NO SCRATCHPAD | SCRATCHPAD [100 | length]]
    [FINAL CALL | NO FINAL CALL]
    [DISALLOW PARALLEL]
    [DBINFO | NODBINFO]
    [CARDINALITY integer]
    [NO COLLID | COLLID collection-id]
    [WLM ENVIRONMENT {name | (name)}]
    [ASUTIME NO LIMIT | ASUTIME LIMIT integer]
    [STAY RESIDENT NO | STAY RESIDENT YES]
    [PROGRAM TYPE SUB | PROGRAM TYPE MAIN]
    [SECURITY DB2 | SECURITY {USER | DEFINED}]
    [RUN OPTIONS run-time-options]
    [STOP AFTER SYSTEM DEFAULT FAILURES |
     STOP AFTER integer FAILURES |
     CONTINUE AFTER FAILURE]

parameter-declaration:

    [parameter-name] parameter-type

parameter-type:

    {data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

    {built-in-data-type | distinct-type-name}

built-in-data-type:

    SMALLINT |
    {INTEGER | INT} |
    {DECIMAL | DEC | NUMERIC} [integer[,...]] |
    {FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
    { {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer)|
    VARCHAR (integer) }
        [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
        {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
        [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
    {BINARY LARGE OBJECT | BLOB} (integer [K|M|G])
    |{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
    {DATE | TIME | TIMESTAMP} |
    ROWID

Description

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type of each parameter (without regard for any length, precision, scale, subtype or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

You can use the same name for more than one function if the function signature of each function is unique.

The unqualified form of function-name is a long SQL identifier. The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE

The unqualified function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of function-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name can be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Identifies the number of input parameters of the function, and specifies the data type of each parameter. All the parameters for a function are input parameters. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is a long SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
column-name | Specifies the name of the column. The name is a long identifier and must be unique within the RETURNS TABLE clause for the function.
data-type | Specifies the data type of the column. The data type can be any built-in data type, except LONG VARCHAR or LONG VARGRAPHIC. The data type can also be any distinct type.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only for a LOB data type or a distinct type based on a LOB data type.
ASSEMBLE | The function is written in Assembler. (Not currently available in XDB Server.)
C | The function is written in C or C++. (Not currently available in XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available in XDB Server.)
NOT DETERMINISTIC | The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements. NOT DETERMINISTIC is the default. Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.
DETERMINISTIC | The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input. XDB does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.
RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is an empty table, which is a table with no rows. RETURNS NULL ON NULL INPUT is the default.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return an empty table, depending on its logic.
NO SQL | The function cannot execute any SQL statements.
READS SQL DATA | The function cannot execute any SQL statements that modify data. SQL statements that are not supported in any function return a different error. READS SQL DATA is the default.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.
NO SCRATCHPAD | A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.
SCRATCHPAD | length When the function is invoked for the first time, XDB allocates memory for a scratchpad. A scratchpad has the following characteristics:
First call | A first call occurs only if the function was defined with FINAL CALL. Before a first call, the scratchpad is set to binary zeros. Argument values are passed to the function, and the function might acquire memory or perform other one-time only resource initialization. However, the function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments.
Open call | An open call occurs unless the function returns an error. The scratchpad is set to binary zeros only if the function was defined with NO FINAL CALL. Argument values are passed to the function, and the function might perform any one-time initialization actions that are required. However, the function should not return any data to XDB.
Fetch call | A fetch call occurs unless the function returns an error during the first call or open call. Argument values are passed to the function, and XDB expects the function to return a row of data or the end-of-table condition. If a scratchpad is also passed to the function, it remains untouched from the previous call.
Close call | A close call occurs unless the function returns an error during the first call, open call, or fetch call. No SQL-argument or SQL-argument-ind values are passed to the function, and if the function attempts to examine these values, unpredictable results may occur. If a scratchpad is also passed to the function, it remains untouched from the previous call. The function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments. Also on close call, a function that is defined with NO FINAL CALL should release any system resources that it acquired. (A function that is defined with FINAL CALL should release any acquired resources on the final call.)
Final | The final call balances the first call, and like the first call, occurs only if the function was defined with FINAL CALL. The function can set return values for the SQL-state and diagnostic-message arguments. The function should also release any system resources that it acquired. A final call occurs at these times:
NO DBINFO | No additional information is passed. NO DBINFO is the default.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function.
NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.
NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.
NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.
SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.
  • A distinct type parameter is passed as the source type of the distinct type.

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB operating environment does not support the LOB data type at this time.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACES.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

The XDB operating environment does not support transition table parameters at this time.

RETURNS TABLE(column-name data-type ...)

Identifies that the output of the function is a table. The parentheses that follow the keyword enclose the list of names and data types of the columns of the table.

column-name | Specifies the name of the column. The name is a long identifier and must be unique within the RETURNS TABLE clause for the function.
data-type | Specifies the data type of the column. The data type can be any built-in data type, except LONG VARCHAR or LONG VARGRAPHIC. The data type can also be any distinct type.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only for a LOB data type or a distinct type based on a LOB data type.

SPECIFIC specific-name

Specifies a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is a long SQL identifier. The qualified form is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk , XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

EXTERNAL

Specifies that the function being registered is based on code that is written in an external programming language and adheres to the documented linkage conventions and interface of that language.

If you do not specify the NAME clause, 'NAME function-name' is implicit. In this case, function-name must not be longer than 8 characters.

NAME 'string' or identifier

Identifies the name of the MVS load module that contains the user-written code that implements the logic of the function. The name can be a string constant that is no longer than 8 characters or a short identifier, The name must conform to the naming conventions for MVS load modules.

XDB loads the load module when the function is invoked. The load module is created when the program that contains the function body is compiled and link-edited. The load module does not need to exist when the CREATE FUNCTION statement is executed. However, it must exist and be accessible by the current server when the function is invoked.

You can specify the EXTERNAL clause in one of the following ways:

EXTERNAL
EXTERNAL NAME PKJVSP1
EXTERNAL NAME 'PKJVSP1'

If you specify an external program name, you must use the NAME keyword. For example, this syntax is not valid:

EXTERNAL PKJVSP1

LANGUAGE

Specifies the application programming language in which the function program is written. All programs must be designed to run in IBM's Language Environment environment.

ASSEMBLE | The function is written in Assembler. (Not currently available in XDB Server.)
C | The function is written in C or C++. (Not currently available in XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available in XDB Server.)

PARAMETER STYLE DB2SQL

Specifies the linkage convention that the function program uses to receive input parameters from and pass return values to the invoking SQL statement.

DB2SQL indicates that parameters for indicator variables are associated with each input and return value to allow for null values. The parameters that are passed between the invoking SQL statement and the function include:

  • The first n parameters are the input parameters that are specified for the function
  • A parameter for the result of the function
  • n parameters for the indicator variables for the input parameters
  • A parameter for the indicator variable for the result
  • The SQLSTATE to be returned to DB2
  • The qualified name of the function
  • The specific name of the function
  • The SQL diagnostic string to be returned to DB2

Zero to three additional parameters might also be passed:

  • The scratchpad, if SCRATCHPAD is specified
  • The call type, if NO FINAL CALL is specified
  • The DBINFO structure, if DBINFO is specified

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the function returns the same results for identical input arguments.

NOT DETERMINISTIC | The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements. NOT DETERMINISTIC is the default. Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.
DETERMINISTIC | The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input. XDB does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

FENCED

This clause has no functional equivalent in the XDB Server operating environment.

RETURNS NULL ON NULL INPUT or CALLED ON NULL INPUT

Specifies whether the function is called if any of the input arguments is null at execution time.

RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is an empty table, which is a table with no rows. RETURNS NULL ON NULL INPUT is the default.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return an empty table, depending on its logic.

NO SQL, READS SQL DATA, or CONTAINS SQL

Indicates whether the function can execute any SQL statements and, if so, what type.

NO SQL | The function cannot execute any SQL statements.
READS SQL DATA | The function cannot execute any SQL statements that modify data. SQL statements that are not supported in any function return a different error. READS SQL DATA is the default.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.

EXTERNAL ACTION or NO EXTERNAL ACTION

This clause has no functional equivalent in the XDB Server operating environment.

NO SCRATCHPAD or SCRATCHPAD

Specifies whether XDB provides a scratchpad for the function. It is strongly recommended that external functions be reentrant, and a scratchpad provides an area for the function to save information from one invocation to the next.

NO SCRATCHPAD | A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.
SCRATCHPAD | length When the function is invoked for the first time, XDB allocates memory for a scratchpad. A scratchpad has the following characteristics:
  • length must be between 1 and 32767. The default value is 100 bytes.
  • XDB initializes the scratchpad to all binary zeros (X'00''s).
  • The scope of a scratchpad is the SQL statement. For each reference to the function in an SQL statement, there is one scratchpad. For example, assuming that function UDFX was defined with the SCRATCHPAD keyword, three scratchpads are allocated for the three references to UDFX in the following SQL statement:
    SELECT A, UDFX(A) FROM TABLEB WHERE UDFX(A) > 103 OR UDFX(A) < 19;

    If the function is run under parallel tasks, one scratchpad is allocated for each parallel task of each reference to the function in the SQL statement. This can lead to unpredictable results. For example, if a function uses the scratchpad to count the number of times that it is invoked, the count reflects the number of invocations done by the parallel task and not the SQL statement. Specify the DISALLOW PARALLEL clause for functions that will not work correctly with parallelism.

  • The scratchpad is persistent. XDB preserves its content from one invocation of the function to the next. Any changes that the function makes to the scratchpad on one call are still there on the next call. XDB initializes the scratchpads when it begins to execute an SQL statement. XDB does not reset scratchpads when a correlated subquery begins to execute.
  • The scratchpad can be a central point for the system resources that the function acquires. If the function acquires system resources, specify FINAL CALL to ensure that XDB calls the function one more time so that the function can free those system resources.

    Each time the function invoked, XDB passes an additional argument to the function that contains the address of the scratchpad.

FINAL CALL or NO FINAL CALL

Specifies whether a first call and a final call are made to the function.

FINAL CALL

A first call and final call are made to the function in addition to one or more open, fetch, or close calls. FINAL CALL is the default.

NO FINAL CALL

A first call and final call are not made to the function.

The types of calls are:

First call | A first call occurs only if the function was defined with FINAL CALL. Before a first call, the scratchpad is set to binary zeros. Argument values are passed to the function, and the function might acquire memory or perform other one-time only resource initialization. However, the function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments.
Open call | An open call occurs unless the function returns an error. The scratchpad is set to binary zeros only if the function was defined with NO FINAL CALL. Argument values are passed to the function, and the function might perform any one-time initialization actions that are required. However, the function should not return any data to XDB.
Fetch call | A fetch call occurs unless the function returns an error during the first call or open call. Argument values are passed to the function, and XDB expects the function to return a row of data or the end-of-table condition. If a scratchpad is also passed to the function, it remains untouched from the previous call.
Close call | A close call occurs unless the function returns an error during the first call, open call, or fetch call. No SQL-argument or SQL-argument-ind values are passed to the function, and if the function attempts to examine these values, unpredictable results may occur. If a scratchpad is also passed to the function, it remains untouched from the previous call. The function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments. Also on close call, a function that is defined with NO FINAL CALL should release any system resources that it acquired. (A function that is defined with FINAL CALL should release any acquired resources on the final call.)
Final | The final call balances the first call, and like the first call, occurs only if the function was defined with FINAL CALL. The function can set return values for the SQL-state and diagnostic-message arguments. The function should also release any system resources that it acquired. A final call occurs at these times:
  • End of statement: When the cursor is closed for cursor-oriented statements, or the execution of the statement has completed.
  • End of transaction: When normal end of statement processing does not occur. For example, the logic of an application, for some reason, bypasses closing the cursor.

If a commit operation occurs while a cursor defined as WITH HOLD is open, a final call is made when the cursor is closed or the application ends. If a commit occurs at the end of a parallel task, a final call is made regardless of whether a cursor defined as WITH HOLD is open.

If a commit, rollback, or abort operation causes the final call, the function cannot issue any SQL statements when it is invoked.

DISALLOW PARALLEL

This clause has no functional equivalent in the XDB Server operating environment.

NO DBINFO or DBINFO

Specifies whether specific information that DB2 knows is passed to the function when it is invoked.

NO DBINFO | No additional information is passed. NO DBINFO is the default.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function.

CARDINALITY integer

Specifies an estimate of the expected number of rows that the function returns. The number is used for optimization purposes. The value of integer must range from 0 to 2147483647.

If you do not specify CARDINALITY, DB2 assumes a finite value. The finite value is the same value that DB2 assumes for tables for which the RUNSTATS utility has not gathered statistics.

If a function has an infinite cardinality--the function never returns the "end-of-table" condition and always returns a row, then a query that requires the "end-of-table" to work correctly will need to be interrupted. Thus, avoid using such functions in queries that involve GROUP BY and ORDER BY.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the function is executed.

NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of the function can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a function, setting a limit can be helpful if the function gets caught in a loop.

NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the load module for the function remains resident in memory when the function ends.

NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the function program runs as a main routine or a subroutine.

SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

Example:

The following registers a table function written to return a row consisting of a single document identifier column for each known document in a text management system. The first parameter matches a given subject area and the second parameter contains a given string.

Within the context of a single session, the table function will always return the same table; therefore, it is defined as DETERMINISTIC. In addition, the DISALLOW PARALLEL keyword is added because table functions cannot operate in parallel.

Although the size of the output for DOCMATCH is highly variable, CARDINALITY 20 is a representative value, and is specified to help DB2.

CREATE FUNCTION DOCMATCH (VARCHAR(30), VARCHAR(255))
        RETURNS TABLE (DOC_ID CHAR(16))
    EXTERNAL NAME ABC
    LANGUAGE C
    PARAMETER STYLE DB2SQL
    NO SQL
    DETERMINISTIC
    NO EXTERNAL ACTION
    FENCED
    SCRATCHPAD
    FINAL CALL
    DISALLOW PARALLEL
    CARDINALITY 20;
Parent topic: SQL Statements


CREATE FUNCTION (sourced)

This CREATE FUNCTION statement registers a user-defined function that is based on an existing scalar or column function with an application server.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

CREATE FUNCTION function-name ([parameter-declaration[,...]])
RETURNS data-type2 [AS LOCATOR] [SPECIFIC specific-name]
SOURCE {function-name | SPECIFIC specific-name | function-name (parameter-type [,...])}

parameter-declaration:

[parameter-name] parameter-type

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer)
| VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type of each parameter (without regard for any length, precision, scale, subtype or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

If the function is sourced on an existing function to enable the use of the existing function with a distinct type, the name can be the same name as the existing function. In general, more than one function can have the same name if the function signature of each function is unique.

The unqualified form of function-name is a long SQL identifier. The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |

The unqualified function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of function-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Identifies the number of input parameters of the function, and specifies the data type of each parameter. All the parameters for a function are input parameters. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is a long SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |
built-in-data-type | The data type of the input parameter is a built-in data type. You can use the same built-in data types as for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead. If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
data-type2 Specifies the data type of the output.

You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result. To specify a LONG VARCHAR or LONG VARGRAPHIC, use VARCHAR or VARGRAPHIC with an explicit length instead.

AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.
function-name | Identifies the function name of the source function. If you specify an unqualified name, XDB searches the schemas of the SQL path; otherwise, XDB searches the named schema.
parameter-type,... Provides a list of data types, separated by commas, that must match the data types of the parameters of the source function. XDB uses the number of data types and the logical concatenation of the data types to identify the source function.

For data types that have length, precision, or scale attributes, you can either specify a value for the attribute or use a set of empty parentheses (with the noted exceptions):

Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match. For example, DEC() will match a parameter whose data type is DEC(7,2).FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement for the source function. For example, DECIMAL(7,4) does not match a parameter whose data type is DECIMAL(7,2). Coding specific values for length, precision, scale, subtype, and encoding scheme attributes ensures that the source function you intend to use is used.

The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.
  • A distinct type parameter is passed as the source type of the distinct type.

You can specify any built-in data type or distinct type that matches or can be cast to the data type of the corresponding parameter of the source function (the function that is identified in the SOURCE clause). Length, precision, or scale attributes do not have be specified for data types with these attributes. When specifying data types with these attributes, follow these rules:

An empty set of parentheses can be used to indicate that the length, precision, or scale is the same as the source function.

If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB operating environment does not support the LOB data type at this time.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACES.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

XDB Server operating environment does not support transition table parameters at this time.

RETURNS

Identifies the output of the function.

data-type2 | Specifies the data type of the output. You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result. To specify a LONG VARCHAR or LONG VARGRAPHIC, use VARCHAR or VARGRAPHIC with an explicit length instead.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.

SPECIFIC specific-name

Specifies a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is a long SQL identifier. The qualified form is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk , XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

SOURCE

Specifies that the function that you are registering is a sourced function. A sourced function is implemented by another function (the source function). The source function can be any previously created user-defined function except an external table function. The source function can also be any built-in function except the following (if a particular syntax is shown, only the indicated form cannot be specified):

  • COUNT(*)
  • COUNT_BIG(*)
  • CHAR(datetime-expression, second-argument) where second-argument is ISO, USA, EUR, JIS, or LOCAL
  • COALESCE
  • NULLIF
  • RAISE-ERROR
  • STRIP with any optional parameters specified
  • VALUE

If you base the sourced function directly or indirectly on an external scalar function, the sourced function inherits the attributes of the external scalar function. This can involve several layers of sourced functions. For example, assume that function A is sourced on function B, which in turn is sourced on function C. Function C is an external scalar function. Functions A and B inherit all of the attributes that are specified on the EXTERNAL clause of the CREATE FUNCTION statement for function C.

EXECUTE authority is required on the source function.

To specify a built-in function as the source function, use the last syntax variation in the following list, function-name (parameter-type, ...).

function-name

Identifies the function to be used as the source function by its function name. A schema name implicitly or explicitly qualifies the name. Only one function with this name must exist in the schema.

If you specify an unqualified function-name, XDB uses the SQL path of the authorization ID (the value of the CURRENT PATH special register) to locate the function. The first schema that has only one function with this name on which the user has EXECUTE authority is selected. XDB returns an error if it cannot find a function or encounters a schema that has more than one function with this name.

If you specify a qualified function-name, XDB returns an error if there is no function with this name in the named schema or more than one function with this name exists in the schema.

SPECIFIC specific-name

Identifies the function to be used as the source function by its specific name. A schema name implicitly or explicitly qualifies the name.

If you specify an unqualified specific-name, XDB uses the SQL path of the authorization ID (the value of the CURRENT PATH special register) to locate the schema. XDB searches the SQL path and selects the first schema that contains a function with this specific name for which the user has EXECUTE authority. XDB returns an error if it cannot find a function with the specific name in one of the schemas in the SQL path.

If you specify a qualified specific-name, XDB searches the named schema for the function. XDB returns an error if it cannot find a function with the specific name.

function-name (parameter-type,...)

Identifies the function to be used as the source function by its function signature. You must use this form of the syntax if the source function is a built-in function. You cannot use this form of the syntax if the source function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table). Instead, identify the function with its function name, if unique, or with its specific name.

XDB does not use function resolution to select the source function because the function signature uniquely identifies the function.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY NOT =
BETWEEN NULL ¬=
DISTINCT ONLY <
EXCEPT OR <=
EXISTS OVERLAPS ¬<
FALSE SIMILAR >
FOR SOME >=
FROM TABLE ¬>
IN TRUE <>
IS | TYPE
built-in-data-type The data type of the input parameter is a built-in data type. You can use the same built-in data types as for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead.

If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:

distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
data-type2 Specifies the data type of the output.

You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result. To specify a LONG VARCHAR or LONG VARGRAPHIC, use VARCHAR or VARGRAPHIC with an explicit length instead.

AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.
parameter-type,... Provides a list of data types, separated by commas, that must match the data types of the parameters of the source function. XDB uses the number of data types and the logical concatenation of the data types to identify the source function.

For data types that have length, precision, or scale attributes, you can either specify a value for the attribute or use a set of empty parentheses (with the noted exceptions):

Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match. For example, DEC() will match a parameter whose data type is DEC(7,2).FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement for the source function. For example, DECIMAL(7,4) does not match a parameter whose data type is DECIMAL(7,2). Coding specific values for length, precision, scale, subtype, and encoding scheme attributes ensures that the source function you intend to use is used.

The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)

For either empty parentheses or specific values, the synonyms for data types are considered a match. For example, DEC and NUMERIC will match.

If you omit the FOR DATA or CCSID clause for data types with a subtype or encoding scheme attribute, XDB ignores the attribute when determining whether the data types match.

If no function with the specified signature exists in the explicitly or implicitly specified schema, an error occurs.

The number of input parameters in the function that is being created must be the same as the number of parameters in the source function. If the data type of each input parameter is not the same as or castable to the corresponding parameter of the source function, an error occurs. The data type of the final result of the source function must match or be castable to the result of the sourced function.

Choosing data types for parameters

When you choose the data types of the input and output parameters for your function, consider the rules of promotion that can affect the values of the parameters. For example, a constant that is one of the input arguments to the function might have a built-in data type that is different from the data type that the function expects, and more significantly, might not be promotable to that expected data type. Based on the rules of promotion, using the following data types for parameters is recommended:

  • INTEGER instead of SMALLINT
  • DOUBLE instead of REAL
  • VARCHAR instead of CHAR
  • VARGRAPHIC instead of GRAPHIC

For portability of functions across platforms that are not DB2 for OS/390, do not use the following data types, which might have different representations on different platforms:

  • FLOAT. Use DOUBLE or REAL instead.
  • NUMERIC. Use DECIMAL instead.

Determining the uniqueness of functions in a schema

At the current server, the function signature of each function, which is the qualified function name combined with the number and data types of the input parameters, must be unique This means that two different schemas can each contain a function with the same name that have the same data types for all of their corresponding data types. However, a single schema must not contain multiple functions with the same name that have the same data types for all of their corresponding data types.

When determining whether corresponding data types match, XDB does not consider any length, precision, scale, subtype or encoding scheme attributes in the comparison. XDB considers the synonyms of data types (DECIMAL and NUMERIC, REAL and FLOAT, and DOUBLE and FLOAT) a match. Therefore, CHAR(8) and CHAR(35) are considered to be the same, as are DECIMAL(11,2), DECIMAL(4,3), and NUMERIC(4,2).

Assume that the following statements are executed to create four functions in the same schema. The second and fourth statements fail because they create functions that are duplicates of the functions that the first and third statements created.

CREATE FUNCTION PART (INT, CHAR(15)) ...
CREATE FUNCTION PART (INTEGER, CHAR(40)) ...
CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
CREATE FUNCTION ANGLE (DEC(10,7)) ...

Rules for creating sourced functions

For the discussion in this section, assume that the function that is being created is named NEWF and the source function is named SOURCEF. Consider the following rules when creating a sourced function:

  • The unqualified names of the sourced function and source function can be different (NEWF and SOURCEF).
  • The number of input parameters for NEWF and SOURCEF must be the same; otherwise, an error occurs when the CREATE FUNCTION statement is executed.
  • When specifying the input parameters and output for NEWF, you can specify a value for the precision, scale, subtype, or encoding scheme for a data type with any of these attributes or use empty parentheses.

    Empty parentheses, such as VARCHAR(), indicate that the value of the attribute is the same as the attribute for the corresponding parameter of SOURCEF, or that is determined by data type promotion. If you specify any values for the attributes, XDB checks the values against the corresponding input parameters and returned output of SOURCEF as described next.

  • When the CREATE FUNCTION statement is executed, XDB checks the input parameters of NEWF against those of SOURCEF. The data type of each input parameter of NEWF function must be either the same as, or promotable to, the data type of the corresponding parameter of SOURCEF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, an argument that matches the data type and length or precision attributes of a NEWF parameter might not be promotable if the corresponding SOURCEF parameter has a shorter length or less precision. In general, do not define the parameters of a sourced function with length or precision attributes that are greater than the attributes of the corresponding parameters of the source function.

  • When the CREATE FUNCTION statement is executed, XDB checks the data type identified in the RETURNS clause of NEWF against the data type that SOURCEF returns. The data type that SOURCEF returns must be either the same as, or promotable to, the RETURNS data type of NEWF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, the value of a result that matches the data type and length or precision attributes of those specified for SOURCEF's result might not be promotable if the RETURNS data type of NEWF has a shorter length or less precision. Consider the possible effects of defining the RETURNS data type of a sourced function with length or precision attributes that are less than the attributes defined for the data type returned by source function.

Examples:

Assume that you created a distinct type HATSIZE, which you based on the built-in data type INTEGER. You want to have an AVG function to compute the average hat size of different departments. Create a sourced function that is based on built-in function AVG.

CREATE FUNCTION AVE (HATSIZE) RETURNS HATSIZE
    SOURCE SYSIBM.AVG (INTEGER);

When you created distinct type HATSIZE, two cast functions were generated, which allow HATSIZE to be cast to INTEGER for the argument and INTEGER to be cast to HATSIZE for the result of the function.

After Smith registered the external scalar function CENTER in his schema, you decide that you want to use this function, but you want it to accept two INTEGER arguments instead of one INTEGER argument and one FLOAT argument. Create a sourced function that is based on CENTER.

CREATE FUNCTION MYCENTER (INTEGER, INTEGER)
    RETURNS FLOAT
    SOURCE SMITH.CENTER (INTEGER, FLOAT);
Parent topic: SQL Statements


CREATE FUNCTION (SQL Scalar)

This statement is used to define a user-defined SQL scalar function. A scalar function returns a single value each time it is invoked. Specifying a function is generally valid wherever an SQL expression is valid.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

CREATE FUNCTION function-name ([parameter-declaration[,...]])
RETURNS data-type2
[LANGUAGE SQL] option-list RETURN-statement

parameter-declaration:

[parameter-name] parameter-type

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer)
| VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

Description

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type each parameter (without regard for any length, precision, scale, subtype, or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

If the function is sourced on an existing function to enable the use of the existing function with a distinct type, the name can be the same name as the existing function. In general, more than one function can have the same name if the function signature of each function is unique.

  • The unqualified form of function-name is an SQL identifier.

    The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

    ALL | LIKE | UNIQUE
    AND | MATCH | UNKNOWN
    ANY NOT =
    BETWEEN NULL ¬=
    DISTINCT ONLY <
    EXCEPT OR <=
    EXISTS OVERLAPS ¬<
    FALSE SIMILAR >
    FOR SOME >=
    FROM TABLE ¬>
    IN TRUE <>
    IS | TYPE

    The unqualified function name is implicitly qualified with a schema name according to the following rules:

    • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
    • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.
  • The qualified form of function-name is an SQL identifier (the schema name) followed by a period and an SQL identifier.

    The schema name can be "SYSTOOLS" if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with "SYS" unless the schema name is "SYSADM".

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Specifies the number of input parameters of the function and the data type of each parameter. All the parameters for a function are input parameters and are nullable. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is an SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

built-in-type

The data type of the input parameter is a built-in data type.

You can use the same built-in data types as for the CREATE TABLE statement.

For parameters with a character or graphic data type, the PARAMETER CCSID clause or CCSID clause indicates the encoding scheme of the parameter. If you do not specify either of these clauses, the encoding scheme is the value of field DEF ENCODING SCHEME on installation panel DSNTIPF.

distinct-type-name

The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.

The implicitly or explicitly specified encoding scheme of all the parameters with a string data type must be the same - either all ASCII, all EBCDIC, or all UNICODE.

Although parameters with a character data type have an implicitly or explicitly specified subtype (BIT, SBCS, or MIXED), the function program can receive character data of any subtype. Therefore, conversion of the input data to the subtype of the parameter might occur when the function is invoked.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.

    The encoding scheme for a datetime type parameter is the same as the implicitly or explicitly specified encoding scheme of any character or graphic string parameters. If no character or graphic string parameters are passed, the encoding scheme is the value of field DEF ENCODING SCHEME on installation panel DSNTIPF.

  • A distinct type parameter is passed as the source type of the distinct type.

You can specify any built-in data type or distinct type that matches or can be cast to the data type of the corresponding parameter of the source function (the function that is identified in the SOURCE clause). Length, precision, or scale attributes do not have be specified for data types with these attributes. When specifying data types with these attributes, follow these rules:

  • An empty set of parentheses can be used to indicate that the length, precision, or scale is the same as the source function.
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default values are used.

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB operating environment does not support the LOB data type.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACE. The number of columns and the attributes of those columns are determined at the time the CREATE FUNCTION statement is processed. Any subsequent changes to the number of columns in the table or the attributes of those columns do not affect the parameters of the function.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

Additionally, a character FOR BIT DATA column of the transition table cannot be passed as input for a table parameter for which the corresponding column of the table specified at the definition is not defined as character FOR BIT DATA. (The definition occurs with the CREATE FUNCTION statement.) Likewise, a character column of the transition table that is not FOR BIT DATA cannot be passed as input for a table parameter for which the corresponding column of the table specified at the definition is defined as character FOR BIT DATA.

The XDB operating environment does not support transition table parameters.

RETURNS

Identifies the output of the function.

data-type2

Specifies the data type of the output. The output is nullable.

You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result.

AS LOCATOR

Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.

The XDB operating environment does not support the LOB data type.

SPECIFIC specific-name

Provides a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is an SQL identifier. The qualified form is an SQL identifier (the schema name) followed by a period and an SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk, XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

PARAMETER CCSID

Indicates whether the encoding scheme for string parameters is ASCII, EBCDIC, or UNICODE. The default encoding scheme is the value specified in the CCSID clauses of the parameter list or RETURNS clause, or in the field DEF ENCODING SCHEME on installation panel DSNTIPF.

This clause provides a convenient way to specify the encoding scheme for all string parameters. If individual CCSID clauses are specified for individual parameters in addition to this PARAMETER CCSID clause, the value specified in all of the CCSID clauses must be the same value that is specified in this clause.

This clause also specifies the encoding scheme to be used for system-generated parameters of the routine such as message tokens and DBINFO.

SOURCE

Specifies that the new function is being defined as a sourced function. A sourced function is implemented by another function (the source function). The source function must be a scalar or aggregate function that exists at the current server, and it must be one of the following types of functions:

  • A function that was defined with a CREATE FUNCTION statement
  • A cast function that was generated by a CREATE DISTINCT TYPE statement
  • A built-in function

If the source function is not a built-in function, the particular function can be identified by its name, function signature, or specific name.

If the source function is a built-in function, the SOURCE clause must include a function signature for the built-in function. The source function must not be any of the built-in functions shown in the table below. If a particular syntax is shown, only the indicated form cannot be specified.

Type of Function | Restricted Functions
Aggregate | COUNT(*)
 | COUNT_BIG(*)
 | Scalar function | CHAR(datetime-expression, second-argument) where second-argument is ISO, USA, EUR, JIS, or LOCAL
COALESCE
DECRYPT_CHAR where second argument is DEFAULT
GETVARIABLE where second argument is DEFAULT
MAX
NULLIF
XML2CLOB
XMLELEMENT
XMLNAMESPACES

If you base the sourced function directly or indirectly on an external scalar function, the sourced function inherits the attributes of the external scalar function. This can involve several layers of sourced functions. For example, assume that function A is sourced on function B, which in turn is sourced on function C. Function C is an external scalar function. Functions A and B inherit all of the attributes that are specified on the EXTERNAL clause of the CREATE FUNCTION statement for function C.

function-name

Identifies the function that is to be used as the source function. The source function can be defined with any number of parameters. If more than one function is defined with the specified name in the specified or implicit schema, an error is returned.

If you specify an unqualified function-name, XDB searches the schemas of the SQL path. XDB selects the first schema that has only one function with this name on which the user has EXECUTE authority. An error is returned if a function is not found or a schema has more than one function with this name.

function-name (parameter-type,...)

Identifies the function that is to be used as the source function by its function signature, which uniquely identifies the function. Thefunction-name (parameter-type,...) must identify a function with the specified signature. The specified parameters must match the data types in the corresponding position that were specified when the function was created. XDB uses the number of data types and the logical concatenation of the data types to identify the specific function instance. Synonyms for data types are considered a match.

If function-name() is specified, the identified function must have zero parameters.

To use a built-in function as the source function, this syntax variation must be used. You cannot use this form of the syntax if the source function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table). Instead, identify the function with its function name, if unique, or with its specific name.

function-name

Identifies the function name of the source function. If you specify an unqualified name, XDB searches the schemas of the SQL path. Otherwise, XDB searches for the function in the specified schema.

parameter-type,...

Identifies the parameters of the function.

If an unqualified distinct type name is specified, XDB searches the SQL path to resolve the schema name for the distinct type.

Empty parentheses are allowed for some data types that are specified in this context. For data types that have a length, precision, or scale attribute, use one of the following specifications:

  • Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match. For example, DEC() is considered a match for a parameter of a function that is defined with a data type of DEC(7,2). However, FLOAT cannot be specified with empty parentheses because its parameter value indicates a specific data type (REAL or DOUBLE).
  • If a specific value for a length, precision, or scale attribute is specified, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement. If the data type is FLOAT, the precision does not need to exactly match the value that was specified because matching is based on the data type (REAL or DOUBLE).
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default attributes of the data type are implied. The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

If you omit the FOR subtype DATA clause or the CCSID clause for data types with a subtype or encoding scheme attribute, XDB is to ignore the attribute when determining whether the data types match.An exception to ignoring the attribute is FOR BIT DATA. A character FOR BIT DATA parameter of the new function cannot correspond to a parameter of the source function that is not defined as character FOR BIT DATA. Likewise, a character parameter of the new function that is not FOR BIT DATA cannot correspond to a parameter of the source function that is defined as character FOR BIT DATA.

The number of input parameters in the function that is being created must be the same as the number of parameters in the source function. If the data type of each input parameter is not the same as or castable to the corresponding parameter of the source function, an error occurs. The data type of the final result of the source function must match or be castable to the result of the sourced function.

AS LOCATOR

Specifies that the function is defined to receive a locator for this parameter. If AS LOCATOR is specified, the data type must be a LOB or distinct type that is based on a LOB.

SPECIFIC specific-name

Identifies the function to be used as the source function by its specific name.

If you specify an unqualified specific-name, XDB searches the SQL path to locate the schema. XDB selects the first schema that contains a function with this specific name for which the user has EXECUTE authority. XDB returns an error if it cannot find a function with the specific name in one of the schemas in the SQL path.

If you specify a qualified specific-name, XDB searches the named schema for the function. XDB returns an error if it cannot find a function with the specific name.

Choosing data types for parameters

When you choose the data types of the input and output parameters for your function, consider the rules of promotion that can affect the values of the parameters. For example, a constant that is one of the input arguments to the function might have a built-in data type that is different from the data type that the function expects, and more significantly, might not be promotable to that expected data type. Based on the rules of promotion, we recommend using the following data types for parameters:

  • INTEGER instead of SMALLINT
  • DOUBLE instead of REAL
  • VARCHAR instead of CHAR
  • VARGRAPHIC instead of GRAPHIC

For portability of functions across platforms that are not DB2 UDB for z/OS, do not use the following data types, which might have different representations on different platforms:

  • FLOAT. Use DOUBLE or REAL instead.
  • NUMERIC. Use DECIMAL instead.

Specifying the encoding scheme for parameters

The implicitly or explicitly specified encoding scheme of all the parameters with a string data type (both input and output parameters) must be the same--either all ASCII, all EBCDIC, or all UNICODE.

Determining the uniqueness of functions in a schema

At the current server, the function signature of each function, which is the qualified function name combined with the number and data types of the input parameters, must be unique. This means that two different schemas can each contain a function with the same name that have the same data types for all of their corresponding data types. However, a schema must not contain two functions with the same name that have the same data types for all of their corresponding data types.

When determining whether corresponding data types match, XDB does not consider any length, precision, scale, subtype or encoding scheme attributes in the comparison. XDB considers the synonyms of data types (DECIMAL and NUMERIC, REAL and FLOAT, and DOUBLE and FLOAT) a match. Therefore, CHAR(8) and CHAR(35) are considered to be the same, as are DECIMAL(11,2), DECIMAL(4,3), and NUMERIC(4,2).

Assume that the following statements are executed to create four functions in the same schema. The second and fourth statements fail because they create functions that are duplicates of the functions that the first and third statements created.

    CREATE FUNCTION PART (INT, CHAR(15)) ...
    CREATE FUNCTION PART (INTEGER, CHAR(40)) ...

    CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
    CREATE FUNCTION ANGLE (DEC(10,7)) ...

Rules for creating sourced functions

For the discussion in this section, assume that the function that is being created is named NEWF and the source function is named SOURCEF. Consider the following rules when creating a sourced function:

  • The unqualified names of the sourced function and source function can be different (NEWF and SOURCEF).
  • The number of input parameters for NEWF and SOURCEF must be the same; otherwise, an error occurs when the CREATE FUNCTION statement is executed.
  • When specifying the input parameters and output for NEWF, you can specify a value for the precision, scale, subtype, or encoding scheme for a data type with any of these attributes or use empty parentheses.

    Empty parentheses, such as VARCHAR(), indicate that the value of the attribute is the same as the attribute for the corresponding parameter of SOURCEF, or that is determined by data type promotion. If you specify any values for the attributes, XDB checks the values against the corresponding input parameters and returned output of SOURCEF as described next.

  • When the CREATE FUNCTION statement is executed, XDB checks the input parameters of NEWF against those of SOURCEF. The data type of each input parameter of NEWF function must be either the same as, or promotable to, the data type of the corresponding parameter of SOURCEF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, an argument that matches the data type and length or precision attributes of a NEWF parameter might not be promotable if the corresponding SOURCEF parameter has a shorter length or less precision. In general, do not define the parameters of a sourced function with length or precision attributes that are greater than the attributes of the corresponding parameters of the source function.

  • When the CREATE FUNCTION statement is executed, XDB checks the data type identified in the RETURNS clause of NEWF against the data type that SOURCEF returns. The data type that SOURCEF returns must be either the same as, or promotable to, the RETURNS data type of NEWF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, the value of a result that matches the data type and length or precision attributes of those specified for SOURCEF's result might not be promotable if the RETURNS data type of NEWF has a shorter length or less precision. Consider the possible effects of defining the RETURNS data type of a sourced function with length or precision attributes that are less than the attributes defined for the data type returned by source function.

Scrollable cursors specified with user-defined functions

A row can be fetched more than once with a scrollable cursor. Therefore, if a scrollable cursor is defined with a nondeterministic function in the select list of the cursor, a row can be fetched multiple times with different results for each fetch. Similarly, if a scrollable cursor is defined with a user-defined function with external action, the action is executed with every fetch.

Parent topic: SQL Statements


CREATE GLOBAL TEMPORARY TABLE

Create a temporary table to store the intermediate results of SQL transactions. The CREATE GLOBAL TEMPORARY TABLE statement creates a description of a temporary table at the current server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

Your privilege set must include at least one of the following:

  • The CREATETMTAB system privilege
  • The CREATETAB database privilege for any database
  • DBADM, DBCTRL, or DBMAINT authority for any database
  • SYSADM or SYSCTRL authority

You may require additional authorization if you use the LIKE keyword.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE GLOBAL TEMPORARY TABLE table-name
    (column-spec ,...)
    [LIKE {table-name | view-name}]
    [CCSID {ASCII | EBCDIC}]

column-spec:

column-name data-type
    [FOR {BIT | MIXED | SBCS} DATA]
    [NOT NULL]

Parameters:

table-name | Names the temporary table. The name, including the implicit or explicit qualifier, must not identify a table, view, alias, synonym, or temporary table that exists at the current server. In the LIKE clause, table-name specifies that the columns of the table have the exact same name and description as the columns of the identified table.
view-name | Specifies that the columns of the table have exactly the same name and description as the columns of the identified view.
column-name | Names the column. The name must not be qualified and must not be the same as the name of another column in the table.
data-type | Specifies the data type of the column. The types allowed and the rules followed are the same as those for the CREATE TABLE statement.

FOR {BIT | MIXED | SBCS} DATA

Specifies a subtype for a character string column. The subtypes allowed and the rules followed are the same as those for the CREATE TABLE statement.

data-type

Specifies the data type of the column. The data type can be a built-in data type or a distinct type.

built-in-data-type | Any built-in data type that can be specified for the CREATE TABLE statement with the exception that you cannot define a temporary table with a LOB or ROWID column.
distinct-type | Any distinct type except one that is based on a LOB or ROWID data type. The privilege set must implicitly or explicitly include the USAGE privilege on the distinct type.

NOT NULL

Specifies that the column cannot contain nulls. Omission of NOT NULL indicates that the column can contain nulls.

LIKE {table-name | view-name}

Specifies that the columns of the table have exactly the same name and description as the columns of the identified table or view. The name specified after LIKE must identify a table, view, or temporary table that exists at the current server. The privilege set must implicitly or explicitly include the SELECT privilege on the identified table or view.

This clause is similar to the LIKE clause on CREATE TABLE, but it has the following differences:

  • If any column of the identified table or view has an attribute value that is not allowed for a column in a temporary table, that attribute value is ignored. The corresponding column in the new temporary table has the default value for that attribute unless otherwise indicated.
  • If any column of the identified table or view allows a default value other than null, then that default value is ignored and the corresponding column in the new temporary table has no default value. A default value other than null is not allowed for any column in a temporary table.
Parent topic: SQL Statements


CREATE INDEX

Creates an index on one or more columns of a table at the current location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE INDEX command, users must possess either INDEX privileges on the table, DBADM authority on the database containing the table, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table. If the index name specified is qualified with another AuthID (different from the application AuthID), the user must possess SYSADM or SYSCTRL authority for the location.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE [TYPE 2] [UNIQUE [WHERE NOT NULL]]
INDEX index-name
    ON {table-name (column-name [ASC | DESC] [,...]) | aux-table-name}
    [using-block | free-block | gbpcache-block | DEFINE {YES|NO}] [...]
    [GBPCACHE {CHANGED | ALL}]
    [DUPQTY number-records]
    [[CLUSTER | NOT CLUSTER]
    [PARTIONED]
    [PADDED | NOT PADDED]
    [using-block]
    [free-block]
    [gbpcache-block]
    [DEFINE YES | DEFINE NO] [...]]
    [PARTITION BY [RANGE] (partition-element
    [using-block | free-block | gbpcache-block] [...] [,...])]]
    [SUBPAGES {4 | 1 | 2 | 8 | 16}]
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [DSETPASS password]
    [DEFER {NO | YES}]
    [COPY YES]
    [PIECESIZE integer {K | M | G}]

using-block:

USING
{
VCAT {WITH | ROOT | PATH | NAME}
| STOGROUP stogroup-name
    [PRIQTY {3 | integer}]
    [SECQTY {3 | integer}]
    [ERASE {NO | YES}]
}

free-block:

[FREEPAGE {0 | integer}]
[PCTFREE {10 | integer}]

partition-element:

PARTITION integer
[ENDING [AT] (constant[,...]) [INCLUSIVE]]

Parameters:

index-name | Uniquely identifies the index among the other indexes and keys in the database. Index names must follow the rules for long identifiers.
table-name | Names the table being indexed.
column-name | Name of the column on which the index is created. If more than one column name is listed, a compound index is built on the named columns. A maximum of 64 columns may be included in a compound index.
integer | A whole number value from zero to 99, specifying the percentage of index space to be left free.
number-records | Specifies the amount of space to allocate for each .ptr block to hold duplicate record numbers.
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.

Description

The CREATE INDEX command syntactically checks many mainframe-specific clauses(bold text). You can specify various XDB Server index file storage options with the USING VCAT clause.

Any number of indexes can be created on a table. An index can be created or dropped at any time. Indexes are maintained automatically by the system. While indexes can speed up retrieval, they do require storage space. Therefore, the tradeoff between space and retrieval speed might become an issue in larger databases. Since it takes time to maintain indexes there also exists a tradeoff between retrieval, and update, delete and insert speed.

Indexes can be created on any or all columns of a table. Only the first 190 characters of the combined indexed field values are used in creating a compound index. The actual number of characters permitted depends on the number and type of columns in the index, with single field character indexes using up to the first 254 characters of a value in an index.

TYPE 2

Specifies a type 2 index. The TYPE 2 clause is not required. A type 2 index is always created.

UNIQUE

This optional keyword (when appearing without the WHERE NOT NULL clause) creates a unique index with no duplicate values allowed. While indexes are generally used to speed data retrieval, unique indexes are also used to prevent the entry of duplicate values in a column or compound key (such as, a key made up of several column values).

A table also requires a unique index if there is a ROWID column that is defined as GENERATED BY DEFAULT.

A unique index cannot be created on a materialized query table.

WHERE NOT NULL

When preceded with the UNIQUE keyword, a single-column index key defined with the UNIQUE WHERE NOT NULL clause can contain more than one null value, but all other non-null values must be unique. A good example would be a table of client data containing a column for Internet addresses. An index on NETADDR, defined with UNIQUE WHERE NOT NULL, allows any number of null values for clients with no Internet address, while still ensuring that any Internet addresses added or updated are unique.

In the case of an index key on multiple columns defined with the UNIQUE WHERE NOT NULL clause, any of the key columns in a particular record can be null and still be a valid key value. An index created with the attribute UNIQUE WHERE NOT NULL is recorded in the catalog table SYSIBM.SYSINDEXES with the value 'N' in the UNIQUERULE column.

ON table-name or aux-table-name

Identifies the table on which the index is created. The name can identify a base table, a declared temporary table, or an auxiliary table.

table-name

Identifies the base table or declared temporary table on which the index is created. The name must identify a table that exists at the current server. (The name of a declared temporary table must be qualified with SESSION.) The name must not identify a created temporary table.

(column-name,...) Specifies the columns of the index key.

Each column-name must identify a column of the table. Do not specify more than 64 columns, the same column more than once, or a LOB column (or a column with a distinct type that is based on a LOB data type). Do not qualify column-name.

The sum of the length attributes of the columns must not be greater than the following limits, where n is the number of columns that can contain null values and m is the number of varying-length columns in the key:

  • 2000 - n for a padded, nonpartitioning index
  • 2000 - n - 2m for a nonpadded, nonpartitioning index
  • 255 - n for a partitioning index (padded or nonpadded)

aux-table-name

Identifies the auxiliary table on which the index is created. The name must identify an auxiliary table that exists at the current server. If the auxiliary table already has an index, do not create another one. An auxiliary table can only have one index.

Do not specify any columns for the index key. The key value is implicitly defined as a unique 19-byte value that is system generated.

If qualified, table-name or aux-table-name can be a two-part or three-part name. If a three-part name is used, the first part must match the value of the field DB2 LOCATION NAME of installation panel DSNTIPR at the current server. (If the current server is not the local DB2, this name is not necessarily the name in the CURRENT SERVER special register.) Whether the name is two-part or three-part, the authorization ID that qualifies the name is the owner of the index.

ASC & DESC

These keywords are supported syntactically only. The XDB Server always creates indexes in ascending (ASC) order.

CLUSTER or NOT CLUSTER

Specifies whether the index is the clustering index for the table.

This clause is only implemented syntactically in the XDB Server operating environment.

CLUSTER

The index is to be used as the clustering index of the table. Do not specify CLUSTER for an index on an auxiliary table.

NOT CLUSTER

The index is not to be used as the clustering index of the table.

PARTITIONED

Specifies that the index is data partitioned (that is, partitioned according to the partitioning scheme of the underlying data). A partitioned index can be created only on a partitioned table space. The types of partitioned indexes are partitioning and secondary.

An index is considered a partitioning index if the specified index key columns match or comprise a superset of the columns specified in the partitioning key, are in the same order, and have the same ascending or descending attributes.

If PARTITION BY was not specified when the table was created, the CREATE INDEX statement must have the ENDING AT clause specified to define a partitioning index and use index-controlled partitioning. This index is created as a partitioned index even if the PARTITIONED keyword is not specified. When a partitioning index is created, if both the PARTITIONED and ENDING AT keywords are omitted, the index will be nonpartitioned. If PARTITIONED is specified, the USING block with PRIQTY and SECQTY specifications are optional. If these space parameters are not specified, default values are used.

A secondary index is any index defined on a partitioned table space that does not meet the definition of the partitioning index. For partitioned secondary indexes (data-partitioned secondary indexes), the ENDING AT clause is not allowed because the partitioning scheme of the index is predetermined by that of the underlying data. UNIQUE and UNIQUE WHERE NOT NULL are also not allowed. If a partitioned secondary index is created on a table that uses index-controlled partitioning, the table is converted to use table-controlled partitioning.

This clause is only implemented syntactically in the XDB Server operating environment.

NOT PADDED or PADDED

Specifies how varying-length string columns are to be stored in the index. If the index contains no varying-length columns, this option is ignored, and a warning message is returned. Indexes that do not have varying-length string columns are always created as physically padded indexes.

NOT PADDED

Specifies that varying-length string columns are not to be padded to their maximum length in the index. The length information for a varying-length column is stored with the key.

NOT PADDED is ignored and has no effect if the index is being created on an auxiliary table. Indexes on auxiliary tables are always padded.

PADDED

Specifies that varying-length string columns within the index are always padded with the default pad character to their maximum length.

When the index contains at least one varying-length column, the default for the option depends on the value of field PAD INDEXES BY DEFAULT on installation panel DSNTIPE:

  • When the value of this field is NO, which is the default for sites that newly installed Version 8, new indexes are not padded unless PADDED is specified.
  • When the value of this field is YES, which is the default value for sites that migrated to Version 8, new indexes are padded unless NOT PADDED is specified.

PCTFREE

This option leaves a percentage of the space free in the index block. The default percentage is 20. The range is 0 to 99. Read-only indexes should be created with PCTFREE 0.

Do not specify PCTFREE for an index on a declared temporary table.

DUPQTY

XDB uses B-tree indexes. Each index consists of two files, with the file extensions .IDX and .PTR. The .PTR extension file will be empty if there are no duplicate values in the indexed column. The DUPQTY option specifies the duplicate index block size. XDB Server index-name.PTR files contain Record IDs (RIDs) of duplicate index values. The DUPQTY clause uses the number-records parameter to specify the amount of space to allocate for each .PTR block (to hold record numbers of duplicate index values).

When one .PTR block is full, it links to another block of the same size. The more links that are required, the slower the system performs when accessing duplicate index RIDs. The smaller the DUPQTY value, the smaller the disk space required. The default is 16 records. Specify a value that is closest to the average number of duplicates per index value. For more information on estimating the storage requirements of an index, see the Server Administration Guide.

DEFER

This clause is supported syntactically and currently does NOT affect when the index is created (since it is always created immediately).

PIECESIZE integer

Specifies the maximum addressability of each piece (data set) for a secondary index . The subsequent keyword K, M, or G, indicates the units of the value specified in integer.

K | Indicates that the integer value is to be multiplied by 1 024 to specify the maximum piece size in bytes. The integer must be a power of two between 256 and 67 108 864.
M | Indicates that the integer value is to be multiplied by 1 048 576 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 65 536.
G | Indicates that the integer value is to be multiplied by 1 073 741 824 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 64.

This clause is only implemented syntactically in the XDB Server operating environment.

COPY

Indicates whether the COPY utility is allowed for the index. Do not specify COPY for an index on a declared temporary table.

NO | Does not allows full image or concurrent copies or the use of the RECOVER utility on the index. NO is the default.
YES | Allows full image or concurrent copies and the use of the RECOVER utility on the index.

This clause is only implemented syntactically in the XDB Server operating environment.

PARTITION BY RANGE

Specifies the partitioning index for the table, which determines the partitioning scheme for the data in the table.

This clause is only implemented syntactically in the XDB Server operating environment.

partition-element

Specifies the range for each partition.

PARTITION integer

A PARTITION clause specifies the highest value of the index key in one partition of a partitioning index. In this context, highest means highest in the sorting sequences of the index columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC), the lowest actual value is highest in the sorting sequence.

If you use CLUSTER, and the table is contained in a partitioned table space, you must use exactly one PARTITION clause for each partition (defined with NUMPARTS on CREATE TABLESPACE). If there are p partitions, the value of integer must range from 1 through p.

The length of the highest value of a partition (also called the limit key) is the same as the length of the partitioning index.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant,...)

Specifies that this is the partitioning index and indicates how the data will be partitioned. The table space is marked complete after this partitioning index is created. You must use at least one constant after ENDING AT in each PARTITION clause. You can use as many as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition of the index unless the VALUES statement was already specified when the table or previous index was created.

The use of the constants to define key values is subject to these rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must conform to the rules for assigning that value to the column. A hexadecimal string constant (GX) cannot be specified.
  • If a key includes a ROWID column (or a column with a distinct type that is based on a ROWID data type), only the first 17 bytes of the constant that is specified for the corresponding ROWID column are considered.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'; if the column is descending, the padding character is X'00'.
  • Using fewer constants than there are columns in the key has the same effect as using the highest possible values for all omitted columns.
  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition.
  • The combination of the number of table space partitions and the corresponding limit key size cannot exceed the number of partitions * (106 + limit key size in bytes) <65394.
  • If the key exceeds 255 bytes, only the first 255 bytes are considered.
  • The highest value of the key in the last partition depends on the type of table space. For table spaces that are not large partitioned table spaces, the constants you specify after ENDING AT are not enforced. The highest value of the key that can be placed in the table is the highest possible value of the key.

    For large partitioned table space, the constants you specify are enforced. The value specified for the last partition is the highest value of the key that can be placed in the table. Any key values greater than the value specified for the last partition are out of range.

    When you define a table space with DSSIZE, you automatically give the same size to all indexes that point to that table space.

    ENDING AT can be specified only if the ENDING AT clause was not specified on a previous CREATE or ALTER TABLE statement for the underlying table.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

BUFFERPOOL

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for indexes with 4K page sizes, while the last ten are for indexes with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server system catalog tables.

The default is the default buffer pool for indexes in the database.

USING VCAT

USING VCAT allows you to specify one of the four values below. This XDB Server extension to the VCATNAME specification allows you to specify various storage location options when creating individual indexes.

Do not specify VCAT for an index on a declared temporary table.

WITH | The default value, stores the index files in the same subdirectory as the table file.
ROOT | Stores the index files in the root directory of the current location.
PATH Stores the index files in the path previously specified in the XDB Server index path environment variable.

To use the VCAT PATH option, you must have the XDBIDX_location-name environment variable set, generally in your computer's configuration file. Enter an index path for each location's index files. For example, statements similar to the following might be included in the OS/2 config.sys file:

SET XDBIDX_location1 = e:\xdb\loc1\indexes
SET XDBIDX_location2 = p:\xdb\loc2\indexes
NAME Stores an individual index file on the path specified by the XDB Server_index name_location name environment variable (OS/2 only). Allows the files for individual indexes to be located on separate storage devices.

Take, for example, an index named COIDX that is to be created in the TUTORIAL location. The physical files for the index are to be placed in C:\IDXSTORE. Given this scenario, first set the following environment variable in your CONFIG.SYS file:

SET XDB_COIDX_TUTORIAL=C:\IDXSTORE

Then issue the following command (from SQLWizard, for example):

CREATE INDEX COIDX ON COMPANY(COKEY) USING VCAT NAME;

By allowing storage on a per index basis, the system can more flexibly use multiple physical devices, thereby increasing capacity and performance.

PRIQTY integer

Specifies the minimum primary space allocation for a DB2-managed data set. When you specify PRIQTY (with a value other than -1), the primary space allocation is at least n kilobytes, where n is:

  • 12 if integer is less than 12
  • integer if integer is between 12 and 4194304
  • 4194304 if integer is greater than 4194304

If you do not specify PRIQTY or specify PRIQTY -1, DB2 uses a default value for the primary space allocation.

If you specify PRIQTY and do not specify a value of -1, DB2 specifies the primary space allocation to access method services using the smallest multiple of 4KB not less than n. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the space requested.

When determining a suitable value for PRIQTY, be aware that two of the pages of the primary space are used by DB2 for purposes other than storing index entries.

This clause is only implemented syntactically in the XDB Server operating environment.

SECQTY integer

Specifies the minimum secondary space allocation for a DB2-managed data set. If you do not specify SECQTY, DB2 uses a formula to determine a value.

If you specify SECQTY and do not specify a value of -1, DB2 specifies the secondary space allocation to access method services using the smallest multiple of 4KB not less than n. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the space requested.

This clause is only implemented syntactically in the XDB Server operating environment.

GBPCACHE

In a data sharing environment, specifies what index pages are written to the group buffer pool. In a non-data-sharing environment, the option is ignored unless the index is on a declared temporary table. Do not specify GBPCAHCE for an index on a declared temporary table in either environment (data sharing or non-data-sharing).

CHANGED When there is inter-DB2 R/W interest on the index or partition, updated pages are written to the group buffer pool. When there is no inter-DB2 R/W interest, the group buffer pool is not used. Inter-DB2 R/W interest exists when more than one member in the data sharing group has the index or partition open, and at least one member has it open for update. GBPCACHE CHANGED is the default.

If the index is in a group buffer pool that is defined as GBPCACHE( NO), CHANGED is ignored and no pages are cached to the group buffer pool.

ALL Indicates that pages are to be cached in the group buffer pool as they are read in from DASD.

Exception: In the case of a single updating DB2 when no other DB2s have any interest in the page set, no pages are cached in the group buffer pool.

Hiperpools are not used for indexes or partitions that are defined with GBPCACHE ALL.

If the index is in a group buffer pool that is defined as GBPCACHE(NO), ALL is ignored and no pages are cached to the group buffer pool.

NONE Indicates that no pages are to be cached to the group buffer pool. DB2 uses the group buffer pool only for cross-invalidation.

If the index is partitioning, the value of GBPCACHE for a particular partition is given by the first of these choices that applies:

  1. The value of GBPCACHE given in the PART clause for that partition. Do not use more than one gbpcache-block in any PART clause.
  2. The value given in a gbpcache-block that is not in any PART clause.
  3. The default value is CHANGED.

This clause is only implemented syntactically in the XDB Server operating environment.

Regular Index

The following example creates an index called suppidx on the SNO column of the SUPPLIER table:

CREATE INDEX suppidx
    ON supplier (sno)

This index is used to speed data retrieval.

Unique Index

Unique indexes provide a means of preventing the insertion of duplicate data in a column which should have only one occurrence of a given value (including NULL values). For example, in the table PART, there should be only one part with the number P1. Building a unique index on PNO will prevent the entry of another P1. The command to build this index is:

CREATE UNIQUE INDEX pnoidx
    ON part (pno)

The system also can use unique indexes to speed data retrieval.

Compound Index

A compound index is an index made up of multiple columns. The XDB Server's compound indexes can contain up to 64 columns of a table, with a combined length of up to 190 characters. A compound index can be used to speed up processing of records that are usually ordered according to the field values in the index columns. However, the primary purpose of a unique compound index is to prevent entry of duplicate keys in a table.

A key consists of one or more table columns, the field values of which are used to identify records in a table. If the PARTSUPP table has a unique key containing the PNO and SNO columns, then there should exist one and only one record for each part supplied by a particular supplier. This can be ensured by creating a unique compound index with the command:

CREATE UNIQUE INDEX psidxON partsupp(pno, sno)
Note:

For a primary key constraint to function when running in DB2 mode, you must have created a unique index on the PNO and SNO columns of the PARTSUPP table using a command like:

CREATE UNIQUE INDEX ps_key
    ON partsupp (pno, sno)

The system checks for duplicate keys in the table when an attempt is made to create a unique compound index. If you are unable to create a unique compound index because your table creates duplicate keys, you should execute a query to determine which values have duplicates. To do this, select and group by all compound fields by using a clause such as:

HAVING COUNT(*) > 1

For example, if you want to create a unique compound index on the PNO and SNO columns of the PARTSUPP table, first execute the following command to verify whether there are any duplicate keys:

SELECT pno, sno
    FROM partsupp
    GROUP BY pno, sno
    HAVING COUNT(*) > 1

If this query retrieves any records, they are duplicates, and must be removed before creating the unique compound index.

Clustered Index

A clustered index is an index that physically orders the table data in the same sequence as the index. Only one clustered index is allowed per table. Building a clustered index causes all other indexes on the table to be rebuilt. Therefore, if the table is large (and contains many indexes) be sure to create the clustered index first.

The DUPQTY, CLUSTER and PCTFREE clauses can appear in any order after the CREATE INDEX clause. For example:

CREATE INDEX aidx ON employee(e_no)
    PCTFREE 10 CLUSTER;
CREATE INDEX aidx ON employee(lname)
    CLUSTER PCTFREE 30;
CREATE INDEX aidx ON employee(fname)
    CLUSTER;
CREATE INDEX aidx ON employee(payrate)
    PCTFREE 50 DUPQTY 16;

Examining Index Definitions

Creating or dropping an index causes the system to automatically update system tables for that location. You can query the system catalog tables for table, view, column, and index information. The query results can be formatted into your own reports. See XDB System Tables for descriptions of the system tables.

You can use the Catalog Browser function of SQLWizard to list table, view and index definitions using the format:

If a column is indexed, the name(s) of the index or indexes are listed after the column name, separated by a slash (/). Index type indicators consisting of a letter or a number may appear within parentheses after the index name.

Indicator | Meaning
no letter | Regular index (duplicate values permitted)
p | Primary key
c | Candidate (Unique) key
f | Foreign key
u | Unique index
no number | Single column index
# | Compound index; # is sequence number indicating order of column in a compound index

Next, the data type of the column is listed. The NOT NULL or NOT NULL WITH DEFAULT keywords specifies the null permission of the column. If omitted, nulls are permitted in the column.

Dropping an Index

Partitioning indexes can only be dropped by dropping the associated table space. Nonpartitioning indexes that are not indexes on auxiliary tables can be dropped simply by dropping the indexes. An empty index on an auxiliary table can be explicitly dropped; a populated index can be dropped only by dropping other objects.

Examples

Create a unique index, named DSN8610.XDEPT1, on table DSN8610.DEPT. Index entries are to be in ascending order by the single column DEPTNO. DB2 is to define the data sets for the index, using storage group DSN8G610. Each data set (piece) should hold 1 megabyte of data at most. Use 512 kilobytes as the primary space allocation for each data set and 64 kilobytes as the secondary space allocation. These specifications enable each data set to be extended up to 8 times before a new data set is used--512KB + (8*64KB)= 1024KB.

The data sets can be closed when no one is using the index and do not need to be erased if the index is dropped.

CREATE UNIQUE INDEX DSN8610.XDEPT1
    ON DSN8610.DEPT(DEPTNO ASC)
    USING STOGROUP DSN8G610
        PRIQTY 512
        SECQTY 64
        ERASE NO
    BUFFERPOOL BP1
    CLOSE YES
    PIECESIZE 1 M;

For the above example, the underlying data sets for the index will be created immediately, which is the default (DEFINE YES). Assuming that table DSN8610.DEPT is empty, if you wanted to defer the creation of the data sets until data is first inserted into the index, you would specify DEFINE NO instead of accepting the default behavior.

Create a cluster index, named XEMP2, on table EMP in database DSN8610. Put the entries in ascending order by column EMPNO. Let DB2 define the data sets for each partition using storage group DSN8G610. Make the primary space allocation be 36 kilobytes, and allow DB2 to use the default value for SECQTY, which for this example is 12 kilobytes (3 times 4KB). If the index is dropped, the data sets need not be erased.

There are to be 4 partitions, with index entries divided among them as follows:

Partition 1 | entries up to H99
Partition 2 | entries above H99 up to P99
Partition 3 | entries above P99 up to Z99
Partition 4 | entries above Z99

Associate the index with buffer pool BP1 and allow the data sets to be closed when no one is using the index. Enable the use of the COPY utility for full image or concurrent copies and the RECOVER utility.

CREATE INDEX DSN8610.XEMP2
    ON DSN8610.EMP(EMPNO ASC)
    USING STOGROUP DSN8G610
        PRIQTY 36
        ERASE NO
    CLUSTER(
        PART 1 VALUES('H99'),
        PART 2 VALUES('P99'),
        PART 3 VALUES('Z99'),
        PART 4 VALUES('999'))
    BUFFERPOOL BP1
    CLOSE YES
    COPY YES;

Create a nonpartitioning index, named DSN8610.XDEPT1, on table DSN8610.DEPT. Put the entries in ascending order by column DEPTNO. Assume that the data sets are managed by the user with catalog name DSNCAT and each data set (piece) is to hold 1 gigabyte of data at most before the next data set is used.

CREATE UNIQUE INDEX DSN8610.XDEPT1
    ON DSN8610.DEPT(DEPTNO ASC)
    USING VCAT DSNCAT
    PIECESIZE 1048576 K;

Assume that a column named EMP_PHOTO with a data type of BLOB(110K) was added to the sample employee table for each employee's photo and auxiliary table EMP_PHOTO_ATAB was created in LOB table space DSN8D61A.PHOTOLTS to store the BLOB data for the column. Create an index named XPHOTO on the auxiliary table. The data sets are to be user-managed with catalog name DSNCAT.

CREATE UNIQUE INDEX DSN8610.XPHOTO
    ON DSN8610.EMP_PHOTO_ATAB
    USING VCAT DSNCAT
    COPY YES;

In this example, no columns are specified for the key because auxiliary indexes have implicitly generated keys.

Parent topic: SQL Statements
Related information
Syntax Support Only
System Table Overview


CREATE LOCATION

The CREATE LOCATION command allows you to define multiple XDB Server locations under the same XDB Server. Each XDB Server location contains a set of catalog tables for that location.

Invocation

CREATE LOCATION is an executable command that can be issued interactively, embedded in a host language or dynamically prepared.

Authorization

Users must possess the INSTALL authority (or be a super user) to create or drop XDB Server locations.

Syntax

CREATE LOCATION <location-name> IN <location-path>
        SORT SEQUENCE {<language-name> EBCDIC | EBCDIC | INSENSITIVE | SENSITIVE | USER}]
    [XDB SYSTEM TABLES]
    [VERSION V23 | V31 | V41 | V51 | V60| V71| V80]

Parameters:

location-name | Specifies a 1 to 16 character name for a new user-created location. This name must be unique among all location names created under this XDB Server.
location-path | Preceded by the keyword IN, specifies a path for storing the new location files. This path is usually a subdirectory under the XDB Server directory, but can be any user-specified path.

Description

When the CREATE LOCATION command is issued, the XDB Server creates a directory structure for the new location and adds information about the new location to the SYSXDB.SYSLOCALS, and SYSIBM.SYSLOCATIONS catalog tables in the SYSTEM location.

A unique name must be specified for each location (following the rules for long identifiers), along with a directory path for the location's files and database subdirectories. The first eight characters of the location-name parameter also serve as the file name for a set of dictionary files, which are automatically created by the XDB Server for each new location, and stored in the location's root directory (location-path parameter).

location-name.DDT | Contains information about the tables associated with a location.
location-name.DDF | Contains information about the table columns associated with a location.
location-name.DDI | Contains information about the indexes associated with a location.
location-name.DDV | Contains information on the XDB Server version used to create the location.

These location dictionary files are automatically maintained and updated by the XDB Server and cannot be accessed by users.

SORT SEQUENCE

This clause allows you to choose between a case SENSITIVE, case INSENSITIVE, EBCDIC, or USER defined sort sequence for the new location. The XDB Server default is case INSENSITIVE.

FORWARD LOG

If Forward Log archiving for the location is desired, you can assign both a Forward Log name and optional path designation. If no Forward Log name is specified, the XDB Server creates a default log name by taking the first eight characters of the location name and appending a .FWD file extension. Forward Log files should ideally be stored on separate disk drives, allowing for extra insurance in the event of a location drive failure. Forward Log options are stored in the SYSXDB.SYSLOCALS catalog table in the SYSTEM location.

VERSION

Since system catalog tables differ with each XDB Server version, locations created with an older version XDB Server are not compatible with a newer version XDB Server. This optional clause creates an XDB Server location compatible with DB2 3.1, 4.1, 5.1, 6.0, 7.1 or 8.0 by using a value of V31, V41, V51, V60, V71 or V80 within the VERSION clause. V23, V31, V41, V51, V60, V71 and V80 are the only valid options for the VERSION clause.

Example:

The following command creates a location subdirectory named locat1 under the XDB Server directory (C:\XDB60):

CREATE LOCATION jbl IN d:\qa\jbl sort sequence german ebcdic;
Parent topic: SQL Statements


CREATE PROCEDURE

The CREATE PROCEDURE command defines a Stored Procedure to the SQL engine. You can then embed an SQL CALL statement in a program to invoke the stored procedure.

Invocation

CREATE PROCEDURE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the CREATE PROCEDURE command, users must possess one (or more) privileges listed in the SYSADM or SYSCTRL authority.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE PROCEDURE procedure-name
    [(parameter-declaration [,...])]
    option-list

parameter-declaration

[IN | OUT | INOUT] [parameter-name] parameter-type

parameter-type

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} AS LOCATOR}

data-type

{built-in-type | distinct-type-name}

built-in-type

{SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [(5,0) | (integer [,integer])] |
{FLOAT [(1) | (integer)] | REAL [PRECISION] | DOUBLE} |
{{{CHARACTER | CHAR} [(1) | (integer)] | {{CHARACTER | CHAR} VARYING | VARCHAR} (integer)}
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {ASCII | EBCDIC | UNICODE}] |
 {{CHARACTER |CHAR} LARGE OBJECT | CLOB} [(1M) | (integer [K | M | G])] [FOR {SBCS | MIXED} DATA]
    [CCSID {ASCII | EBCDIC | UNICODE}] } |
{{GRAPHIC [(1) | (integer)] | VARGRAPHIC (integer) | DBCLOB [(1M) | (integer [K | M | G])]}
    [CCSID {ASCII | EBCDIC | UNICODE}]} |
{{BINARY LARGE OBJECT | BLOB} [(1M) | (integer [K | M | G])]} |
{DATE | TIME | TIMESTAMP} |
ROWID}

option-list

[DYNAMIC RESULT SETS 0 | DYNAMIC RESULT SETS integer]
[PARAMETER CCSID {ASCII | EBCDIC | UNICODE}]
[EXTERNAL [NAME {'string' | identifier}]]
[LANGUAGE {ASSEMBLE | C | COBOL | JAVA | PLI | REXX}]
[MODIFIES SQL DATA | READS SQL DATA | CONTAINS SQL | NO SQL]
[PARAMETER STYLE {SQL | GENERAL | GENERAL WITH NULLS | JAVA}]
[DETERMINISTIC | NOT DETERMINISTIC]
[FENCED]
[DBINFO | NO DBINFO]
[COLLID collection-id | NO COLLID]
[WLM ENVIRONMENT {name | (name,*)}]
[ASUTIME NO LIMIT | ASUTIME LIMIT integer]
[STAY RESIDENT YES | STAY RESIDENT NO]
[PROGRAM TYPE {SUB | MAIN}]
[SECURITY {DB2 | USER | DEFINER}]
[STOP AFTER SYSTEM DEFAULT FAILURES | STOP AFTER integer FAILURES | CONTINUE AFTER FAILURE]
[RUN OPTIONS run-time-options]
[COMMIT ON RETURN YES | COMMIT ON RETURN NO]
[INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
[CALLED ON NULL INPUT]

Parameters:

Procedure-name | If unqualified, the procedure name is any long identifier that uniquely names the procedure. A qualified procedure name is schema name (short identifier), a period, and then a long identifier. If unqualified, the schema name is the SQL authorization ID in the CURRENT SQLID special register.The schema name can be 'SYSIBM' or 'SYSPROC'. It can also be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.
Load-module-name | Load module name is a short identifier naming the procedure executable module. The load module name specifies the name of a DLL file.

Comments:

If no length is specified for CHAR, VARCHAR, GRAPHIC, or VARGRAPHIC, the default length is 1. If precision is not specified for DECIMAL, the default is DECIMAL (5,0).

Parameter-name:

A parameter name is a long identifier naming the parameter.

RESULT SETS clause:

Specifies the maximum number of result sets that the stored procedure can return to the invoking program. The default is RESULT SETS 0, indicating there are no result sets being returned.

PARAMETER STYLE clause:

Identifies the convention used to pass arguments to the stored procedure. When using GENERAL, none of the arguments can be null. GENERAL WITH NULLS passes an additional argument after the arguments on the CALL PROCEDURE statement. The additional argument is an array of null indicators, one for each of the defined arguments for the stored procedure.

PROGRAM TYPE clause:

For stored procedures defined as LANGUAGE COBOL or PLI, there is no difference between MAIN or SUB.

COMMIT ON RETURN clause:

This default for this clause is NO. If COMMIT ON RETURN YES is specified, the SQL engine will issue a commit when the stored procedure returns if the transaction is not in a must rollback state. If the stored procedure uses the WITH RETURN clause to define cursors that will be returned as result sets, the cursors must also be defined as WITH HOLD if COMMIT ON RETURN YES is specified or the cursors will be closed by the SQL engine.

Parent topic: SQL Statements


CREATE PROCEDURE

The CREATE PROCEDURE statement defines an SQL procedure at the current server and specifies the source statements for the procedure.

The XDB Server operating environment only provides syntax support for external Procedures (SQL) at this time.

Invocation

This statement can only be dynamically prepared, but the DYNAMICRULES run behavior must be specified implicitly or explicitly. It is intended to be processed using one of the following methods:

  • JCL
  • The DB2 UDB for z/OS SQL procedure processor (DSNTPSMP)

Issuing the CREATE PROCEDURE statement from another context will result in an incomplete procedure definition even though the statement processing returns without error.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATEIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

The privilege set is the privileges that are held by the SQL authorization ID of the process.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process. The specified procedure name can include a schema name (a qualifier). However, if the schema name is not the same as the SQL authorization ID, one of the following conditions must be met:

  • The privilege set includes SYSADM or SYSCTRL authority.
  • The SQL authorization ID of the process has the CREATEIN privilege on the schema.

The authorization ID that is used to create the stored procedure must have authority to create programs that are to be run either in the DB2-established stored procedure address space or the specified workload manager (WLM) environment.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE PROCEDURE procedure-name
    [(parameter-declaration [,...])] LANGUAGE SQL
    option-list SQL-routine-body

parameter-declaration

[IN | OUT | INOUT] parameter-name parameter-type

parameter-type

{built-in-type | TABLE LIKE table-name AS LOCATOR}

built-in-type

[SMALLINT]
[INTEGER | INT]
[DECIMAL | DEC | NUMERIC} [(5,0) | (integer [,integer])]
[FLOAT [(53) | (integer)] | REAL [PRECISION] | DOUBLE}]
[{{CHARACTER | CHAR} [(1) | (integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] |
    {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(1M) | (integer [K | M | G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] }]
[{GRAPHIC [(1) | (integer)] | VARGRAPHIC (integer) | DBCLOB [(1M) | (integer [K | M | G])]}
    [CCSID {ASCII | EBCDIC | UNICODE}]]
[{BINARY LARGE OBJECT | BLOB} [(1M) | (integer [K | M | G])]]
[DATE | TIME | TIMESTAMP]
[ROWID]

option-list

[DYNAMIC RESULT SETS 0 | DYNAMIC RESULT SETS integer]
[PARAMETER CCSID {ASCII | EBCDIC | UNICODE}]
[EXTERNAL [NAME {'string' | identifier}]]
[MODIFIES SQL DATA | READS SQL DATA | CONTAINS SQL]
[DETERMINISTIC | NOT DETERMINISTIC]
[FENCED]
[NO DBINFO]
[COLLID collection-id | NO COLLID]
[WLM ENVIRONMENT {name | (name,*)}]
[ASUTIME NO LIMIT | ASUTIME LIMIT integer]
[STAY RESIDENT YES | STAY RESIDENT NO]
[PROGRAM TYPE {SUB | MAIN}]
[SECURITY {DB2 | USER | DEFINER}]
[STOP AFTER SYSTEM DEFAULT FAILURES | STOP AFTER integer FAILURES | CONTINUE AFTER FAILURE]
[RUN OPTIONS run-time-options]
[COMMIT ON RETURN YES | COMMIT ON RETURN NO]
[INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
[CALLED ON NULL INPUT]
Parent topic: SQL Statements


CREATE SEQUENCE

The CREATE SEQUENCE statement creates a sequence at the application server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATEIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process.

If the data type of the sequence is a distinct type, the privilege set must include the USAGE privilege on the distinct type.

Syntax

CREATE SEQUENCE sequence-name [AS {INTEGER | data-type} |
     START WITH numeric-constant |
     {INCREMENT BY 1 | INCREMENT BY numeric-constant} |
     {MINVALUE numeric-constant | NO MINVALUE} |
     {MAXVALUE numeric-constant | NO MAXVALUE} |
     {CYCLE | NO CYCLE} |
     {CACHE 20 | CACHE integer-constant | NO CACHE} |
     {ORDER | NO ORDER}
     ] [,...]
Note: The same clause must not be specified more than once. Separator commas may or may not be specified between sequence attributes when a sequence is defined.

Description

SEQUENCE sequence-name

Names the sequence. The combination of name and the implicit or explicit name must not identify an existing sequence at the current server, including the internal names generated by DB2 for identity names.

The unqualified form of sequence-name is an SQL identifier. The unqualified name is implicitly qualified with a schema name according to the following rules:

  • If the CREATE SEQUENCE statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the CREATE SEQUENCE statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The contents of the SQL PATH are not used to determine the implicit qualifier of a sequence name.

The qualified form of sequence-name is a schema followed by a period and an SQL identifier. The schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the sequence is determined by the following conditions. If the CREATE SEQUENCE statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package. If the CREATE SEQUENCE statement is dynamically prepared, the owner is the SQL authorization ID contained in the CURRENT SQLID special register. The owner has the ALTER and USAGE privileges on the new sequence with the GRANT option. These privileges can be granted by the owner and cannot be revoked from the owner.

AS data-type

Specifies the data type to be used for the sequence value. The data type can be any exact numeric data type (SMALLINT, INTEGER, or DECIMAL with a scale of zero), or a user-defined distinct type for which the source type is an exact numeric data type with a scale of zero. The default is INTEGER.

START WITH numeric-constant

Specifies the first value for the sequence. The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point.

If the START WITH key word is not explicitly specified with a value, the default is the MINVALUE for ascending sequences and MAXVALUE for descending sequences.

This value is not necessarily the value that a sequence would cycle to after reaching the maximum or minimum value of the sequence. The START WITH clause can be used to start a sequence outside the range that is used for cycles. The range used for cycles is defined by MINVALUE and MAXVALUE.

INCREMENT BY numeric-constant

Specifies the interval between consecutive values of the sequence. The value can be any positive or negative value (including 0) that could be assigned to a column of the data type that is associated with the sequence without any non-zero digits existing to the right of the decimal point. The default is 1.

If INCREMENT BY is positive, the sequence ascends. If INCREMENT BY is negative, the sequence descends. If INCREMENT is 0, the sequence is treated as an ascending sequence.

The absolute value of INCREMENT BY can be greater than the difference between MAXVALUE and MINVALUE.

MINVALUE or NO MINVALUE

Specifies the minimum value at which a descending sequence either cycles or stops generating values or an ascending sequence cycles to after reaching the maximum value. The default is NO MINVALUE.

MINVALUE numeric-constant

Specifies the minimum end of the range of values for the sequence. The last value that is generated for a cycle of a descending sequence will be equal to or greater than this value. MINVALUE is the value to which an ascending sequence cycles to after reaching the maximum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

NO MINVALUE

Specifies that the minimum end point of the range of values for the sequence has not been specified explicitly. In such a case, the default value for MINVALUE becomes one of the following:

  • For an ascending sequence, the value is the START WITH value or 1 if START WITH is not specified.
  • For a descending sequence, the value is the minimum value of the data type that is associated with the sequence.

MAXVALUE or NO MAXVALUE

Specifies the minimum value at which an ascending sequence either cycles or stops generating values or an descending sequence cycles to after reaching the minimum value. The default is NO MAXVALUE.

MAXVALUE numeric-constant

Specifies the maximum end of the range of values for the sequence. The last value that is generated for a cycle of an ascending sequence will be less than or equal to this value. MAXVALUE is the value to which a descending sequence cycles to after reaching the minimum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

NO MAXVALUE

Specifies the maximum end point of the range of values for the sequence has not been specified explicitly. In such a case, the default value for MAXVALUE becomes one of the following:

  • For an ascending sequence, the value is the maximum value of the data type that is associated with the sequence.
  • For a descending sequence, the value is the START WITH value or -1 if START WITH is not specified.

CYCLE or NO CYCLE

Specifies whether or not the sequence should continue to generate values after reaching either its maximum or minimum value. The boundary of the sequence can be reached either with the next value landing exactly on the boundary condition or by overshooting it. The default is NO CYCLE.

CYCLE

Specifies that the sequence continue to generate values after either the maximum or minimum value has been reached. If this option is used, after an ascending sequence reaches its maximum value, it generates its minimum value. After a descending sequence reaches its minimum value, it generates its maximum value. The maximum and minimum values for the sequence defined by the MINVALUE and MAXVALUE options determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by the sequence. When a sequence is defined with CYCLE, any application conversion tools for converting applications from other vendor platforms to DB2 should also explicitly specify MINVALUE, MAXVALUE, and START WITH values.

NO CYCLE

Specifies that the sequence cannot generate more values once the maximum or minimum value for the sequence has been reached. The NO CYCLE option (the default) can be altered to CYCLE at any time during the life of the sequence.

When the next value is being generated for a sequence if the maximum value (for an ascending sequence) or the minimum value (for a descending sequence) of the logical range of the sequence is exceeded and the NO CYCLE option is in effect, an error occurs.

CACHE or NO CACHE

Specifies whether or not to keep some preallocated values in memory for faster access. This is a performance and tuning option.

CACHE integer-constant

Specifies the maximum number of values of the sequence that XDB can preallocate and keep in memory. Preallocating values in the cache reduces synchronous I/O when values are generated for the sequence. The actual number of values that XDB caches is always the lesser of the number in effect for the CACHE option and the number of remaining values within the logical range. Thus, the CACHE value is essentially an upper limit for the size of the cache.

In the event of a system failure, all cached sequence values that have not been used in committed statements are lost (that is, they will never be used). The value specified for the CACHE option is the maximum number of sequence values that could be lost in case of system failure.

The minimum value is 2. The default is CACHE 20.

In a data sharing environment, you can use the CACHE and NO ORDER options to allow multiple XDB members to cache sequence values simultaneously.

NO CACHE

Specifies that values of the sequence are not to be preallocated. This option ensures that there is not a loss of values in the case of a system failure. When NO CACHE is specified, the values of the sequence are not stored in the cache. In this case, every request for a new value for the sequence results in synchronous I/O.

ORDER or NO ORDER

Specifies whether the sequence numbers must be generated in order of request. The default is NO ORDER.

ORDER

Specifies that the sequence numbers are generated in order of request. Specifying ORDER may disable the caching of values. There is no guarantee that values are assigned in order across the entire server unless NO CACHE is also specified. ORDER applies only to a single-application process.

NO ORDER

Specifies that the sequence numbers do not need to be generated in order of request.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for next value assignments from different members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the same sequence, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested for next value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that sequence numbers are generated in strict numeric order among multiple members using the same sequence concurrently, specify the ORDER option.

Note:
  • MINVALUE must not be greater than MAXVALUE. Although MINVALUE is typically less than MAXVALUE, MINVALUE can equal MAXVALUE. If START WITH were the same value as MINVALUE and MAXVALUE, the sequence would be constant. The request for the next value in a constant sequence appears to have no effect because all of the values that are generated by the sequence are in fact the same value.
  • When you define a sequence, you can choose to have it cycle automatically or not when the maximum or minimum value for the sequence has been reached.
    • Implicitly or explicitly defining a sequence with NO CYCLE causes the sequence to not cycle automatically after the boundary is reached. However, you can use the ALTER SEQUENCE statement to cycle the sequence manually. ALTER SEQUENCE allows you to restart or extend the sequence, which causes sequence values to continue to be generated.
    • Explicitly defining a sequence with CYCLE causes the sequence to cycle automatically after the boundary is reached. Sequence values continue to be generated after the sequence cycles.

      When a sequence is defined to cycle automatically, the maximum or minimum value that is generated for a sequence may not be the actual MAXVALUE or MINVALUE value that is specified if the increment is a value other than 1 or -1. For example, the sequence defined with START WITH=1, INCREMENT=2, MAXVALUE=10 will generate a maximum value of 9, and will not generate the value 10.

      When a sequence is defined with CYCLE, any application conversion tools (for converting applications from other vendor platforms to DB2) should also explicitly specify MINVALUE, MAXVALUE, and START WITH.

  • You can define a sequence such that it always returns the same (or a constant) value. To create a constant sequence, use either of these techniques when defining the sequence:
    • Specify an INCREMENT value of zero and a START WITH value that does not exceed MAXVALUE.
    • Specify the same value for START WITH, MINVALUE, and MAXVALUE, and specify CYCLE. A constant sequence can be used as a numeric global variable. You can use ALTER SEQUENCE to adjust the values that are generated for a constant sequence.
  • After XDB generates a value for a sequence, that value can be said to be "consumed" regardless of whether or not that value is utilized by the application or not. The value is not reused within the current cycle. A consumed value may not be utilized when the statement that caused the value to be generated fails for some reason or is rolled back after the value was generated. Generated but unused values may constitute gaps in a sequence.
  • Consecutive values in a sequence differ by the constant INCREMENT BY value specified for the sequence. However, gaps can be introduced in a sequence in situations like the following ones:
    • A transaction has advanced the sequence and then rolls back.
    • The SQL statement leading to the generation of the next value fails after the value was generated.
    • The NEXT VALUE expression is used in the SELECT statement of a cursor in a DRDA environment where the client uses block-fetch and not all retrieved rows are fetched by the application.
    • The sequence is altered and then the alteration is rolled back.
    • The sequence is dropped and then the dropping is rolled back.

      Values of such gaps are not available for the current cycle, unless the sequence is altered and restarted in a specific way to make them available.

      A sequence is incremented independently of a transaction. Thus, a given transaction increments the sequence two times may see a gap in the two numbers that it receives if other transactions concurrently increment the same sequence. Most applications can tolerate these instances as these are not really gaps.

  • It is possible the duplicate values can be generated for a sequence. Duplicate values are most likely to occur when a sequence is defined with the CYCLE option, is defined as a constant sequence, or is altered. For example, the following situations could cause duplicate sequence values:
    • A sequence is defined with the attributes START WITH=2, INCREMENT BY 2, MINVALUE=2, MAXVALUE=10, and CYCLE.
    • The ALTER SEQUENCE statement is used to restart the sequence with a value that has already been generated.
    • The ALTER SEQUENCE statement is used to reverse the ascending direction of a sequence by changing the INCREMENT BY value from a positive to a negative.
  • A sequence can be referenced using a sequence reference. A sequence reference can appear in most places that an expression can appear. A sequence reference can specify whether the value to be returned is a newly generated value or the previously generated value. A NEXT VALUE sequence expression is used to generate a new value. A PREVIOUS VALUE sequence expression is used to obtain the last assigned value of a sequence.
  • To provide compatibility with previous releases, XDB supports the following keywords:
    • NOMINVALUE (single key word) as a synonym for NO MINVALUE
    • NOMAXVALUE (single key word) as a synonym for NO MAXVALUE
    • NOCYCLE (single key word) as a synonym for NO CYCLE
    • NOCACHE (single key word) as a synonym for NO CACHE
    • NOORDER (single key word) as a synonym for NO ORDER
Parent topic: SQL Statements


CREATE STOGROUP

The CREATE STOGROUP command creates an XDB Server stogroup which associates a user-specified directory path with the named stogroup. Once the SYSIBM.SYSVOLUMES catalog table has been updated to reflect this path assignment, newly created objects can be physically stored in this directory path by designating the named stogroup when creating the objects.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The XDB Server checks to verify whether the AuthID issuing this command has either the CREATESG privilege, or SYSADM or SYSCTRL authority for the location.

Syntax

CREATE STOGROUP stogroup-name
    VOLUMES (volume-id[,...])
    VCAT catalog-name [PASSWORD password]

Parameters:

stogroup-name | Identifies the stogroup. This 1 to 8 characters name must be unique among stogroup names created at the currently set location.
volume-id | Identifies one or more Volume IDs, any of which can be associated (by updating the SYSIBM.SYSVOLUMES table) with a path designated specifically for the named stogroup.
catalog-name | Identifies an Integrated Catalog Facility catalog existing on a DB2-mainframe system.
password | Furnishes a VSAM control or master level password for the ICF catalog on a DB2-mainframe system.

Description

The stogroup feature allows XDB Server users greater control in assigning objects to specific directory paths. For example, you can assign storage of individual data objects to specially created stogroup directories (such as E:\STOR1\ or D:\STOR2\).

VOLUMES

This clause assigns a series of volume-id values (limit of 133) to the named stogroup. The XDB Server stores these values in the VOLID column of the SYSIBM.SYSVOLUMES catalog table. Whenever the stogroup is specified in an object creation command, the XDB Server uses these volume-id values to physically store the new objects on the path recorded in SYSIBM.SYSVOLUMES for the named stogroup. Users must first manually update the XDBPRIMEVOLPATH and XDBVOLPATH columns in SYSIBM.SYSVOLUMES. These columns associate a physical path with the value recorded in the VOLID column.

Asterisks are recognized only by Storage Management Subsystem (SMS). Contact your site's storage administrator to determine if the SMS Guaranteed Space attribute applies. If SMS Guaranteed Space does not apply for SMS-managed data sets, it is recommended that the VOLUMES clause be specified with one asterisk, VOLUMES('*' ). If SMS Guaranteed Space does apply, contact your site storage manager and refer to DFSMS/MVS: Access Method Services for the Integrated Catalog and DFSMS/MVS: Storage Administration Reference for DFSMSdfp for information on how to specify the VOLUMES clause.

Note:

There is no specific limit on the number of volumes that can be defined for a storage group. However, the maximum number of volumes that can be managed for a storage group is 133. Thus, there is no point in creating a storage group with more than 133 volumes.

VCAT

Although this clause has no physical functionality within the XDB Server system architecture, the keyword VCAT and a catalog-name value of "xdb" must be specified when working in DB2 mode. This information is recorded in the catalog tables for the current XDB Server location. The password parameter is also mainframe-specific, and is recorded in the XDB Server catalog tables.

Example:

The following command (executed in DB2 mode) creates a stogroup named STOR1 and assigns a volume-id value of "myid" to the VOLID column of the SYSIBM.SYSVOLUMES catalog table:

CREATE STOGROUP stor1 VOLUMES (myid) VCAT xdb;

The next example updates the SYSIBM.SYSVOLUMES catalog table by associating a user-created path (D:\STOR1) with myid:

UPDATE SYSIBM.SYSVOLUMES
    SET xdbprimevolpath = "y"
    , xdbvolpath = "d:\stor1\"
WHERE volid = "myid";
Parent topic: SQL Statements


CREATE SYNONYM

The CREATE SYNONYM command is used to define alternate names for tables or views within the currently set location.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

No special authorization is required. However, you must possess the appropriate privileges on the object to which the synonym refers before you can use the synonym. If dynamically prepared, the synonym is owned by the CURRENT SQLID.

In the case of users with SYSADM authority, ownership can be assigned to other users by first changing the CURRENT SQLID special register value, and then issuing the CREATE SYNONYM statement. The originally recorded AuthID for a synonym is the only AuthID for which the synonym is defined, and the only AuthID that can drop the synonym.

Syntax

CREATE SYNONYM synonym
FOR authorization-name.{table-name | view-name}

Parameters:

synonym | Specifies the alternate name you want to define. The synonym may be up to 18 characters long, and must meet all other criteria for a table or view name. The synonym must be unique among the set of all table names, view names and synonyms in the current location.
authorization-name.{table-name or view-name} | Identifies an existing table or view (with associated AuthID) to which you intend to assign a synonym. The name must consist of two parts and must identify a table, view, or alias that exists at the current server. If a table is identified, it must not be an auxiliary table or a declared temporary table. If an alias is identified, it must be an alias for a table or view at the current server and the synonym is defined for that table or view.

Description

Synonyms can be used to assign alternate names to existing tables or views at the current location. Synonyms may be used interchangeably with their corresponding view or table names in SQL commands. If using a synonym name when granting or revoking privileges or creating indexes, the actual table or view name is substituted for the synonym name before the command is executed.

If a CREATE SYNONYM command denotes an alias name instead of an actual table or view, that table or view (not the named alias) is recorded in the system catalog as the object of the synonym. In these cases the connection between the synonym and alias is severed. If the original alias name is later dropped and redefined, the synonym naming the original table or view is still in effect.

Example:

The example below assigns the alternate name syscolumns for the system table SYSIBM.SYSCOLUMNS:

CREATE SYNONYM syscolumns FOR SYSIBM.SYSCOLUMNS

Once this synonym is created, the query:

SELECT * FROM syscolumns

returns the same result as:

SELECT * FROM SYSIBM.SYSCOLUMNS
Parent topic: SQL Statements


CREATE TABLE

The CREATE TABLE statement defines a table. The definition must include its name and the names and attributes of its columns. The definition can include other attributes of the table, such as its primary key and its table space.

CREATE TABLE clauses have been extended to include options for defining and dropping table check constraints, and specifying columns with user-defined defaults.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE TABLE command, users must possess one (or more) privileges listed in at least one of the following:

  • DBADM, DBCTRL, DBMAINT or CREATETS authority for the database.
  • Overall SYSADM or SYSCTRL authority for the location.
  • CREATETAB privilege for the database that is implicitly or explicitly specified by the IN clause.

Additional privileges might be required in the following conditions:

  • The clause IN, LIKE or FOREIGN KEY is specified.
  • The data type of a column is a distinct type.
  • The table space is implicitly created.
  • A fullselect is specified.
  • A column is defined as a security label column.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package.

  • If the privilege set lacks SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table must be the same as the authorization ID of the owner of the plan or package.
  • If the privilege set includes SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table can be any authorization ID.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process.

  • If the privilege set lacks SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table must be the same as one of the authorization IDs of the process and the privilege set that is held by that authorization ID includes all privileges needed to create the table.
  • If the privilege set includes SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table can be any authorization ID.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE TABLE table-name
{
    (column-definition
        [unique-constraint]
        [referential-constraint]
        [select-command]
        [check-constraint] [,...])
     | LIKE {table-name | view-name} [INCLUDING IDENTITY [COLUMN ATTRIBUTES]]
     | materialized-query-definition
}
    [WITH RESTRICT ON DROP]
    [{IN [database-name.]tablespace-name
        | IN DATABASE database-name}]
    [partitioning-clause]
    [EDITPROC program-name]
    [VALIDPROC program-name]
    [AUDIT {NONE | CHANGES | ALL}]
    [OBID integer]
    [DATA CAPTURE {NONE | CHANGES}]
    [WITH RESTRICT ON DROP]
    [CCSID {ASCII | EBCDIC | UNICODE}]
     [{VOLATILE | NOT VOLATILE} [CARDINALITY]]

unique-constraint:

{UNIQUE | PRIMARY KEY}(column-name[,...])

referential-constraint:

FOREIGN KEY [constraint-name] (column-name[,...])
    references-clause

references-clause:

REFERENCES referenced-table
    [column-name ,...]
    [ON DELETE {RESTRICT | NO ACTION | CASCADE | SET NULL}]
    [ENFORCED | NOT ENFORCED]
    [ENABLE QUERY OPTIMIZATION]

check-constraint:

[CONSTRAINT constraint-name] CHECK (check-condition)

column-definition:

column-name data-type
    [NOT NULL]
    [column-constraint]
    [{UNIQUE | PRIMARY KEY}]
    [FOR {BIT | SBCS | MIXED} DATA]
    [default-clause]
    [GENERATED {ALWAYS | BY DEFAULT} [as-identity-clause]
    [references-clause]
    [check-constraint]
    [FIELDPROC program-name [(constant[,...])]]
    [AS SECURITY LABEL]

default-clause:

[WITH] DEFAULT
[{constant | USER | CURRENT SQLID | NULL | cast-function-name ({constant | USER | CURRENT SQLID | NULL})}]

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

as-identity-clause:

AS IDENTITY
[({START WITH {numeric-constant | 1}
| INCREMENT BY {numeric-constant | 1}
| MINVALUE numeric-constant | NOMINVALUE
| MAXVALUE numeric-constant | NOMAXVALUE
| CYCLE | NOCYCLE
| ORDER | NO ORDER
| {CACHE 20 | NO CACHE | CACHE integer}}][,..])]

partitioning-clause:

PARTITION BY [RANGE] (partition-expression[,...]) (partition-element[,...])

partition-expresion:

column-name [NULLS LAST] [ASC | DESC]

partition-element:

PARTITION integer ENDING [AT] (constant[,...]) [INCLUSIVE]

materialized-query-definition:

[(column-name[,...])] AS (fullselect)
{WITH NO DATA [copy-options] | refreshable-table-options}

copy-options:

[EXCLUDING IDENTITY [COLUMN ATTRIBUTES] |
INCLUDING IDENTITY [COLUMN ATTRIBUTES]]
[EXCLUDING [COLUMN] DEFAULTS | INCLUDING [COLUMN] DEFAULTS | USING TYPE DEFAULTS]

refreshable-table-options:

DATA INITIALLY DEFERRED REFRESH DEFERRED
[[MAINTAINED BY SYSTEM | MAINTAINED BY USER]
[ENABLE QUERY OPTIMIZATION | DISABLE QUERY OPTIMIZATION] ...]

Parameters:

table-name
Any long identifier naming the table. The name must uniquely identify the table, and must not match any other table, view, alias, or synonym name existing within the current location. If qualified, the table name consists of a two-part or three-part name. If a three-part name is specified, the first part must match the value of the CURRENT SERVER special register -- that is, the current location. In any case, the AuthID qualifying the table name is the table owner.
column-name
Any long identifier naming the column. Each column in a table must have an unqualified column name, unique within the table. Dependent tables (tables containing a foreign key referencing a primary key in another table) can have up to 749 columns named, while nondependent tables (tables containing the primary key) may have 750 named columns. Column names are optional only when the select-command statement is included, in which case the column names from the source table are used.
constant
FIELDPROC clause: a parameter passed to the field procedure when it is invoked during execution of the CREATE TABLE statement. A parameter list is optional, and the number of parameters and the data type of each are determined by the field procedure. The maximum length of the parameter list is 254 bytes, including commas but excluding insignificant blanks and the delimiting parentheses.

[WITH] DEFAULT clause: names the default value for the column. The value of the constant must conform to the rules for assigning that value to the column. A default value can be specified for a column with a data type of LONG VARCHAR or LONG VARGRAPHIC and a maximum length of 254 bytes.

A character or graphic string constant must be short enough so that its UTF-8 representation requires no more than 1536. In addition, a hexadecimal graphic string constant (GX) cannot be specified.

data-type
Specifies the column data type. Data type is optional only when a select-command statement is included. FOR BIT DATA is optional; it is for use with CHAR, VARCHAR and LONG VARCHAR columns to indicate that the contents of the field values are to be treated as bit (binary) data. This is important for COBOL programs that use character and variable character fields to store integers, structures, etc. If not specified as FOR BIT DATA, the field is assumed to contain ASCII characters. Note that the FOR BIT DATA clause must precede the NULL specification for the field.

To conform with DB2 mainframe-specific operations, the XDB Server also records the FOR SBCS DATA and FOR MIXED DATA clause options in the appropriate system catalog tables.

NOT NULL is an optional instruction that prevents the column from containing null values.

NOT NULL WITH DEFAULT prevents columns from containing null values. When an attempt is made to place a NULL value in such a column, a default value is inserted. The default value is dependent on the data type as shown in the following table.

built-in-data-type
Specifies the data type of the column as one of the following built-in data types, and for character string data types, specifies the subtype. If you define the table with a LOB column (CLOB, DBCLOB, or BLOB), you must also define a ROWID column.

[WITH] DEFAULT clause: In a given column definition neither NOT NULL nor DEFAULT can be specified more than once. Both NOT NULL and DEFAULT cannot be specified. Omitting NOT NULL and DEFAULT implies that DEFAULT NULL is intended.

Data Type | Default Value
Numeric | 0
Date | current date
Time | current time
Timestamp | current timestamp
Character | Blanks
Varchar | Blanks
Graphic | Blanks
select-command
Can consist of any SELECT statement that retrieves data values from a database and inserts them into the newly created table. See CREATE With SELECT below.
column-name
Names a column on which a key is to be created. Up to 64 columns can be included in the key. If creating a PRIMARY key, a unique index must be created on the table; in this index exactly the same column names must appear, in exactly the same order as in the PRIMARY KEY constraint. The index will be designated the primary key. See PRIMARY KEY below and the CREATE GLOBAL TEMPORARY TABLE command for more information.
constraint-name
Defines a FOREIGN KEY constraint (which cannot be a unique index). If constraint-name is not specified in the command, the system generates a constraint name by taking the first eight characters of the first column name and checking for uniqueness. If not unique, the XDB Server adds a number to the first seven characters of the this first column name, and checks for uniqueness again. If necessary, additional character(s) at the end of the column name string are replaced with numbers until the name becomes unique among all constraint names on the table.

Also defines a table CHECK constraint within the CONSTRAINT...CHECK clause. The constraint-name is an SQL long identifier. A constraint-name cannot be specified more than once for the same table (see CONSTRAINT keyword).

check-condition
Provides a shorthand method of defining a check constraint that applies to a single column.

A check condition can consist of a single predicate, or two or more predicates joined by AND or OR. The first operand of each predicate must be the name of a column of the table. The second operand can be a column name or a constant. A check-condition can evaluate to unknown if a column that is an operand of the predicate is null. A check-condition that evaluates to unknown does not violate the check constraint (see CHECK clause).

For conformance with the SQL standard, if CHECK is specified in the column definition of column C, no columns other than C should be referenced in the check condition of the check constraint. The effect is the same as if the check condition were specified as a separate clause.

referenced-table
Identifies the table referenced by the referential integrity constraint (or the parent table containing the primary key referenced).

The ON DELETE or ON UPDATE (XDB mode only) clause tells the system how to handle dependent records in this table when a corresponding record in the parent table is being deleted. The RESTRICT option (default) prevents the record from being deleted from the parent table. The CASCADE option deletes or updates the dependent records from the current table, and allows the deletion or updating of the parent record. The SET NULL option causes the foreign key fields in the dependent records to be set to NULL before the parent record is deleted.

Description

XDB Server tables can be created using the CREATE TABLE command. Tables can also be created using SQLWizard. For more information on SQLWizard, see the SQLWizard User's Guide. The XDB Server supports a CREATE with SELECT command which allows a table to be created and populated in one command execution. The CREATE LIKE command allows the creation of a table using an existing table or view specification. See CREATE LIKE below.

The following example creates the table INVENT:

CREATE TABLE invent
    (item_no SMALLINT NOT NULL,
     description CHAR (12),
     model CHAR (6),
     type CHAR 12,
     weight FLOAT,
     qoh INTEGER,
     unit_cost DECIMAL(6,3),
     price MONEY)

The INVENT table will have the structure shown in the following table:

Column Name | Data Type
item_no | SMALLINT (nulls not permitted)
Description | CHAR 12
Model | CHAR 6
Type | CHAR 12
Weight | FLOAT
Qoh | INTEGER
unit_cost | DECIMAL(6,3)
Price | MONEY

Once a table has been created, data can be entered or indexes created. The column types and the number of columns can be changed using the ALTER TABLE command. The table name can be changed by the RENAME command. The table can also be altered or renamed using SQLWizard. (For more information on SQLWizard, see the SQLWizard User's Guide.)

With DB2 V7, XDB locations (either EBCDIC or ASCII) can now contain Unicode data. If you create a table with CCSID UNICODE, all character data in corresponding tables is stored in UTF-8 format and all graphic data is stored in UTF-16 format.

FOR subtype DATA
Specifies a subtype for a character string column, which is a column with a data type of CHAR, VARCHAR, LONG VARCHAR, or CLOB. Do not use the FOR DATA clause with columns of any other data type (including any distinct type). subtype can be one of the following:
SBCS | Column holds single-byte data.
MIXED | Column holds mixed data. Do not specify MIXED if the value of field MIXED DATA on installation panel DSNTIPF is NO.
BIT | Column holds BIT data. Do not specify BIT for a CLOB column.

If you do not specify the FOR clause, the column is defined with a default subtype. The default is SBCS when the value of field MIXED DATA on installation panel DSNTIPF is NO. The default is MIXED when the value is YES.

A security label column is always considered SBCS data, regardless of the encoding scheme of the table.

XDB Server operating environment does not support the CLOB data type at this time.

GRAPHIC (integer)
For a fixed-length graphic string of length integer, which can range from 1 to 127. If the length specification is omitted, a length of 1 character is assumed.
VARGRAPHIC (integer)
For a varying-length graphic string of maximum length integer, which must range from 1 to n/2, where n is the maximum row size minus 2 bytes. An integer longer than 127 defines a long string column.
ROWID

For a row ID type.

A table can have only one ROWID column. The values in a ROWID column are unique for every row in the table and cannot be updated. You must specify NOT NULL with ROWID.

NOT NULL

Prevents the column from containing null values.

PRIMARY KEY

Provides a shorthand method of defining a primary key composed of a single column. Thus, if PRIMARY KEY is specified in the definition of column C, the effect is the same as if the PRIMARY KEY(C) clause is specified as a separate clause.

The NOT NULL clause must be specified with this clause. Each column-name must be an unqualified name that identifies a column of the table except a LOB or ROWID column (including a distinct type that is based on a LOB or ROWID), and the same column must not be identified more than once. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 -2m, where m is the number of varying-length columns in the key.

The table is marked as unavailable until its primary index is explicitly created unless the CREATE TABLE statement is processed by the schema processor. In that case, DB2 implicitly creates an index to enforce the uniqueness of the primary key and the table definition is considered complete.

UNIQUE

Provides a shorthand method of defining a unique key composed of a single column. Thus, if UNIQUE is specified in the definition of column C, the effect is the same as if the UNIQUE(C) clause is specified as a separate clause.

The NOT NULL clause must be specified with this clause. UNIQUE cannot be specified more than once in a column definition and must not be specified if the PRIMARY KEY clause is specified in the column definition or if the definition is for a LOB column. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 -2m, where m is the number of varying-length columns in the key.

Each column-name must be an unqualified name that identifies a column of the table except a LOB column, and the same column must not be identified more than once.

DEFAULT

The default value assigned to the column in the absence of a value specified on INSERT or LOAD. Do not specify DEFAULT for a ROWID column, an identity column (a column that is defined AS IDENTITY) or a security label column (a column that is defined AS SECURITY LABEL); DB2 generates default values. If a value is not specified after DEFAULT, the default value depends on the data type of the column, as follows:

Data Type | Default Value
Numeric | 0
Fixed-length string | Blanks
Varying-length string | A string of length 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP
Distinct type | The default of the source data type

A default value other than the one that is listed above can be specified in one of the following forms, except for a LOB column. The only form that can be specified for a LOB column is DEFAULT NULL. Unlike other varying-length strings, a LOB column can only have the default value of a zero-length string as listed above or null.

GENERATED

Specifies that XDB generates values for the column. GENERATED must be specified if the column is to be considered an identity column. If the data type of the column is a ROWID (or a distinct type that is based on a ROWID), the default is GENERATED ALWAYS.

ALWAYS Indicates that XDB will always generate a value for the column when a row is inserted into the table. ALWAYS is the recommended value unless you are using data propagation.
BY DEFAULT Indicates that XDB will generate a value for the column when a row is inserted into the table unless a value is specified.

For a ROWID column, XDB uses a specified value only if it is a valid row ID value that was previously generated by XDB and the column has a unique, single-column index. Until this index is created on the ROWID column, the SQL INSERT statement and the LOAD utility cannot be used to add rows to the table. If the value of special register CURRENT RULES is 'STD' when the CREATE TABLE statement is processed, XDB implicitly creates the index on the ROWID column. The name of this index is 'I' followed by the first ten characters of the column name followed by seven randomly generated characters. If the column name is less than ten characters, XDB adds underscore characters to the end of the name until it has ten characters. The implicitly created index has the COPY NO attribute.

For an identity column, XDB inserts a specified value but does not verify that it is a unique value for the column unless the identity column has a unique, single-column index. Without a unique index, XDB can guarantee unique values only among the set of system-generated values.

BY DEFAULT is the recommended value only when you are using data propagation.

AS SECURITY LABEL

Specifies that the column will contain security label values. This also indicates that the table is defined with multilevel security with row level granularity. A table can have only one security label column. To define a table with a security label column, the primary authorization ID of the statement must have a valid security label, and the RACF SECLABEL class must be active. In addition, the following conditions are also required:

  • The data type of the column must be CHAR(8).
  • The subtype of the column must be SBCS.
  • The column must be defined with the NOT NULL and WITH DEFAULT clauses.
  • No field procedures, check constraints, or referential constraints are defined on the column.
  • An edit procedure is not defined on the table.
  • You are using z/OS Version 1 Release 5 or later.
AS IDENTITY

Specifies that the column is an identity column for the table. A table can have only one identity column. AS IDENTITY can be specified only if the data type for the column is an exact numeric type with a scale of zero (SMALLINT, INTEGER, DECIMAL with a scale of zero, or a distinct type based on one of these types).

An identity column is implicitly NOT NULL.

START WITH numeric-constant Specifies the first value for the identity column. The value can be any positive or negative value that could be assigned to the column without non-zero digits exisiting to the right of the decimal point. The default is 1.
INCREMENT BY numeric-constant Specifies the interval between consecutive values of the identity column. The value can be any positive or negative value (including 0) that does not exceed the value of a large integer constant, and could be assigned to the column without any non-zero digits existing to the right of the decimal point. The default is 1.

If this value is negative, the values for the identity column descend. If this value is 0 or positive, the values for the identity column ascend. The default is 1.

MINVALUE or NO MINVALUE

Specifies the minimum value at which a descending identity column either cycles or stops generating values or an ascending identity column cycles to after reaching the maximum value. The default is NO MINVALUE.

NO MINVALUE

Specifies that the minimum end point of the range of values for the identity column has not be set. In such a case, the default value for MINVALUE becomes one of the following:

  • For an ascending identity column, the value is the START WITH value or 1 if START WITH was not specified.
  • For a descending identity column, the value is the minimum value of the data type of the column.
MINVALUE numeric-constant

Specifies the numeric constant that is the minimum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

MAXVALUE or NO MAXVALUE

Specifies the maximum value at which an ascending identity column either cycles or stops generating values or a descending identity column cycles to after reaching the minimum value. The default is NO MAXVALUE.

NO MAXVALUE

Specifies that the minimum end point of the range of values for the identity column has not be set. In such a case, the default value for MAXVALUE becomes one of the following:

  • For an ascending identity column, the value is the maximum value of the data type of the column.
  • For a descending identity column, the value is the START WITH value or -1 if START WITH is not specified.
MAXVALUE numeric-constant

Specifies the numeric constant that is the maximum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

NO CYCLE or CYCLE

Specifies whether this identity column should continue to generate values after reaching either its maximum or minimum value.

NO CYCLE

Specifies that values will not be generated for the identity column after the maximum or minimum value has been reached. This is the default.

CYCLE

Specifies that values continue to be generated for the identity column after the maximum or minimum value has been reached. If this option is used, after an ascending identity column reaches the maximum value, it generates its minimum value. After a descending identity column reaches its minimum value, it generates its maximum value. The maximum and minimum values for the identity column determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by DB2 for an identity column. However, if a unique index exists on the identity column and a non-unique value is generated for it, an error occurs.

CACHE or NO CACHE

This clause has no functional equivalent in the XDB Server operating environment.

NO ORDER or ORDER

Specifies whether the identity column values must be generated in order of request. The default is NO ORDER.

NO ORDER

Specifies that the values do not need to be generated in order of request.

ORDER

Specifies that the values are generated in order of request. Specifying ORDER may disable the caching of values. ORDER applies only to a single-application process.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for identity values from different DB2 members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the identity column, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested a value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that identity values are generated in strict numeric order among multiple DB2 members using the same identity column, specify the ORDER option.

PARTITION BY RANGE

Specifies the range partitioning scheme for the table (the columns used to partition the data). When this clause is specified, the table space is complete, and it is not necessary to create a partitioned index on the table. If this clause is used, the ENDING AT clause cannot be used on a subsequent CREATE INDEX statement for this table.

If this clause is specified, the IN database-name.table-space-name clause is required. This clause applies only to tables in a partitioned table space.

This clause is only implemented syntactically in the XDB Server operating environment.

partition-expression

Specifies the key data over which the range is defined to determine the target data partition of the data.

column-name

Specifies the columns of the key. Each column-name must identify a column of the table. Do not specify more than 64 columns, the same column more than once, a LOB column, a column with a distinct type that is based on a LOB data type, or a qualified column name. The sum of length attributes of the columns must not be greater than 255 - n, where n is the number of columns that can contain null values.

NULLS LAST

Specifies that null values are treated as positive infinity for purposes of comparison.

ASC

Puts the entries in ascending order by the column. ASC is the default.

DESC

Puts the entries in descending order by the column.

partition-element

Specifies ranges for a data partitioning key and the table space where rows of the table in the range will be stored.

PARTITION integer

integer is the physical number of a partition in the table space. A PARTITION clause must be specified for every partition of the table space. In this context, highest means highest in the sorting sequences of the columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC), the lowest actual value is highest in the sorting sequence.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant, ...)

constant defines the limit key for a partition boundary. Specify at least one constant after ENDING AT in each PARTITION clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key for ascending and the lowest for descending. The use of constants to define key values is subject to the following rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must conform to the rules for assigning that value to the column. A hexadecimal string constant (GX) cannot be specified.

    Using fewer constants than there are columns in the key has the same effect as using the highest or lowest values for the omitted columns, depending on whether they are ascending or descending.

  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition for ascending cases.
  • The constants specified for the last partition are enforced. The value specified for the last partition is the highest value of the key that can be placed in the table. Any key values greater than the value specified for the last partition are out of range.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'. If the column is descending, the padding character is X'00'.
  • If a key includes a ROWID column or a column with a distinct type that is based on a ROWID data type, then 17 bytes of the constant that is specified for the corresponding ROWID column are considered.
INCLUSIVE

Specifies that the specified range values are included in the data partition.

CREATE With SELECT

The CREATE command may include an optional SELECT command (XDB mode only) that selects data from an existing table to insert into the new table. The order of the selected columns defines the column order of the new table. However, the number of columns selected does not need to match the number of columns defined for the new table. If the new table has more columns than the SELECT statement, the extra columns are assigned NULL values. If the new table has fewer columns than the SELECT command, the system uses only as many of the first columns as will fit into the new table. If no column names are given in the create command, the column names listed in the SELECT command are used to create the table.

Any search condition can be used in the SELECT statement including a join condition or a subselect. See WHERE Clause for more information on search conditions. The columns selected do not have to match the data type of the new table columns, but they must be type-compatible. The new table, for example, accepts floating point data in a column defined as an integer -- however, the fractional part of the data is truncated. See the ALTER TABLE command for a type compatibility matrix. When converting from character data to another type, if the conversion is not possible the new value will be NULL.

Three examples of CREATE with SELECT are given below:

CREATE TABLE parispno
    (pno CHAR 2, pname CHAR 6, city CHAR 6,
     weight DECIMAL(4,3))
    SELECT pno, pname, city
        FROM part
        WHERE city = "PARIS"
CREATE TABLE lowinv
    SELECT *
        FROM partsupp
        WHERE qty < 400
CREATE TABLE (a, b, c)
    SELECT A.a, B.b, C.c
        FROM A, B, C
        WHERE A.x = B.x
          AND B.x = C.x
Subselects and Locations

When populating new tables with subselects, the subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

CREATE TABLE tutorial.tutorial.sample
    SELECT * FROM tutorial.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM debloc.debbie.employee
                WHERE st = "MD";

Valid:

CREATE TABLE tutorial.tutorial.sample
    SELECT * FROM tutorial.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM tutorial.debbie.employee
                WHERE st = "MD";
CREATE LIKE

The LIKE table-name or LIKE view-name clause is used to create a new table with the same definition as an existing table or view. The columns of the table will have exactly the same names and column specifications (data type, null permission, etc.) as the source table or view. However, neither the primary nor foreign keys, nor any check option existing on the source table or view are defined for the new table. Data from the source table is NOT transferred to the new table.

An example of the CREATE TABLE...LIKE command is:

CREATE TABLE personnel LIKE employee

Creating a table like a view

If the LIKE clause is specified and the definition of the table is being based on a view, the view must not include a ROWID column or an identity column. A view column is considered to be an identity column if the corresponding column of the table or view indirectly or directly maps to the name of an identity column in a base table with these exceptions:

  • The select-list of the view definition identifies the same identity column more than once.
  • The select-list of the view definition references multiple identity columns and thus involves a join.
  • A column in the view definition includes an expression that refers to an identity column.
IN or IN DATABASE

Specifies a database-name alone (preceded by keyword IN DATABASE), or both a tablespace-name with an optional database-name qualifier (preceded by keyword IN). If a database is named, it must be described in the system catalog for the current location, and must not be the DSNDB06 catalog database.

If a table space name is not explicitly specified, a table space is created implicitly within database-name. In these cases, the XDB Server checks the privileges held by the user for either SYSADM or SYSCTRL authority for the location, DBADM, DBCTRL or DBMAINT authority for the database, or the CREATETS privilege for the database. The table space name is taken from the table name specified in the CREATE TABLE command. Except for the name, the other attributes of this table space match those that would result from a CREATE TABLESPACE statement minus all its optional clauses.

If tablespace-name is specified, this name must not reference an already existing table space that was implicitly created. If both a database and table space are specified, the table space must belong to the named database. If only a table space is named, it must belong to the default DSNDB04 database for the current location. If the table space references a stogroup, then any tables created with that table space name are stored in the path specified for the stogroup.

A subselect and an IN DATABASE clause cannot be used in the same CREATE TABLE statement. Instead, create the table in the database and then use an INSERT INTO command with a subselect to populate the table.

For example:

Invalid:

CREATE TABLE tutorial.debbie.employee
SELECT * FROM tutorial.tutorial.employee
    WHERE st = "MD"
IN DATABASE debdb;

Valid:

CREATE TABLE tutorial.debbie.employee (e_no SMALLINT NOT NULL,
    lname CHAR 10 NOT NULL,
    fname CHAR 10 NOT NULL, street CHAR 20,
    city CHAR 15, st CHAR 2, zip CHAR 5,
    dept CHAR 4, payrate MONEY, com DECIMAL(2,2))
IN DATABASE debdb;
INSERT INTO tutorial.debbie.employee
    SELECT * FROM tutorial.tutorial.employee
        WHERE st = "MD";
OBID integer

Identifies the OBID to be used for this table. An OBID is the identifier for an object's internal descriptor.

The OBID keyword option is used with ROSHARE databases, and can be viewed by querying the SYSIBM.SYSTABLES catalog table. The integer must not identify an existing or previously used OBID of the database. If you omit OBID, DB2 generates a value.

The following statement retrieves the value of OBID:

SELECT OBID
    FROM SYSIBM.SYSTABLES
    WHERE CREATOR = 'ccc' AND NAME = 'nnn';

Here, nnn is the table name and ccc is the table's creator

UNIQUE

Defines a unique key composed of the identified columns. Each column name must be an unqualified name that identifies a column of the table, and the same column must not be identified more than once. A unique key is a duplicate if it is the same as the primary key or a previously defined unique key. A unique key on a single column can be defined in a column definition. In a given column definition neither UNIQUE nor PRIMARY KEY can be specified more than once, nor can UNIQUE and PRIMARY KEY both be specified for the same column.

PRIMARY KEY

A table can have at most one constraint condition specified as a PRIMARY KEY. The purpose of the primary key is to enforce entity integrity -- that is, to uniquely identify each row of a table. Note that the columns in the primary key must be defined as NOT NULL when the columns are specified.

Note:

You must create an index for a primary key or a unique key if the CREATE TABLE statement is processed by the XDB Server. XDB Server does not implicitly create an index.

A primary key on a single column can be defined in a column definition. In a given column definition neither UNIQUE nor PRIMARY KEY can be specified more than once, nor can UNIQUE and PRIMARY KEY both be specified for the same column.

You cannot create foreign keys on tables that are in a pending state. A table is in a pending state if a primary key clause has been specified but a unique index has not been built on those columns.

For example, to define the SNO and PNO columns as the primary key of the PARTSUPP table, use the command:

CREATE TABLE partsupp(sno SMALLINT NOT NULL,
    pno SMALLINT NOT NULL,
    qty SMALLINT, PRIMARY KEY (sno, pno))

To define the SNO column as the primary key of the SUPPLIER table, use a command like:

CREATE TABLE supplier(sno CHAR 3 NOT NULL,
    sname CHAR 5, status SMALLINT,
    city CHAR 6, PRIMARY KEY (sno))
FOREIGN KEY

A FOREIGN KEY constraint is used to enforce referential integrity -- the relationship between a referencing (or dependent) table and a referenced (or parent) table. The referential integrity rule requires that, for any value in the dependent columns, there must exist a row in the parent table such that the value of the dependent columns equals the value of the corresponding columns in the primary key of the parent table. This is enforced as follows:

  1. When an update or insert is performed on the dependent table, the set of values placed in the referencing columns must match a set of values that exists in the parent table.
  2. If an attempt is made to delete or update a row of the parent table that contains values matching those in a dependent table, the system uses the ON DELETE or ON UPDATE (XDB Server extension only, not available on DB2 or other modes) clause to determine the delete rule to use. The options are:
    • RESTRICT

      Prevents record deletion from the parent table if dependents exist. RESTRICT is the default value.

    • NO ACTION

      Prevents records from being deleted from the parent table (as in the RESTRICT option), except the referential constraint is enforced at the end of the statement. This is the default setting if the CURRENT RULES special register is STD (SQL standard).

    • CASCADE

      Deletes the dependent records from the current table and then deletes the parent records.

    • SET NULL

      Causes each nullable column in the foreign key of each dependent record to be set to NULL before the corresponding parent records are deleted.

Note that whenever a cyclical situation exists (for example a foreign key of table B references the primary key of table A, and a foreign key of table A references a primary key of table B, the delete rules should be the same for all foreign keys, and the SET NULL option should not be used.

In order to create a referential integrity constraint you must create a FOREIGN KEY constraint on the referencing table. The FOREIGN KEY constraint must reference the existing PRIMARY KEY of the referenced table.

Foreign key columns do not need to have the same names as the corresponding columns in the PRIMARY KEY of the referenced table, but the columns must match in type, number and order.

Each column-name must be an unqualified name that identifies a column of the table except a LOB, ROWID, or security label column, and the same column must not be identified more than once. The number of identified columns must not exceed 64, and the sum of their length attributes must not exceed 255 minus the number of columns that allow null values. The referential constraint is a duplicate if the FOREIGN KEY and parent table are the same as the FOREIGN KEY and parent table of a previously defined referential constraint. The specification of a duplicate referential constraint is ignored with a warning.

A constraint name is used to uniquely identify a FOREIGN KEY constraint, and is stored in the appropriate system catalog table. The constraint name should be a short identifier (up to eight characters) that is unique among all constraints built on the table. Since this constraint name is also used in error messages to indicate constraint violation, it is important to use a meaningful name.

Although it is good practice to provide a meaningful constraint name, if one is not supplied, the system automatically generates one by taking the first eight characters of the first column (appearing in the column list) and then checking for uniqueness. If this name is not unique, the XDB Server takes the first seven characters of the first column name plus a number. If necessary one letter at a time is removed from the end of this constraint name and replaced with a number, until the constraint name becomes unique among all constraint names existing for the table.

Indexes on Foreign Keys

The XDB Server automatically builds an index on your FOREIGN KEY columns. The system will generate the name of the index and store it in the REFKEYNAME column of the SYSIBM.SYSREF catalog table. DB2, in contrast, does not automatically create an index on FOREIGN KEY columns. If you are using your DB2 data definition language (DDL) script, and this script contains CREATE INDEX commands on FOREIGN KEY columns, you can end up with redundant indexes. For optimal performance, you should modify your DB2 DDL script to remove any CREATE INDEX commands on FOREIGN KEY columns.

REFERENCES

The references portion of the referential-constraint clause is a separate clause. A single column can be identified as a foreign key of a referential constraint by using the references-clause in a column definition. Define a key that consists of more than one column by listing the column names to which the REFERENCES privilege applies.

Do not specify references-clause in the definition of a LOB, ROWID, or security label column; a LOB, ROWID, or security label column cannot be a foreign key.

A foreign key can reference a unique key or a primary key. When a foreign key refers to a nonprimary unique key, you must specify the columns of the key. If the foreign key includes a column defined as a distinct type, the corresponding column of the nominated parent key must be the same distinct type.

ENFORCED or NOT ENFORCED

Indicates whether or not the referential constraint is enforced by DB2 during normal operations, such as insert, update, or delete.

ENFORCED

Specifies that the referential constraint is enforced by the DB2 during normal operations (such as insert, update, or delete) and that it is guaranteed to be correct. This is the default.

NOT ENFORCED

Specifies that the referential constraint is not enforced by DB2 during normal operations, such as insert, update, or delete. This option should only be used when the data that is stored in the table is verified to conform to the constraint by some other method than relying on the database manager.

ENABLE QUERY OPTIMIZATION

Specifies that the constraint can be used for query optimization. DB2 uses the information in query optimization using materialized query tables with the assumption that the constraint is correct. This is the default.

LIKE table-name or view-name

Specifies that the columns of the table have exactly the same name and description as the columns of the identified table or view. The name specified after LIKE must identify a table or view that exists at the current server, and the privilege set must implicitly or explicitly include the SELECT privilege on the identified table or view. An identified view must not include a column that is an explicitly defined ROWID column (including a distinct type that is based on a ROWID) or an identity column.

The use of LIKE is an implicit definition of n columns, where n is the number of columns in the identified table or view. The implicit definition includes all attributes of the n columns as they are described in SYSCOLUMNS with these exceptions:

  • When a table is identified in the LIKE clause and a column in the table has a field procedure, the corresponding column of the new table has the same field procedure and the field description. However, the field procedure is not invoked during the execution of the CREATE TABLE statement.
  • When a table is identified in the LIKE clause and a column in the table an identity column, the corresponding column of the new table inherits only the data type of the identity column; none of the identity attributes of the column are inherited unless the INCLUDING IDENTITY clause is specified.
  • When a table is identified in the LIKE clause and a column in the table is a security label column, the corresponding column of the new table inherits only the data type of the security label column; none of the security label attributes of the column are inherited.
  • When a table is identified in the LIKE clause and the table contains a ROWID column (explicitly-defined, hidden, or both), the corresponding columns of the new table inherits the ROWID columns.
  • When a view is identified in the LIKE clause, the default value that is associated with the corresponding column of the new table depends on the column of the underlying base table for the view. If the column of the base table does not have a default, the new column does not have a default. If the column of the base table has a default, the default of the new column is:
    • Null if the column of the underlying base table allows nulls.
    • The default for the data type of the underlying base table if the underlying base table does not allow nulls.
  • When a table that uses table-controlled partitioning is identified in the LIKE clause, the new table does not inherit that table's partitioning scheme. If desired, these partition boundaries can be added by specifying ALTER TABLE with the ADD PARTITION BY RANGE clause.
  • The CCSID of the column is determined by the implicit or explicit CCSID clause.

The above defaults are chosen regardless of the current default of the base table column. Also, no column in the new table has a field procedure because the catalog descriptions of view columns do not include field procedures.

The implicit definition does not include any other attributes of the identified table or view. For example, the new table does not have a primary key or foreign key. The table is created in the table space implicitly or explicitly specified by the IN clause, and the table has any other optional clause only if the optional clause is specified.

EXCLUDING IDENTITY COLUMN ATTRIBUTES or INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies whether identity column attributes are inherited from the definition of the source of the result table.

EXCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that identity column attributes are not inherited from the source result table definition. This is the default.

INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that, if available, identity column attributes (such as START WITH, INCREMENT BY, and CACHE values) are inherited from the definition of the source table. These attributes can be inherited if the element of the corresponding column in the table, view, or fullselect is the name of a column of a table or the name of a column of a view that directly or indirectly maps to the column name of a base table with the identity attribute. In other cases, the columns of the new temporary table do not inherit the identity attributes. The columns of the new table do not inherit the identity attributes in the following cases:

  • The select list of the fullselect includes multiple instances of an identity column name (that is, selecting the same column more than once).
  • The select list of the fullselect includes multiple identity columns (that is, it involves a join).
  • The identity column is included in an expression in the select list.
  • The fullselect includes a set operation (union).
Using an identity column

When a table has an identity column, DB2 can automatically generate unique, sequential numeric values for the column as rows are inserted into the table. Thus, identity columns are ideal for primary keys. Identity columns and ROWID columns are similar in that both types of columns contain values that DB2 generates and guarantees as unique. ROWID columns are used in large object (LOB) table spaces and can be useful in direct-row access. ROWID columns contain values of the ROWID data type, which returns a 40-byte VARCHAR value that is not regularly ascending or descending. ROWID data values are therefore not well suited to many application uses, such as generating employee numbers or product numbers. For data that is not LOB data and that does not require direct-row access, identity columns are usually a better approach, because identity columns contain existing numeric data types and can be used in a wide variety of uses for which ROWID values would not be suitable.

When a table is recovered to a point-in-time, it is possible that a large gap in the sequence of generated values for the identity column might result. For example, assume a table has an identity column that has an incremental value of 1 and that the last generated value at time T1 was 100 and DB2 subsequently generates values up to 1000. Now, assume that the table space is recovered back to time T1. The generated value of the identity column for the next row that is inserted after the recovery completes will be 1001, leaving a gap from 100 to 1001 in the values of the identity column.

Sometimes you may need to change the attributes of an identity column, For example, if you had defined an identity column with a data type of SMALLINT and then run out of assignable values, you need to redefine the column as INTEGER. To change the attributes of an identity column, you unload the data from the table, drop the table, recreate the table, and reload athe data.

But when you recreate the table, you must specify GENERATED BY DEFAULT and a new START WITH value for the identify column.Using GENERATED BY DEFAULT allows LOAD to reload the previously existing identity column values. You cannot use GENERATED ALWAYS in this case, but not using it is not a problem since DB2 always generates a value if a column value is not provided during insertion of an identity column defined as GENERATED BY DEFAULT. The new START WITH value should be the next value in the sequence from where the original sequence of values left off; this value is the next value that DB2 would generate first.

WITH RESTRICT ON DROP

Indicates that the table cannot be dropped. Also, the database and table space that contain the table cannot be dropped.

If a table space is named, it must not be one that was created implicitly, be a partitioned table space that already contains a table, or be a LOB table space. If you name a partitioned table space, you cannot load or use the table until its partitioned index is created.

CCSID

The CCSID clause is only syntactically supported for EBCDIC and ASCII. This is because the definition of the XDB location itself defines how character data is stored.

If you specify UNICODE, your character and graphic data is stored as UNICODE within the table.

VOLATILE or NOT VOLATILE

Specifies how DB2 is to choose access to the table.

VOLATILE

Specifies that index access should be used on this table whenever possible for SQL operations. However, be aware that list prefetch and certain other optimization techniques are disabled when VOLATILE is used.

One instance in which use of VOLATILE may be desired is for a table whose size can vary greatly. If statistics are taken when the table is empty or has only a few rows, those statistics might not be appropriate when the table has many rows. Another instance in which use of VOLATILE may be desired is for a table that contains groups of rows, as defined by the primary key on the table. All but the last column of the primary key of such a table indicate the group to which a given row belongs. The last column of the primary key is the sequence number indicating the order in which the rows are to be read from the group. VOLATILE maximizes concurrency of operations on rows within each group, since rows are usually accessed in the same order for each operation.

NOT VOLATILE

Specifies that SQL access to this table should be based on the current statistics. NOT VOLATILE is the default.

CARDINALITY

An optional keyword that currently has no effect, but that is provided for DB2 family compatibility.

materialized-query-definition

Specifies that the column definitions are based on the result of a fullselect. If materialized-query-table-options are specified, the table is a materialized query table and the REFRESH TABLE statement can be used to populate the table with the results of the fullselect.

column-name

Names the columns in the table. If a list of column names is specified, it must consist of as many names as there are columns in the result table of the fullselect. Each column-name must be unique and unqualified. If a list of column names is not specified, the columns of the table inherit the names of the columns of the result table of the fullselect.

A list of column names must be specified if the result table of the fullselect has duplicate column names or an unnamed column. An unnamed column is a column derived from a constant, function, expression, or set operation that is not named using the AS clause of the select list.

AS(fullselect)

Specifies that the table definition is based on the column definitions from the result of a query expression. The use of AS (fullselect) is an implicit definition of n columns for the table, where n is the number of columns that would result from the fullselect. The columns of the new table are defined by the columns that result from the fullselect. Every select list element must have a unique name. The AS clause can be used in the select-clause to provide unique names. The implicit definition includes the column name, data type, and nullability characteristic of each of the result columns of fullselect.

If the fullselect is specified, for the statement that is embedded or prepared dynamically, the owner of the table being created must have the SELECT privilege on the tables or views referenced in the fullselect, or the privilege set must include SYSADM or DBADM authority for the database in which the tables of the fullselect reside. Having SELECT privilege means that the owner has at least one of the following authorizations:

  • Ownership of the tables or views referenced in the fullselect
  • The SELECT privilege on the tables and views referenced in the fullselect
  • SYSADM authority
  • DBADM authority for the database in which the tables of the fullselect reside

The rules for establishing the qualifiers for names used in the fullselect are the same as the rules used to establish the qualifiers for table-name. The fullselect must not refer to host variables or include parameter markers.

When WITH NO DATA is specified, the fullselect must not:

  • Reference a remote object.
  • Result in a column having a ROWID data type or a distinct type based on ROWID.
  • Result in a column having a BLOB, CLOB, or DBCLOB data type or a distinct type based on these data types.
  • Contain PREVIOUS VALUE or a NEXT VALUE expression.
  • Include an INSERT statement in the FROM clause. When a materialized query table is defined, the column attributes, such as DEFAULT and IDENTITY, are not inherited from the fullselect.

When DISABLE QUERY OPTIMIZATION is specified, the following additional restrictions apply:

  • The fullselect cannot contain a reference to a created global temporary table or a declared global temporary table.
  • The fullselect cannot reference another materialized query table.

When a materialized query table is defined with ENABLE QUERY OPTIMIZATION specified, the following additional restrictions apply:

  • The fullselect must be a subselect.
  • The subselect cannot include a function that is nondeterministic or has external actions. For example, a user-defined function that is defined with either EXTERNAL ACTION or NOT DETERMINISTIC or the RAND built-in function cannot be referenced.
  • The subselect cannot contain any predicates that include subqueries.
  • The subselect cannot contain:
    • A nested table expression or view that requires temporary materialization
    • A join using the INNER JOIN syntax
    • An outer join
    • A special register
    • A scalar fullselect
    • A row expression predicate
    • Sideway references
  • The outermost SELECT list of the subselect must not reference data that is encoded with different CCSID sets.
  • If the subselect references a view, the fullselect in the view definition must satisfy the preceding restrictions.

When fullselect does not satisfy the restrictions, an error occurs.

WITH NO DATA

Specifies that the query is used only to define the attributes of the new a table. The table is not populated using the results of the query and the REFRESH TABLE statement cannot be used. When the WITH NO DATA clause is specified, the table is not considered a materialized query table.

The columns of the table are defined based on the definitions of the columns that result from the fullselect.

copy-options

Specifies whether identity column attributes and column defaults are inherited from the definition of the source of the result table.

EXCLUDING IDENTITY COLUMN ATTRIBUTES or INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies whether identity column attributes are inherited.

EXCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that identity column attributes are not inherited from the definition of the source of the result table. This is the default.

INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that, if available, identity column attributes (such as START WITH, INCREMENT BY, and CACHE values) are inherited from the definition of the source table. These attributes can be inherited if the element of the corresponding column in the table, view, or fullselect is the name of a column of a table or the name of a column of a view that directly or indirectly maps to the column name of a base table with the identity attribute. In other cases, the columns of the new temporary table do not inherit the identity attributes. The columns of the new table do not inherit the identity attributes in the following cases:

  • The select list of the fullselect includes multiple instances of an identity column name (that is, selecting the same column more than once).
  • The select list of the fullselect includes multiple identity columns (that is, it involves a join).
  • The identity column is included in an expression in the select list.
  • The fullselect includes a set operation (union).
EXCLUDING COLUMN DEFAULTS, INCLUDING COLUMN DEFAULTS, or USING TYPE DEFAULTS

Specifies whether column defaults are inherited.

EXCLUDING COLUMN DEFAULTS

Specifies that the column defaults are not inherited from the definition of the source table. The default values of the column of the new table are either null or there are no default values. If the column can be null, the default is the null value. If the column cannot be null, there is no default value, and an error occurs if a value is not provided for a column on INSERT for the new table.

INCLUDING COLUMN DEFAULTS

Specifies that column defaults for each updatable column of the definition of the source table are inherited. Columns that are not updatable do not have a default defined in the corresponding column of the created table.

USING TYPE DEFAULTS

Specifies that the default values for the table depend on data type of the columns that result from fullselect, as follows:

Data type | Default value
Numeric | 0
Fixed-length string | Blanks
Varying-length string | A string length of 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP
refreshable-table-options

Specifies the options for a refreshable materialized query table.

DATA INITIALLY DEFERRED

Specifies that the data is not inserted into the materialized query table when it is created. Use the REFRESH TABLE statement to populate the materialized query table, or use the INSERT statement to insert data into a user-maintained materialized query table.

REFRESH DEFERRED

Specifies that the data in the table can be refreshed at any time using the REFRESH TABLE statement. The data in the table only reflects the result of the query as a snapshot at the time when the REFRESH TABLE statement is processed or when it was last updated for a user-maintained materialized query table.

MAINTAINED BY SYSTEM or MAINTAINED BY USER

Specifies how the data in the materialized query table is maintained.

MAINTAINED BY SYSTEM

Specifies that the materialized query table is maintained by the system. Only the REFRESH statement is allowed on the table. This is the default.

MAINTAINED BY USER

Specifies that the materialized query table is maintained by the user, who can use the LOAD utility or the INSERT, DELETE, UPDATE, SELECT FOR UPDATE, or REFRESH TABLE statements on the table.

ENABLE QUERY OPTIMIZATION or DISABLE QUERY OPTIMIZATION

Specifies whether this materialized query table can be used for optimization.

ENABLE QUERY OPTIMIZATION

Specifies that the materialized query table can be used for query optimization. If the fullselect specified does not satisfy the restrictions for query optimization, an error occurs. This is the default.

DISABLE QUERY OPTIMIZATION

Specifies that the materialized query table cannot be used for query optimization. The table can still be queried directly.

CONSTRAINT

Names a table check constraint. If a constraint-name is not specified, a unique constraint name is derived from the name of the first column in the check-condition specified in the definition of the table check constraint.

CHECK

Table check constraints can be defined on individual columns within the CREATE TABLE command. The check constraint is the check condition that defines the values that designated columns of the table can contain, with the following restrictions:

  • It can refer only to columns of table table-name; however, the columns cannot be LOB or ROWID columns.
  • It can be up to 3800 bytes long, not including redundant blanks.

It must not contain any of the following:

  • Subselects
  • Built-in or user-defined functions
  • Cast functions other than those created when the distinct type was created
  • Host variables
  • Parameter markers
  • Special registers
  • Columns that include a field procedure
  • CASE Expressions
  • Quantified predicates
  • EXISTS predicates
  • Row expressions
  • DISTINCT predicates
  • GX literals (hexadecimal graphic string constants)

For example, the CREATE TABLE command below builds the EMPLOYEE table with the following constraints:

  • Employee names must be a value other than NULL (this constraint is equivalent to specifying NOT NULL).
  • The Department number must be 1050.
  • The commission rate must be less than or equal to six percent.
CREATE TABLE EMPLOYEE
(
e_no         SMALLINT
lname        CHAR 10              CHECK (lname IS NOT NULL),
fname        CHAR 10              CHECK (fname IS NOT NULL),
street       CHAR 20,
city         CHAR 15,
st           CHAR 2,
zip          CHAR 5,
dept         CHAR 4               CHECK (dept='1050'),
payrate      MONEY,
com          DECIMAL(2,2),
CONSTRAINT   com CHECK (com <= 06)
)

A table check constraint is not enforced on the default value of a column when the constraint is defined. A table check constraint is enforced on the default value of a column when rows are inserted or updated.

The syntax of a table check constraint is checked when the constraint is defined but the meaning is not checked. A table check constraint is not checked for consistency with other types of constraints.

Check Constraint Storage

Table check information is stored in two new catalog tables:

  • SYSIBM.SYSCHECKS

    Contains one row for each table check constraint defined on a table.

  • SYSIBM.SYSCHECKDEP

    Contains a row for each reference to a column in a table check constraint.

Enforcing Check Constraints

After table check constraints are defined on a table, any change must satisfy those constraints if it is made by an INSERT or UPDATE statement. A row satisfies a check constraint if its condition evaluates either to true or to unknown. A condition can evaluate to unknown for a row if one of the columns named contains the null value for that row. For INSERT or UPDATE statements, table check constraints are enforced on views and their underlying tables.

CURRENT RULES Special Register

For populated tables, the enforcement of a table check constraint is determined by the value, STD or DB2, of the CURRENT RULES special register.

  • If the value is STD, a check constraint is enforced immediately when it is defined. If a row does not conform, the table check constraint is not added to the table and an error occurs.
  • If the value is DB2, the check constraint is added to the table description but its enforcement is deferred. Because there might be rows in the table that violate the check constraint, the table is placed in check pending status.
DEFAULT

You can define a table column that has a default value other than null. When a row is inserted and no value is specified for the column, the default you defined is assigned to the column.

The default value depends on the data type of the column. The DEFAULT clause allows you to specify a default value in one of the following forms:

  • A constant
  • The execution time value of the USER special register
  • The SQL authorization ID (SQLID) of the process
  • The null value
NOT NULL clause

In a given column definition neither NOT NULL nor DEFAULT can be specified more than once. Both NOT NULL and DEFAULT cannot be specified. Omitting NOT NULL and DEFAULT implies that DEFAULT NULL is intended.

For example, if you want to record the identity of anyone inserting rows into a table, define the table with two additional columns:

PRIMARY_ID | CHAR(8) | WITH DEFAULT USER,
SQL_ID | CHAR(8) | WITH DEFAULT CURRENT SQLID,

You can allow updates and inserts to the table only through a view that omits those columns. Then, the primary authorization ID and the SQLID of the process are added by default.

Examples

Constraint Examples

The following shows how referential integrity can be used to enforce common business rules by defining relationships between the CUSTOMER, ORDERS, PRODUCTS, ITEMS, and EMPLOYEE tables in the TUTORIAL location.

All of the tables named already exist in the TUTORIAL location. However, if the tables did not already exist (or if you create them in another location), you could specify the referential integrity constraints at the same time you created the table.

The order in which the commands are executed is important. You cannot create a table that references another table until the referenced table is created. For example, the CUSTOMER table must be created before the ORDERS table.

Business Rule 1
An order can be placed for a customer only if complete customer information is available.

Database Relationships

Before inserting or updating into the ORDERS table, check for matching C_NO values in the CUSTOMER table. Do not delete CUSTOMER table record if orders for customer exist in the ORDERS table.
Primary key: customer(c_no)
Foreign key: orders(o_no)
Delete rule: RESTRICT
Business Rule 2
Orders must be taken by an employee of the company. If a salesperson for an order is unknown, the order is treated as a house order.

Database Relationships

Before updating or inserting into the ORDERS table, check whether S_NO value has matching E_NO in the EMPLOYEE table. Before deleting EMPLOYEE table records, set S_NO of corresponding ORDERS table records to null.
Primary key: employee(e_no)
Foreign key: orders(s_no)
Delete rule: SET NULL
Business Rule 3
A request for an item must always be associated with a specific order.

Database Relationships

Before inserting or updating the ITEMS table, check whether O_NO columns have matching O_NO values in the ORDERS table. If ORDERS record is deleted, delete matching ITEMS table records.
Primary key: orders(o_no)
Foreign key: items(o_no)
Delete rule: CASCADE
Business Rule 4
Only items that are carried can be requested on an order.

Database Relationships

Before inserting or updating records in ITEMS, make sure P_NO matches a P_NO in the PRODUCTS table. Prevent deletion of a PRODUCTS table record if dependent ITEMS table records exist.
Primary key: products(p_no)
Foreign key: items(p_no)
Delete rule: RESTRICT
Batch SQL Example
As presented, these commands could be run through interactive or batch SQL (with SQLWizard).
CREATE TABLE customer (c_no SMALLINT NOT NULL,
    company CHAR(25), address CHAR(20), city CHAR(15),
    state CHAR(2), zip CHAR(5), phone CHAR(14),
    balance MONEY,
PRIMARY KEY (c_no));
CREATE UNIQUE INDEX custpkey ON customer(c_no)
CREATE TABLE employee (e_no SMALLINT NOT NULL,
    lname CHAR(10), fname CHAR(10), street CHAR(20),
    city CHAR(15), st CHAR(2), zip CHAR(5), dept CHAR(4),
    payrate MONEY, com DECIMAL(2,2),PRIMARY KEY (e_no));
CREATE UNIQUE INDEX emppkey ON employee(e_no)
CREATE TABLE products (p_no SMALLINT NOT NULL,
    description CHAR(18), price MONEY,PRIMARY KEY (p_no));
CREATE UNIQUE INDEX prodpkey ON products(p_no)
CREATE TABLE orders (o_no SMALLINT NOT NULL,
    c_no SMALLINT, o_date DATE, s_no SMALLINT,
    PRIMARY KEY (o_no),
    FOREIGN KEY bad_cust (c_no)
        REFERENCES customer ON DELETE RESTRICT,
    FOREIGN KEY bad_emp (s_no)
        REFERENCES employee ON DELETE SET NULL);
CREATE UNIQUE INDEX ordpkey ON orders(o_no)
CREATE TABLE items (o_no SMALLINT, p_no SMALLINT,
    quantity SMALLINT, price MONEY,
    FOREIGN KEY bad_ord(o_no)
        REFERENCES orders ON DELETE CASCADE,
    FOREIGN KEY bad_prod(p_no)
        REFERENCES products ON DELETE CASCADE);

If the tables already exist you can specify the referential constraints using the ALTER TABLE command. This simply requires that you append the appropriate PRIMARY KEY and FOREIGN KEY clauses onto an ALTER TABLE table-name clause. The CREATE INDEX commands would remain the same, but should be issued before the ALTER TABLE ... PRIMARY KEY commands.

Examining the System Catalog

Creating, dropping or altering a table causes the system to automatically update the sysibm.systables and sysibm.syscolumns tables. You can query the system catalog tables for table, view, column and index information. The query results can be formatted into your own reports. See XDB Server System Tables for a description of the system catalog tables.

Optionally, you can use SQLWizard to examine table definitions interactively. In addition, the Catalog Browser function of SQLWizard lists table, view and index definitions.

If a column is indexed, the name(s) of the index or indexes are listed after the column name, separated by a slash (/). Index type indicator codes (see the following table) appear in parentheses after the index name.

Next, the data type of the column is listed. The NOT NULL or NOT NULL WITH DEFAULT clauses specifies the null permission of the column. If omitted, nulls are permitted in the column.
Indicator | Meaning
no letter | Regular index (duplicate values permitted)
p | Primary key
c | Candidate (Unique) key
f | Foreign key
u | Unique index
no number | Single column index
# Compound index; # is sequence number indicating order of column in a compound index
Parent topic: SQL Statements


CREATE TABLESPACE

This statement defines a table space in the current location. A table space in the XDB Server system architecture is logically compatible with DB2 table spaces. However, an XDB Server table space does not physically store XDB Server table (.TAB) files. This XDB Server interpretation of table spaces differs from a DB2 subsystem, where a table space can physically store multiple tables. Refer to the appropriate DB2 documentation for details on the mainframe implementation of table spaces.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE TABLESPACE command, users must possess either DBADM, DBCTRL or DBMAINT authority for the database, overall SYSADM or SYSCTRL authority for the location, or the CREATETS privilege for the database.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE [LARGE | LOB] TABLESPACE tablespace-name
    [IN {DSNDB04 | database-name}]
    [using-block]
    [free-block]
    [GBPCACHE {CHANGED | ALL}]
    [trackmod-block]
    [LOG {YES | NO}]
    [DEFINE {YES | NO}]
    [DSSIZE integer G]
    [{NUMPARTS integer]
    [(PART integer {using-block | free-block | gbpcache-block | trackmod-block | COMPRESS {YES | NO})]
    [COMPRESS {NO | YES}] [,...])]|
    SEGSIZE integer}]
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [DSETPASS password]
    [COMPRESS {NO | YES}]
    [LOCKSIZE {ANY | TABLESPACE | TABLE | LOB | {PAGE | ROW}
    [LOCKMAX {0 | integer | SYSTEM}]}]
    [CCSID {ASCII | EBCDIC | UNICODE}]
    [LOCKPART {NO | YES}]
    [MAXROWS integer]

using-block:

USING {VCAT catalog-name
        | STOGROUP stogroup-name
            [PRIQTY {3 | integer}]
             [SECQTY {3 | integer}]
             [ERASE {NO | YES}]}

free-block:

[FREEPAGE {0 | integer}]
[PCTFREE {5 | integer}]gbpcache-block:[GBPCACHE {CHANGED | ALL | SYSTEM | NONE}]

trackmod-block:

[TRACKMOD {YES | NO}]

Parameters:

tablespace-name | Identifies a unique table space name under the current location. The table space can be explicitly qualified with a database name by using the IN database-name clause.but must not identify a table space, index space, or LOB table space that exists at the current server. If a database is not specified, the table space will be associated with the dsndb04 default database for the location.
database-name | Identifies a unique database name (under the current location) in which the table space is created. The system catalog database (dsndb06) must not be specified for any type of table space and a work file database must not be specified for a LOB table space. The default database is the DSNDB04 database for the current location.
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.

Description

In DB2, when you create tables in a table space, all of the tables are physically stored in the same DASD volume (assuming no storage groups). Both logically and physically, each table is in the same table space. On an XDB Server, you can create a table space and have several different tables logically associated with that table space. Physically, however, the tables are stored in their own .TAB files.

All mainframe-specific option clauses of the CREATE TABLESPACE command are recorded in the XDB Server system catalog. The XDB Server also checks the syntax for each option. The XDB Server system architecture does not physically support many of these clauses. Refer to appropriate DB2 documentation for complete descriptions of these mainframe-specific options.

With DB2 V7, XDB locations (either EBCDIC or ASCII) can now contain Unicode data. If you create a table space with CCSID UNICODE, all character data in corresponding tables is stored in UTF-8 format and all graphic data is stored in UTF-16 format.

LARGE

Identifies that each partition of a partitioned table space has a maximum partition size of 4 GB, which enables the table space to contain more than 64 GB of data. The preferred method to specify a maximum partition size of 4 GB and larger is the DSSIZE clause. The LARGE clause is for compatibility of releases of DB2 for OS/390 prior to Version 6. Do not specify LARGE if LOB or DSSIZE is specified.

LOB

Identifies the table space as LOB table space. A LOB table space is used to hold LOB values.

The LOB table space must be in the same database as its associated base table space.

PRIQTY integer

Specifies the minimum primary space allocation for a DB2-managed data set. The primary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

If PRIQTY integer is specified:

  • For 4KB page sizes, if integer is less than 12, n is 12.
  • For 8KB page sizes, if integer is less than 24, n is 24.
  • For 16KB page sizes, if integer is less than 48, n is 48.
  • For 32KB page sizes, if integer is less than 96, n is 96.
  • For any page size, if integer is greater than 4194304, n is 4194304.
  • If PRIQTY is omitted, n is 12, 24, 48, or 96 for 4KB, 8KB, 16KB, and 32KB page sizes, respectively.

For LOB table spaces, the exceptions are:

If PRIQTY integer is specified:

  • For 4KB page sizes, if integer is less than 200, n is 200.
  • For 8KB page sizes, if integer is less than 400, n is 400.
  • For 16KB page sizes, if integer is less than 800, n is 800.
  • For 32KB page sizes, if integer is less than 1600, n is 1600.
  • For any page size, if integer is greater than 4194304, n is 4194304.
  • If PRIQTY is omitted, n is 200, 400, 800, or 1600 for 4KB, 8KB, 16KB, and 32KB page sizes, respectively.

If you do not specify PRIQTY or specify PRIQTY -1, DB2 uses a default value for the primary space allocation.

DB2 specifies the primary space allocation to access method services using the smallest multiple of pKB not less than n, where p is the page size of the table space. The allocated space can be greater than the amount of space requested by DB2.

For example, it could be the smallest number of tracks that will accommodate the request. The amount of storage space requested must be available on some volume in the storage group based on VSAM space allocation restrictions. Otherwise, the primary space allocation will fail. To more closely estimate the actual amount of storage, see the description of the DEFINE CLUSTER command in DFSMS/MVS: Access Method Services for the Integrated Catalog.

Executing this statement causes only one data set to be created. However, you might have more data than this one data set can hold. DB2 automatically defines more data sets when they are needed. Regardless of the value in PRIQTY, when a data set reaches its maximum size, DB2 creates a new one. To avoid wasting space, use the following formula to make sure that PRIQTY and its associated secondary extent values do not exceed the maximum size of the data set:

PRIQTY + (number of extents * SECQTY) <= DSSIZE (implicit or explicit)

This clause is only implemented syntactically in the XDB Server operating environment.

SECQTY integer

Specifies the minimum secondary space allocation for a DB2-managed data set. If you do not specify SECQTY DB2 uses a formula to determine a value.

If you specify SECQTY and do not specify a value of -1, DB2 specifies the secondary space allocation to access method services using the smallest multiple of p KB not less than n, where p is the page size of the table space. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the request.

The secondary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

  • If SECQTY integer is specified and integer is greater than 4194304, n is 4194304. A value of 0 for integer indicates that no data set can be extended.
  • If SECQTY and PRIQTY are omitted:
    • For 4KB page sizes, n is 12.
    • For 8KB page sizes, n is 24.
    • For 16KB page sizes, n is 48.
    • For 32KB page sizes, n is 96.
  • If SECQTY is omitted and PRIQTY is specified, n is either 10% of PRIQTY or 3 times the page size of the table space, whichever is larger.

For LOB table spaces the exceptions are:

  • If SECQTY integer is specified:
    • For 4KB page sizes, if integer is greater than 0 and less than 200, n is 200.
    • For 8KB page sizes, if integer is greater than 0 and less than 400, n is 400.
    • For 16KB page sizes, if integer is greater than 0 and less than 800, n is 800.
    • For 32KB page sizes, if integer is greater than 0 and less than 1600, n is 1600.
    • For any page size, if integer is greater than 4194304, n is 4194304.
  • If SECQTY is omitted, n is either 10% of PRIQTY or 50 times the page size of the table space, whichever is larger.

DB2 specifies the secondary space allocation to access method services using the smallest multiple of pKB not less than n, where p is the page size of the table space. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the request.

This clause is only implemented syntactically in the XDB Server operating environment.

PCTFREE integer

Indicates what percentage of each page to leave as free space when the table is loaded or reorganized. integer can range from 0 to 99. The first record on each page is loaded without restriction. When additional records are loaded, at least integer percent of free space is left on each page.

The default is PCTFREE 5. Do not specify PCTFREE for a LOB table space, or a table space in a work file database or a TEMP database.

This clause is only implemented syntactically in the XDB Server operating environment.

TRACKMOD

Specifies whether DB2 tracks modified pages in the space map pages of the table space or partition. Do not specify TRACKMOD for a LOB table space. For a table space in a TEMP database, DB2 uses TRACKMOD NO regardless of the value specified.

YES DB2 tracks changed pages in the space map pages to improve the performance of incremental image copy. YES is the default unless the table space is in a TEMP database.
NO DB2 does not track changed pages in the space map pages. It uses the LRSN value in each page to determine whether a page has been changed.

If the table space is partitioned, the value of TRACKMOD for a particular partition is given by the first of these choices that applies:

  1. The value of TRACKMOD given in the PART clause for that partition.
  2. The value given in a trackmod-block that is not in any PART clause.

The default value YES.

This clause is only implemented syntactically in the XDB Server operating environment.

LOG

Specifies whether changes to a LOB column in the table space are to be written to the log. You can use the LOG clause only for a LOB table space.

YES Indicates that changes to a LOB column are to be written to the log. You cannot use YES if the auxiliary table in the table space stores a LOB column that is greater than 1 gigabyte in length.

YES is the default.

NO Indicates that changes to a LOB column are not to be written to the log.

LOG NO has no effect on a commit or rollback operation; the consistency of the database is maintained regardless of whether the LOB value is logged. All committed changes and changes that are rolled back reflect the expected results.

Even when LOG NO is specified, changes to system pages and to the auxiliary index are logged. During the log apply operation of the RECOVER utility, LPL recovery, or GPB recovery, all LOB values that were not logged are marked invalid and cannot be accessed by a SELECT or FETCH statement. Invalid LOB values can be updated or deleted.

This clause is only implemented syntactically in the XDB Server operating environment.

DSSIZE integer G

A value in gigabytes that indicates the maximum size for each partition or, for LOB table spaces, each data set. If you specify DSSIZE, you must also specify NUMPARTS or LOB.The following values are valid:

1G | 1 gigabyte
2G | 2 gigabytes
4G | 4 gigabytes
8G | 8 gigabytes
16G | 16 gigabytes
32G | 32 gigabytes
64G | 64 gigabytes

To specify a value greater than 4G, the following conditions must be true:

  • DB2 is running with DFSMS Version 1 Release 5.
  • The data sets for the table space are associated with a DFSMS data class that has been specified with extended format and extended addressability.

For all table spaces except LOB table spaces, if DSSIZE (or LARGE) is omitted, the default for the maximum size of each partition depends on the value of NUMPARTS:

If NUMPARTS is ...Maximum partition size is...

1 to 16 | 4 GB
17 to 32 | 2 GB
33 to 64 | 1 GB
65 to 254 | 4 GB

The partition size shown is not necessarily the actual number of bytes used or allocated for any one partition; it is the largest number that can be logically addressed. Each partition occupies one data set.

For LOB table spaces, if DSSIZE is not specified, the default for the maximum size of each data set is 4 GB. The maximum number of data sets is 254.

When you give a table space a DSSIZE value, you also give the same size to all the indexes that point to that tablespace.

This clause is only implemented syntactically in the XDB Server operating environment.

NUMPARTS integer

Indicates that the table space is partitioned.

Integer is the number of partitions, and can range from 1 to 254 inclusive. NUMPARTS must be specified if DSSIZE is specified and LOB is omitted, or LARGE is specified.

The maximum size of each partition depends on the value specified for DSSIZE or LARGE. If DSSIZE or LARGE is not specified, the number of partitions specified determines the maximum size of each partition

If you omit NUMPARTS, the table space is not partitioned and initially occupies one data set. Do not specify NUMPARTS for a LOB table space, or a table space in a work file database or a TEMP database.

LOCKSIZE

Specifies the size of locks used within the table space and, in some cases, also the threshold at which lock escalation occurs. Do not use this clause for a table space in a work file database or a TEMP database.

ANY | Specifies that DB2 can use any lock size. Currently, DB2 never chooses row locks, but reserves the right to do so. In most cases, DB2 uses LOCKSIZE PAGE LOCKMAX SYSTEM for non-LOB table spaces and LOCKSIZE LOB LOCKMAX SYSTEM for LOB table spaces. However, when the number of locks acquired for the table space exceeds the maximum number of locks allowed for a table space (an installation parameter), the page or LOB locks are released and locking is set at the next higher level. If the table space is segmented, the next higher level is the table. If the table space is nonsegmented, the next higher level is the table space.
TABLESPACE | Specifies table space locks.
TABLE | Specifies table locks. Use TABLE only for a segmented table space.
PAGE | Specifies page locks. Do not use PAGE for a LOB table space.
ROW | Specifies row locks. Do not use ROW for a LOB table space.
LOB | Specifies LOB locks. Use LOB only for a LOB table space.

This clause is only implemented syntactically in the XDB Server operating environment.

CCSID

The CCSID clause is only syntactically supported for EBCDIC and ASCII. This is because the definition of the XDB location itself defines how character data is stored.

If you specify UNICODE, your character and graphic data is stored as UNICODE within the table space.

LOCKMAX

Specifies the maximum number of page, row, or LOB locks an application process can hold simultaneously in the table space. If a program requests more than that number, locks are escalated. The page, row, or LOB locks are released and the intent lock on the table space or segmented table is promoted to S or X mode. If you specify LOCKMAX for table space in a TEMP database, DB2 ignores the value because these types of locks are not used.

Integer | Specifies the number of locks allowed before escalating, in the range 0 to 2 147 483 647. Zero (0) indicates that the number of locks on the table or table space are not counted and escalation does not occur.
SYSTEM | Indicates that the value of LOCKS PER TABLE(SPACE), on installation panel DSNTIPJ, specifies the maximum number of page, row, or LOB locks a program can hold simultaneously in the table or table space.
LOCKSIZE | Resultant LOCKMAX
ANY | SYSTEM
TABLESPACE, TABLE, PAGE ROW, or LOB | 0

If the lock size is TABLESPACE or TABLE, LOCKMAX must be omitted, or its operand must be 0.

For an application that uses Sysplex query parallelism, a lock count is maintained on each member.

This clause is only implemented syntactically in the XDB Server operating environment.

USING

XDB records either the catalog-name (preceded by VCAT keyword), or the stogroup-name (preceded by STOGROUP) that is associated with the table space. If the USING clause is left out, a default stogroup for the database must already exist. If a path has already been associated with stogroup-name (through the SYSIBM.SYSVOLUMES catalog table), then any objects created within the table space are implicitly located in that stogroup path.

CLOSE

When the limit on the number of open data sets is reached, specifies the priority in which data sets are closed.

YES | Eligible for closing before CLOSE NO data sets. This is the default unless the table space is in a TEMP database.
NO | Eligible for closing after all eligible CLOSE YES data sets are closed.

For a table space in a TEMP database, DB2 uses CLOSE NO regardless of the value specified.

COMPRESS

Either the option specified or the default value is recorded in the SYSIBM.SYSTABLEPART system catalog table. This option does not compress data in any way. Do not specify COMPRESS for a LOB table space or a table space in a TEMP database.

SEGSIZE integer

Indicates that the table space will be segmented. integer specifies how many pages are to be assigned to each segment. integer must be a multiple of 4 such that 4 <= integer <= 64. If the SEGSIZE clause is not specified, the table space is not segmented.

SEGSIZE must be specified for a table space in a TEMP database because the table space must be segmented. Do not specify SEGSIZE for a LOB table space or a table space in work file database; neither can be segmented.

A segmented table space cannot be partitioned. Therefore, do not specify NUMPARTS if you specify SEGSIZE.

This clause is only implemented syntactically in the XDB Server operating environment.

MAXROWS integer

Specifies the maximum number of rows that DB2 will consider placing on each data page. The integer can range from 1 through 255. This value is considered for INSERT, LOAD, and REORG. For LOAD and REORG (which do not apply for a table space in the TEMP database), the PCTFREE specification is considered before MAXROWS; therefore, fewer rows might be stored than the value you specify for MAXROWS.

If you do not specify MAXROWS, the default number of rows is 255.

Do not use MAXROWS for a LOB table space or a table space in a work file database.

This clause is only implemented syntactically in the XDB Server operating environment.

BUFFERPOOL

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for table spaces with 4K page sizes, while the last ten are for table spaces with 32K page sizes. Although not functionally supported, this new information is checked syntactically and recorded in the XDB Server system catalog tables.

If the table space is in a group buffer pool that is defined to be used only for cross-invalidation (GBPCACHE NO), CHANGED is ignored and no pages are cached to the group buffer pool.

Note:

When a table space is created in a workfile database, the following clauses are not allowed:

DEFINE NO | LOB | NUMPARTS
FREEPAGE | LOG | PCTFREE
GBPCACHE | LOCKSIZE | SEGSIZE

When a table space is created in a TEMP database, the following clauses are not allowed:

CCSID | GBPCACHE | LOG
COMPRESS | LARGE | MEMBER CLUSTER
DEFINE NO | LOB | NUMPARTS
DSSIZE | LOCKSIZE | PCTFEE
FREEPAGE | LOCKPART | TRACKMOD

When a LOB table space is created, the following clauses are not allowed:

CCSID | LOCKSIZE PAGE | PCTFREE
COMPRESS | LOCKSIZE ROW | SEGSIZE
FREEPAGE | NUMPARTS | LOCKSIZE TABLE
TRACKMOD |  |

If neither LOB, NUMPARTS, nor SEGSIZE are specified, the table space that is created is a simple table space.

Example:

The following example creates a table space named abc within the xyz database, while specifying the stor1 stogroup for that table space:

CREATE TABLESPACE abc IN xyz
    USING STOGROUP stor1;

In the above case, all objects created within the abc table space are stored in the path associated with the stor1 stogroup. This last result is true even if the logical database xyz is associated with a different stogroup.

In this example, assume that a column named EMP_PHOTO with a data type of BLOB(110K) has been added to the sample employee table for each employee's photo. Create LOB table space PHOTOLTS in database DSN8D61A for the auxiliary table that will hold the BLOB data.

Let DB2 define the data sets for the table space, using storage group DSN8G610. For each data set, the primary space allocation is 3200 kilobytes, and the secondary space allocation is 1600 kilobytes. The data sets do not need to be erased before they are deleted.

CREATE LOB TABLESPACE PHOTOLTS
    IN DSN8D61A
    USING STOGROUP DSN8G610
        PRIQTY 3200
        SECQTY 1600
    LOCKSIZE LOB
    BUFFERPOOL BP16K0
    GBPCACHE SYSTEM
    LOG NO
    CLOSE NO;
Parent topic: SQL Statements


CREATE TRIGGER

The CREATE TRIGGER statement defines a trigger in a schema and builds a trigger package at the current server.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set that is defined below must include all of the following:

Either of these privileges:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The TRIGGER privilege on the table. The privilege set must include at least one of the following:

  • The TRIGGER privilege on the table on which the trigger is defined
  • The ALTER privilege on the table on which the trigger is defined
  • DBADM authority on the database that contains the table
  • SYSADM or SYSCTRL authority

The SELECT privilege on the table on which the trigger is defined if any transition variables or transition tables are specified

The SELECT privilege on any table or view to which the search condition of triggered action refers

The EXECUTE privilege on any user-defined function or stored procedure that is invoked in the triggered action

The necessary privileges to invoke the triggered SQL statements in the triggered action

Syntax

CREATE TRIGGER trigger-name {NO CASCADE BEFORE | AFTER}
    {INSERT | DELETE | UPDATE [OF column-name[,...]]} ON table-name
    [REFERENCING {OLD [AS] correlation-name |
                  NEW [AS] correlation-name |
                  OLD TABLE [AS] identifier |
                  NEW TABLE [AS] identifier}
    {FOR EACH ROW | FOR EACH STATEMENT} MODE DB2SQL triggered-action]

triggered-action:

[WHEN (search-condition) BEGIN ATOMIC triggered-SQL-statement;... END]

Description

trigger-name

Names the trigger. The name is implicitly or explicitly qualified by a schema. The name, including the implicit or explicit schema name, must not identify a trigger that exists at the current server.

The name is also used to create the trigger package; therefore, the name must also not identify a package that is already described in the catalog. The schema name becomes the collection-id of the trigger package.

  • The unqualified form of trigger-name is a short SQL identifier. The unqualified name is implicitly qualified with a schema name according to the following rules:

    If the statement is embedded in a program, the schema name of the trigger is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name of the trigger is the owner of the package or plan.

    If the statement is dynamically prepared, the schema name of the trigger is the SQL authorization ID of the process.

  • The qualified form of trigger-name is a short SQL identifier (the schema name) followed by a period and a short SQL identifier. The schema name must not begin with 'SYS' unless the name is 'SYSADM'. The schema name that qualifies the trigger name is the trigger's owner.

The owner of the trigger is determined by how the CREATE TRIGGER statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

NO CASCADE BEFORE

Specifies that the trigger is a before trigger. XDB executes the triggered action before it applies any changes caused by an insert, delete, or update operation on the triggering table. It also specifies that the triggered action does not activate other triggers because the triggered action of a before trigger cannot contain any updates.

AFTER

Specifies that the trigger is an after trigger. XDB executes the triggered action after it applies any changes caused by an insert, delete, or update operation on the triggering table.

INSERT

Specifies that the trigger is an insert trigger. XDB executes the triggered action whenever there is an insert operation on the triggering table.

However, if the insert trigger is defined on PLAN_TABLE, DSN_STATEMNT_TABLE, or DSN_FUNCTION_TABLE, and the insert operation was

caused by XDB adding a row to the table, the triggered action is not be executed.

DELETE

Specifies that the trigger is a delete trigger. XDB executes the triggered action whenever there is a delete operation on the triggering table.

UPDATE

Specifies that the trigger is an update trigger. XDB executes the triggered action whenever there is an update operation on the triggering table.

If you do not specify a list of column names, an update operation on any column of the triggering table, including columns that are subsequently added with the ALTER TABLE statement, activates the triggered action.

OF column-name,... Each column-name that you specify must be a column of the subject table and must appear in the list only once. An update operation on any of the listed columns activates the triggered action.

ON table-name

Identifies the subject table with which the trigger is associated. The name must identify a base table at the current server. It must not identify a temporary table, an auxiliary table, an alias, a synonym, or a catalog table.

REFERENCING

Specifies the correlation names for the transition variables and the table names for the transition tables. For the rows in the subject table that are modified by the triggering SQL operation (insert, delete, or update), a correlation name identifies the columns of a specific row. A table name identifies the complete set of modified rows.

Each row that is modified by the triggering operation is available to the triggered action by using column names that are qualified with correlation names that are specified as follows:

OLD AS correlation-name | Specifies the correlation name that identifies the state of the row prior to the triggering SQL operation.
NEW AS correlation-name | Specifies the correlation name that identifies the state of the row as modified by the triggering SQL operation and by any SET statement in a before trigger that has already been executed.

The complete set of rows that is modified by the triggering operation is available to the triggered action by using a temporary table name that is specified as follows:

OLD TABLE AS identifier | Specifies the name of a temporary table that identifies the state of the complete set of rows that are modified rows by the triggering SQL operation prior to any actual changes. identifier is a long SQL identifier.
NEW TABLE AS identifier | Specifies the name of a temporary table that identifies the state of the complete set of rows as modified by the triggering SQL operation and by any SET statement in a before trigger that has already been executed. identifier is a long SQL identifier.

At most, the trigger definition can include two correlation names (OLD and NEW) and two table names (OLD TABLE and NEW TABLE). All the names must be unique from one another.

FOR EACH ROW

Specifies that XDB executes the triggered action for each row of the subject table that the triggering SQL operation modifies. If the triggering SQL operation does not modify any rows, the triggered action is not executed.

FOR EACH STATEMENT

Specifies that XDB executes the triggered action only once for the triggering SQL operation. Even if the triggering SQL operation does not modify any rows, the triggered action is executed once. Do not specify FOR EACH STATEMENT for a before trigger.

MODE DB2SQL

Specifies the mode of the trigger. Currently, XDB supports only MODE DB2SQL.

triggered-action

Specifies the action to be performed when the trigger is activated. The triggered action is composed of one or more SQL statements and by an optional condition that controls whether the statements are executed.

WHEN (search-condition) | Specifies a condition that evaluates to true, false, or unknown. The condition for a before trigger must not include a subselect that references the triggering table. The triggered SQL statements are executed only if the search condition evaluates to true, or if WHEN is omitted.
BEGIN ATOMIC triggered-SQL-statement;... END | Specifies the SQL statements that are to be executed for the triggered action. The statements are executed in the order in which you specify them. The keywords BEGIN ATOMIC and END are required only if you specify more than one SQL statement. In which case, you must enclose the SQL statements in these keywords and end each statement with a semicolon (;).

The statements in the triggered action have these restrictions:

  • They must not refer to host variables, parameter markers, undefined transition variables, or declared temporary tables.
  • They must only refer to a table or view that is at the current server.
  • They must only invoke a stored procedure or user-defined function that is at the current server. An invoked routine can, however, access a server other than the current server.
  • They must not contain a fullselect that refers to the subject table if the trigger is defined as BEFORE

The triggered action may refer to the values in the set of affected rows. This action is supported through the use of transition variables and transition tables.

Transition variables use the names of the columns in the subject table qualified by a specified name that identifies whether the reference is to the old value (before the update) or the new value (after the update). A transition variable can be referenced in search-condition or triggered-SQL-statement of the triggered action wherever a host variable is allowed in the statement if it were issued outside the body of a trigger.

Transition tables can be referenced in the triggered action of an after trigger. Transition tables are read-only. Transition tables also use the name of the columns of the subject table but have a name specified that allows the complete set of affected rows to be treated as a table. The name of the transition table can be referenced in triggered-SQL-statement of the triggered action whenever a table name is allowed in the statement if it were issued outside the body of a trigger. The name of the transition table can be specified in search-condition or triggered-SQL-statement of the triggered action whenever a column name is allowed in the statement if it were issued outside the body of a trigger.

In addition, a transition table can be passed as a parameter to a user-defined function or procedure specifying the TABLE keyword before the name of the transition table. When the function or procedure is invoked, a table locator is passed for the transition table.

A transition variable or transition table is not affected after being returned from a procedure invoked from within a triggered action regardless of whether the corresponding parameter was defined in the CREATE PROCEDURE statement as IN, INOUT, or OUT.

The implicitly created trigger package

When you create a trigger, DB2 automatically creates a trigger package with the same name as the trigger name. The collection name of the trigger package is the schema name of the trigger, and the version identifier is the empty string. Multiple versions of a trigger package are not allowed.

The user executing the triggering SQL operation does not need authority to execute a trigger package. The trigger package does not need to be in the package list for the plan that is associated with the program that contains the SQL statement.

A trigger package becomes invalid if an object or privilege on which it depends is dropped or revoked. The next time the trigger is activated, DB2 attempts to rebind the invalid trigger package. If the automatic rebind is unsuccessful, the trigger package remains invalid.

You cannot create another package from the trigger package, such as with the BIND COPY command. The only way to drop a trigger package is to drop the trigger or the triggering table. Dropping the trigger drops the trigger package; dropping the subject table drops the trigger and the trigger package.

DB2 creates the trigger package with the following attributes:

  • ACTION(ADD)
  • CURRENTDATA(YES)
  • DBPROTOCOL(DRDA)
  • DEGREE(1)
  • DYNAMICRULES(BIND)
  • ENABLE(*)
  • EXPLAIN(NO)
  • FLAG(I)
  • ISOLATION(CS)
  • NOREOPT(VARS) and NODEFER(PREPARE)
  • OWNER(authorization ID)
  • QUERYOPT(1)
  • PATH(path)
  • RELEASE(COMMIT)
  • SQLERROR(NOPACKAGE)
  • QUALIFIER(authorization ID)
  • VALIDATE(BIND)

The values of OWNER, QUALIFIER, and PATH are set depending on whether the CREATE TRIGGER statement is embedded in a program or issued interactively. If the statement is embedded in a program, OWNER and QUALIFIER are the owner and qualifier of the package or plan. PATH is the value from the PATH bind option. If the statement is issued interactively, both OWNER and QUALIFIER are the SQL authorization ID. PATH is the value in the CURRENT PATH special register.

This functionality is only implemented syntactically in the XDB Server operating environment.

Activating a trigger

Only the SQL statements INSERT, DELETE, or UPDATE, or an update or delete operation that occurs as the result of a referential constraint with ON DELETE SET NULL or ON DELETE CASCADE can activate a trigger. Loading a table with the LOAD utility does not activate any triggers that are defined for the table.

This functionality is only implemented syntactically in the XDB Server operating environment.

Simultaneously activated triggers

Multiple triggers that have the same triggering SQL operation and activation time (BEFORE or AFTER) can be defined on a table. The triggers are activated in the order in which they were created. For example, the trigger that was created first is executed first; the trigger that was created second is executed second; and so on.

This functionality is only implemented syntactically in the XDB Server operating environment.

Adding columns to subject tables or tables that the triggered action references

If a column is added to a table for which a trigger is defined (the subject table), the following rules apply:

  • If the trigger is an update trigger that was defined without an explicit list of column names, an update to the new column activates the trigger.
  • If the SQL statements in the triggered action refer to the subject table, the new column is not accessible to the SQL statements until the trigger package is rebound.
  • The transition tables contain the new column. If the transition tables are passed to a user-defined function or a stored procedure, the user-defined function or stored procedure must be recreated with the new definition of the table (that is, the function or procedure must be dropped and recreated), and the package for the user-defined function or stored procedure must be rebound.

If a column is added to any table to which the SQL statements in the triggered action refers, the new column is not accessible to the SQL statements until the trigger package is rebound.

This functionality is only implemented syntactically in the XDB Server operating environment.

Adding triggers to enforce constraints

Creating a trigger on a table that already has rows does not cause the triggered action to be executed. Thus, if the trigger is designed to enforce constraints on the data in the table, the data in the existing rows might not satisfy those constraints.

Defining triggers on plan, statement, and function tables: You can create a trigger on PLAN_TABLE, DSN_STATEMNT_TABLE, or DSN_FUNCTION_TABLE. However, insert triggers that are defined on these tables are not activated when XDB adds rows to the tables.

This functionality is only implemented syntactically in the XDB Server operating environment.

Renaming triggering tables or tables that the triggered action references

You cannot rename a table for which a trigger is defined (the triggering table). Except for the triggering table, you can rename any table to which the SQL statements in the triggered action refer. After renaming such a table, drop the trigger and then re-create the trigger so that it refers to the renamed table.

Dependencies when dropping objects and revoking privileges: The following dependencies apply to a trigger:

  • Dropping the subject table (the table on which the trigger is defined) causes the trigger and its package to also be dropped.
  • Dropping any table, view, alias, or index that is referenced or used within the SQL statements in the triggered action causes the trigger and its package to be invalidated. Dropping a referenced synonym has no effect.
  • Dropping a user-defined function that is referenced by the SQL statements in the triggered action is not allowed. An error occurs.
  • Revoking a privilege on which the trigger depends causes the trigger and its package to be invalidated.

This functionality is only implemented syntactically in the XDB Server operating environment.

Result sets for stored procedures

If a trigger invokes a stored procedure that returns result sets, the application that activated the trigger cannot access those result sets.

Values of special registers

The values of the special registers are saved before a trigger is activated and are restored on return from the

trigger.

Errors when binding triggers

When a CREATE TRIGGER statement is bound, the SQL statements within the triggered action may not be fully parsed. Syntax errors in those statements might not be caught until the CREATE TRIGGER statement is executed.

Errors when executing triggers

Severe errors that occur during the execution of triggered SQL statements are returned with SQLCODE -901, -906, -911, and -913 and the corresponding SQLSTATE. Non-severe errors raised by a triggered SQL statement that is a SIGNAL SQLSTATE statement or that contains a RAISE_ERROR function are returned with SQLCODE -438 and the SQLSTATE that is specified in the SIGNAL SQLSTATE statement or the RAISE_ERROR condition. Other non-severe errors are returned with SQLCODE -723 and SQLSTATE 09000.

Warnings are not returned.

Limiting processor time

XDB's resource limit facility allows you to specify the maximum amount of processor time for a dynamic, manipulative SQL statement (SELECT, INSERT, UPDATE, and DELETE). The execution of a trigger is counted as part of the triggering SQL statement.

Example:

Create two triggers that track the number of employees that a company manages. The subject table is the EMPLOYEE table, and the triggers increment and decrement a column with the total number of employees in the COMPANY_STATS table. The tables have these columns:

EMPLOYEE table: ID, NAME, ADDRESS, and POSITION

COMPANY_STATS table: NBEMP, NBPRODUCT, and REVENUE

This example shows the use of transition variables in a row trigger to maintain summary data in another table.

Create the first trigger, NEW_HIRE, so that it increments the number of employees each time a new person is hired; that is, each time a new row is inserted into the EMPLOYEE table, increase the value of column NBEMP in table COMPANY_STATS by 1.

CREATE TRIGGER NEW_HIRE
    AFTER INSERT ON EMPLOYEE
    FOR EACH ROW MODE DB2SQL
    BEGIN ATOMIC
        UPDATE COMPANY_STATS SET NBEMP = NBEMP + 1;
    END

Create the second trigger, FORM_EMP, so that it decrements the number of employees each time an employee leaves the company; that is, each time a row is deleted from the table EMPLOYEE, decrease the value of column NBEMP in table COMPANY_STATS by 1.

CREATE TRIGGER FORM_EMP
    AFTER DELETE ON EMPLOYEE
    FOR EACH ROW MODE DB2SQL
    BEGIN ATOMIC
        UPDATE COMPANY_STATS SET NBEMP = NBEMP - 1;
    END
Parent topic: SQL Statements


CREATE USER

The CREATE USER statement enables you to create additional XDB user accounts.

Syntax

CREATE USER username
         TYPE [ USER | SUPERUSER ]
         PASSWORD password REQUIRED [ YES | NO ]
         option_list

option-list:

SECONDARY ID authid
        GROUPS group_list
        PRIORITY priority
        ACCESS AUTHORITY [ YES | NO ]
        COMMENT quoted-string

Description

Requirements for XDB passwords can be controlled on an XDB user basis. ACCESS AUTHORITY set to NO completely disables an XDB user id. The SECONDARY ID, GROUPS, and PRIORITY concepts are all discussed in the section System Level Access Control in the Security and Authority chapter in your SQL Option Server Administration Guide

Parent topic: SQL Statements


CREATE VIEW

The CREATE VIEW command is used to define a view or virtual table that is based on one or more tables or views. The view definition is stored at the current location. While a view does not actually contain data, it provides indirect access to data contained in the tables upon which the view is based. Views may be used to define subsets of tables, or to combine data from several tables into a logical view. Views may contain expressions that are computed from other columns, including aggregate functions such as averages, totals, etc.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

For every table or view identified in the subselect of the CREATE VIEW statement, you must possess either DBADM authority for the database, SELECT privilege on the table or view, overall SYSADM or SYSCTRL authority for the location, or be the owner of the source table or view.

Authority requirements for using the view depend on the owner assigned to the view. (See the view-name parameter description under Syntax.) In order to use a view you must have the appropriate SELECT, UPDATE, INSERT, or DELETE privilege on the view.

The following authorization rules apply with using CREATE VIEW with an XDB Server:

  • If the AuthID for the application process possesses SYSADM authority, the view owner can be any AuthID.
  • If the view satisfies the rule in the previous bullet, and if the CREATE VIEW statement is error-free, the view is created, whether or not the owner has privileges on the tables and views identified in the view subselect.
  • If the AuthID for the application process does not possess SYSADM or SYSCTRL authority, only the AuthIDs of the process can own the view. In these circumstances, the view privileges match those held by the AuthID selected for ownership.

Syntax

CREATE VIEW view-name [(view-col-name[,...])]
    AS subselect [WITH [CASCADED | LOCAL] CHECK OPTION]

Parameters:

view-name Is any long identifier naming the view. This view name cannot have the same name as another view, table or synonym in the same location. If qualified, the name can be two-part or three-part name. If the name has three-parts, the first part must match the value of the CURRENT LOCATION register. The AuthID that qualifies the view name becomes the view owner. If the view name is unqualified in the CREATE VIEW statement, then the view owner is the SQL AuthID of the application process.

The view owner always acquires the authority to drop the view, as well as the SELECT privilege on the view. The owner must already possess grantable SELECT privileges on every table or view identified in the first FROM clause of the view subselect statement, in order to obtain a grantable SELECT privilege on the view. These grantable privileges must be acquired by the owner before the creation of the view.

INSERT, UPDATE and DELETE privileges on the view are also acquired by the owner if the view is not "read only." In these cases, the first FROM clause of the subselect identifies a single table or view only. If the owner already has either INSERT, UPDATE or DELETE privileges on this table or view, the owner acquires that privilege on the newly created view. These privileges are grantable only if the object privileges from which the view was derived are also grantable. These privileges must be acquired by the owner before the new view is created.

view-col-name | Any long identifier specifying a column in the view. Column names for views must satisfy the same naming criteria as table column names. If multiple view-col-name items are specified, the number of these columns must match the number of columns in the result table specified in the subselect. If the view-col-name list is missing, the view columns take the names of the columns specified in the subselect result table. If the result table of the subselect has duplicate column names or unnamed columns derived from constants, functions or expressions, a view-col-name list must be specified.
subselect | A SELECT command statement (following the keyword AS) producing a results table constituting the data contained in the view.

When creating views with subselects all referenced table(s) and all subselects in a single SQL statement must be from the same location -- which must also be the current location. subselect must not refer to any declared temporary tables. It must also not refer to host variables or include parameter markers (question marks). CREATE VIEW is not a DUW or RUW capable command.

Description

When a view is created or dropped, the system automatically updates the appropriate system catalog tables containing the definitions of all views in the current location. When a user queries the view, the system reads the view definition, and performs the corresponding query to obtain the result.

Note:

If you modify the underlying tables used by a view, you should drop the view and recreate it.

Updatable Views

When data in a view is updated, the changes are reflected in the underlying database table. For views to be updatable, the subselect used to define the view must satisfy the following criteria:

  • The query cannot contain DISTINCT.
  • The SELECT clause can contain only column names (no expressions or functions, including aggregate functions.)
  • The FROM clause can contain only one table name.
  • GROUP BY, ORDER BY or HAVING clauses are not permitted.

A simple way to determine whether a view can be defined as an updatable view is to attempt to create it using the WITH CHECK OPTION clause. If the view cannot be defined as updatable view, an error message is displayed.

CHECK OPTION must not be specified if any of the following conditions are true:

  • The view is read-only.
  • The search condition of the view includes a subquery, or the search condition of an underlying view includes a subquery.
  • The search condition of the view includes a user-defined function that is nondeterministic or has an external action.
  • The subselect refers to a created temporary table.

Expressions

Expressions, including those involving aggregate functions, are permitted in views. If expressions are selected, you must explicitly name all columns of the view. Such views are read-only views.

Joins

You may create views by joining other tables and views. The SELECT statement must explicitly name all columns if the tables or views being joined contain duplicate names. Views containing joins are read-only views.

GROUP BY and HAVING

Views defined using GROUP BY cannot be joined with another table or view. These views cannot be updated. HAVING clauses are allowed in view definitions containing GROUP BY.

ORDER BY

ORDER BY clauses are not permitted in the SELECT statement that defines a view.

UNION

The UNION operator cannot be used in the definition of a view.

WITH CHECK OPTION

The search condition of a view is specified in the first WHERE clause of the subselect that defines the view. The WITH CHECK OPTION specifies that every row of the view must conform to the search condition of this WHERE clause. The XDB Server enforces this constraint whenever rows of the view are inserted or updated. If an updatable view is created using the WITH CHECK OPTION clause, the system automatically tests whether inserts or updates to the view will satisfy the WHERE clause of the view definition. If they do not, the system signals an error, and any changes to the underlying tables are aborted.

To prevent the search condition of the view from checking insert or update operations, omit the WITH CHECK OPTION clause. This omission allows the insertion of "nonconforming" rows of data into the underlying table, as well as the updating of table rows in such a way that these rows will no longer be retrievable by the original view.

The two forms of the check option (CASCADED and LOCAL) are meaningful only when views are defined on each other. The view upon which another view is directly or indirectly defined is an underlying view.

  • CASCADED

    Update and insert operations must satisfy the search conditions of the view and underlying views, regardless of whether the underlying views were defined with a check option. This value is the default.

  • LOCAL

    Update and insert operations must satisfy the search conditions of the view and underlying views that are defined with a check option.

View Definitions

Creating or dropping a view causes the system to automatically update the SYSIBM.SYSTABLES, SYSIBM.SYSCOLUMNS and SYSIBM.SYSVIEWS catalog tables. Dropping a table or view causes all views dependent on that table or view to be dropped as well. You can query the system catalog tables for table, view, column and index information. The query results can be formatted into your own reports. See XDB Server System Tables for a list of the system catalog tables used for this purpose.

You can use SQLWizard to examine table definitions interactively. In addition, the Catalog Browser function of SQLWizard lists table, view and index definitions.

Read-only views

A view is read-only if one or more of the following statements is true of its definition:

  • The first FROM clause identifies more than one table or view, or identifies a table function
  • The first SELECT clause specifies the keyword DISTINCT
  • The outer subselect contains a GROUP BY clause
  • The outer subselect contains a HAVING clause
  • The first SELECT clause contains a column function
  • It contains a subquery such that the base object of the outer subselect, and of the subquery, is the same table
  • The first FROM clause identifies a read-only view

A read-only view cannot be the object of an INSERT, UPDATE, or DELETE statement. A view that includes GROUP BY or HAVING cannot be referred to in a subquery of a basic predicate.

Examples:

The following example defines a view that is a subset of the PART table. The optional view column list is omitted. The view column names will be the same as the PART table column names:

CREATE VIEW redparts AS
    SELECT *
        FROM part
        WHERE color = 'RED'
        WITH CHECK OPTION

If you retrieve all records from the REDPARTS view, the result would be:

pno | pname | color | weight | city
P1 | NUT | RED | 12 | LONDON
P4 | SCREW | RED | 14 | LONDON
P6 | COG | RED | 19 | LONDON

This view is not updatable. However, since the view was created using the WITH CHECK OPTION clause, you cannot update the view or insert any records into the view that do not satisfy the condition color = 'RED'.

The next example shows a read-only view defined by joining three tables, PART, SUPPLIER and PARTSUPP:

CREATE VIEW s_ps_p
    (s#, supplier, p#, part, quantity) AS
        SELECT sno, sname, pno, pname, qty
            FROM supplier s, partsupp ps, part p
            WHERE s.sno = ps.sno
              AND p.pno = ps.pno

If you retrieve all records from the S_PS_P view, the result would be:

s# | supplier | p# | part | quantity
S1 | SMITH | P1 | NUT | 300
S1 | SMITH | P3 | CAM | 400
S2 | JONES | P2 | BOLT | 400
S3 | BLAKE | P2 | BOLT | 200
S1 | SMITH | P2 | BOLT | 200
S1 | SMITH | P4 | SCREW | 200
S1 | SMITH | P5 | CAM | 100
S1 | SMITH | P6 | COG | 100
S2 | JONES | P1 | NUT | 300
S4 | CLARK | P2 | BOLT | 200
S4 | CLARK | P4 | SCREW | 300
S4 | CLARK | P5 | CAM | 400

The following is an example of a read-only view containing aggregate functions and a GROUP BY clause:

CREATE VIEW order_statistics
    (o_no, total_items, total_order) AS
    SELECT o_no, COUNT(p_no), SUM(quantity * price)
        FROM items
        GROUP BY o_no

Selecting all records from the view would produce the following result:

o_no | tot_items | total_order
1 | 1 | $120.00
2 | 2 | $985.00
3 | 1 | $240.00
4 | 2 | $830.00
5 | 2 | $2,070.00
Parent topic: SQL Statements


DECLARE CURSOR

The DECLARE CURSOR command (embedded SQL only) is used to define a cursor, which is a named control structure that points to a row in a set of records defined by a query.

Invocation

DECLARE CURSOR is not an executable statement. It can only be embedded in an application language.

Authorization

For each table (or view) identified in the SELECT portion of the DECLARE CURSOR statement, users must possess either DBADM authority for the corresponding database (tables only), the SELECT privilege on the table or view, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table or view.

The SELECT statement specified as an argument within the DECLARE CURSOR statement can be either a standard SELECT statement (select-statement) or a dynamically prepared (PREPARE command) select statement stored in a declared SQL statement (statement-name). Each of these distinct SELECT statement types must have access to different sets of authorization privileges in order to execute.

If a select-statement is specified, then the privileges available for this SELECT statement match those held by the CURRENT SQLID when the cursor is opened.

If a statement-name is specified, the available privileges for the prepared SELECT statement are a combination of the privileges held by the AuthID of the application process. The authorization check is performed when the SELECT statement is prepared. The cursor cannot be opened (OPEN command) unless the SELECT statement has been successfully prepared.

Syntax

DECLARE cursor-name
    [[NOSCROLL] | {ASENSITIVE | INSENSITIVE} SCROLL | SENSITIVE [DYNAMIC | STATIC] SCROLL]
    CURSOR [holdability | returnability | rowset-positioning [...]]
    FOR {select-statement | statement-name}

holdability

[WITH HOLD | WITHOUT HOLD]

returnability

[WITH RETURN [TO CALLER] | WITHOUT RETURN]

rowset-positioning

[WITH ROWSET POSITIONING | WITHOUT ROWSET POSITIONING]

Parameters:

cursor-name | Any valid identifier that names the new cursor and does not identify an already declared cursor in the source program.
select-statement | Specifies an actual query (SELECT statement) represented by the cursor. This SELECT statement can include host variables, the declarations for which must precede the DECLARE CURSOR statement in the source program.
statement-name | Indicates that the query occurring when opening the cursor originated from a prepared SELECT statement identified by statement-name. The statement-name must not match any other statement-name specified within any other DECLARE CURSOR statement in the source program.

Description

The DECLARE CURSOR command is only available when SQL is embedded in a host language such as COBOL or C. The DECLARE CURSOR command is checked for the following syntactical elements:

  • Is the command a SELECT or a statement-name? The SELECT may be a full select statement as defined in this reference. If it is a statement-name, it must be the name of a previously prepared SELECT command.
  • The DECLARE CURSOR statement must precede all commands that explicitly reference the cursor defined by the DECLARE CURSOR command.
  • A cursor may only be referenced within the source program in which it is defined.
Note:

The sample programs contain examples of declaring cursors.

NO SCROLL or SCROLL

Specifies whether the cursor is scrollable or not scrollable.

NO SCROLL

Specifies that the cursor is not scrollable. This is the default.

SCROLL

Specifies that the cursor is scrollable. For a scrollable cursor, whether the cursor has sensitivity to inserts, updates, or deletes depends on the cursor sensitivity option in effect for the cursor. If a sensitivity option is not specified, ASENSITIVE is the default. The sensitivity options include the following ones:

asensitivity

Specifies the desired sensitivity of the cursor to inserts, updates, or deletes that made to the rows underlying the result table. The sensitivity of the cursor determines whether XDB can materialize the rows of the result into a temporary table.

ASENSITIVE

Specifies that the cursor should be as sensitive as possible. This is the default.

A cursor that defined as ASENSITIVE will be either insensitive or sensitive dynamic; it will not be sensitive static.

INSENSITIVE

Specifies that the cursor does not have sensitivity to inserts, updates, or deletes that are made to the rows underlying the result table. As a result, the size of the result table, the order of the rows, and the values for each row do not change after the cursor is opened. In addition, the cursor is read-only. The SELECT statement or attribute-string of the PREPARE statement cannot contain a FOR UPDATE clause, and the cursor cannot be used for positioned updates or deletes.

SENSITIVE

Specifies that the cursor has sensitivity to changes that are made to the database after the result table is materialized. The cursor is always sensitive to updates and deletes that are made using the cursor (that is, positioned updates and deletes using the same cursor). When the current value of a row no longer satisfies the select-statement or statement-name, that row is no longer visible through the cursor. When a row of the result table is deleted from the underlying base table, the row is no longer visible through the cursor.

If XDB cannot make changes visible to the cursor, then an error is issued at bind time for OPEN CURSOR. XDB cannot make changes visible to the cursor when the cursor implicitly becomes read-only. Such is the case when the result table must be materialized, as when the FROM clause of the SELECT statement contains more than one table or view.

The default is DYNAMIC.

DYNAMIC

Specifies that the result table of the cursor is dynamic, meaning that the size of the result table may change after the cursor is opened as rows are inserted into or deleted from the underlying table, and the order of the rows may change. Rows that are inserted, deleted, or updated by statements that are executed by the same application process as the cursor are visible to the cursor immediately. Rows that are inserted, deleted, or updated by statements that are executed by other application processes are visible only after the statements are committed. If a column for an ORDER BY clause is updated via a cursor or any means outside the process, the next FETCH statement behaves as if the updated row was deleted and re-inserted into the result table at its correct location. At the time of a positioned update, the cursor is positioned before the next row of the original location and there is no current row, making the row appear to have moved.

If a SENSITIVE DYNAMIC cursor is not possible, an error is returned. For example, if a temporary table is needed (such as for processing a FETCH FIRST n ROWS ONLY clause), an error is returned. The SELECT statement of a cursor that is defined as SENSITIVE DYNAMIC cannot contain an INSERT statement.

STATIC

Specifies that the size of the result table and the order of the rows do not change after the cursor is opened. Rows inserted into the underlying table are not added to the result table regardless of how the rows are inserted. Rows in the result table do not move if columns in the ORDER BY clause are updated in rows that have already been materialized. Positioned updates and deletes are allowed if the result table is updatable. The SELECT statement of a cursor that is defined as SENSITIVE STATIC cannot contain an INSERT statement.

A STATIC cursor has visibility to changes made by this cursor using positioned updates or deletes. Committed changes made outside this cursor are visible with the SENSITIVE option of the FETCH statement. A FETCH SENSITIVE can result in a hole in the result table (that is, a difference between the result table and its underlying base table). If an updated row in the base table of a cursor no longer satisfies the predicate of its SELECT statement, an update hole occurs in the result table. If a row of a cursor was deleted in the base table, a delete hole occurs in the result table. When a FETCH SENSITIVE detects an update hole, no data is returned (a warning is issued), and the cursor is left positioned on the update hole. When a FETCH SENSITIVE detects a delete hole, no data is returned (a warning is issued), and the cursor is left positioned on the delete hole.

Updates through a cursor result in an automatic re-fetch of the row. This re-fetch means that updates can create a hole themselves. The re-fetched row also reflects changes as a result of triggers updating the same row. It is important to reflect these changes to maintain the consistency of data in the row.

Using a nondeterministic function (built-in or user-defined) in the WHERE clause of the select-statement or statement-name of a SENSITIVE STATIC cursor can cause misleading results. This situation occurs because XDB constructs a temporary result table and retrieves rows from this table for FETCH INSENSITIVE statements. When XDB processes a FETCH SENSITIVE statement, rows are fetched from the underlying table and predicates are re-evaluated. Using a nondeterministic function can yield a different result on each FETCH SENSITIVE of the same row, which could also result in the row no longer being considered a match.

A FETCH INSENSITIVE on a SENSITIVE STATIC SCROLL cursor is not sensitive to changes made outside the cursor, unless a previous FETCH SENSITIVE has already refreshed that row; however, positioned updates and delete changes with the cursor are visible.

STATIC cursors are insensitive to insertions.

WITH HOLD Clause

This optional clause prevents a commit operation from closing the cursor. Instead, a COMMIT statement logs all the changes from the current unit of work, leaving in place those locks required to maintain the cursor. After the commit operation, a single FETCH statement must initially be executed before a subsequently positioned UPDATE or DELETE statement can be executed on the cursor. After this FETCH, the cursor pointer can be advanced onto the next cursor row (or the row following the current row before the COMMIT). A ROLLBACK command, however, will close the cursor.

Omitting the WITH HOLD option from the cursor declaration causes that cursor to be implicitly closed by a COMMIT operation. A CONNECT or ROLLBACK operation also implicitly closes all cursors.

Closing a cursor before a COMMIT operation, has the same effect as declaring the cursor without the WITH HOLD option.

WITH RETURN Clause

This optional clause specifies that the cursor, if it is declared in a stored procedure, can return a result set to the caller.

Result Table

A result table is a temporary table of row data created when an OPEN command is issued against a previously declared cursor. This temporary table remains in memory until a CLOSE command is issued against the cursor (or a COMMIT or ROLLBACK occurs). The query criteria specified in the cursor's original PREPARE statement determines the row data retrieved into the result table. An opened (OPEN command) cursor consists of both a result table and a position pointer that moves among the table rows.

Read-Only Result Tables

A read-only result table occurs in any of the following situations:

  • When the first FROM clause of the cursor query identifies more than one table or view.
  • The first SELECT clause specifies the keyword DISTINCT.
  • The outer subselect contains either a GROUP BY or HAVING clause.
  • The first SELECT clause contains a column function.
  • The cursor contains a subquery in which the base table of the outer subselect is the same as the subquery table.
  • The first FROM clause of the cursor query identifies either a read-only view or a catalog table with no updatable columns.
  • The first FROM clause identifies a table function
  • The first FROM clause contains a nested table expression
  • A UNION or UNION ALL operator is present in the cursor query.
  • An ORDER BY clause or a FOR FETCH ONLY clause is present in the cursor query.

COBOL Usage

In COBOL source programs, a DECLARE CURSOR command is checked to verify whether host variables exist in either the LINKAGE or WORKING STORAGE section. In COBOL applications (as mentioned above), an application called from another application cannot use a cursor that was declared by the calling application. The scope of the cursor is the source program in which it is defined, which limits cursor references to statements precompiled along with the cursor declaration.

ExampleS:

The following COBOL language examples illustrate PREPARE, DECLARE, OPEN, and FETCH cursor statements:

EXEC SQL
    DECLARE d1 CURSOR FOR
        SELECT deptno, dname
            FROM dept
            WHERE mgrno = :mgrno
END-EXEC

or:

EXEC SQL
    PREPARE emp_in_dept FROM
        SELECT e_no, lname
            FROM employee
            WHERE dept = ?
END-EXEC

EXEC SQL
    DECLARE e1 CURSOR FOR emp_in_dept
END-EXEC

EXEC SQL
    OPEN e1 USING :deptnum
END-EXEC

EXEC SQL
    FETCH e1 INTO :enum, :last_name
END-EXEC
Parent topic: SQL Statements


DECLARE GLOBAL TEMPORARY TABLE

The DECLARE GLOBAL TEMPORARY TABLE statement defines a declared temporary table for the current application process and instantiates an empty instance of the table for the process.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required, unless the LIKE clause is specified when additional privileges might be required.

PUBLIC implicitly has the following privileges without GRANT authority for declared temporary tables:

  • The CREATETAB privilege to define a declared temporary table in the database that is defined AS TEMP, which is the database for declared temporary tables.
  • The USE privilege to use the table spaces in the database that is defined as TEMP.
  • All table privileges on the table and authority to drop the table. (Table privileges for a declared temporary table cannot be granted or revoked.)

These implicit privileges are not recorded in the DB2 catalog and cannot be revoked.

Syntax

DECLARE GLOBAL TEMPORARY TABLE table-name
{
    (column-spec[,...]) |
    LIKE {table-name | view-name} [INCLUDING INDENTITY [COLUMN ATTRIBUTES]] |
    AS (subselect) DEFINITION ONLY [as-attribute]
}
    [CCSID {EBCDIC | ASCII}]
    [ON COMMIT PRESERVE ROWS]

column-spec:

column-name data-type
[NOT NULL]
[[WITH] DEFAULT [constant | USER | CURRENT SQLID | NULL]]
[GENERATED {ALWAYS | BY DEFAULT} [as-identity-clause}]

as-attribute:

[INCLUDING IDENTITY [COLUMN ATTRIBUTES]]
[INCLUDING [COLUMN] DEFAULTS]
[USING TYPE DEFAULTS]

as-identity-clause:

AS IDENTITY
    [({START WITH {numeric-constant | 1} | INCREMENT BY {numeric-constant | 1} |
    {CACHE 20 | NO CACHE | CACHE integer}}][,..])]

table-name

Names the temporary table. The qualifier, if specified explicitly, must be SESSION. If the qualifier is not specified, it is implicitly defined to be SESSION.

If a table, view, synonym, or alias already exists with the same name and an implicit or explicit qualifier of SESSION:

  • The declared temporary table is still defined with SESSION.table-name. An error is not issued because the resolution of a declared temporary table name does not include the persistent and shared names in the XDB catalog tables.
  • Any references to SESSION.table-name will resolve to the declared temporary table rather than to any existing SESSION.table-name whose definition is persistent and is in the XDB catalog tables.

PUBLIC implicitly acquires ALL PRIVILEGES on the table and authority to drop the table. These implicit privileges are not recorded in the XDB catalog and cannot be revoked.

column-spec

Defines the attributes of a column for each instance of the table. The number of columns defined must not exceed 750. The maximum record size must not exceed 32714 bytes. The maximum row size must not exceed 32706 bytes (8 bytes less than the maximum record size).

column-name

Names the column. The name must not be qualified and must not be the same as the name of another column in the table.

data-type

Specifies the data type of the column. The data type can be any built-in data type that can be specified for the CREATE TABLE statement except for a LOB (BLOB, CLOB, and DBCLOB) or ROWID type. The FOR subtype DATA clause can be specified as part of data-type.

NOT NULL

Specifies that the column cannot contain nulls. Omission of NOT NULL indicates that the column can contain nulls.

DEFAULT

The default value assigned to the column in the absence of a value specified on INSERT. Do not specify DEFAULT for a column that is defined AS IDENTITY (an identity column); XDB generates default values.

If DEFAULT is not specified, the default value for the column is the null value.

If DEFAULT is specified without a value after it, the default value of the column depends on the data type of the column, as follows:

Data type | Default value
Numeric | 0
Fixed length string | Blanks
Varying-length string | A string of length 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP

A default value other than the one that is listed above can be specified in one of the following forms:

Constant | Specifies a constant as the default value for the column. The value of the constant must conform to the rules for assigning that value to the column.
USER | Specifies the value of the USER special register at the time of INSERT or LOAD as the default value for the column. If USER is specified, the data type of the column must be a character string with a length attribute greater than or equal to the length attribute of the USER special register, which is 8 bytes.
CURRENT SQLID | Specifies the value of the SQL authorization ID of the process at the time of INSERT or LOAD as the default value for the column. If CURRENT SQLID is specified, the data type of the column must be a character string with a length attribute greater than or equal to the length attribute of the CURRENT SQLID special register, which is 8 bytes.
NULL | Specifies null as the default value for the column.

In a given column definition:

  • NOT NULL and DEFAULT NULL cannot both be specified.
  • DEFAULT cannot be specified for an identity column.
  • Omission of NOT NULL and DEFAULT for a column other than an identity column is an implicit specification of DEFAULT NULL. For an identity column, it is an implicit specification of NOT NULL, and XDB generates default values.

GENERATED

Specifies that XDB generates values for the column. You must specify GENERATED if the column is to be considered an identity column (a column defined with the AS IDENTITY clause).

ALWAYS | Specifies that XDB always generates a value for the column when a row is inserted into the table.
BY DEFAULT | Specifies that XDB generates a value for the column when a row is inserted into the table unless a value is specified. BY DEFAULT is the recommended value only when you are using data propagation.
AS IDENTITY | Specifies that the column is an identity column for the table. A table can have only one identity column. AS IDENTITY can be specified only if the data type for the column is an exact numeric type with a scale of zero (SMALLINT, INTEGER, DECIMAL with a scale of zero).

LIKE table-name or view-name

Specifies that the columns of the table have exactly the same name and description as the columns of the identified table or view. The name specified must identify a table, view, synonym, or alias that exists at the current server. The identified table must not be an auxiliary table or a declared temporary table.

The privilege set must include the SELECT privilege on the identified table or view.

This clause is similar to the LIKE clause on CREATE TABLE, but it has the following differences:

  • If LIKE results in a column having a LOB data type, a ROWID data type, or distinct type, the DECLARE GLOBAL TEMPORARY TABLE statement fails.
  • In addition to these data type restrictions, if any column has any other attribute value that is not allowed in a declared temporary table, that attribute value is ignored. The corresponding column in the new temporary table has the default value for that attribute unless otherwise indicated.

When the identified object is a table, the column name, data type, nullability, and default attributes are determined from the columns of the specified table; any identity column attributes are inherited only if the INCLUDING IDENTITY COLUMN ATTRIBUTES clause is specified. When the identified object is a view, only the column name, data type, and nullability attributes are determined from the columns of the specified view.

INCLUDING IDENTITY COLUMN ATTRIBUTES Specifies that the new table inherits all of the identity attributes of the identity column. If the table identified by LIKE does not have an identity column, the INCLUDING IDENTITY clause is ignored. If the LIKE clause identifies a view, INCLUDING IDENTITY COLUMN ATTRIBUTES cannot be specified.

AS (subselect) DEFINITION ONLY

Specifies that the columns of the table are to have the same name and description as the columns that would appear in the derived result table of the subselect if the subselect were to be executed. The use of AS subselect is an implicit definition of n columns for the table, where n is the number of columns that would result from the subselect.

DEFINITION ONLY indicates that the subselect is not executed. Therefore, there is no result table with a set of rows with which to automatically populate the declared temporary table. However, you can use the INSERT INTO statement with the same subselect specified in the AS clause to populate the declared temporary table with the set of rows from the result table of the subselect.

The implicit definition includes all the attributes of the n columns of subselect that are applicable for a declared temporary table with the exception of these column attributes:

  • The default value assigned to a column when a value is not specified on INSERT
  • The identity attribute, if any

The behavior of these column attributes are controlled with the INCLUDING or USING TYPE DEFAULTS clauses, which are defined below.

If subselect results in a column having a LOB data type, a ROWID data type, or a distinct type, the DECLARE GLOBAL TEMPORARY statement fails.

If subselect results in other column attributes that are not applicable for a declared temporary table, those attributes are ignored in the implicit definition for the declared temporary table.

The implicitly defined columns of the declared temporary table inherit the names of the columns from the result table of the subselect. Therefore, a column name must be specified in the subselect for all result columns. For result columns that are derived from expressions, constants, and functions, the subselect must include the AS column-name clause immediately after the result column.

The subselect must not refer to host variables or include parameter markers (question marks).

INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that the declared temporary table inherits the identity attribute, if any, of the columns resulting from subselect. In general, the identity attribute is copied if the element of the corresponding column in the table, view, or subselect is the name of a table column or the name of a view column that directly or indirectly maps to the name of a base table column with the identity property. The columns of the new table do not inherit the identity attribute in the following cases:

  • The select list of the subselect includes multiple instances of an identity column name (that is, selecting the same column more than once).
  • The select list of the subselect includes multiple identity columns (that is, it involves a join).
  • The identity column is included in an expression in the select list.
  • The subselect includes a set operation (union).

If INCLUDING IDENTITY is not specified, the declared temporary table will not have an identity column.

INCLUDING COLUMN DEFAULTS

Specifies that the declared temporary table inherits the default values of the columns resulting from subselect. A default value is the value assigned to a column when a value is not specified on an INSERT.

Do not specify INCLUDING COLUMN DEFAULTS, if you specify USING TYPE DEFAULTS.

If neither INCLUDING COLUMN DEFAULTS nor USING TYPE DEFAULTS is specified, the default values of the columns of the declared temporary table are either null or there are no default values. If the column can be null, the default is the null value; if the column cannot be null, there is no default value, and an error occurs if a value is not provided for a column on an INSERT for the declared temporary table.

USING TYPE DEFAULTS

Specifies that the default values for the declared temporary table depend on the data type of the columns that result from subselect, as follows:

Data type | Default value
Numeric | 0
Fixed-length string | Blanks
Varying-length string | A string of length 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP

Do not specify USING TYPE DEFAULTS, if you specify INCLUDING COLUMN DEFAULTS.

ON COMMIT commit-action ROWS

Specifies whether the contents of the table are to be deleted or preserved across a commit operation.

DELETE | The rows of the table are deleted if no WITH HOLD cursors are open on the table. DELETE is the default.
PRESERVE | The rows of the table are preserved. Thread reuse capability is not available to any application process or thread that contains, at its most recent COMMIT, an active declared temporary table that was defined with the ON COMMIT PRESERVE ROWS clause.

Example:

Define a declared temporary table with column definitions for an employee number, salary, commission, and bonus.

DECLARE GLOBAL TEMPORARY TABLE SESSION.TEMP_EMP
   (EMPNO   CHAR(6)        NOT NULL,
    SALARY  DECIMAL(9, 2),
    BONUS   DECIMAL(9, 2),
    COMM    DECIMAL(9, 2))
    CCSID EBCDIC
    ON COMMIT PRESERVE ROWS;
Parent topic: SQL Statements


DECLARE STATEMENT

The DECLARE STATEMENT command (embedded SQL only) identifies prepared SQL statements for later use in application programs.

Invocation

DECLARE STATEMENT is not an executable statement. It can only be embedded in an application language.

Authorization

None required.

Syntax

DECLARE statement-name[,...] STATEMENT

Parameters:

statement-name Names one or more prepared SQL statements to be used in an application program.

Description

This nonexecutable statement is used in application programs to identify statement-name variables that can later be substituted for various kinds of SQL statements.

Example:

The C language example below first declares an SQL statement variable named mystatement. Next the contents of the host variable hostvar (typically the text of an SQL statement assembled in the host application) are placed into mystatement using the PREPARE command:

EXEC SQL
    DECLARE mystatement STATEMENT
;
...

EXEC SQL
    PREPARE mystatement FROM :hostvar
;
...
Parent topic: SQL Statements


DECLARE TABLE

The DECLARE TABLE statement (embedded SQL only) is used for application program documentation and providing the precompiler with information for checking embedded SQL statements.

Invocation

DECLARE TABLE is not an executable statement. It can only be embedded in an application language.

Authorization

None required.

Syntax

This command is supported only syntactically.

DECLARE {table-name | view-name}
    TABLE (column-name {built-in-data-type | distinct-type-name}
    [NOT NULL]
    [NOT NULL WITH DEFAULT] [,...])

This command is supported only syntactically.

DECLARE {table-name | view-name}
    TABLE (column-name {built-in-data-type | distinct-type-name}
    [NOT NULL]
    [NOT NULL WITH DEFAULT] [,...])

Parameters:

table-name or view-name Is the name of the table or view you want to document. If the table is defined in your application program, the description of the table in the SQL statement in which it is defined (for example, CREATE TABLE or DECLARE GLOBAL TEMPORARY TABLE statement) and the DECLARE TABLE statement must be identical.
column-definition One or more column definitions (separated by commas) can be chosen as specified below:
column-name data-type [NOT NULL]
[NOT NULL WITH DEFAULT]

Description

The XDB Server supports the DECLARE TABLE command syntactically only. The VALIDATE directive can be used to achieve the same functionality when precompiling. Use the Declaration Generator utility to generate declarations for tables and views. Mainframe DB2 users should use the DCLGEN utility.

built-in-data-type

Is the built-in data type of the column. Use one of the built-in data types.

distinct-type-name

Is the distinct type (user-defined data type) of the column. An implicit or explicit schema name qualifies the name.

Parent topic: SQL Statements


DELETE (Positioned)

The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).

Invocation

DELETE is an executable command that can be issued interactively or embedded in a host language. DELETE can be dynamically prepared. The Positioned DELETE command (explained below) can be used only with embedded SQL.

Authorization

Authorization requirements depend on whether the object identified in the statement is a table or a view. To execute the DELETE command on a table, users must possess either DBADM authority for the database containing the table, DELETE privilege on the table, overall SYSADM authority for the location, or be the owner of the table.

To execute the DELETE command on a view, users must possess the DELETE privilege on the view or have overall SYSADM authority. For more information on view privileges, see CREATE VIEW. If a subselect is specified within the view or table, the user must have the necessary privileges to execute the subselect.

To execute a DELETE at another location, the set of available privileges consists only of those privileges recorded in the system catalog at the location where the DELETE statement is to be executed.

Syntax

DELETE FROM {table-name | view-name}
    [correlation-name]
    WHERE CURRENT OF cursor-name
    [FOR ROW [host-variable | integer-constant] OF ROWSET]

Parameters:

table-name or view-name | Names an object (table or view) from which records are to be deleted. If a view name is identified, the view must be an updatable view since the underlying table will be affected. The named table or view may exist at a location other than the current location, as long as the correct location is either implicitly specified (SET LOCATION TO or CONNECT command precedes the DELETE command) or explicitly specified in the object name (location-name.AuthID.object-name).
correlation-name | Identifies an optional correlation name that then qualifies table or view column references within the search-condition.
search-condition | Determines which records to delete. Can be any valid query search condition, with each column name (other than in a subquery) identifying a column in table-name or view-name. The search condition must not include a subquery that also operates on either table-name or view-name.
cursor-name | Identifies a previously defined, opened, and fetched cursor, which points to the row to be deleted.

Description

Both Searched DELETE and Positioned DELETE are supported -- with the first type of command deleting one or more rows (with the option of including a WHERE clause), and the second type deleting only one row at a time, using the row pointer position within a cursor result table. When the DELETE command is embedded in a host language such as COBOL, C, or PL/I, it can contain host variables.

The Positioned DELETE can only be used in embedded SQL, since it involves the use of a previously defined cursor. When a positioned DELETE is executed, the row that the cursor currently points to is deleted.

When a record is deleted, the XDB Server simply marks the record as deleted. The data are still present in the table. If the Backward Log is set to ON, the ROLLBACK command can remove these delete markers and return the records to their former state. See the SELECT command for information on how to view records marked for deletion.

Index Considerations

If an index exists on a table, deleting records automatically updates the index. This could lead to a performance penalty if many records are deleted because each record deleted will cause the index to be updated. When deleting a large number of records from a table, it is sometimes more efficient to drop the index, delete the records, then re-create the index.

FOREIGN KEY Considerations

When deleting records from a table involved in a FOREIGN KEY constraint, the rule defined for the FOREIGN KEY will be followed. See the ALTER TABLE and CREATE TABLE commands for more information on deleting records containing FOREIGN KEYs.

DELETE vs. TRUNCATE TABLE

When deleting all records from a table, the TRUNCATE TABLE command can save time and system overhead. TRUNCATE TABLE deletes all records in a table without logging the deleted records or maintaining the table indexes. The system will not be able to rollback the deleted records. This command is not allowed on a table containing a primary key, since it may be referenced by another table.

WHERE CURRENT OF

This keyword clause identifies the cursor to be used in a positioned DELETE statement. The cursor-name specified must identify an already declared cursor. When a DELETE statement is executed, the cursor must already be positioned on the row to be deleted. After deleting the row, a FETCH statement should be executed to retrieve the next result table row.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Examples:

A sample DELETE statement appears below:

DELETE FROM partsupp
    WHERE sno = "S1"

This command deletes all the records where the supplier is S1.

The more complex example shown below deletes all suppliers who supply part P4:

DELETE FROM supplier
    WHERE sno IN
    SELECT sno
    FROM partsupp
    WHERE pno = "P4"

If the optional WHERE clause is not included, all records in the table are deleted. After the DELETE command is issued, the table will not contain any active records, but the table still exists and still appears in the directory of active tables. You cannot recover deleted records if DELETE is issued without a WHERE condition. You can reenter new data at any time using either the INSERT command or the SQLWizard data entry facility. For example, the following command removes all of the records from the SUPPLIER table:

DELETE FROM supplier

When the DELETE command is embedded in a host language, it must appear within the "EXEC SQL ... END-EXEC" or "EXEC SQL ...;" delimiters, as required by the XDB Server host language preprocessor. The following COBOL language example shows a positioned DELETE command. It is assumed that the cursor EMPTBL has been declared, opened and fetched to the row desired:

EXEC SQL
    DELETE FROM employee
    WHERE CURRENT OF emptbl;
Parent topic: SQL Statements
Related reference
CREATE VIEW
SELECT
ALTER TABLE
CREATE TABLE
DELETE (Searched)


DELETE (Searched)

The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).

Invocation

DELETE is an executable command that can be issued interactively or embedded in a host language. DELETE can be dynamically prepared.

Authorization

Authorization requirements depend on whether the object identified in the statement is a table or a view. To execute the DELETE command on a table, users must possess either DBADM authority for the database containing the table, DELETE privilege on the table, overall SYSADM authority for the location, or ownership of the table.

To execute the DELETE command on a view, users must possess the DELETE privilege on the view or have overall SYSADM authority. For more information on view privileges, see CREATE VIEW. If a subselect is specified within the view or table, the user must have the necessary privileges to execute the subselect.

To execute a DELETE at another location, the set of available privileges consists only of those privileges recorded in the system catalog at the location where the DELETE statement is to be executed.

The SELECT privilege is required in addition to the DELETE privilege when the option for the SQL standard is set as follows:

  • For static SQL statements, if the SQLRULES (STD) bind option was specified
  • For dynamic SQL statements, if the CURRENT RULES special register is set to STD

Syntax

DELETE FROM {table-name | view-name} [correlation-name]
    [WHERE search-condition]
    [WITH {CS | RR}][QUERYNO integer]

Description

Both Searched DELETE and Positioned DELETE are supported -- with the first type of command deleting one or more rows (with the option of including a WHERE clause), and the second type deleting only one row at a time, using the row pointer position within a cursor result table. When the DELETE command is embedded in a host language such as COBOL, C, or PL/I, it can contain host variables.

The Searched DELETE uses the standard SQL syntax for a DELETE statement, which relies on a WHERE condition to determine the records to be deleted. The WHERE condition is defined in the same way as it would be for a SELECT command. To determine which records a searched DELETE command will delete, first SELECT from the table using the same WHERE condition. See WHERE Clause for more information on searching for records.

When using subselects as search conditions, the subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

DELETE FROM tutorial.tutorial.employee
    WHERE e_no IN
        SELECT e_no FROM debloc.debbie.employee
            WHERE st = "MD";

Valid:

DELETE FROM tutorial.tutorial.employee
    WHERE e_no IN
        SELECT e_no FROM tutorial.debbie.employee
            WHERE st = "MD";
Note:

If no WHERE condition is specified, all records in the table are deleted.

When a record is deleted, the XDB Server simply marks the record as deleted. The data are still present in the table. If the Backward Log is set to ON, the ROLLBACK command can remove these delete markers and return the records to their former state. See the SELECT command for information on how to view records marked for deletion.

Index Considerations

If an index exists on a table, deleting records automatically updates the index. This could lead to a performance penalty if many records are deleted because each record deleted will cause the index to be updated. When deleting a large number of records from a table, it is sometimes more efficient to drop the index, delete the records, then re-create the index.

FOREIGN KEY Considerations

When deleting records from a table involved in a FOREIGN KEY constraint, the rule defined for the FOREIGN KEY will be followed. See the ALTER TABLE and CREATE TABLE commands for more information on deleting records containing FOREIGN KEYs.

DELETE vs. TRUNCATE TABLE

When deleting all records from a table, the TRUNCATE TABLE command can save time and system overhead. TRUNCATE TABLE deletes all records in a table without logging the deleted records or maintaining the table indexes. The system will not be able to rollback the deleted records. This command is not allowed on a table containing a primary key, since it may be referenced by another table.

WHERE

This keyword identifies rows to be deleted in a searched DELETE. If WHERE is omitted, all rows of the table or view named are deleted. The search condition following the WHERE keyword is applied to each row of the named table or view, deleting all rows for which the search condition is true. A subquery with no correlated references will be executed just once. A subquery with a correlated reference will be executed once for each row identified in the WHERE clause.

WITH Clause

Specifies an isolation level with which the statement is executed in Searched DELETE statements. You can override the isolation level of the statement using the new WITH {RR | CS} clause. Because WITH UR only applies to read only operations, you cannot use it on a DELETE statement. The WITH clause overrides the default isolation level only for the statement in which it appears.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Searched DELETE and SQL standard rules

If SQL standard rules are in effect and the search-condition in a searched DELETE contains a reference to a column of the table or view, the privilege set must include at least one of the following:

  • The SELECT privilege on the table or view
  • SYSADM authority

SQL standard rules are in effect as follows:

  • For static SQL statements, if the SQLRULES(STD) bind option was specified
  • For dynamic SQL statements, if the CURRENT RULES special register is set to 'STD

Examples:

A sample DELETE statement appears below:

DELETE FROM partsupp
    WHERE sno = "S1"

This command deletes all the records where the supplier is S1.

The more complex example shown below deletes all suppliers who supply part P4:

DELETE FROM supplier
    WHERE sno IN
        SELECT sno
            FROM partsupp
            WHERE pno = "P4"

If the optional WHERE clause is not included, all records in the table are deleted. After the DELETE command is issued, the table will not contain any active records, but the table still exists and still appears in the directory of active tables. You cannot recover deleted records if DELETE is issued without a WHERE condition. You can reenter new data at any time using either the INSERT command or the SQLWizard data entry facility. For example, the following command removes all of the records from the SUPPLIER table:

DELETE FROM supplier

When the DELETE command is embedded in a host language, it must appear within the "EXEC SQL ... END-EXEC" or "EXEC SQL ...;" delimiters, as required by the XDB Server host language preprocessor. The following COBOL language example shows a searched DELETE command containing a host variable in the WHERE clause:

EXEC SQL
    DELETE FROM employee
    WHERE lname = :ENAME
END-EXEC
Parent topic: SQL Statements
Related reference
CREATE VIEW
SELECT
ALTER TABLE
CREATE TABLE
DELETE (Positioned)
Related information
WHERE Clause Syntax and Description


DESCRIBE

The DESCRIBE statement (embedded SQL only) obtains information about a previously prepared (PREPARE command) SQL statement and places this information inside an SQL Descriptor Area (SQLDA). This information is needed in dynamic SQL queries that utilize a varying-list SELECT statement. A varying-list SELECT statement is a SELECT statement where the number of columns retrieved is not known before run time. Alternatively, the DESCRIBE statement can provide information about a specified table or view.

Invocation

DESCRIBE is an executable command that can only be embedded in a host language. DESCRIBE cannot be dynamically prepared.

Authorization

No special privileges are required when describing a prepared statement. However, when describing a table or view, the privileges held by the AuthID owning the application must include either ownership of the table, SELECT, INSERT, UPDATE, or DELETE privilege on the table or view, ALTER or INDEX privilege on the table, DBADM authority over the database containing the object (tables only), or SYSADM or SYSCTRL authority for the location.

See the PREPARE statement description for authorization privileges required to prepare a command.

Syntax

DESCRIBE {statement-name | TABLE host-variable}
    INTO descriptor-name [USING {NAMES | LABELS | ANY | BOTH}]

Parameters:

statement-name | Identifies an SQL statement already prepared by an application process at the current location.
host-variable | The combination of the keyword TABLE followed by host-variable, identifies a table or view. The name must not identify an auxiliary table
descriptor-name | preceded by the keyword INTO, names an SQL Descriptor Area (SQLDA) variable.

Description

You may have a uniquely named SQLDA defined for every cursor utilized in an application process. When the DESCRIBE statement is applied to a prepared query statement, the information returned to the specified SQLDA describes the columns of the result table (for that cursor). When a table or view is named in the DESCRIBE statement, the information returned in the SQLDA defines the columns in the table or view.

The SQLDA must be allocated before the DESCRIBE statement is executed. Once allocated, the SQLDA consists of the SQLDAID, SQLDABC, SQLN, and SQLD fields followed by the SQLVAR array structure (containing one or more occurrences). The number of elements within the SQLVAR must be equal to or greater than the number of columns in the described table. For more details on the SQLDA, see XDB Server SQL Descriptor Area (SQLDA).

Before executing the DESCRIBE statement, the SQLN field in the SQLDA must be set to indicate the number of SQLVAR occurrences in the SQLDA (this value is not changed by the XDB Server). Once SQLN is determined, performance can be improved by resetting this value after the DESCRIBE statement is first executed. With the exception of SQLN, all other SQLDA fields are set by the XDB Server software or are ignored, as indicated in the field descriptions below. Please note that the following descriptions do not necessarily apply to SQLDA usage with PREPARE, EXECUTE, OPEN, and FETCH statements:

  • SQLDAID is set to "SQLDA" by the XDB Server software.
  • SQLDABC is the length of the SQLDA in bytes, and equals SQLN*44+16 (as set by the XDB Server software).
  • SQLD is set to either the number of columns in the object being described or to zero (if DESCRIBE is applied to a nonquery statement). In order for the SQLDA to be large enough for the information requested, the returned value of SQLD must be less than or equal to the value of SQLN. If SQLD is larger than SQLN, no information is returned from the query into the SQLDA.
  • SQLVAR array values are assigned for each column in the object being described, such that the first array value describes the first column in the object, the second array value describes the second column, etc.
  • SQLTYPE is a code indicating the data type of the column and whether or not the column can contain null values.
  • SQLLEN is the length of the result column, which varies according to the data type of the column.
  • SQLDATA stores a dynamic memory address for the column.
  • SQLIND stores an indicator variable address for nullable columns.
  • SQLNAME is the unqualified name of the column.

Allocating SQLDA

To aid in the allocation of SQLDA memory space, first execute a DESCRIBE statement into an SQL Descriptor Area where the SQLN variable is deliberately set to zero. The value returned for the SQLD variable will equal the number of columns that need to be processed in the select list (which is the required value of SQLN). Use this returned value of SQLD to allocate another SQLDA, with the SQLN value preset to at least SQLD (or more) occurrences of the SQLVAR array. Execute the DESCRIBE statement again specifying this new SQLDA.

  • First technique

    Allocate an SQLDA with enough occurrences of SQLVAR to accommodate any select list that the application will have to process. At the extreme, the number of SQLVARs could equal three times the maximum number of columns allowed in a result table. After the SQLDA is allocated, the application can use the SQLDA repeatedly.

    This technique uses a large amount of storage that is never deallocated, even when most of this storage is not used for a particular select list.

  • Second technique

    Repeat the following for every processed select list:

    1. Execute a DESCRIBE statement with an SQLDA that has no occurrences of SQLVAR; that is, an SQLDA for which SQLN is zero.
    2. Allocate a new SQLDA with enough occurrences of SQLVAR. Use the values that are returned in SQLD and SQLCODE to determine the number of SQLVAR entries that are needed. The value of SQLD is the number of columns in the result table, which is either the required number of occurrences of SQLVAR or a fraction of the required number If the SQLCODE is +236, +237, +238, or +239, the number of SQLVAR entries that is needed is two or three times the value in SQLD, depending on whether USING BOTH was specified. Set SQLN to reflect the number of SQLVAR entries that have been allocated.
    3. Execute the DESCRIBE statement again, using the new SQLDA.

    This technique allows better storage management than the first technique, but it doubles the number of DESCRIBE statements.

  • Third technique

    Allocate an SQLDA that is large enough to handle most (hopefully, all) select lists but is also reasonably small. If an execution of DESCRIBE fails because SQLDA is too small, allocate a larger SQLDA and execute the DESCRIBE statement again.

    For the new larger SQLDA, use the values that are returned in SQLD and SQLCODE from the failing DESCRIBE statement to calculate the number of occurrences of SQLVAR that are needed, as described in technique two. Remember to check for SQLCODEs +236, +237, +238, and +239, which indicate whether extended SQLVAR entries are needed because the data includes LOBs or distinct types.

    This third technique is a compromise between the first two techniques. Its effectiveness depends on a good choice of size for the original SQLDA.

SQLDAID

XDB sets the first 6 bytes to 'SQLDA ' (5 letters followed by the space character) and the eighth byte to a space character. The seventh byte is set to indicate the number of SQLVAR entries that are needed to describe each column of the result table as follows:

space

The value of space occurs when:

  • USING BOTH was not specified and the columns being described do not include LOBs or distinct types. Each column only needs one SQLVAR entry. If the SQL standard option is yes, XDB sets SQLCODE to warning code +236. Otherwise, SQLCODE is zero.
  • USING BOTH was specified and the columns being described do not include LOBs or distinct types. Each column needs two SQLVAR entries. XDB sets SQLD to two times the number of columns of the result table. The second set of SQLVARs is used for the labels.

2

Each column needs two SQLVAR entries. Two entries per column are required when:

  • USING BOTH was not specified and the columns being described include LOBs or distinct types or both. XDB sets the second set of SQLVAR entries with information for the LOBs or distinct types being described.
  • USING BOTH was specified and the columns include LOBs but not distinct types. XDB sets the second set of SQLVAR entries with information for the LOBs and labels for the columns being described.

3

Each column needs three SQLVAR entries. Three entries are required only when USING BOTH is specified and the columns being described include distinct types. The presence of LOB data does not matter. It is the distinct types and not the LOBs that cause the need for three SQLVAR entries per column when labels are also requested. XDB sets the second set of SQLVAR entries with information for the distinct types (and LOBs, if any) and the third set of SQLVAR entries with the labels of the columns being described.

SQLD

If the prepared statement is a query, XDB sets the value to the number of columns in the object being described (the value is actually twice the number of columns in the case where USING BOTH was specified and the result table does not include LOBs or distinct types).

Otherwise, if the statement is not a query, XDB sets the value to 0.

SQLVAR

An array of field description information for the column being described. There are two types of SQLVAR entries--the base SQLVAR and the extended SQLVAR.

If the value of SQLD is 0, or is greater than the value of SQLN, no values are assigned to any occurrences of SQLVAR. If the value of SQLN was set so that there are enough SQLVAR occurrences to describe the specified columns (columns with LOBs or distinct types and a request for labels increase the number of SQLVAR entries that are needed), the values are assigned to the first n occurrences of SQLVAR so that the first occurrence of SQLVAR contains a description of the first column, the second occurrence of SQLVAR contains a description of the second column, and so on. This first set of SQLVAR entries are referred to as base SQLVAR entries. Each column always has a base SQLVAR entry.

If the DESCRIBE statement included the USING BOTH clause, or the columns being described include LOBs or distinct types, additional SQLVAR entries are needed. These additional SQLVAR entries are referred to as the extended SQLVAR entries. There can be up to two sets of extended SQLVAR entries for each column.

The base SQLVAR

SQLTYPE | A code that indicates the data type of the column and whether the column can contain null values.
SQLLEN | A length value depending on the data type of the result columns. SQLLEN is 0 for LOB data types.
SQLDATA | The CCSID of a string column.
SQLIND | Reserved.
SQLNAME | The unqualified name or label of the column, depending on the value of USING (NAMES, LABELS, ANY, or BOTH). The field is a string of length 0 if the column does not have a name or label.

The extended SQLVAR

SQLLONGLEN | The length attribute of a BLOB, CLOB, or DBCLOB column.
* | Reserved.
SQLDATALEN | Not Used.
SQLDATATYPE-NAME | For a distinct type, the fully qualified distinct type name. Otherwise, the value is the fully qualified name of the built-in data type. For a label, the label for the column.

USING

Indicates what value to assign to each SQLNAME variable in the SQLDA. If the requested value does not exist, SQLNAME is set to a length of 0.

NAMES | Assigns the name of the column. This is the default.
LABELS | Assigns the label of the column. (Column labels are defined by the LABEL ON statement.)
ANY | Assigns the column label, and if the column has no label, the column name.
BOTH | Assigns both the label and name of the column. In this case, two or three occurrences of SQLVAR per column, depending on whether the result set contains distinct types, are needed to accommodate the additional information. To specify this expansion of the SQLVAR array, set SQLN to 2¦n or 3¦n, where n is the number of columns in the object being described. For each of the columns, the first n occurrences of SQLVAR, which are the base SQLVAR entries, contain the column names. Either the second or third n occurrences of SQLVAR, which are the extended SQLVAR entries, contain the column labels. If there are no distinct types, the labels are returned in the second set of SQLVAR entries. Otherwise, the labels are returned in the third set of SQLVAR entries.

For a declared temporary table, the name of the column is assigned regardless of the value specified in the USING clause because declared temporary tables cannot have labels.

Performance considerations

Although XDB does not change the value of SQLN, you might want to reset this value after the DESCRIBE statement is executed. If the contents of SQLDA from the DESCRIBE statement is used in a later FETCH statement, set SQLN to n (where n is the number of columns of the result table) before executing the FETCH statement.

Example:

EXEC SQL
    DESCRIBE getcust INTO mydesc
END-EXEC

where mydesc is a defined SQLDA in working storage and getcust is a previously prepared command.

Parent topic: SQL Statements


DESCRIBE CURSOR

The DESCRIBE CURSOR statement gets information about the result set that is associated with the cursor. The information, such as column information, is put into a descriptor. Use DESCRIBE CURSOR for result set cursors from stored procedures. The cursor must be defined with the ALLOCATE CURSOR statement.

Invocation

This statement can be embedded in an application program only. It is an executable statement that cannot be dynamically prepared.

Authorization

No authorization is required for this statement.

Syntax

DESCRIBE CURSOR {cursor-name | host-variable}
    INTO descriptor-name

Parameters:

cursor- name | Indentifies a cursor by the specified cursor name. The name must identify a cursor that has already been allocated in the source program.
host-variable | Indentifies a cursor by the cursor name contained in the host variable. The name must identify a cursor that has already been allocated in the source program.
descriptor-name | Identifies an SQL descriptor area (SQLDA). The information returned in the SQLDA describes the columns in the result set associated with the named cursor.
Note:

For the statement to execute successfully, the application program must be connected to the site at which the stored procedure was executed.

Parent topic: SQL Statements


DESCRIBE INPUT Example

Execute a DESCRIBE INPUT statement with an SQLDA that has enough SQLVAR occurrences to describe any number of input parameters a prepared statement might have. Assume that five parameter markers at most will need to be described and that the input data does not contain LOBs.

/* STMT1_STR contains INSERT statement with VALUES clause */

EXEC SQL PREPARE STMT1_NAME FROM :STMT1_STR;

/* code to set SQLN to 5 and to allocate the SQLDA */

EXEC SQL DESCRIBE INPUT STMT1_NAME INTO :SQLDA;
Parent topic: SQL Statements


DESCRIBE PROCEDURE

The DESCRIBE PROCEDURE statement gets information about the result sets returned by a stored procedure. The information, such as the number of result sets, is put into a descriptor.

Invocation

This statement can be embedded in an application program only. It is an executable statement that cannot be dynamically prepared.

Authorization

No authorization is required for this statement.

Syntax

DESCRIBE PROCEDURE {procedure-name | host-variable}
    INTO descriptor-name

Parameters:

procedure-name | Identifies the stored procedure to describe by the specified procedure name.
host-variable | Identifies the stored procedure to describe by the procedure name contained in the host variable.
descriptor-name | Identifies an SQL descriptor area (SQLDA). The information returned in the SQLDA describes the result sets returned by the stored procedure. Considerations for allocating and initializing the SQLDA are similar to those for DESCRIBE TABLE.

Description

When the DESCRIBE PROCEDURE statement is executed, the procedure name or specification must identify a stored procedure that the requestor has already invoked by using a CALL statement.

A procedure name is a qualified or unqualified name. Each part of the name is a long SQL identifier that must be composed of SBCS characters:

  • A fully qualified procedure name is a three-part name. The first part is a location name that identifies the DBMS at which the procedure is stored. The next two parts identify the stored procedure. The last part is a long identifier that contains the name of the stored procedure. A period must separate each of the parts.
  • An implicitly qualified procedure name is a two-part name that is qualified by the location name of the current server. The name and its implicit qualifier identifies a stored procedure. A period must separate the two parts. The first part identifies the stored procedure at the server. The meaning of the first part depends on the application server.
  • An unqualified procedure name is a one-part name with two implicit qualifiers. The first implicit qualifier is the location name of the current server. The second implicit qualifier identifies the stored procedure at the server. The meaning of the second implicit qualifier depends on the application server (for MVS, the qualifier is SYSPROC). The name and its implicit qualifiers identifies a stored procedure.

If a host variable is used:

  • It must be a character string variable with a length attribute that is not greater than 254.
  • It must be preceded by a colon and must not be followed by an indicator variable.
  • The value of the host variable is a specification that depends on the application server. Regardless of the application server, the specification must:
    • Be left justified within the host variable
    • Not contain embedded blanks
    • Be padded on the right with blanks if its length is less than that of the host variable

The procedure name in the DESCRIBE PROCEDURE statement must be specified the same way that it was specified on the CALL statement. For example, if a two-part name was specified on the CALL statement, you must use a two-part name in the DESCRIBE PROCEDURE statement. However, there is one condition under which the names do not have to match. If the CALL statement was made with a three-part name and the current server is the same as the location in the three-part name, you can omit the location name and specify a two-part name.

Example:

The statements in the following examples are assumed to be in PL/I programs.

Place information about the result sets returned by stored procedure P1 into the descriptor named by SQLDA1. Assume that the stored procedure is called with a one-part name from current server SITE2.

EXEC SQL CONNECT TO SITE2;
EXEC SQL CALL P1;
EXEC SQL DESCRIBE PROCEDURE P1 INTO :SQLDA1;
Parent topic: SQL Statements


DISABLE LOGIN

Use this command to prevent all users, except those with SYSADM privileges, from logging on to the XDB Server. This command does not affect users who are already logged on.

This command is useful for removing the XDB Server from service for routine maintenance, upgrades or repairs.

To make the server available again, use the ENABLE LOGIN command.

Note:

This command functions only when server security is on.

Invocation

This command can be embedded in a host language or executed interactively .

Authorization

Any of the following:

  • A super user
  • A user with SYSADM privileges

Syntax

DISABLE LOGIN
Parent topic: SQL Statements


DROP

The DROP statement removes (erases) an object from the current location. When an object is deleted, its description is also deleted from the system catalog at the current location.

Note:

With the exception of removed storage groups, any objects directly or indirectly dependent on the deleted object are also removed.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The XDB Server checks to ensure that users dropping different kinds of objects possess the following privileges as appropriate:

  • To drop a table, table space, or index, users must possess either DBADM for the database, SYSADM or SYSCTRL authority for the location, or be the owner of the object.
  • To drop an alias, storage group or view, users must possess either SYSADM or SYSCTRL authority or be the owner of the object.
  • To drop a database, users must possess either SYSADM or SYSCTRL authority for the location, DBADM or DBCTRL authority for the database or the DROP privilege on the database.
  • To drop a synonym, users must be owners of the synonym.

To drop a distinct type, stored procedure, trigger, or user-defined function, users must possess ownership of the object, the DROPIN privilege for the schema or all schemas, or SYSADM or SYSCTRL authority.

The DROP statement has access to the same privileges held by the combined AuthIDs of the application process.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

DROP
{
    ALIAS alias-name
    | DATABASE database-name
    | DISTINCT TYPE distinct-type-name RESTRICT
    | FUNCTION function-name (parameter-type[,...]) RESTRICT
    | INDEX index-name
    | SEQUENCE sequence-name
    | STOGROUP stogroup-name
    | LOCATION location-name
    | SYNONYM synonym
    | TABLE table-name
    | TABLESPACE [database-name.]tablespace-name
    | VIEW view-name
    | {PACKAGE | PROGRAM} collection-id.package.id[[VERSION] version-id]
    | PROCEDURE procedure-name RESTRICT
    | SPECIFIC FUNCTION specific-name RESTRICT
    | TRIGGER trigger-name
}

parameter-type:

{data-type [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] |
REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] |
    {CHARACTER | CHAR} VARYING (integer) |
    VARCHAR (integer) } [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

Parameters:

alias-name | Identifies the alias to be dropped. The name must identify an alias that exists at the current server. Dropping an alias has no effect on any view, materialized query table, or synonym that was defined using the alias.
database-name | Identifies the database to be dropped.
location-name | Identifies a user-created location to be dropped.
index-name | Identifies the index to be dropped.
stogroup-name | Identifies the storage group to be dropped.
synonym | Identifies the synonym to be dropped.
table-name | Identifies the table to be dropped.
[database-name.]tablespace-name | Identifies the table space (optionally qualified with a database name) to be dropped.
view-name | Identifies the view to be dropped.

Description

DELETE command rules do not apply when using the DROP command. When dropping a table, for instance, parent and dependent table relationships are not a consideration.

If the user-defined storage group for a database is dropped, then that database no longer has an active default storage group. A USING clause must be specified when creating future table space or indexes within that database. The USING clause must be specified until either another storage group is created with the same name (using CREATE STOGROUP) or another default storage group is designated for the database (using ALTER DATABASE).

ALIAS

This keyword indicates that an alias is to be dropped. The alias must exist at the current location. Dropping an alias does not affect any view or synonym previously defined using the dropped alias.

DATABASE

The keyword indicates that a database is to be dropped. This database must not be a system database (DSNDB04, DSNDB06, DSNDDF, XDBACF, etc.), and must exist at the current location. The database, along with all table spaces, tables and indexes associated with the database are dropped.

DISTINCT TYPE distinct-type-name RESTRICT

Identifies the distinct type to be dropped. The name must identify a distinct type that exists at the current server. The default keyword RESTRICT indicates that the distinct type is not dropped if any of the following dependencies exist:

  • The definition of a column of a table uses the distinct type.
  • The definition of an input or result parameter of a user-defined function uses the distinct type.
  • The definition of a parameter of a stored procedure uses the distinct type.
  • A sequence exists for which the data type of the sequence is the distinct type.

Whenever a distinct type is dropped, all privileges on the distinct type are also dropped. In addition, the cast functions that were generated when the distinct type was created and the privileges on those cast functions are also dropped.

FUNCTION

Identifies the user-defined function to be dropped. The name must identify a function that has been defined with the CREATE FUNCTION statement at the current server. The name must not identify a cast function that was generated for a distinct type or a function that is in the SYSIBM schema. The required keyword RESTRICT enforces the rule that the function is not dropped if any of the following dependencies exist:

  • Another function is sourced on the function.
  • A view uses the function.
  • A trigger package uses the function.

Whenever a function is dropped, all privileges on the user-defined function are also dropped. Any plans or packages that are dependent on the function dropped are made inoperative.

You can identify the particular function to be dropped by its name, function signature, or specific name. If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name RESTRICT | Identifies the function by its name. There must be exactly one function with function-name in the implicitly or explicitly specified schema; otherwise, an error occurs.
FUNCTION function-name (parameter-type,...) RESTRICT | Provides the function signature, which uniquely identifies the function. There must be exactly one function with the function signature in the implicitly or explicitly specified schema; otherwise, an error occurs. If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to uniquely identify the function. Instead, use one of the other syntax variations to identify the function with its function name, if unique, or its specific name.
function-name | Identifies the name of the function.
(parameter-type,...) | Identifies the parameters of the function.

If an unqualified distinct type name is specified, XDB searches the SQL path to resolve the schema name for the distinct type.

The data types of the parameters must match the data types that were specified on the CREATE FUNCTION statement in the corresponding position. The number of data types and the logical concatenation of the data types are used to identify the function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.
  • The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:
    CHAR | CHAR(1)
    GRAPHIC | GRAPHIC(1)
    DECIMAL | DECIMAL(5,0)
    FLOAT | DOUBLE (length of 8)

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that XDB ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name RESTRICT Identifies the function by its specific name, which was explicitly specified or implicitly created when the function was created. There must be exactly one function with specific-name in the implicitly or explicitly specified schema.

INDEX

The name must identify a user-defined index that exists at the current server but must not identify a populated index on an auxiliary table. A populated index on an auxiliary table can only be dropped by dropping the base table.

If the index that is dropped was created by specifying the ENDING AT clause to define partition boundaries, the table is converted to use table-controlled partitioning. The high limit key for the last partition is set to the highest possible value for ascending key columns or the lowest possible value for descending key columns.

Whenever an index is directly or indirectly dropped, its index space is also dropped. The name of a dropped index space cannot be reused until a commit operation is performed.

If the index is a unique index used to enforce a unique constraint (primary or unique key), the unique constraint must be dropped before the index can be dropped. In addition, if a unique constraint supports a referential constraint, the index cannot be dropped unless the referential constraint is dropped.

However, a unique index (for a unique key only) can be dropped without first dropping the unique key constraint if the unique key was created in a release of DB2 before Version 7 and if the unique key constraint has no associated referential constraints.

If a unique index is dropped and that index was defined on a ROWID column that is defined as GENERATED BY DEFAULT, the table can still be used, but rows cannot be inserted into that table.

If an empty index on an auxiliary table is dropped, the base table is marked incomplete.

LOCATION

This keyword indicates that a user-created location is to be dropped. All database and other objects stored within the location are also dropped. INSTALL authority is needed to drop a location. When dropping a location, not all files are cleaned up. Some files may be left in the directory that contained the location. If you attempt to create another location in the same directory, these files will be overwritten. If you wish to clean up your hard drive, delete these files -- just make sure that you are deleting files from an already deleted location.

Note:

You cannot drop a location that was created in the same session. You must first exit the interactive SQL session during which you created the location, and then start another interactive SQL session to drop the newly created location.

PROCEDURE procedure-name RESTRICT

Identifies the stored procedure to be dropped. The name must identify a stored procedure that has been defined with the CREATE PROCEDURE statement at the current server. The required keyword RESTRICT prevents the procedure from being dropped if a trigger definition contains a CALL statement with the name of the procedure.

When a procedure is directly or indirectly dropped, all privileges on the procedure are also dropped. In addition, any plans or packages that are dependent on the procedure are made inoperative.

SEQUENCE sequence-name

Identifies the sequence to be dropped. The name must identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs.

sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column. Sequences generated by the system for identity columns cannot be dropped with the DROP SEQUENCE statement. A sequence object for an identity column is implicitly dropped when the table containing the identify column is dropped.

The default keyword RESTRICT indicates that the sequence is not dropped if any of the following dependencies exist:

  • A trigger that uses the sequence in a NEXT VALUE or PREVIOUS VALUE expression exists.
  • An inline SQL function that uses the sequences in a NEXT VALUE or PREVIOUS VALUE expression exists.

Whenever a sequence is dropped, all privileges on the sequence are also dropped, and the plans and packages that refer to the sequence are invalidated. Dropping a sequence, even if the drop process is rolled back, results in the loss of the still-unassigned cache values for the sequence.

STOGROUP

This keyword indicates that a stogroup is to be dropped. The storage group must exist at the current location and must not be the default storage group (SYSDEFLT) or a storage group still used by any table space or index space. Objects defined within a stogroup are not automatically dropped when the stogroup is dropped. Users must first drop the individual objects in the stogroup or alter the objects to utilize a different stogroup. An error occurs when attempting to drop a stogroup being used by a table space.

SYNONYM

This keyword indicates that a synonym is to be dropped. In a dynamic DROP SYNONYM statement, the synonym identified must be owned by the CURRENT SQLID. Dropping a synonym does not affect any view or alias previously defined using the synonym. A user with SYSADM privileges can drop synonyms owned by other users.

Dropping a synonym has no effect on any view, materialized query table, or alias that was defined using the synonym, nor does it invalidate any plans or packages that use such views, materialized query tables, or aliases.

TABLE

This keyword indicates that a table is to be dropped. The table must exist at the current location and must not be a system catalog table. When a table is dropped (either directly or indirectly), all privileges on the table are dropped. Additionally, all parent or dependent referential constraints built on the table, all synonyms, views, and indexes defined on the table are also dropped.

A table in a partitioned table space can only be dropped by dropping the table space. A populated auxiliary table can only be dropped by dropping the associated base table.

Whenever a table is directly or indirectly dropped, all materialized query tables defined on the table are also dropped. Whenever a materialized query table is directly or indirectly dropped, all privileges on the materialized query table and all synonyms, views, and indexes that are defined on the materialized query table are also dropped. Any alias defined on the materialized query table is not dropped. Any plans or packages that are dependent on the dropped materialized query table are marked invalid.

If a table with LOB columns is dropped, the auxiliary tables associated with the table and the indexes on the auxiliary tables are also dropped. Any LOB table spaces that were implicitly created for the auxiliary tables are also dropped.

If an empty auxiliary table is dropped, the definition of the base table is marked incomplete.

If the table has a security label column, the primary authorization ID of the DROP statement must have a valid security label, and the RACF SECLABEL class must be active.

TABLESPACE

This keyword indicates that a table space is to be dropped. All tables in the dropped table space are also dropped.

The table space must exist at the current location (and must not be in the DSNDB06 database). Table spaces that were created implicitly cannot be dropped. If a database name qualifier is not included, than the default DSNDB04 database for that location is implicitly specified.

A table space in a TEMP database can be dropped only if it does not contain an active declared temporary table. A LOB table space can be dropped only if it does not contain an auxiliary table.

Whenever a base table space that contains tables with LOB columns is dropped, all the auxiliary tables and indexes on those auxiliary tables that are associated with the base table space are also dropped.

TRIGGER trigger-name

Identifies the trigger to be dropped. The name must identify a trigger that exists at the current server.

Whenever a trigger is directly or indirectly dropped, all privileges on the trigger are also dropped and the associated trigger package is freed. The name of that trigger package is the same as the trigger name and the collection ID is the schema name.

VIEW

This keyword indicates that a view is to be dropped. The name must identify a view that exists at the current server.

Whenever a view is directly or indirectly dropped, all privileges on the view and all synonyms and views that are defined on the view are also dropped. Whenever a view is directly or indirectly dropped, all materialized query tables defined on the view are also dropped.

Dependencies when dropping objects

Whenever an object is directly or indirectly dropped, other objects that depend on the dropped object might also be dropped. (The catalog stores information about the dependencies of objects on each other.) The following semantics determine what happens to a dependent object when the object that it depends on (the underlying object) is dropped:

Cascade (D) | Dropping the underlying object causes the dependent object to be dropped. However, if the dependent object cannot be dropped because it has a restrict dependency on another object, the drop of the underlying object fails.
Restrict (R) | The underlying object cannot be dropped if a dependent object exists.
Inoperative (O) | Dropping the underlying object causes the dependent object to become inoperative.
Invalidation (V) | Dropping the underlying object causes the dependent object to become invalidated.

Example:

The statements in the following examples are assumed to be in PL/I programs.

Place information about the result sets returned by stored procedure P1 into the descriptor named by SQLDA1. Assume that the stored procedure is called with a one-part name from current server SITE2.

EXEC SQL CONNECT TO SITE2;
EXEC SQL CALL P1;
EXEC SQL DESCRIBE PROCEDURE P1 INTO :SQLDA1;
Parent topic: SQL Statements


ENABLE LOGIN

Use this command to return a server to service after it has been taken out of service with the DISABLE LOGIN command.

Note:

This command functions only when server security is on.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSADM privileges

Syntax

ENABLE LOGIN
Parent topic: SQL Statements


END DECLARE SECTION

The END DECLARE SECTION statement (embedded SQL only) marks the end of a host variable declaration block in an application program.

Invocation

END DECLARE SECTION is not an executable statement. It can only be embedded in a host language.

Authorization

No special authorization is required.

Syntax

END DECLARE SECTION

Description

END DECLARE SECTION may be used in an application program to mark the end of the section of code where host variables are declared. If an END DECLARE SECTION is used, the host variable declaration section must begin with the BEGIN DECLARE SECTION statement.

When programming in C, or when the DECLARE or ANSI COBOL preprocessor directives are used, BEGIN and END DECLARE SECTION commands must surround the declarations for all host variables, creating host variable declaration blocks. The host variable declaration blocks can appear anywhere the host language allows variable declarations, but they cannot be nested.

Example:

EXEC SQL BEGIN DECLARE SECTION;
    short in cust_num = 28;
    char name[30];
EXEC SQL END DECLARE SECTION;
Parent topic: SQL Statements


END DECLARE SECTION Example

EXEC SQL BEGIN DECLARE SECTION;
    short in cust_num = 28;
    char name[30];
EXEC SQL END DECLARE SECTION;
Parent topic: SQL Statements


EXECUTE

The EXECUTE command (embedded SQL only) executes a previously prepared nonquery statement. To prepare and execute in one step, see the EXECUTE IMMEDIATE command.

Invocation

EXECUTE is an executable command that can only be embedded in a host language. EXECUTE cannot be dynamically prepared.

Authorization

The user must have the authority to use the previously prepared command.

Syntax

EXECUTE statement-name
    [USING {host-variable[,...] |
    DESCRIPTOR descriptor-name} |
    multiple-row-insert]

multiple-row-insert

USING {{host-variable-array | host-variable} [,...]}
   | DESCRIPTOR descriptor-name}
   [FOR {host-variable | integer-constant} ROWS]

Parameters:

statement-name | Identifies a previously prepared nonquery statement to be executed.
host-variable | Identifies a variable described in the application program in accordance with the rules for declaring host variables in the application language.
descriptor-name | Identifies an SQLDA containing a valid description of the host variables to be inserted into the prepared statement during execution.

Description

The EXECUTE command is always used in conjunction with the PREPARE statement, since the main argument for EXECUTE is a previously prepared SQL statement. The PREPARE statement tells the XDB Server about the statement to be executed, while the EXECUTE statement executes that statement, substituting host variable values where specified.

USING

This optional keyword precedes a list of host variables whose values are substituted for the parameter markers (question marks) in the prepared statement. If the prepared statement includes parameter markers, the USING clause must be included in the EXECUTE statement.

The total number of host variables specified must equal the total number of parameter markers in the prepared statement. The order of host variables specified determines their order of substitution into the prepared statement -- with the first variable substituting for the first parameter marker in the prepared statement, etc.

DESCRIPTOR

This keyword indicator precedes a valid SQL Descriptor Area (SQLDA) name. The total number of host variables (as stored in SQLD) must match the total number of parameter markers in the prepared statement. The length of the SQLDA (as stored in SQLDABC) must be sufficient to accommodate all host variables. As with ordinary host variables, there is an ordered one-to-one correspondence between each host variable described in the SQLDA, and the parameter markers inside the prepared statement.

The SQLDA must have enough storage to contain all SQLVAR occurrences.

Parameter Marker Replacement

Before the prepared statement is executed, each parameter marker in the prepared statement string is essentially replaced by a corresponding host variable from the application. This replacement operation transfers the value of the host variable (source) to the corresponding parameter marker (target) within the prepared SQL statement string. The attribute of each host variable -- once transferred into its new "target position" within the SQL statement string -- depends on the original location (and role) of the replaced parameter marker.

Example:

In COBOL, host-variables are data structures defined in working storage. In the following example, we PREPARE inscust and substitute the values of the host variables c_no and company.

EXEC SQL
    PREPARE inscust
        FROM
            INSERT INTO customer(c_no, company) VALUES(?, ?)
END-EXEC
EXEC SQL
    EXECUTE inscust USING :CNO, :CNAME
END-EXEC
Parent topic: SQL Statements
Related information
EXECUTE IMMEDIATE


EXECUTE IMMEDIATE

The EXECUTE IMMEDIATE statement (embedded SQL only) prepares an executable statement from a character string and then immediately executes the statement.

Invocation

EXECUTE IMMEDIATE is an executable command that can only be embedded in a host language. EXECUTE IMMEDIATE cannot be dynamically prepared.

Authorization

The authorization required for EXECUTE IMMEDIATE conforms exactly with whatever authorization is needed to dynamically prepare the SQL statement indicated in the statement string argument. Consult individual SQL command descriptions in this reference for authorization requirements.

Syntax

EXECUTE IMMEDIATE
    {string-expression | host-variable}

Parameters:

string-expression | A delimited character string that can contain any valid SQL command except CLOSE, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, FETCH, INCLUDE, OPEN, PREPARE, WHENEVER, or SELECT.
host-variable | Identifies a variable defined in working storage (according to the rules for declaring character string variables in the host language) that contains a valid string expression (statement string).

Description

The EXECUTE IMMEDIATE command prepares and executes non-SELECT SQL commands within a statement string. You should check the syntax of the SQL statement you plan to use before placing that statement into an EXECUTE IMMEDIATE command. This check can be performed with SQLWizard.

The statement string cannot contain parameter markers (question marks) or references to host variables. The statement cannot begin with EXEC SQL or end with END-EXEC (or a semicolon). If the SQL command appearing in the statement string is invalid, an error condition is reported to the SQLCA.

The statement string must be one of the following SQL statements:

ALTER | RENAME
COMMENT ON | REVOKE
COMMIT | ROLLBACK
CREATE | SET CURRENT DEGREE
DELETE | SET CURRENT LOCALE LC_CTYPE
DROP | SET CURRENT OPTIMIZATION HINT
EXPLAIN | SET CURRENT PATH
GRANT | SET CURRENT PRECISION
INSERT | SET CURRENT RULES
LABEL ON | SET CURRENT SQLID
LOCK TABLE | UPDATE

Examples:

Host variables cannot be used in the string expressions.

EXEC SQL
    EXECUTE IMMEDIATE
    'DELETE FROM employee WHERE fname = "Elvis"'
END-EXEC

EXEC SQL
    EXECUTE IMMEDIATE
        'UPDATE employee
    SET fname = "Elvis"
    WHERE e_no = 1'
END-EXEC

Another example of EXECUTE IMMEDIATE embedded in COBOL appears below:

MOVE 'UPDATE employee SET fname = "Elvis"
    WHERE e_no = 1'
    TO exstr

EXEC SQL
    EXECUTE IMMEDIATE :exstr
END-EXEC
Parent topic: SQL Statements


EXPLAIN

The EXPLAIN statement uses the optimizer to acquire access path selection information about SELECT, INSERT (and the searched form of UPDATE or DELETE) statements. This information is placed by the XDB Server into a table named PLAN_TABLE. The XDB Server creates this table automatically if it has not already been created by the user.

Invocation

EXPLAIN is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

The authorization privileges needed for an EXPLAIN statement are the same privileges required to execute the SQL statement for which you are requesting explanation.

If the EXPLAIN statement is embedded in an application program, the authorization rules that apply are those defined for embedding the specified SQL statement in an application program. In addition, the authorization ID of the owner of the plan or package must also have one of the following characteristics:

  • Be the owner of a plan table named PLAN_TABLE
  • Have an alias on a plan table named owner.PLAN_TABLE and have SELECT and INSERT privileges on the table

If the EXPLAIN statement is dynamically prepared, the authorization rules that apply are those defined for dynamically preparing the specified SQL statement. In addition, the SQL authorization ID of the process must also have one of the following characteristics:

  • Be the owner of a plan table named PLAN_TABLE
  • Have an alias on a plan table named owner.PLAN_TABLE and have SELECT and INSERT privileges on the table.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

EXPLAIN { {PLAN | ALL} [SET QUERYNO=integer]
    FOR explainable-sql-statement
    | STMTCACHE {STMTID {id-host-variable|integer-constant} |
                 STMTTOKEN {token-host-variable|string-constant}} }

Parameters:

integer Preceded by the keywords SET QUERYNO=, specifies an integer to be inserted into the QUERYNO column of the plan_table.
explainable-sql-statement Preceded by the keyword FOR, specifies the SQL statement for which information is returned to the plan table. Only SELECT and INSERT statements or the searched form of an UPDATE or DELETE statement, can be the SQL statement in an EXPLAIN command. The statement must not be a statement-name or a host-variable, and must refer to objects at the current location.

explainable-sql-statement must not contain a QUERYNO clause. To specify the value of the QUERYNO column in plan table for the statement being explained, use the SET QUERYNO = clause of the EXPLAIN statement.

If embedded in an application program, the EXPLAIN statement can contain host variable references. These host variables must be defined in the application program.

SET QUERYNO=

When these optional keywords are specified, the plan table column QUERYNO is given the value integer for each subsequent row inserted by the EXPLAIN statement. If this clause is not specified, XDB Server assigns its own number to QUERYNO.

STMTCACHE STMTID id-host-variable or integer-constant

Specifies that the cached statement with the specified statement ID is to be explained. The value contained in id-host-variable or specified by integer-constant identifies the statement ID. The statement ID is an integer that uniquely identifies a statement that has been cached in the dynamic statement cache. The statement ID of a cached statement can be retrieved through IFI monitor facilities from IFCID 316 or 124. Some diagnostic trace records, such as 173, 196, and 337, also show the statement ID.

For every row that the EXPLAIN statement inserts into the plan table, statement table, or function table, the QUERYNO column contains the value of the statement ID.

STMTCACHE STMTOKEN id-host-variable or integer-constant

Specifies that the cached statements with the specified statement token are to be explained. The value contained in token-host-variable or specified by string-constant identifies the statement token. The statement token must be a character string that is no longer than 240 bytes. The application program that originally prepares and inserts a statement into the cache associates a statement token with the cached statement. The program can make this association with the RRSAF SET_ID function, or the sqleseti API if the program is connected remotely.

For every row that the EXPLAIN statement inserts into the plan table, statement table, or function table, the STMTTOKEN column contains the value of the statement token, and the QUERYNO column contains the value of the statement ID for the cached statement with the statement token.

PLAN_TABLE Output

The XDB Server explain facility is highly compatible with the explain facility in DB2. While a one-to-one correspondence exists in the order and naming of XDB Server and DB2 PLAN_TABLE columns, differences do occur in some of the values which the optimizer writes to the PLAN_TABLE columns. In those cases where the optimizer produces a PLAN_TABLE column value that varies from that produced by a comparable EXPLAIN statement under DB2, the variation is noted.

If it does not already exist, the XDB Server creates an empty table named PLAN_TABLE for the user's CURRENT SQLID at the current location. Each time an EXPLAIN statement is executed, the XDB Server appends another row of information to the PLAN_TABLE. This information accumulates, allowing comparison and analysis of individual query information.

The following table describes the standard column arrangement in PLAN_TABLE. Each step in the execution of a query or subquery (in an explainable statement) is described in its own row in PLAN_TABLE. Each column value in a row identifies an aspect of the execution step -- such as the query or subquery, which tables are involved, and the access path used to carry out the step.

Column Name | Description
integer | Preceded by the keywords SET QUERYNO=, specifies an integer to be inserted into the QUERYNO column of the plan_table.
explainable-sql-statement Preceded by the keyword FOR, specifies the SQL statement for which information is returned to the plan table. Only SELECT and INSERT statements or the searched form of an UPDATE or DELETE statement, can be the SQL statement in an EXPLAIN command. The statement must not be a statement-name or a host-variable, and must refer to objects at the current location.

explainable-sql-statement must not contain a QUERYNO clause. To specify the value of the QUERYNO column in plan table for the statement being explained, use the SET QUERYNO = clause of the EXPLAIN statement.

If embedded in an application program, the EXPLAIN statement can contain host variable references. These host variables must be defined in the application program.

QUERYNO | A number identifying the explained statement. Can be specified with the SET QUERYNO clause.
QBLOCKNO | A number to identify subqueries.
APPLNAME | BLANK (XDB Server currently only explains individual queries)
PROGNAME | BLANK (XDB Server currently only explains individual queries)
PLANNO | Constant value of "1" (since only one individual query can be described per EXPLAIN command)
METHOD | Constant value of "1" (the XDB Server currently processes all joins using the "nested loop" method)
CREATOR | Creator of the table accessed.
TNAME | The name of the table accessed.
TABNO | A number distinguishing multiple references to the same table.
ACCESSTYPE Method of accessing the table:
I
An index (identified in ACCESSCREATOR and ACCESSNAME)
I1
One-fetch index scan
N
Index scan when predicate contains keyword IN
R
Sequential scan of its pages (commonly called table space scan)
M
Multiple index scan; followed by MX, MI, or MU
MX
Index scan on the index named in ACCESSNAME
MI
Intersection of multiple indexes
MU
Union of multiple indexes
blank
Not applicable to current row
MATCHCOLS | The number of index keys matched in the index scan. Zero (0) for a nonmatching index scan.
ACCESSCREATOR | The creator of the index named in ACCESSNAME.
ACCESSNAME | Name of the index referred to in ACCESSTYPE.
INDEXONLY | "Y" if data pages need not be accessed.
SORTN_UNIQ | Always "N"
SORTN_JOIN | Always "N"
SORTN_ORDERBY | Always "N"
SORTN_GROUPBY | Always "N"
SORTC_UNIQ | "Y" if sort on result table is required to remove duplicate rows.
SORTC_JOIN | Always "N"
SORTC_ORDERBY | "Y" if sort on result table is required for ORDER BY.
SORTC_GROUPBY | Always "N"
TSLOCKMODE | Always "IS"
TIMESTAMP | The time at which the EXPLAIN statement was processed.
REMARKS | Optional user remarks.
PREFETCH Whether or not prefetch can be used to read pages in advance:
P
Pure sequential prefetch
L
Prefetch through a page list
COLUMN_FN_EVAL Normally Blank. Contains a nonblank value "R" only when the XDB Server can evaluate the function directly from the index.

If the statement:

SELECT COUNT(field1)
    FROM table1
    WHERE field1 = ?

did not contain a WHERE clause, then the aggregate would be evaluated from the index (providing a simple index exists on field1).

MIXOPSEQ | A number indicating the sequence in which the steps of a multiple index operation are performed. Zero (0) if ACCESSTYPE is other than MX, MI or MU.
VERSION | Always Blank.
COLLID | Always Blank.

Comments:

Table Creation Options

Plan tables can function with fewer columns than those described in the previous table. The XDB Server accepts three configurations (corresponding to different DB2 versions) of plan tables. The PLAN_TABLE format on the XDB Server defaults to the same 30 column table as used in DB2. Users have the option of explicitly creating their own 25, 28 or 30 column PLAN_TABLE:

  • A 30 column table ending with the COLLID column (used with DB2 Version 2.3).
  • A 25 column table ending with the REMARKS column.
  • A 28 column table ending with the MIXOPSEQ column.

A plan table must include one of the following sets of columns:

  • All the columns up to and including REMARKS (COLCOUNT = 25)
  • All the columns up to and including MIXOPSEQ (COLCOUNT = 28)
  • All the columns up to and including COLLID (COLCOUNT = 30)
  • All the columns up to and including JOIN_PGROUP_ID (COLCOUNT = 34)
  • All the columns up to and including IBM_SERVICE_DATA (COLCOUNT = 43)
  • All the columns up to and including BIND_TIME (COLCOUNT = 46)
  • All the columns shown in the CREATE statement (COLCOUNT = 58)

Whichever option is used, the columns must appear in the same order indicated in the previous table. A plan table can be modified with an ALTER TABLE command, as long as the final table configuration matches one of the three options above.

When using the 58-column format for the plan table, remember that many columns (PROGNAME, COLLID, CREATOR, TNAME, ACCESSCREATOR, ACCESSNAME, CORRELATION_NAME) must be defined as VARCHAR(128). In previous releases of DB2, these columns were smaller.

Plan table migration

You can migrate existing plan tables to subsequent releases or fall back to prior releases. If you fall back to a prior release, the extra columns are simply ignored when EXPLAIN is executed. If you migrate to a subsequent release, the missing columns are likewise ignored.

Example:

The following example places a description of the steps taken by the XDB Server to execute the SELECT statement shown into the user's plan table. The QUERYNO value of "1212" uniquely marks the PLAN_TABLE row entries as pertaining to this SELECT statement:

EXPLAIN PLAN SET QUERYNO = 1212 FOR
    SELECT pno, shipcost = weight * 1.15
        FROM part
        WHERE city = "LONDON"

To retrieve the PLAN_TABLE row entries belonging solely to the SELECT statement "explained" above, query the PLAN_TABLE by specifying a value of "1212" for the QUERYNO column:

SELECT *
    FROM plan_table
    WHERE queryno = 1212
Parent topic: SQL Statements


FETCH

The FETCH command (embedded SQL only) positions a cursor on a row of its result table. It can return zero, one, or multiple rows and assigns the values of the rows to host variables if there is a target specification.

There are two forms of this statement:

  • Single row fetch: positions the cursor and, optionally, retrieves data from a single row of the result table.
  • Multiple row fetch: positions the cursor on zero or more rows of the result table and, optionally, returns data if there is a target specification.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

To execute a FETCH command on an opened cursor, the user requires the same authority needed to declare that cursor for a given table or set of tables.

Syntax

FETCH [SENSITIVE | INSENSITIVE] fetch-orientation [FROM]
    cursor-name [single-row-fetch | multiple-row-fetch]

fetch-orientation

{BEFORE |
 AFTER |
 row-positioned |
 rowset-positioned}

row-positioned

[NEXT |
 PRIOR |
 FIRST |
 LAST |
 CURRENT |
 ABSOLUTE {host-variable | integer-constant} |
 RELATIVE {host-variable | integer-constant}]

rowset-positioned

[NEXT ROWSET |
 PRIOR ROWSET |
 FIRST ROWSET |
 LAST ROWSET |
 CURRENT ROWSET |
 ROWSET STARTING AT {ABSOLUTE | RELATIVE} {host-variable | integer-constant}]

single-row-fetch

[INTO {host-variable [,...] | DESCRIPTOR descriptor-name}]

multiple-row-fetch

[FOR {host-variable | integer-constant} ROWS]
[INTO {host-variable-array [,...] | DESCRIPTOR descriptor-name}]

Description

The FETCH command retrieves data from the next row of a cursor result table. A cursor defines the current row of the result. A FETCH statement also advances this cursor to the next available row in the result table. The result table is a collection of rows of data that satisfy the conditions of a SELECT statement defined in a DECLARE CURSOR statement.

If currently positioned before a row of its result table, the FETCH command moves the cursor onto that row and assigns the column values in that row to the host variables as specified by either the INTO or USING clauses. If positioned on a row (other than the last row), the FETCH command moves the cursor onto the next row, assigning the column values of that row to the host variables specified. Once the cursor becomes positioned on or after the last row, a value of +100 is assigned to the SQLCODE indicator field (SQLCA), and the FETCH command positions the cursor after the last row. No values are assigned to the host variables indicated.

INSENSITIVE

Returns the row from the result table as it is. If the row has been previously fetched with a FETCH SENSITIVE, it reflects changes made outside this cursor before the FETCH SENSITIVE statement was issued. Positioned updates and deletes are reflected with FETCH INSENSITIVE if the same cursor was used for the positioned update or delete.

INSENSITIVE can only be specified for cursors declared as INSENSITIVE or SENSITIVE STATIC (or if the cursor is declared as ASENSITIVE and DB2 defaults to INSENSITIVE). Otherwise, if the cursor is declared as SENSITIVE DYNAMIC (or if the cursor is declared as ASENSITIVE and DB2 defaults to SENSITIVE DYNAMIC), an error occurs and the FETCH statement has no effect. For an INSENSITIVE cursor, specifying INSENSITIVE is optional because it is the default.

SENSITIVE

Updates the fetched row in the result table from the corresponding row in the base table of the cursor's SELECT statement and returns the current values. Thus, it reflects changes made outside this cursor. SENSITIVE can only be specified for a sensitive cursor. Otherwise, if the cursor is insensitive, an error occurs and the FETCH statement has no effect. For a SENSITIVE cursor, specifying SENSITIVE is optional because it is the default.

When the cursor is declared as SENSITIVE STATIC and a FETCH SENSITIVE is requested, the following steps are taken:

  1. SQL Option retrieves the row of the database that corresponds to the row of the result table that is about to be fetched.
  2. If the corresponding row has been deleted, a "delete hole" occurs in the result table, a warning is issued, the cursor is repositioned on the "hole", and no data is fetched. (SQL Option marks a row in the result table as a "delete hole" when the corresponding row in the database is deleted.)
  3. If the corresponding row has not been deleted, the predicate of the underlying SELECT statement is re-evaluated. If the row no longer satisfies the predicate, an "update hole" occurs in the result table, a warning is issued, the cursor is repositioned on the "hole," and no data is fetched. (SQL Option marks a row in the result table as an "update hole" when an update to the corresponding row in the database causes the row to no longer qualify for the result table.)
  4. If the corresponding row does not result in a delete or an update hole in the result table, the cursor is repositioned on the row of the result table and the data is fetched.

AFTER

Positions the cursor after the last row of the result table. Values are not assigned to host variables. The number of rows of the result table are returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA for cursors with an effective sensitivity of INSENSITIVE or SENSITIVE STATIC.

BEFORE

Positions the cursor before the first row of the result table. Values are not assigned to host variables.

row-positioned

Positioning of the cursor with row-positioned fetch orientations NEXT, PRIOR, and RELATIVE is done in relation to the current cursor position. Following a successful row-positioned FETCH statement, the cursor is positioned on a single row of data. If the cursor is enabled for rowsets, positioning is performed relative to the first row of the current rowset, and the cursor is positioned on a rowset consisting of a single row.

NEXT

Positions the cursor on the next row or rows of the result table relative to the current cursor position, and returns data if a target is specified. NEXT is the only row-positioned fetch operation that can be explicitly specified for cursors that are defined as NO SCROLL. NEXT is the default if no other cursor positioning is specified. If a specified row reflects a hole, a warning is issued and data values are not assigned to host variables for that row.

The following table shows situations for different cursor positions and the results when NEXT is used.

Current state of the cursor | Result of FETCH NEXT
Before the first row | Cursor is positioned on the first row and data is returned if requested.
On the last row or after the last row | A warning occurs, values are not row assigned to host variables, and the cursor is positioned after the last row.
Before a hole | For a SENSITIVE STATIC cursor, a warning occurs for a delete hole or an update hole, values are not assigned to host variables, and the cursor is positioned on the hole.
Unknown | An error occurs, values are not assigned to host variables, and the cursor position remains unknown.

PRIOR

Positions the cursor on the previous row or rows of the result table relative to the current cursor position, and returns data if a target is specified. If a specified row reflects a hole, a warning is issued, and data values are not assigned to host variables for that row.

The following table shows situations for different cursor positions and the results when PRIOR is used.

Current state of the cursor | Result of FETCH PRIOR
Before or on the first row | A warning occurs, values are not first row assigned to host variables, and the cursor is positioned before the first row.
After a hole | For a SENSITIVE STATIC cursor, a warning occurs for a delete hole or an update hole, values are not assigned to host variables, and the cursor is positioned on the hole.
After the last row | Cursor is positioned on the last row.
Unknown | An error occurs, values are not assigned to host variables, and the cursor position remains unknown.

FIRST

Positions the cursor on the first row of the result table, and returns data if a target is specified. For a SENSITIVE STATIC cursor, if the first row of the result table is a hole, a warning occurs for a delete hole or an update hole and values are not assigned to host variables.

LAST

Positions the cursor on the last row of the result table, and returns data if a target is specified. The number of rows of the result table is returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA for an insensitive or sensitive static cursor. For a SENSITIVE STATIC cursor, if the last row of the result table is a hole, a warning occurs for a delete hole or an update hole and values are not assigned to host variables.

CURRENT

The cursor position is not changed, data is returned if a target is specified. If the cursor was positioned on a rowset of more than one row, then the cursor position is on the first row of the rowset.

The following table shows situations in which errors occur with CURRENT.

Current state of the cursor | Result of FETCH CURRENT
Before the first row or after the last row | A warning occurs, values are not last row assigned to host variables.
On a hole | For a SENSITIVE STATIC or a SENSITIVE DYNAMIC cursor, a warning occurs for a delete hole or an update hole, values are not assigned to host variables, and the cursor is positioned on the hole. A hole is detected for a SENSITIVE DYNAMIC cursor when the current row is deleted or updated so that it no longer meets the selection criterion, and a FETCH CURRENT or a FETCH RELATIVE +0 is executed without repositioning the cursor.
Unknown | An error occurs, values are not assigned to host variables, and the cursor position remains unknown.

ABSOLUTE

host-variable or integer-constant is assigned to an integral value k. If a host-variable is specified, it must be an exact numeric type with zero scale and must not include an indicator variable. The possible data types for the host variable are DECIMAL(n,0) or integer. The DECIMAL data type is limited to DECIMAL(18,0). An integer-constant can be up to 31 digits, depending on the application language.

If k=0, the cursor is positioned before the first row of the result table. Otherwise, ABSOLUTE positions the cursor to row k of the result table if k>0, or to k rows from the bottom of the table if k<0. For example, "ABSOLUTE -1" is the same as "LAST".

Data is returned if the specified position is within the rows of the result table, and a target is specified.

If an absolute position is specified that is before the first row or after the last row of the result table, a warning occurs, values are not assigned to host variables, and the cursor is positioned either before the first row or after the last row. If the resulting cursor position is after the last row for INSENSITIVE and SENSITIVE STATIC scrollable cursors, the number of rows of the result table are returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA. If row k of the result table is a hole, a warning occurs and values are not assigned to host variables.

FETCH ABSOLUTE 0 results in positioning before the first row and a warning is issued. FETCH BEFORE results in positioning before the first row and no warning is issued.

The following table shows some synonymous specifications.

Specification | Alternative
ABSOLUTE 0 (but with a warning) | BEFORE (without a warning)
ABSOLUTE +1 | FIRST
ABSOLUTE -1 | LAST
ABSOLUTE -m, 0<m=n | ABSOLUTE n+1-m
ABSOLUTE n | LAST
ABSOLUTE -n | FIRST
ABSOLUTE x (with a warning) | AFTER (without a warning)
ABSOLUTE -x (with a warning) | BEFORE (without a warning)

RELATIVE

host-variable or integer-constant is assigned to an integral value k. If a host-variable is specified, it must be an exact numeric type with zero scale and must not include an indicator variable. The possible data types for the host variable are DECIMAL(n,0) or integer. The DECIMAL data type is limited to DECIMAL(18,0). An integer-constant can be up to 31 digits, depending on the application language.

Data is returned if the specified position is within the rows of the result table, and a target is specified.

RELATIVE positions the cursor to the row in the result table that is either k rows after the current row if k>0, or ABS(k) rows before the current row if k<0. For example, "RELATIVE -1" is the same as "PRIOR". If k=0, the position of the cursor does not change (that is, "RELATIVE 0" is the same as "CURRENT").

If a relative position is specified that results in positioning before the first row or after the last row, a warning is issued, values are not assigned to host variables, and the cursor is positioned either before the first row or after the last row. If the resulting cursor position is after the last row for INSENSITIVE and SENSITIVE STATIC scrollable cursors, the number of rows of the result table is returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA. If the cursor is positioned on a hole and RELATIVE 0 is specified or if the target row is a hole, a warning occurs and values are not assigned to host variables. If the cursor position is unknown and RELATIVE 0 is specified, an error occurs.

The following table shows some synonymous specifications.

Specification | Alternative
RELATIVE +1 | NEXT
RELATIVE -1 | PRIOR
RELATIVE 0 | CURRENT
RELATIVE +r (with a warning) | AFTER (without a warning)
RELATIVE -r (with a warning) | BEFORE (without a warning)

rowset-positioned

Positioning of the cursor with rowset-positioned fetch orientations NEXT ROWSET, PRIOR ROWSET, and ROWSET STARTING AT RELATIVE is done in relation to the current rowset. The number of rows in the rowset is determined either explicitly or implicitly. The FOR n ROWS clause in the multiple-row-fetch clause is used to explicitly specify the size of the rowset. Following a successful rowset-positioned FETCH statement, the cursor is positioned on all rows of the rowset.

A rowset-positioned fetch orientation must not be specified if the current cursor position is not defined to access rowsets. NEXT ROWSET is the only rowset-positioned fetch orientation that can be specified for cursors that are defined as NO SCROLL.

If a row of the rowset reflects a hole, a warning is returned, data values are not assigned to host variable arrays for that row (that is, the corresponding positions in the target host variable arrays are untouched), and -3 is returned in all provided indicator variables for that row. If a hole is detected, and at least one indicator variable is not provided, an error occurs.

NEXT ROWSET

Positions the cursor on the next rowset of the result table relative to the current cursor position, and returns data if a target is specified. The next rowset is logically obtained by fetching the row that follows the current rowset and fetching additional rows until the number of rows that is specified implicitly or explicitly in the FOR n ROWS clause is obtained or the last row of the result table is reached.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the cursor is not positioned because of a prior error, values are not assigned to the host-variable-array, and an error is returned. If a row of the rowset would be after the last row of the result table, values are not assigned to host-variable-arrays for that row and any subsequent requested rows of the rowset, and a warning is returned.

NEXT ROWSET is the only rowset positioned fetch orientation that can be explicitly be specified for cursors that are defined as NO SCROLL.

PRIOR ROWSET

Positions the cursor on the previous rowset of the result table relative to the current position, and returns data if a target is specified.

The prior rowset is logically obtained by fetching the row that follows the current rowset and fetching additional rows until the number of rows that is specified implicitly or explicitly in the FOR n ROWS clause is obtained or the last row of the result table is reached.

If a row would be before the first row of the result table, the cursor is positioned on a partial rowset that consists of only those rows that are prior to the current position of the cursor starting with the first row of the result table, and a warning is returned. Values are not assigned to the host-variable-arrays for the rows in the rowset for which the warning is returned.

Although the rowset is logically obtained by fetching backwards from before the current rowset, the data is returned to the application starting with the first row of the rowset, to the end of the rowset.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the cursor is not positioned because of a prior error, values are not assigned to the host-variable-array, and an error is returned.

FIRST ROWSET

Positions the cursor on the first rowset of the result table, and returns data if a target is specified.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the result table contains fewer rows than specified implicitly or explicitly in the FOR n ROWS clause, values are not assigned to host-variable-arrays after the last row of the result table, and a warning is returned.

LAST ROWSET

Positions the cursor on the last rowset of the result table and returns data if a target is specified. The last rowset is logically obtained by fetching the last row of the result table and fetching prior rows until the number of rows in the rowset is obtained or the first row of the result table is reached. Although the rowset is logically obtained by fetching backwards from the bottom of the result table, the data is returned to the application starting with the first row of the rowset, to the end of the rowset, which is also the end of the result table.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the result table contains fewer rows than specified implicitly or explicitly in the FOR n ROWS clause, the last rowset is the same as the first rowset, values are not assigned to host-variable-arrays after the last row of the result table, and a warning is returned.

CURRENT ROWSET

If the FOR n ROWS clause specifies a number different from the number of rows specified implicitly or explicitly in the FOR n ROWS clause on the most recent FETCH statement for this cursor, the cursor is repositioned on the specified number of rows, starting with the first row of the current rowset. Otherwise, the position of the cursor on the current rowset is unchanged. Data is returned if a target is specified.

With isolation level UR or a sensitive dynamic scrollable cursor, it is possible that different rows will be returned than the FETCH that established the most recent rowset cursor position. This can occur while refetching the first row of the rowset when it is determined to not be there anymore. In this case, fetching continues moving forward to get the first row of data for the rowset. This can also occur when changes have been made to other rows in the current rowset such that they no longer exist or have been logically moved within (or out of) the result table of the cursor.

If the cursor is not positioned because of a prior error, values are not assigned to the host-variable-array, and an error occurs.

If the current rowset contains fewer rows than specified implicitly or explicitly in the FOR n ROWS clause, values are not assigned to host-variable-arrays after the last row, and a warning is returned.

ROWSET STARTING AT ABSOLUTE or RELATIVE host-variable or integer-constant

Positions the cursor on the rowset beginning at the row of the result table that is indicated by the ABSOLUTE or RELATIVE specification, and returns data if a target is specified.

host-variable or integer-constant is assigned to an integral value k. If host-variable is specified, it must be an exact numeric type with scale zero, and must not include an indicator variable. The possible data types for the host variable are DECIMAL(n,0) or integer, where the DECIMAL data type is limited to DECIMAL(18,0). If a constant is specified, the value must be an integer.

If a row of the result table would be after the last row or before the first row of the result table, values are not assigned to host-variable-arrays for that row and a warning is returned.

ABSOLUTE

If k=0, an error occurs. If k>0, the first row of the rowset is row k. If k<0, the rowset is positioned on the ABS(k) rows from the bottom of the result table. Assume that ABS(k) is equal to the number of rows for the rowset and that there are enough row to return a complete rowset:

  • FETCH ROWSET STARTING AT ABSOLUTE -k is the same as FETCH LAST ROWSET.
  • FETCH ROWSET STARTING AT ABSOLUTE 1 is the same as FETCH FIRST ROWSET.

RELATIVE

If k=0 and the FOR n ROWS clause does not specify a number different from the number most recently specified implicitly or explicitly for this cursor, then the position of the cursor does not change (that is, "RELATIVE ROWSET 0" is the same as "CURRENT ROWSET"). If k=0 and the FOR n ROWS clause specifies a number different from the number most recently specified implicitly or explicitly for this cursor, then the cursor is repositioned on the specified number of rows, starting with the first row of the current rowset. Otherwise, RELATIVE repositions the cursor so that the first row of the new rowset cursor position is on the row in the result table that is either k rows after the first row of the current rowset cursor position if k>0, or ABS(k) rows before the first row of the current rowset cursor position if k<0. Assume that ABS(k) is equal to the number of rows for the resulting rowset

  • FETCH ROWSET STARTING AT RELATIVE -k is the same as FETCH PRIOR ROWSET.
  • FETCH ROWSET STARTING AT RELATIVE k is the same as FETCH NEXT ROWSET.
  • FETCH ROWSET STARTING AT RELATIVE 0 is the same as FETCH CURRENT ROWSET.

When ROWSET STARTING AT RELATIVE -n is specified and there are not enough rows between the current position of the cursor and the beginning of the result table to return a complete rowset:

  • A warning is returned.
  • Values are not assigned to the host-variable-arrays.
  • The cursor position remains unchanged.

If a row of the rowset reflects a hole, If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned. If a row of the rowset is unknown, values are not assigned to host variable arrays for that row, and an error is returned. If a row of the rowset would be after the last row or before the first row of the result table, values are not assigned to host-variable-arrays for that row, and a warning is returned.

cursor-name

Identifies the cursor to be used in the fetch operation. The cursor name must identify a declared cursor, as explained in the description of the DECLARE CURSOR statement in "DECLARE CURSOR" in topic 5.42, or an allocated cursor, as explained in "ALLOCATE CURSOR" in topic 5.2. When the FETCH statement is executed, the cursor must be in the open state.

If a single-row-fetch or multiple-row-fetch clause is not specified, the cursor position is adjusted as specified, but no data is returned to the user.

single-row-fetch

When single-row-fetch is specified, SENSITIVE or INSENSITIVE can be specified though there is a default. The default depends on the sensitivity of the cursor. If the sensitivity of the cursor is INSENSITIVE, then the default is INSENSITIVE. If the effective sensitivity of the cursor is SENSITIVE DYNAMIC or SENSITIVE STATIC, then the default is SENSITIVE. The single-row-fetch or multiple-row-fetch clause must not be specified when the FETCH BEFORE or FETCH AFTER option is specified. They are required when FETCH BEFORE or FETCH AFTER is not specified. If an individual fetch operation causes the cursor to be positioned or to remain positioned on a row if there is a target specification, the values of the result table are assigned to host variables as specified by the single-fetch-clause.

INTO host-variable,...

Specifies a list of host variables. Each host-variable must identify a structure or variable that is described in the application program in accordance with the rules for declaring host structures and variables. A reference to a structure is replaced by a reference to each of its variables. The first value in the result row is assigned to the first host variable, the second value to the second host variable, and so on.

INTO DESCRIPTOR descriptor-name

Identifies an SQLDA that contains a valid description of the host output variables. Result values from the associated SELECT statement are returned to the application program in the output host variables.

Before the FETCH statement is processed, you must set the following fields in the SQLDA:

  • SQLN to indicate the number of SQLVAR occurrences provided in the SQLDA

    A REXX SQLDA does not contain this field.

  • SQLABC to indicate the number of bytes of storage allocated in the SQLDA
  • SQLD to indicate the number of variables used in the SQLDA when processing the statement
  • SQLVAR occurrences to indicate the attributes of the variables

The SQLDA must have enough storage to contain all SQLVAR occurrences. Each SQLVAR occurrence describes a host variable or buffer into which a value in the result table is to be assigned. If LOBs are present in the results, there must be additional SQLVAR entries for each column of the result table. If the result table contains only base types and distinct types, multiple SQLVAR entries are not needed for each column. However, extra SQLVAR entries are needed for distinct types as well as for LOBs in DESCRIBE and PREPARE INTO statements.

SQLD must be set to a value greater than or equal to zero and less than or equal to SQLN.

multiple-row-fetch

Retrieves multiple rows of data from the result table of a query. The FOR n ROWS clause of the FETCH statement controls how many rows are returned on a single FETCH statement. The fetch orientation determines whether the resulting cursor position (for example, on a single row, rowset, before, or after the result table). Fetching stops when an error is returned, all requested rows are fetched, or the end of data condition is reached.

Fetching multiple rows of data can be done with scrollable or non-scrollable cursors. The operations used to define, open, and close a cursor used for fetching multiple rows of data are the same as for those used for single row FETCH statements.

If the BEFORE or AFTER option is specified, neither single-row-fetch or multiple-row-fetch can be specified.

FOR host-variable or integer-constant ROWS

host-variable or integer-constant is assigned to an integral value k. If a host variable is specified, it must be an exact numeric type with a scale of zero and must not include an indicator variable. Furthermore, k must be in the range, 0<k<=32767.

This clause must not be specified if a row-positioned fetch-orientation clause was specified. This clause must also not be specified for a cursor that is defined without rowset access.

If a rowset fetch orientation is specified and this clause is not specified, the number of rows in the resulting rowset is determined as follows:

  • If the most recent FETCH statement for this cursor was a rowset-positioned FETCH, the number of rows of the rowset is implicitly determined by the number of rows that was most recently specified (implicitly or explicitly) for this cursor.
  • When the most recent FETCH statement for this cursor was either FETCH BEFORE or FETCH AFTER and the most recent FETCH statement for this cursor prior to that was a rowset-positioned FETCH, the number of rows of the rowset is implicitly determined by the number of rows that were most recently specified (implicitly or explicitly) for this cursor.
  • Otherwise, the rowset consists of a single row.

For result set cursors, the number of rows for a rowset cursor position, established in the procedure that defined the rowset, is not inherited by the caller when the rowset is returned. Use the FOR n ROWS clause on the first rowset FETCH statement for the result set in the calling program to establish the number of rows for the cursor. Otherwise, the rowset consists of a single row.

The cursor is positioned on the row or rowset that is specified by the orientation clause (for example, NEXT ROWSET), and those rows are fetched if a target is specified. After the cursor is positioned on the first row being fetched, the next k-1 rows are fetched. Fetching moves forward from the cursor position in the result table and continues until the end of data condition is returned, k-1 rows have been fetched, or an assignment error is returned.

The resulting cursor position depends on the fetch orientation that is specified:

  • For a row-positioned fetch orientation, the cursor is positioned at the last row successfully retrieved.
  • For a rowset-positioned fetch orientation, the cursor is positioned on all the rows retrieved.

The values from each individual fetch are placed in data areas that are described in the INTO or USING clause. If a target specification is provided for a rowset-positioned FETCH, the host variable arrays must be specified as the target specification, and the arrays must be defined with a dimension of 1 or greater. The target specification must be defined as an array for a rowset-positioned FETCH even if the number of rows that is specified implicitly or explicitly is one.

INTO host-variable-array

Identifies for each column of the result table a host-variable-array to receive the data that is retrieved with this FETCH statement. If the number of host-variable-arrays is less than the number of columns of the result table, the SQLWARN3 field of the SQLCA is set to 'W'. No warning is given if there are more host-variable-arrays than the number of columns in the result table.

Each host-variable-array must be defined in the application program in accordance with the rules for declaring an array. A host-variable-array is used to return the values for a column of the result table. The number of rows to be fetched must be less than or equal to the dimension of each of the host-variable-arrays.

An optional indicator array can be specified for a host-variable-array. It should be specified if the SQLTYPE of any SQLVAR occurrence indicates that the column of the result table is nullable. Additionally, if an operation may result in null values, such as an UPDATE operation that results in a hole, is performed in the application, an indicator array should be specified. Otherwise an error occurs if null values are encountered. The indicators are returned as small integers.

INTO DESCRIPTOR descriptor-name

Identifies an SQLDA that must contain a valid description of zero or more host-variable-arrays or buffers into which the values for a column of the result table are to be returned.

Before the FETCH statement is processed, you must set the following fields in the SQLDA:

  • SQLN to indicate the number of SQLVAR occurrences provided in the SQLDA.
  • SQLABC to indicate the number of bytes of storage allocated for the SQLDA.
  • SQLD to indicate the number of variables used in the SQLDA when processing the statement.
  • SQLVAR occurrences to indicate the attributes of an element of the host-variable-array. Within each SQLVAR representing an array:
    • SQLTYPE indicates the data type of the elements of the host-variable-array.
    • SQLDATA field points to the first element of the host-variable-array.
    • The length fields (SQLLEN and SQLLONGLEN) are set to indicate the maximum length of a single element of the array.
    • SQLNAME - The length of SQLNAME must be set to 8, and the first two bytes of the data portion of SQLNAME must be initialized to X'0000'. The fifth and sixth bytes must contain a flag field and the seventh and eighth bytes must be initialized to a binary small integer (half word) representation of the dimension of the host-variable-array, and the corresponding indicator array, if one is specified.

The SQLVAR entry for the number of rows must also contain a flag value. The number of rows to be fetched must be less than or equal to the dimension of each of the host variable arrays.

You set the SQLDATA and SQLIND pointers to the beginning of the corresponding arrays. The SQLDA must have enough storage to contain all SQLVAR occurrences. Each SQLVAR occurrence describes a host-variable-array or buffer into which the values for a column in the result table are to be returned. If any column of the result table is a LOB, two SQLVAR entries must be provided for each SQLVAR, and SQLN must be set to two times the number of SQLVARS. SQLD must be set to a value greater than or equal to zero and less than or equal to SQLN.

Example:

The host-variables parameter identifies a list of COBOL variables defined in working storage. The following is an example of a FETCH statement. We assume that custbl is a cursor previously defined in a DECLARE CURSOR statement.

EXEC SQL
    FETCH custbl
    INTO :CNO, :CNAME
END-EXEC
Parent topic: SQL Statements


FREE LOCATOR

The FREE LOCATOR statement removes the association between a LOB locator variable and its value.

The XDB Server operating environment does not provide support for FREE LOCATOR at this time.

Invocation

This statement can only be embedded in an application program. It cannot be issued interactively. It is an executable statement that can be dynamically prepared. However, the EXECUTE statement with the USING clause must be used to execute the prepared statement. FREE LOCATOR cannot be used with the EXECUTE IMMEDIATE statement.

Authorization

None required.

Syntax

FREE LOCATOR {host-variable}

Description

host-variable,...

Identifies a host-variable locator variable that must have been previously declared according to the rules for declaring host-variable locator variables. The locator variable type must be a binary large object locator, a character large object locator, or a double-byte character large object locator.

After the FREE LOCATOR statement is executed, each locator variable in the host-variable list is no longer associated with the string value it represented.

If a locator variable is not an established locator within the current unit of work, an invalid locator error occurs. When this error occurs and more than one host variable was specified in the FREE LOCATOR statement, only the locators up to the first invalid locator are freed. Locators listed after the first invalid locator are not freed.

Example:

Assume that the employee table contains columns RESUME, HISTORY, and PICTURE and that locators have been established in a program to represent the column values. Free the CLOB locator variables LOCRES and LOCHIST, and the BLOB locator variable LOCPIC.

EXEC SQL FREE LOCATOR :LOCRES, :LOCHIST, :LOCPIC
Parent topic: SQL Statements


GET DIAGNOSTICS

The GET DIAGNOSTICS statement provides diagnostic information about the last SQL statement (other than a GET DIAGNOSTICS statement) that was executed. This diagnostic information is gathered as the previous SQL statement is executed. Some of the information available through the GET DIAGNOSTICS statement is also available in the SQLCA.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

GET DIAGNOSTICS {statement-information | condition-information | combined-information}

statement-information:

{host-variable1 = statement-information-item-name | host-variable1 = DB2_GET_DIAGNOSTICS_DIAGNOSTICS} [,...]

statement-information-item-name:

{DB2_LAST_ROW | DB2_NUMBER_PARAMETER_MARKERS | DB2_NUMBER_RESULT_SETS |
        DB2_RETURN_STATUS | DB2_SQL_ATTR_CURSOR_HOLD |
        DB2_SQL_ATTR_CURSOR_ROWSET | DB2_SQL_ATTR_CURSOR_SCROLLABLE |
        DB2_SQL_ATTR_CURSOR_SENSITIVITY | DB2_SQL_ATTR_CURSOR_TYPE |
        MORE | NUMBER | ROW_COUNT} [,...]

condition-information:

CONDITION {host-variable2 | integer}
       {host-variable3 = {condition-information-item-name | connection-information-item-name}} [,...]

condition-information-item-name:

{CATALOG_NAME | CONDITION_NUMBER | CURSOR_NAME | DB2_ERROR_CODE1 |
DB2_ERROR_CODE2 | DB2_ERROR_CODE3 | DB2_ERROR_CODE4 | DB2_INTERNAL_ERROR_POINTER |
DB2_MESSAGE_ID | DB2_MODULE_DETECTING_ERROR | DB2_ORDINAL_TOKEN_n | DB2_REASON_CODE |
DB2_RETURNED_SQLCODE | DB2_ROW_NUMBER | DB2_SQLERRD_SET | DB2_SQLERRD1 | DB2_SQLERRD2 |
DB2_SQLERRD3 | DB2_SQLERRD4 | DB2_SQLERRD5 | DB2_SQLERRD6 | DB2_TOKEN_COUNT | MESSAGE_TEXT |
RETURNED_SQLSTATE | SERVER_NAME}

connection-information-item-name:

{DB2_AUTHENTICATION_TYPE | DB2_AUTHORIZATION_ID | DB2_CONNECTION_STATE |
DB2_CONNECTION_STATUS | DB2_ENCRYPTION_TYPE | DB2_SERVER_CLASS_NAME | DB2_PRODUCT_ID}

combined-information:

host-variable4 = ALL {STATEMENT | {CONDITION | CONNECTION} [host-variable5 | integer]} [,...]
Note:
  • STATEMENT can only be specified once.
  • CONDITION and CONNECTION can only be specified once if host-variable5 or integer is not also specified.

Description

Diagnostic information is provided in three main areas: statement information, condition information, and combined information. After the execution of an SQL statement, information about the execution of the statement is provided as statement information, and at least one instance of condition information is provided. The number of instances of the condition information is indicated by the NUMBER item that is available in the statement information. Combined information contains a text representation of all the information gathered about the execution of the SQL statement.

The diagnostic information that is provided is specific to the server. If you are connected to a server other than DB2 UDB for z/OS, see that product's documentation for the diagnostic information that is returned.

statement-information

Provides information about the last SQL statement executed.

host-variable1

Identifies a variable described in the program in accordance with the rules for declaring host variables. The data type of the host variable must be the data type as specified in Data types for GET DIAGNOSTICS items.

The host variable is assigned the value of the specified statement information item. If the value is truncated when assigning it to the host variable, a warning is returned and the GET_DIAGNOSTICS_DIAGNOSTICS item of the diagnostics area is updated with the details of this condition. If a DIAGNOSTICS item is not set, then the host variable is set to a default value, based on its data type: 0 for an exact numeric field, an empty string for a VARCHAR field, and blanks for a CHAR field.

DB2_GET_DIAGNOSTICS_DIAGNOSTICS

Contains textual information about errors or warnings that may have occurred in the execution of the GET DIAGNOSTICS statement. The format of the information is similar to what would be returned by a GET DIAGNOSTICS :hv = ALL statement.

statement-information-item-name:

DB2_LAST_ROW

For a multiple-row FETCH statement, contains a value of +100 if the last row currently in the table is in the set of rows that have been fetched. For cursors that are not sensitive to updates, there would be no need to do a subsequent FETCH, because the result would be an end-of-data indication. For cursors that are sensitive to updates, a subsequent FETCH may return more data if a row had been inserted before the FETCH was executed. For statements other than multiple-row FETCH statements, or for multiple-row FETCH statements that do not contain the last row, this variable contains the value 0.

DB2_NUMBER_PARAMETER_MARKERS

For a PREPARE statement, contains the number of parameter markers in the prepared statement. Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_NUMBER_RESULT_SETS

For a CALL statement, contains the actual number of result sets returned by the procedure. Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_NUMBER_ROWS

If the previous SQL statement was an OPEN or a FETCH that caused the size of the result table to be unknown, returns the number of rows in the result table. For SENSITIVE DYNAMIC cursors, this value can be thought of as an approximation because rows that are inserted and deleted will affect the next retrieval of this value. If the previous SQL statement was a PREPARE statement, returns the estimated number of rows in the result table for the prepared statement. Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_RETURN_STATUS

Identifies the status value returned from the stored procedure associated with the previously executed SQL statement, provided that the statement was a CALL statement that invoked a procedure that returns a status. . Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_SQL_ATTR_CURSOR_HOLD

For an ALLOCATE or OPEN statement, indicates whether a cursor can be held open across multiple units of work.

  • N indicates that this cursor does not remain open across multiple units of work.
  • Y indicates that this cursor remains open across multiple units of work.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_ROWSET

For an ALLOCATE or OPEN statement, indicates whether or not a cursor can be accesses using rowset positioning.

  • N indicates that this cursor supports only row positioned operations.
  • Y indicates that this cursor supports rowset positioned operations.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_SCROLLABLE

For an ALLOCATE or OPEN statement, indicates whether or not a cursor can be scrolled forward and backward.

  • N indicates that this cursor is not scrollable.
  • Y indicates that this cursor is scrollable.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_SENSITIVITY

For an ALLOCATE or OPEN statement, indicates whether or not a cursor does or does not show updates to cursor rows made by other connections.

  • I indicates insensitive.
  • S indicates sensitive.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_TYPE

For an ALLOCATE or OPEN statement, indicates the type of cursor, whether a cursor type is forward-only, static, or dynamic.

  • F indicates a forward cursor.
  • D indicates a dynamic cursor.
  • S indicates a static cursor.

Otherwise, a blank is returned.

MORE

Indicates whether some of the warning and errors from the previous SQL statement were stored or discarded.

  • N indicates that all the warnings and errors from the previous SQL statement are stored in the diagnostic area.
  • Y indicates that some of the warnings and errors from the previous SQL statement were discarded because the amount of storage needed to record warnings and errors exceeded 65535 bytes.

NUMBER

Returns the number of errors and warnings detected by the execution of the previous SQL statement, other than a GET DIAGNOSTICS statement, that have been stored in the diagnostics area. If the previous SQL statement returned an SQLSTATE of 00000 or no previous SQL statement has been executed, the number returned is one.

The GET DIAGNOSTICS statement itself may return information via the SQLSTATE parameter, but does not modify the previous contents of the diagnostics area, except for the DB2_GET_DIAGNOSTICS_DIAGNOSTICS item.

ROW_COUNT

Identifies the number of rows associated with the previous SQL statement that was executed.

If the previous SQL statement is a DELETE, INSERT, or UPDATE statement, ROW_COUNT identifies the number of rows deleted, inserted, or updated by that statement, excluding rows affected by either triggers or referential integrity constraints.

If the previous SQL statement is a multiple-row FETCH, ROW_COUNT identifies the number of rows fetched.

A value of -1 indicates a mass delete from a table in a segmented table space.

Otherwise, or if the server only returns an SQLCA, the value zero is returned.

condition-information

Assigns the values of the specified condition information to the associated host variables. The host variable specified must be of the data type that is compatible with the data type of the specified diagnostic-ID or an error occurs. If the value of the condition is truncated when assigning it to the host variable, an error occurs. If an indicator variable was provided, the length of the value is returned in the indicator variable.

If a DIAGNOSTICS item is not set, then the host variable is set to a default value, based on the data type of the item. The specific value will be 0 for a numeric field, an empty string for a VARCHAR field, and blanks for a CHAR field.

host-variable2 or integer

Identifies the diagnostic for which information is requested. Each diagnostic that occurs while executing an SQL statement is assigned an integer. The value 1 indicates the first diagnostic, 2 indicates the second diagnostic, and so on. If the value is 1, the diagnostic information that is retrieved corresponds to the condition that is indicated by the SQLSTATE value actually returned by the execution of the previous SQL statement (other than a GET DIAGNOSTICS statement). The host variable specified must be a numeric data type or an error occurs. An indicator variable is not allowed for this host variable. If a value is specified that is less than or equal to zero or greater than the number of available diagnostics, an error occurs.

host-variable3

Identifies a variable described in the program in accordance with the rules for declaring host variables. The data type of the host variable must be the data type as specified in Data types for GET DIAGNOSTICS items for the indicated condition-information item.

condition-information-item-name:

CATALOG_NAME

If the returned SQLSTATE is any one of the following values, the constraint that caused the error is a referential, check, or unique constraint. The location (RDB) name of the server that generated the condition is returned.

  • Class 09 (Triggered Action Exception)
  • Class 23 (Integrity Constraint Violation)
  • Class 27 (Triggered Data Change Violation)
  • 40002 (Transaction Rollback - Integrity Constraint Violation)
  • 40004 (Transaction Rollback - Triggered Action Exception)

If the returned SQLSTATE is class 42 (Syntax Error or Access Rule Violation), the server name of the table that caused the error is returned.

If the returned SQLSTATE is class 44 (WITH CHECK OPTION Violation), the server name of the view that caused the error is returned.

Otherwise, the empty string is returned.

The actual server name may be different than the server name specified, either implicitly or explicitly, on the CONNECT statement because of the use of aliases or synonyms.

CONDITION_NUMBER

Returns the number of the diagnostic returned.

CURSOR_NAME

If the returned SQLSTATE is class 24 (Invalid Cursor State), the name of the cursor is returned. Otherwise, the empty string is returned.

DB2_ERROR_CODE1

Returns an internal error code (SQLERRD1). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_ERROR_CODE2

Returns an internal error code (SQLERRD2). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_ERROR_CODE3

Returns an internal error code (SQLERRD3). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_ERROR_CODE4

Returns an internal error code (SQLERRD4). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_INTERNAL_ERROR_POINTER

For some errors, this is a negative value that is an internal error pointer. Otherwise, the value 0 is returned.

DB2_MESSAGE_ID

Corresponds to the message that is contained in the MESSAGE_TEXT diagnostic item (for example, DSNT102I or DSNU180I).

DB2_MODULE_DETECTING_ERROR

Returns an identifier indicating which module detected the error. For a SIGNAL statement that is issued from a routine, the value 'ROUTINE' is returned. Otherwise, the string 'DSN ' is returned.

DB2_ORDINAL_TOKEN_n

Returns the nth token. n must be a value from 1 to 100. For example, DB2_ORDINAL_TOKEN_1 would return the value of the first token, DB2_ORDINAL_TOKEN_2 the second token, and so on. A numeric value for a token is converted to characters before being returned. If there is no value for the token, or if the server only returns an SQLCA, an empty string is returned.

DB2_REASON_CODE

Contains the reason code for errors that have a reason code token in the message text. Otherwise, the value zero is returned.

DB2_RETURNED_SQLCODE

Returns the SQLCODE for the specified diagnostic.

DB2_ROW_NUMBER

Returns the number of the row where the condition was encountered, when such information is available and applicable.

DB2_SQLERRD_SET

A value of Y indicates that the DB2_SQLERRD1 through DB2_SQLERRD items might be set. These items are set only when communicating with a server that returns the SQLCA SQL communications area and not the new diagnositics area. Otherwise, a blank is returned.

DB2_SQLERRD1

Returns the value of sqlerrd(1) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD2

Returns the value of sqlerrd(2) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD3

Returns the value of sqlerrd(3) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD4

Returns the value of sqlerrd(4) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD5

Returns the value of sqlerrd(5) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD6

Returns the value of sqlerrd(6) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_TOKEN_COUNT

Returns the number of tokens available for the specified diagnostic ID.

MESSAGE_TEXT

Returns the message text that is associated with the SQLCODE. This is the short text, including substituted tokens. The message text does not contain the message number.

RETURNED_SQLSTATE

Returns the SQLSTATE for the specified diagnostic.

SERVER_NAME

If the previous SQL statement is a CONNECT, DISCONNECT, or SET CONNECTION statement, returns the name of the server specified in the previous statement is returned. Otherwise, the name of the server where the statement executes is returned.

connection-information-item-name

Provides information about the last SQL statement executed if it was a CONNECT statement.

DB2_AUTHENTICATION_TYPE

Contains an authentication type value of:

  • 'S' for a server authentication
  • 'C' for client authentication
  • Otherwise, or if the server only returns an SQLCA, a blank is returned

DB2_AUTHORIZATION_ID

Authorization ID used by connected server. Because of user ID translation and authorization exits, the local user ID may not be the authorized ID used by the server.

DB2_CONNECTION_STATE

Contains the connection state:

  • -1 if the connection is unconnected
  • 1 if the connection is connected

Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_CONNECTION_STATUS

Contains a value of:

  • 1 if committable updates can be performed on the connection for this unit of work
  • 2 if no committable updates can be performed on the connection for this unit of work

Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_SERVER_CLASS_NAME

For a CONNECT or SET CONNECTION statement, contains one of the following values:

  • QAS for DB2 UDB for iSeries(TM)
  • QDB2 for DB2 UDB for OS/390 and z/OS
  • QDB2/2 for DB2 UDB for OS/2
  • QDB2/6000 for DB2 UDB for AIX
  • QDB2/6000 PE for DB2 UDB for AIX Parallel Edition
  • QDB2/AIX64 for DB2 UDB for AIX 64-bit
  • QDB2/HPUX for DB2 UDB for HP-UX
  • QDB2/HP64 for DB2 UDB for HP-UX 64-bit
  • QDB2/LINUX for DB2 UDB for Linux
  • QDB2/LINUX390 for DB2 UDB for Linux
  • QDB2/LINUXIA64 for DB2 UDB for Linux
  • QDB2/LINUXPPC for DB2 UDB for Linux
  • QDB2/LINUXPPC64 for DB2 UDB for Linux
  • QDB2/LINUXZ64 for DB2 UDB for Linux
  • QDB2/PTX for DB2 UDB for NUMA-Q
  • QDB2/SCO for DB2 UDB for SCO UnixWare
  • QDB2/SGI for DB2 UDB for Silicon Graphics
  • QDB2/SNI for DB2 UDB for Siemens Nixdorf
  • QDB2/SUN for DB2 UDB for SUN Solaris
  • QDB2/SUN64 for DB2 UDB for SUN Solaris 64-bit
  • QSQLDS/VM for DB2 for VM and VSE
  • QSQLDS/VSE for DB2 for VM and VSE

Otherwise, the empty string is returned.

DB2_ENCRYPTION_TYPE

The level of encryption for the connection:

  • A indicates only the authentication tokens (authid and password) are encrypted.
  • D indicates all data is encrypted for the connection.

Otherwise, a blank is returned.

DB2_PRODUCT_ID

Returns a product signature. If the application server is an IBM relational database product, the form is pppvvrrm, where:

  • ppp identifies the product as follows:
    • ARI for DB2 Server for VSE & VM
    • DSN for DB2 UDB for z/OS
    • QSQ for DB2 UDB for iSeries
    • SQL for all other DB2 UDB products
  • vv is a two-digit version identifier such as '08'
  • rr is a two-digit release identifier such as '01'
  • m is a one-digit maintenance level identifier such as '5' (Values 0, 1, 2, 3, and 4 are for maintenance levels in compatibility and enabling-new-function mode. Values 5, 6, 7, 8, and 9 are for maintenance levels in new-function mode.)

For example, if the application server is Version 8 of DB2 UDB for z/OS in new-function mode with the latest maintenance, the value would be 'DSN08015'.

combined-information

Provides a text representation of all the information gathered about the execution of the SQL statement.

ALL

Indicates that all diagnostic items that are set for the last SQL statement executed are to be combined into one string. The format of the string is a semicolon separated list of all of the available diagnostic information in the form:

item-name[(condition-number)]=value-converted-to-character;... as shown in the following example:

NUMBER=1;RETURNED_SQLSTATE=02000;DB2_RETURNED_SQLCODE=+100;

host-variable4

Identifies a variable described in the program in accordance with the rules for declaring host variables. The data type of the host variable must be VARCHAR. If the length of host-variable4 is not sufficient to hold the full returned diagnostic string, the string is truncated, a warning is returned, and the GET_DIAGNOSTICS_DIAGNOSITICS item of the diagnostics area is updated with the details of this condition.

STATEMENT

Indicates that all statement-information-item-name diagnostic items that are set for the last SQL statement executed should be combined into one string. The format is the same as described for the ALL option.

CONDITION

Indicates that all condition-information-item-name diagnostic items that are set for the last SQL statement executed should be combined into one string. If host-variable5 or integer is supplied after CONDITION, the format is the same as described above for the ALL option. If host-variable5 or integer is not supplied, the format includes a condition number entry at the beginning of the information for that condition in the form:

CONDITION_NUMBER=X;item-name=value-converted-to-character;... where X is the number of the condition, as shown in the following example:

CONDITION_NUMBER=1;RETURNED_SQLSTATE=02000;RETURNED_SQLCODE=100;

  CONDITION_NUMBER=2;RETURNED_SQLSTATE=01004;

CONNECTION

Indicates that all connection-information-item-name diagnostic items that are set for the last SQL statement executed should be combined into one string. If host-variable5 or integer is supplied after CONNECTION, the format is the same as described for the ALL option. If host-variable5 or integer is not supplied, then the format includes a condition number entry at the beginning of the information for that condition in the form:

CONNECTION_NUMBER=X;item-name=value-converted-to-character;... where X is the number of the condition, as shown in the following example:

CONNECTION_NUMBER=1;CONNECTION_NAME=SVL1;DB2_PRODUCT_ID=DSN08010;

host-variable5 or integer

Identifies the diagnostic for which ALL CONDITION or ALL CONNECTION information is requested. The host variable specified must be a numeric data type or an error occurs. An indicator variable is not allowed for this host variable or an error occurs. If a value is specified that is less than or equal to zero or greater than the number of available diagnostics, an error occurs.

Note:

The GET DIAGNOSTICS statement does not change the contents of the diagnostics area (SQLCA). If an SQLSTATE or SQLCODE special variable is declared in the SQL procedure, these are set to the SQLSTATE or SQLCODE returned from issuing the GET DIAGNOSTICS statement. The SQLSTATE and SQLCODE values from before the GET DIAGNOSTICS statement was issued are still available in the diagnostics area by issuing a GET DIAGNOSTICS for RETURNED_SQLSTATE and DB2_RETURNED_SQLCODE.

Data types for GET DIAGNOSTICS items

Item | Data Type
Statement Information
DB2_GET_DIAGNOSTICS_DIAGNOSTICS | VARCHAR(32672)
DB2_LAST_ROW | INTEGER
DB2_NUMBER_PARAMETER_MARKERS | INTEGER
DB2_NUMBER_RESULT_SETS | INTEGER
DB2_NUMBER_ROWS | DECIMAL(31,0)
DB2_RETURN_STATUS | INTEGER
DB2_SQL_ATTR_CURSOR_HOLD | CHAR(1)
DB2_SQL_ATTR_CURSOR_ROWSET | CHAR(1)
DB2_SQL_ATTR_CURSOR_SCROLLABLE | CHAR(1)
DB2_SQL_ATTR_CURSOR_SENSITIVITY | CHAR(1)
DB2_SQL_ATTR_CURSOR_TYPE | CHAR(1)
MORE | CHAR(1)
NUMBER | INTEGER
ROW_COUNT | DECIMAL(31,0)
CATALOG NAME | VARCHAR(128)
CONDITION_NUMBER | INTEGER
CURSOR_NAME | VARCHAR(128)
DB2_ERROR_CODE1 | INTEGER
DB2_ERROR_CODE2 | INTEGER
DB2_ERROR_CODE3 | INTEGER
DB2_ERROR_CODE4 | INTEGER
DB2_INTERNAL_ERROR_POINTER | INTEGER
DB2_MESSAGE_ID | CHAR(10)
DB2_MODULE_DETECTING_ERROR | CHAR(8)
DB2_ORDINAL_TOKEN_n | VARCHAR(515)
DB2_REASON_CODE | INTEGER
DB2_RETURNED_SQLCODE | INTEGER
DB2_ROW_NUMBER | DECIMAL(31,0)
DB2_TOKEN_COUNT | INTEGER
MESSAGE_TEXT | VARCHAR(32672)
RETURNED_SQLSTATE | CHAR(5)
SERVER_NAME | VARCHAR(128)
Connection Information
DB2_AUTHENTICATION_TYPE | CHAR(1)
DB2_AUTHORIZATION_ID | VARCHAR(128)
DB2_CONNECTION_STATE | INTEGER
DB2_CONNECTION_STATUS | INTEGER
DB2_ENCRYPTION_TYPE | CHAR(1)
DB2_PRODUCT_ID | VARCHAR(8)
DB2_SERVER_CLASS_NAMED | CHAR(128)
ALL | VARCHAR(32672)
Note:
  • The GET DIAGNOSTICS statement is supported from a DB2 UDB for z/OS Version 8 client, regardless of the level of the server (a DB2 UDB for z/OS Version 7 or a DB2 UDB for Windows Version 7, for example). When connected to servers that do not support the Open Group Version 3 DRDA standard, a subset of diagnostic information is generated based on the returned SQLCA. The condition contains the following information:
    • The DB2_RETURNED_SQLCODE is set based on the SQLCODE.
    • The RETURNED_SQLSTATE is set based on the SQLSTATE.
    • The DB2_GET_DIAGNOSTICS_DIAGNOSTICS item contains the information from the SQLCA that came from the server.

    Only if you are using multi-row fetch or insert is there a need to have the extended diagnostic information that is provided by servers that support the Open Group Version 3 DRDA standard.

  • To provide compatibility with previous releases of DB2 or other products in the DB2 UDB family, DB2 supports the following keywords:
    • RETURN_STATUS as a synonym for DB2_RETURN_STATUS
    • EXCEPTION as a synonym for CONDITION
Parent topic: SQL Statements


GRANT (Database Privileges)

The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. Since the XDB Server does not functionally use these types of privileges, they are not detailed in this reference. Users are encouraged to consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

GRANT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To grant privileges on an object, users must either possess a specific privilege WITH GRANT OPTION for the object, be the owner of the object, or possess overall SYSADM authority for the location. Users with DBADM authority over a database also possess GRANT option privileges on tables (except for views) within that database, provided DBADM authority was acquired with the GRANT option. When embedded in a host language or dynamically prepared, the GRANT command has access to the same privileges held by the CURRENT SQLID of the application process.

Syntax

This format is used to grant privileges on a specified database. Please note that to grant the CREATETAB privilege, you must also grant CREATETS privileges for that database to the same AuthID. One or more privilege option keywords (separated with commas) may be specified after GRANT, allowing multiple privileges to be granted in one statement.

For a TEMP database, PUBLIC implicitly has the CREATETAB privilege (without GRANT authority) to define declared temporary tables; this privilege is not recorded in the DB2 catalog, and it cannot be revoked.

In every case, the privileges chosen are granted only to the logical database(s) named in the GRANT statement.

GRANT
        [DBADM[, ]]
        [DBCTRL[, ]]
        [DBMAINT[, ]]
        [CREATETAB[, ]]
        [CREATETS[, ]]
        [DROP[, ]]
        [STARTDB[, ]]
        [STATS[, ]]
        [STOPDB[, ]]
    ON DATABASE database-name[,...]
    TO [AuthID][,...][PUBLIC]
    [WITH GRANT OPTION]

Parameters:

DBADM | Database administrator authority.
DBCTRL | Database control authority.
DBMAINT | Database maintenance authority.
CREATETAB | Privilege to create new tables.
CREATETS | Privilege to create new table spaces.
DROP | Privilege to issue the DROP or ALTER DATABASE statements for the designated databases.
STARTDB | Privilege to issue the START DATABASE command.
STOPDB | Privilege to issue the STOP DATABASE command.
Note: The DISPLAYDB, IMAGCOPY, LOAD, RECOVERDB, REORG and REPAIR, and STATS database grant/revoke privileges are specific to the DB2 mainframe environment, and control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, the XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.
database-name | Identifies a database on which privileges are to be granted. The grantor must already possess all the privileges specified with the GRANT option, for each database named. Each database named must exist at the current location.
AuthID | Identifies a user authorization ID being granted the privilege(s) specified. The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), granting privileges to all valid authorization IDs at the current location.

Description

The GRANT command is used to confer system, database, table and view privileges to specified AuthID(s). The XDB Server supports three separate formats for the GRANT command, depending on the type of privilege granted. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

The privileges resulting from the execution of a GRANT command statement are recorded as one or more individual grants in the current location system catalog. Each individual grant involves the granting of one privilege by a grantor to one grantee. A grantee can be any AuthID (as recorded in the system catalog for that location), plus the PUBLIC or PUBLIC AT ALL LOCATIONS designations. The status of each privilege granted is recorded in the system catalog for each AuthID.

The same privilege can be granted to a single grantee by several different grantor AuthIDs. The grantee retains the privilege as long as one (or more) of these grants remains recorded in the system catalog. Individual grants (or groups of grants) can be removed from the system catalog by executing REVOKE commands.

WITH GRANT OPTION

If the WITH GRANT OPTION clause is used, the grantee can grant the privileges specified in the GRANT command to other valid AuthIDs. If users attempt to assign GRANT authority to either PUBLIC or PUBLIC AT ALL LOCATIONS, the privileges named in the GRANT command are granted, but without GRANT authority. Specifying WITH GRANT OPTION is valid but unnecessary when granting SYSADM privileges, since whoever is granted this high-level system privilege automatically receives the ability to assign privileges to other AuthIDs.

PUBLIC

Privileges may be granted to a specific set of users by listing their AuthIDs in the TO clause of the GRANT statement. To grant privileges to all system users in the location, use the keyword PUBLIC. To GRANT to all users system-wide, use PUBLIC AT ALL LOCATIONS in the TO clause of the GRANT statement. Users who have not been specifically granted any privileges have only those privileges granted to PUBLIC. When a privilege is granted to PUBLIC, the system continues to maintain the list of user names that have been specifically granted the privilege.

Example:

To grant database administrator (DBADM) authority on the EMPLOYEE database to AuthID usera:

GRANT DBADM
    ON DATABASE employee
    TO usera;
Parent topic: SQL Statements


GRANT (Function or Procedure Privileges)

This form of the GRANT statement grants privileges on user-defined functions, cast functions that are generated for distinct types, and stored procedures.

Syntax

GRANT EXECUTE ON
{   FUNCTION {function-name [(parameter-type[,...])] | * } |
    SPECIFIC FUNCTION specific-name[,...] |
    PROCEDURE {procedure-name[,...] |
    *
}
    TO {authorization-name[,...] | PUBLIC} [WITH GRANT OPTION]

parameter-type:

{data-type [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{ {CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

EXECUTE

Grants the privilege to run the identified user-defined function, cast function that was generated for a distinct type, or stored procedure.

FUNCTION or SPECIFIC FUNCTION

Identifies the function on which the privilege is granted. The function must exist at the current server, and it must be a function that was defined with the CREATE FUNCTION statement or a cast function that was generated by a CREATE DISTINCT TYPE statement.

If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name

Identifies the function by its name. You can identify a function by its name only if there is exactly one function with function name in the schema. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified on unqualified function-name. An * (or schema-name.*) indicates that the privilege is granted on all the functions in the schema including those that do not currently exist. Specifying an * does not affect any EXECUTE privileges that are already granted on a function.

FUNCTION function-name (parameter-type,...)

Identifies the function by its function signature, which uniquely identifies the function.

function-name Specifies the name of the function. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.
(parameter-type,...) Identifies the number of input parameters of the function and their data types.

The data type of each parameter must match the data type that was specified in the CREATE FUNCTION statement for the parameter in the corresponding position. The number of data types and the logical concatenation of the data types is used to uniquely identify the function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that DB2 ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:
    • CHAR implies CHAR(1)
    • GRAPHIC implies GRAPHIC(1)
    • DECIMAL implies DECIMAL(5,0)
    • FLOAT implies DOUBLE (length of 8)

    The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that DB2 ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name

Identifies the function by its specific name.

PROCEDURE procedure-name

Identifies a stored procedure that is defined at the current server. If you do not explicitly qualify the procedure name with a schema name, the procedure name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified or unqualified procedure-name. An * (or schema-name.*) indicates that the privilege is granted on all the stored procedures in the schema including those that do not currently exist. Specifying an * does not affect any EXECUTE privileges that are already granted on a stored procedure.

Example:

Grant the EXECUTE privilege on function CALC_SALARY to user JONES. Assume that there is only one function in the schema with function name CALC_SALARY.

GRANT EXECUTE ON FUNCTION CALC_SALARY TO JONES;

Grant the EXECUTE privilege on procedure VACATION_ACCR to all users at the current server.

GRANT EXECUTE ON PROCEDURE VACATION_ACCR TO PUBLIC;

Grant the EXECUTE privilege on function DEPT_TOTALS to the administrative assistant and give the assistant the ability to grant the EXECUTE privilege on this function to others. The function has the specific name DEPT85_TOT. Assume that the schema has more than one function that is named DEPT_TOTALS.

GRANT EXECUTE ON SPECIFIC FUNCTION DEPT85_TOT TO ADMIN_A
    WITH GRANT OPTION;

Grant the EXECUTE privilege on function NEW_DEPT_HIRES to HR (Human Resources). The function has two input parameters with data types of INTEGER and CHAR(10), respectively. Assume that the schema has more than one function that is named NEW_DEPT_HIRES.

GRANT EXECUTE ON FUNCTION NEW_DEPT_HIRES (INTEGER, CHAR(10))
    TO HR;

You can also code the CHAR(10) data type as CHAR().

Parent topic: SQL Statements
Related information
GRANT (Table or View Privileges)
GRANT (System Privileges)
GRANT (Database Privileges)


GRANT (Table or View Privileges)

The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. Since the XDB Server does not functionally use these types of privileges, they are not detailed in this reference. Users are encouraged to consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

GRANT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To grant privileges on an object, users must either possess a specific privilege WITH GRANT OPTION for the object, be the owner of the object, or possess overall SYSADM authority for the location. Users with DBADM authority over a database also possess GRANT option privileges on tables (except for views) within that database, provided DBADM authority was acquired with the GRANT option. When embedded in a host language or dynamically prepared, the GRANT command has access to the same privileges held by the CURRENT SQLID of the application process.

Syntax

This format is used to grant privileges on individual tables or views. One or more of the privilege keywords defined below (separated with commas) or the optional keyword(s) ALL [PRIVILEGES] may be specified after GRANT, allowing multiple table privileges to be evoked in one GRANT statement. Does not include ALTER, INDEX, REFERENCES, or TRIGGER for a grant to PUBLIC AT ALL LOCATIONS.

GRANT
{
        [ALTER[, ]]
        [DELETE[, ]]
        [INDEX[, ]]
        [INSERT[, ]]
        [SELECT[, ]]
        [UPDATE [(column-name[,...])]]
        [TRIGGER]
        [REFERENCES [(column-name [,...])]]
        | ALL [PRIVILEGES]
}
    ON [TABLE] {table-name[,...] | view-name[,...]}
    TO [AuthID][,...][PUBLIC [AT ALL LOCATIONS]]
    [WITH GRANT OPTION]

This format is used to grant privileges on individual tables or views. One or more of the privilege keywords defined below (separated with commas) or the optional keyword(s) ALL [PRIVILEGES] may be specified after GRANT, allowing multiple table privileges to be evoked in one GRANT statement. Does not include ALTER, INDEX, REFERENCES, or TRIGGER for a grant to PUBLIC AT ALL LOCATIONS.

GRANT
{
        [ALTER[, ]]
        [DELETE[, ]]
        [INDEX[, ]]
        [INSERT[, ]]
        [SELECT[, ]]
        [UPDATE [(column-name[,...])]]
        [TRIGGER]
        [REFERENCES [(column-name [,...])]]
        | ALL [PRIVILEGES]
}
    ON [TABLE] {table-name[,...] | view-name[,...]}
    TO [AuthID][,...][PUBLIC [AT ALL LOCATIONS]]
    [WITH GRANT OPTION]

Parameters:

ALTER | Privilege to use the ALTER TABLE statement ALTER cannot be granted to PUBLIC AT ALL LOCATIONS. (cannot specify an auxiliary table or view).
DELETE | Privilege to use the DELETE statement.
INDEX | Privilege to use the CREATE INDEX statement (cannot specify a view).
INSERT | Privilege to use the INSERT statement (cannot be granted on an auxiliary table.)
SELECT | Privilege to use the SELECT statement. (cannot be granted on an auxiliary table.)
UPDATE | Privilege to use the UPDATE statement on all columns of the tables named in the ON clause. When followed by (column-name[,...]), the update privilege applies only to the columns specified in parentheses.( must not identify a column of an auxiliary table.)
REFERENCES | Privilege to create/drop a foreign key. (cannot specify an auxiliary table or view).
column-name | Specifies an individual column in a table for which the UPDATE or the REFERENCES privilege is being granted. If you specify a list of columns after the REFERENCES keyword, each column-name must be the unqualified name of a column in a table that is identified in the ON clause.
table-name or view-name | Preceded by the keyword(s) ON [TABLE], identifies a table or view affected.
authID | Identifies a user authorization ID being granted the privilege(s) specified. The optional PUBLIC [AT ALL LOCATIONS] keyword(s) can be specified along with (or in place of) an AuthID (or a list of AuthIDs). The PUBLIC AT ALL LOCATIONS keyword option grants the specified table privileges to all users at every location.
Note:

To grant privileges to all tables (or views) contained within a database, simply grant the privilege to the database.

If the ALL [PRIVILEGES] keywords are specified following GRANT, all table or view privileges (for which the issuer has GRANT authority) are granted for the objects identified in the ON clause.

In every case, the privileges specified are granted only on the tables or views named in the ON [TABLE] clause. Multiple table and/or view names can be listed, provided they are separated by commas. Table privileges may be granted by users possessing DBADM for the database or by the creator of the table or view the privilege is granted on. ALTER or INDEX privileges are not included in a grant to PUBLIC AT ALL LOCATIONS.

For an auxiliary table, only the INDEX privilege can be granted. DELETE, INSERT, SELECT, and UPDATE privileges on the base table that is associated with the auxiliary table extend to the auxiliary table.

Description

The GRANT command is used to confer system, database, table and view privileges to specified AuthID(s). The XDB Server supports three separate formats for the GRANT command, depending on the type of privilege granted. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

The privileges resulting from the execution of a GRANT command statement are recorded as one or more individual grants in the current location system catalog. Each individual grant involves the granting of one privilege by a grantor to one grantee. A grantee can be any AuthID (as recorded in the system catalog for that location), plus the PUBLIC or PUBLIC AT ALL LOCATIONS designations. The status of each privilege granted is recorded in the system catalog for each AuthID.

The same privilege can be granted to a single grantee by several different grantor AuthIDs. The grantee retains the privilege as long as one (or more) of these grants remains recorded in the system catalog. Individual grants (or groups of grants) can be removed from the system catalog by executing REVOKE commands.

WITH GRANT OPTION

If the WITH GRANT OPTION clause is used, the grantee can grant the privileges specified in the GRANT command to other valid AuthIDs. If users attempt to assign GRANT authority to either PUBLIC or PUBLIC AT ALL LOCATIONS, the privileges named in the GRANT command are granted, but without GRANT authority. Specifying WITH GRANT OPTION is valid but unnecessary when granting SYSADM privileges, since whoever is granted this high-level system privilege automatically receives the ability to assign privileges to other AuthIDs.

PUBLIC

Privileges may be granted to a specific set of users by listing their AuthIDs in the TO clause of the GRANT statement. To grant privileges to all system users in the location, use the keyword PUBLIC. To GRANT to all users system-wide, use PUBLIC AT ALL LOCATIONS in the TO clause of the GRANT statement. Users who have not been specifically granted any privileges have only those privileges granted to PUBLIC. When a privilege is granted to PUBLIC, the system continues to maintain the list of user names that have been specifically granted the privilege.

Example:

The example below grants authority for the individuals with the AuthIDs userb and userc to update the PART table.

GRANT UPDATE
    ON part
    TO userb, userc

To grant privileges to all users in the location to select, update, insert, and delete records from the PART and SUPPLIER tables, use the command:

GRANT SELECT, UPDATE, INSERT, DELETE
    ON part, supplier
    TO PUBLIC

To grant privileges on a subset of the columns in the EMPLOYEE table to usera, and at the same time give usera the ability to grant the privilege to other users, issue the command:

GRANT UPDATE(address, city, state, zip, phone)
    ON employee
    TO usera
    WITH GRANT OPTION

In this case AuthID usera does not have the ability to update employee number, name, department, or pay rate values.

To grant all privileges on the EMPLOYEE table to AuthID usera:

GRANT ALL
    ON TABLE employee
    TO usera;
Parent topic: SQL Statements
Related information
REVOKE (Table or View Privileges)
GRANT (Database Privileges)
GRANT (System Privileges)
GRANT (Function or Procedure Privileges)


GRANT (Sequence Privileges)

This form of the GRANT statement grants privileges on a user-defined sequence.

Syntax

GRANT {ALTER | USAGE} [,...] ON SEQUENCE sequence-name [,...]
TO {authorization-name | PUBLIC} [,...] [WITH GRANT OPTION]
Note: The keyword SELECT is an alternative keyword for USAGE.

Description

ALTER

Grants the privilege to alter a sequence or record a comment on a sequence.

USAGE

Grants the USAGE privilege to use a sequence. This privilege is needed when the NEXT VALUE or PREVIOUS VALUE expression is invoked for a sequence name.

SEQUENCE sequence-name

Identifies the sequence. The name, including the implicit or explicit schema qualifier, must uniquely identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs. sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column.

TO

Specifies to what authorization IDs the privileges are granted.

authorization-name,...

Lists one or more authorization IDs. The value of CURRENT RULES determines whether you can use the ID of the GRANT statement itself (to grant privileges to yourself). When CURRENT RULES is:

DB2 | You cannot use the ID of the GRANT statement.
STD | You can use the ID of the GRANT statement.

PUBLIC

Grants the privileges to all users at the current server, including database requesters using DRDA access.

PUBLIC AT ALL LOCATIONS

Grants the privileges to all users in the network. Applies to table privileges only, excluding ALTER, INDEX, REFERENCES, and TRIGGER. PUBLIC AT ALL LOCATIONS applies to DB2 private protocol access only.

WITH GRANT OPTION

Allows the named users to grant the privileges to others. Granting an administrative authority with this option allows the user to specifically grant any privilege belonging to that authority. If you omit WITH GRANT OPTION, the named users cannot grant the privileges to others unless they have that authority from some other source. GRANT authority cannot be passed to PUBLIC or to PUBLIC AT ALL LOCATIONS. When WITH GRANT OPTION is used with either of these, a warning is issued, and the named privileges are granted, but without GRANT authority.

Parent topic: SQL Statements


GRANT (System Privileges)

The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. Since the XDB Server does not functionally use these types of privileges, they are not detailed in this reference. Users are encouraged to consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

GRANT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To grant privileges on an object, users must either possess a specific privilege WITH GRANT OPTION for the object, be the owner of the object, or possess overall SYSADM authority for the location. Users with DBADM authority over a database also possess GRANT option privileges on tables (except for views) within that database, provided DBADM authority was acquired with the GRANT option. When embedded in a host language or dynamically prepared, the GRANT command has access to the same privileges held by the CURRENT SQLID of the application process.

Syntax

This format is used to grant system privileges. In every case, the system privileges specified are granted only to the AuthID(s) specified in the TO clause. One or more of the privilege option keywords defined below (separated with commas) may be specified after GRANT, allowing multiple system privileges to be granted in one GRANT statement.

GRANT
        [CREATEALIAS[, ]]
        [CREATEDBA[, ]]
        [CREATEDBC[, ]]
        [CREATETMTAB[, ]]
        [CREATESG[, ]]
        [SYSADM[, ]]
        [SYSCTRL[, ]]
    TO [AuthID][,...][PUBLIC]
    [WITH GRANT OPTION]

This format is used to grant system privileges. In every case, the system privileges specified are granted only to the AuthID(s) specified in the TO clause. One or more of the privilege option keywords defined below (separated with commas) may be specified after GRANT, allowing multiple system privileges to be granted in one GRANT statement.

GRANT
        [CREATEALIAS[, ]]
        [CREATEDBA[, ]]
        [CREATEDBC[, ]]
        [CREATETMTAB[, ]]
        [CREATESG[, ]]
        [SYSADM[, ]]
        [SYSCTRL[, ]]
    TO [AuthID][,...][PUBLIC]
    [WITH GRANT OPTION]

Parameters:

CREATEALIAS | Privilege to use the CREATE ALIAS statement.
CREATEDBA | Privilege to issue the CREATE DATABASE statement and acquire DBADM authority over those databases.
CREATEDBC | Privilege to issue the CREATE DATABASE statement and acquire DBCTRL authority over those databases.
CREATETMTAB | Privilege to issue the CREATE GLOBAL TEMPORARY TABLE statement.
CREATESG | Privilege to create new storage groups.
SYSADM | Grants system administrator authority for the location, which includes all privileges except for a few reserved for INSTALL authority. These privileges are all grantable, including the SYSADM authority itself.
SYSCTRL | Grants the system control authority for the location, allowing the holder most of the privileges of a system administrator, but excluding privileges to read or change user data.
Note:

The ARCHIVE, BINDADD, BINDAGENT, BSDS, DISPLAY, MONITOR1, MONITOR2, RECOVER, STOPALL, STOSPACE, SYSOPR, and TRACE system privileges are specific to the DB2 mainframe environment, and control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, the XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.

AuthID Identifies a user authorization ID being granted the specified privilege(s). The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), granting privileges to each valid AuthID at the current location.

Description

The GRANT command is used to confer system, database, table and view privileges to specified AuthID(s). The XDB Server supports three separate formats for the GRANT command, depending on the type of privilege granted. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

The privileges resulting from the execution of a GRANT command statement are recorded as one or more individual grants in the current location system catalog. Each individual grant involves the granting of one privilege by a grantor to one grantee. A grantee can be any AuthID (as recorded in the system catalog for that location), plus the PUBLIC or PUBLIC AT ALL LOCATIONS designations. The status of each privilege granted is recorded in the system catalog for each AuthID.

The same privilege can be granted to a single grantee by several different grantor AuthIDs. The grantee retains the privilege as long as one (or more) of these grants remains recorded in the system catalog. Individual grants (or groups of grants) can be removed from the system catalog by executing REVOKE commands.

WITH GRANT OPTION

If the WITH GRANT OPTION clause is used, the grantee can grant the privileges specified in the GRANT command to other valid AuthIDs. If users attempt to assign GRANT authority to either PUBLIC or PUBLIC AT ALL LOCATIONS, the privileges named in the GRANT command are granted, but without GRANT authority. Specifying WITH GRANT OPTION is valid but unnecessary when granting SYSADM privileges, since whoever is granted this high-level system privilege automatically receives the ability to assign privileges to other AuthIDs.

PUBLIC

Privileges may be granted to a specific set of users by listing their AuthIDs in the TO clause of the GRANT statement. To grant privileges to all system users in the location, use the keyword PUBLIC. To GRANT to all users system-wide, use PUBLIC AT ALL LOCATIONS in the TO clause of the GRANT statement. Users who have not been specifically granted any privileges have only those privileges granted to PUBLIC. When a privilege is granted to PUBLIC, the system continues to maintain the list of user names that have been specifically granted the privilege.

Example:

The following example grants SYSADM authority for the TUTORIAL location to the individual with the AuthID usera. With SYSADM authority AuthID usera acquires authority to perform all functions on the TUTORIAL location, including authority to grant privileges.

GRANT SYSADM TO usera
Parent topic: SQL Statements


HALT QUERY FROM

Use the HALT QUERY FROM command to terminate a running query. You can specify the query by user ID or by node name. This command is useful for canceling a query operation that is monopolizing the server computer.

Note:

The HALT QUERY FROM command affects only running queries--ones that are literally in process on the XDB Server at the moment the command is issued. It does not cancel queries that are not actively under execution; for example, ones in which the client is simply fetching records from a result table. A query in this state is active, but is not running on the server. To cancel a query in this state, you must terminate it from the client application or force the user off the system using the XDB Server Monitor.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following

  • The owner of the query
  • A super user
  • A user with SYSADM or SYSCTRL privileges

Syntax

HALT QUERY FROM USER user-name

or ...

HALT QUERY FROM node-name

Parameters:

user-name | Is the user ID of the user (or program) that initiated the query. The HALT QUERY FROM USER command cancels all running queries for the specified ID. For example, if three users were each running a query program that logged on to the server using the same ID, all three queries would be canceled. If you need to cancel one specific user's query, use HALT QUERY FROM node-name instead
node-name | Is the name of the node from which the query was issued. To display a list of the active node names, use the XDB Server Monitor or query the Virtual Statistics table (XDBSTAT.USERLIST). Specify the entire name of the node as displayed by the XDB Server Monitor or listed in the Virtual Statistics table, including the :number part of the name
Parent topic: SQL Statements


HOLD LOCATOR

The HOLD LOCATOR statement allows a LOB locator variable to retain its association with a value beyond a unit of work. The XDB operating environment does not support the LOB data type at this time.

Invocation

This statement can only be embedded in an application program. It cannot be issued interactively. It is an executable statement that can be dynamically prepared. However, the EXECUTE statement with the USING clause must be used to execute the prepared statement. HOLD LOCATOR cannot be used with the EXECUTE IMMEDIATE statement.

Authorization

None required.

Syntax

HOLD LOCATOR {host-variable}

Description:

host_variable,...

Identifies a host-variable locator variable that must have been previously declared according to the rules for declaring host variables. The locator variable type must be a binary large object locator, a character large object locator, or a double-byte character large object locator.

After the HOLD LOCATOR statement is executed, each locator variable in the host-variable list has the hold property. If a locator variable is not an established locator within the current unit of work, an invalid locator error occurs. When this error occurs and more than one host variable was specified in the HOLD LOCATOR statement, only the locators up to the first invalid locator are held. Locators listed after the first invalid locator are not held.

A host-variable LOB locator variable that has the hold property is freed (has its association between it and its value removed) when:

  • The SQL FREE LOCATOR statement is executed for the locator variable.
  • The SQL ROLLBACK statement is executed.
  • The SQL session is terminated.

Example:

Assume that the employee table contains columns RESUME, HISTORY, and PICTURE and that locators have been established in a program to represent the values represented by the columns. Give the CLOB locator variables LOCRES and LOCHIST, and the BLOB locator variable LOCPIC the hold property.

EXEC SQL HOLD LOCATOR :LOCRES, :LOCHIST, :LOCPIC
Parent topic: SQL Statements


INCLUDE

The INCLUDE statement (embedded SQL only) inserts declarations or code into source programs from external files.

Invocation

INCLUDE can only be embedded in a host language. INCLUDE is not an executable command and cannot be dynamically prepared.

Authorization

No special authorization is needed for INCLUDE.

Syntax

INCLUDE {SQLCA | SQLDA | member-name}

Parameters:

member-name The member name (or file name) can contain any host language source statements or SQL statements, except the INCLUDE statement. In COBOL, the statement "INCLUDE member-name" must not appear anywhere other than the DATA DIVISION or the PROCEDURE DIVISION section. See your XDB Server precompiler documentation for specifics about the member-name parameter.

Description

The INCLUDE statement is used to bring external files (containing either data definitions or segments of program code that must be precompiled) into an application. When precompiled, the INCLUDE statement is replaced by the source statements. The INCLUDE statement must therefore be specified at a point in the application program where the resulting source statements are accepted by the compiler. The INCLUDE statement cannot introduce source statements that themselves contain INCLUDE statements. Depending on the host language used, INCLUDE can also identify SQL communication and descriptor areas.

SQLCA

Indicates an SQL communication area (SQLCA) description is to be included. Do not specify INCLUDE SQLCA more than once in the same application program. See XDB Server SQL Communications Area (SQLCA) for more information about the SQLCA.

SQLDA

Indicates an SQL descriptor area (SQLDA) description is to be included. See XDB Server SQL Descriptor Area (SQLDA) for more information about the SQLDA.

Example:

The file must reside in the directory specified by the environment variable COBCPY (Micro Focus) or SYSLIB (CA-Realia II). The XDB Server precompiler looks for the file extensions .CPY and .CBL if the XDBCPY directive is active. With CA-Realia II, the XDB Server precompiler looks for the .COB extension by default. Consult your XDB Server precompiler documentation for further details.

EXEC SQL
    INCLUDE emprec
END-EXEC
Parent topic: SQL Statements


INSERT

The INSERT command is an SQL command used to insert zero or more rows of data values (or records) into an existing table or view. The table or view receiving the new rows can be at the current location or any other location accessible to the XDB Server. Inserting a row into a view also inserts the row into that view's underlying table (if the view is updatable).

Invocation

INSERT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

Authority requirements depend on whether the object identified in the statement is a table or view. When rows are inserted into a table, the privileges held by the user must include either the INSERT privilege on the table, ownership of the table, DBADM authority on the database containing the table, or overall SYSADM authority for the location. When rows are inserted into a view, the privileges held by the user must include either the INSERT privilege on the view, or overall SYSADM authority.

Users should be aware that a view owner (unlike a table owner) may not have INSERT authority on the view, since the nature of the view itself could preclude its use for INSERT. Alternatively, the view owner might possess INSERT authority, but be unable to grant it to others. Additionally, if a subselect is specified, the user must possess authority to execute the subselect.

If the INSERT command is prepared at a location other than the current location, the total available privileges include all privileges recorded in the system catalog where the INSERT is executed.

If an expression that refers to a function is specified, the privilege set must include any authority that is necessary to execute the function.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke.)

Syntax

INSERT INTO {table-name | view-name}
    [(column-name [,...])]
    [OVERRIDING USER VALUE]
    {VALUES {{expression | DEFAULT | NULL} | ({expression | DEFAULT | NULL}[,...]) |
    [WITH common-table-expression [,...]] fullselect [isolation-clause] [QUERYNO integer] |
    multiple-row-insert}

isolation-clause

WITH {RR | RS | CS

multiple-row-insert

VALUES {expression | host-variable-array | NULL | DEFAULT |
    ({expression | host-variable-array | NULL | DEFAULT} [,...]})
    [FOR [host-variable | integer-constant] ROWS]
    [ATOMIC | NOT ATOMIC CONTINUE ON SQLEXCEPTION]

Parameters:

table-name or view-name | Preceded by the keyword INTO, identifies the object (table or view) of the INSERT statement. If a view, the view must be updatable, in which case the underlying table is affected. A catalog table (or a view of a catalog table) or an auxiliary table cannot be specified.
column-list | Specifies an optional list of columns into which the data is to be inserted. The column list, if specified, must be enclosed in parentheses, with each column name separated by a comma. If the column list is omitted, all columns in the target table or view are assigned values -- proceeding in order from left to right.
value-list | Preceded by the keyword VALUES, specifies one row of values (composed of constants, host-variables, NULLs, or special-registers) to be inserted into the target table or view. Each host variable named must represent a declared variable or structure, properly described in the application program in accordance with the rules for declaring variables and structures in the host language.
subselect | Indicates a subselect that retrieves data from another table to insert into the table named in the INSERT command. The same table cannot be the base object of both the INSERT command and the subselect (or any subquery of the subselect). An INSERT command cannot include both a subselect statement and a VALUES clause.

Tables referenced in all selects (or subselects) contained in a single INSERT command must be from the same location as the table or view into which data is being inserted. That is, you cannot INSERT into the TUTORIAL location and select from the DEBLOC location.

Invalid:

INSERT INTO tutorial.tutorial.practice
    SELECT * FROM debloc.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM debloc.debbie.employee
                WHERE st = "MD";

Valid:

INSERT INTO tutorial.tutorial.practice
    SELECT * FROM tutorial.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM tutorial.debbie.employee
                WHERE st = "MD";

Description

The INSERT command is used to insert one or more record(s) into an existing table. Data inserted with the INSERT command can be specified by the user in the INSERT command or retrieved from other tables using a subselect statement. The INSERT command takes on one of the following two configurations:

  • The INSERT statement using the VALUES keyword inserts a single row into the table or view, using the values provided or referenced.
  • The INSERT statement with a subselect inserts zero or more rows into the table or view, using values retrieved from other tables and/or views by the subselect.

OVERRIDING USER VALUE

Specifies that the value specified in the VALUES clause or produced by a subselect for a column that is defined as GENERATED ALWAYS is ignored. Instead, a system-generated value is inserted, overriding the user-specified value.

Specify OVERRIDING USER VALUE only if the insert involves a column defined as GENERATED ALWAYS, such as a ROWID column or an identity column.

VALUES

The number of individual data items in the VALUES clause must equal the number of items in the column list. The first data item in the value list is inserted in the first column in the column list, the second value in the second column, etc. A value list must be included if a subselect is not specified. The value list must be enclosed in parentheses. Values must be separated from each other by commas. Character strings should appear in quotes (single or double). If the value to be inserted in a column is null, the keyword NULL should appear in the appropriate location in the value list.

expression | Any expression of the type described in "Expressions" in topic 3.19. The expression must not include a column name. If expression is a single host variable, the host variable can identify a structure. Any host variable or structure that is specified must be described in the application program according to the rules for declaring host structures and variables.
DEFAULT | The default value assigned to the column. If the column is a ROWID column or an identity column, DB2 will generate a unique value for the column. You can specify DEFAULT only for columns that have an assigned default value, ROWID columns, and identity columns.
NULL | The null value.

WITH Clause

Overrides the isolation level of the statement using the WITH {RR | CS} clause, specifying the isolation level with which a searched INSERT statement is executed. The WITH clause specifies an isolation level only for the INSERT statement in which it appears. WITH UR only applies to read only operations, and cannot be used in INSERT statements. The WITH clause overrides the default isolation level for the statement in which it appears.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Data Compatibility

If the insert value for a column is a number, the column must be configured as a numeric data type column with the capability of representing the integral part of the inserted number value. If the insert value for a column is a string, the column must be configured either as a string column (with a length greater than or equal to the string length) or a datetime column (if the string represents a date, time, or timestamp).

If a table (or the base table of a view) named in an INSERT statement contains unique indexes, then each row of values inserted into the table must comply with the uniqueness constraints imposed by these indexes. If the table has a check constraint, each row of data must comply with the check condition.

When a view named in an INSERT statement includes a WITH CHECK OPTION clause in its definition, each row inserted into the view must comply with the view as specified in its definition. If the named view contains other views in its definition -- and these views happen to contain WITH CHECK OPTION clauses in their definitions, the row data values inserted must also comply with these other views as specified in their definitions. An INSERT statement might cause triggers to be activated. A trigger might cause other statements to be executed or raise error conditions based on the insert values.

A named view with no WITH CHECK OPTION clause in its definition can allow nonconforming rows to be inserted into the view's base table(s). However, these rows cannot be retrieved again using the view. Additionally, each non-null insert value must conform to any foreign and parent key relationships defined for target tables -- such that a value inserted into a column defined as a foreign key must equal some value in the primary key column of the parent table.

Locking

Unless appropriate locks already exist, one or more exclusive locks are acquired at the execution of a successful INSERT statement. Until a commit or rollback operation releases the locks, only the application process that performed the insert can access the inserted row. If LOBs are not inserted into the row, application processes that are running with uncommitted read can also access the inserted row. The locks can also prevent other application processes from performing operations on the table. However, application processes that are running with uncommitted read can access locked pages and rows.

Example:

An example of the INSERT command is:

INSERT INTO part
    VALUES ("P7", "WHEEL", "WHITE", 2, "ATHENS")

This statement inserts P7, a two pound white wheel made in Athens, into table PART. To perform this operation correctly, you must enter the data in exactly the order it is to appear in the table. If the column list is specified, it determines the insertion sequence.

To insert a NULL (empty) value, enter NULL in the appropriate column location of the INSERT command statement. Any table column can record inserted NULL values, unless a CREATE or ALTER TABLE command originally defined the column as either NOT NULL or NOT NULL WITH DEFAULT. In the later case, NULL values can be inserted, but will not be recorded in the table (the default values for the column data type will be recorded instead). For example, if the weight and color of the part we are about to insert are not known, type:

INSERT INTO part
    VALUES ("P7", "WHEEL", NULL, NULL, "ATHENS")

If a value list is not specified for the INSERT command, a SELECT command must be specified. The order of the columns selected must match the order in the column list specification. However, the number of columns selected does not need to match the number of columns defined in the column list. If the column list has more columns than the SELECT command, the extra columns will be assigned NULL values. If the column list has fewer columns than the SELECT command, the system will use only as many columns as are available.

The columns selected do not need to match the data type of the column list. They must, however, be type compatible. See the ALTER TABLE command for the definition of compatible conversions.

Try the following sequence of commands using the part-supplier database. First enter the command:

CREATE TABLE bluparts(pno CHAR 2, pname CHAR 5)

This creates a new table called BLUPARTS. Next enter the command:

INSERT INTO bluparts
    (pno, pname)
    SELECT pno, pname
        FROM part
        WHERE color = "blue"

Note that because the PART table has a different number of columns than the BLUPARTS table, you should be careful when specifying the columns selected from the PART table to insert into the BLUPARTS table.

Parent topic: SQL Statements


LABEL ON

The LABEL ON statement adds or replaces descriptive text labels in the system catalog for the current location. These text labels describe tables, views, aliases, or columns existing at the current location.

Invocation

LABEL ON is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the LABEL ON command, users must possess either DBADM authority on the database, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table, view, or alias affected.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke.)

Syntax

LABEL ON
{
    TABLE {table-name | view-name} |
    ALIAS alias-name |
    COLUMN {table-name.column-name | view-name.column-name}
}
    IS string-constant

Use the following syntax of the LABEL ON command when labeling more than one column per statement.

LABEL ON {table-name | view-name}
    (column-name IS string-constant[,...])

Parameters:

table-name or view-name | Identifies the table or view described by the label (string-constant).
alias-name | Identifies the alias to which the comment (string-constant) applies.
column-name | Preceded with an optional qualifier of [table-name.] or [view-name.], identifies a column to which the comment (string-constant) applies.
string-constant | Preceded by the keyword IS, any character string constant (up to 30 bytes in length) enclosed in quotes.

Description

Choose one of the following object keywords (with corresponding object name) for labeling in the system catalog.

TABLE

Keyword indicating that a table or view is being labeled. The identified object must exist at the current location. The string-constant specified in the LABEL ON command is recorded in the SYSIBM.SYSTABLES catalog table, in the LABEL column of the row describing the table or view. table-name must not identify a declared temporary table.

ALIAS

Keyword indicating that an alias is being labeled. The alias identified must exist at the current location. The string-constant specified in the LABEL ON command is recorded in the SYSIBM.SYSTABLES catalog table, in the LABEL column of the row describing the alias.

COLUMN

Keyword indicating that a column is being labeled. The column identified must belong to a table or view existing at the current location. The string-constant specified in the LABEL ON command is recorded in the SYSIBM.SYSCOLUMNS catalog table -- in the LABEL column of the row describing the column. The column name must not identify a column of a declared temporary table.

Parent topic: SQL Statements


LOCK TABLE

The LOCK TABLE statement is used to acquire a shared or exclusive lock on a table at the current location.

Invocation

LOCK TABLE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the LOCK TABLE command, users must either possess DBADM authority on the database, overall SYSADM or SYSCTRL authority for the location, SELECT privilege on the table identified, or be the owner of the table.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke.)

Syntax

Bold text indicates clauses or options that are supported only syntactically.

LOCK TABLE table-name [PARTITION integer]
    IN {SHARE | EXCLUSIVE} MODE

Parameters:

table-name Identifies the table to be locked. The table must exist at the current server, and cannot be a view, temporary table (created or declared) or system catalog table.

Description

Locking is effective in multi-user environments only. However, the command is accepted in single-user environments, so that you can run your applications unchanged in either environment. The XDB Server automatically acquires record level locks as required during processing, so it is not necessary to acquire table level locks. However, table level locks may reduce the amount of time required to process large numbers of records in the same table. Two table locking modes are supported: exclusive and shared. All types of locks are released by a ROLLBACK or COMMIT command. For more information about the use of locks, see the Server Administration Guide.

IN EXCLUSIVE MODE

The keyword EXCLUSIVE is used to acquire an exclusive lock on an existing table, usually when the intent of the transaction is to modify a number of records in the table. Until the lock is released, it prevents concurrent processes from executing any operations on the table. However, unless the lock is on a LOB table space, concurrent processes that are running at an isolation level of uncommitted read (UR) can execute read-only operations on the table.

When an exclusive table level lock is acquired, update transactions progress more quickly because there is no delay waiting for individual record level locks. However, an exclusive lock may take longer to acquire, and it does reduce concurrency by preventing any other transactions from accessing the locked table. For these reasons, the exclusive mode should be reserved for use by high volume record update transactions or when a transaction has a high priority. The loss of concurrency and the possible need to undo many changes when the transaction is rolled back can be minimized by keeping transactions as short as possible.

IN SHARE MODE

The keyword SHARE is used to acquire a shared lock on an existing database table, usually when the intent of the transaction is to read many records or perform repeatable reads. When a shared lock is acquired on a table, other users may read the records in that table, but cannot perform inserts, updates or deletes. Other users must acquire an exclusive record level lock on the table first, before executing INSERT, UPDATE and DELETE transactions.

All table level locks may be released by the UNLOCK TABLE command. The XDB Server protects against deadlock by regulating the persistency of lock requests. You can change the timeout interval through the Options utility. A single attempt to acquire a lock will last no longer than the period specified.

Example:

The example below shows the command to acquire an exclusive lock on the PART table:

LOCK TABLE part IN EXCLUSIVE MODE

The next example shows the command to acquire a shared lock on the PARTSUPP table:

LOCK TABLE partsupp IN SHARE MODE

Acquiring a table lock on a table ensures the correctness of "repeatable reads." For example, the query

SELECT SUM(qty)
    FROM partsupp

will be correct because no other transaction will have the opportunity to change values in the QTY column while the lock is held.

Parent topic: SQL Statements


OPEN

The OPEN command (embedded SQL only) opens a previously declared cursor creating a result table containing row data.

Invocation

OPEN is an executable command that can only be embedded in a host language. OPEN cannot be dynamically prepared.

Authorization

The privileges required to execute an OPEN statement correspond to those privileges required for declaring the cursor being opened. See the authorization description under the DECLARE CURSOR command.

Syntax

OPEN cursor-name
    [USING {host-variable[,...]
    | DESCRIPTOR descriptor-name }]

Parameters:

cursor-name | Identifies a previously declared cursor.
host-variable | Identifies a variable described in the application program in accordance with the rules for declaring host variables.
descriptor-name | Preceded by the keyword DESCRIPTOR, identifies an SQLDA containing a valid description of application program host variables, which contains certain field values that must be set in order prior to executing an OPEN statement.

Description

The cursor must be in the closed state in order to execute an OPEN command. The OPEN command has two basic configurations. The first syntax format is the simple OPEN command, consisting of the keyword OPEN followed by the name of a previously declared cursor name. The second syntax format is used in dynamic SQL applications, and includes a USING clause. The USING clause introduces either a list of host variables (previously defined in the application) or an SQL Descriptor Area (SQLDA) also containing host variable information (including SELECT statement column information) previously described into the SQLDA. (See the DESCRIBE command.)

The cursor select statement can either be a SELECT statement specified in the DECLARE CURSOR statement or a previously prepared (see PREPARE command) SELECT statement identified by a statement name, which can also be specified in the DECLARE CURSOR statement. The OPEN command evaluates the cursor select statement and determines a result table for that cursor. This result table includes current values of any special registers specified in the cursor select statement, as well as the current values of any host variables specified in either the cursor select statement or the USING clause of the OPEN statement.

Result table rows can be determined either during the execution of the OPEN statement (in which case a temporary table will be created to hold them) or these rows can be determined during the execution of subsequent FETCH statements performed on the opened cursor. In either case, the cursor is opened, and the cursor pointer is positioned before the first row of the result table. If the table happens to be empty, the cursor pointer is considered to be positioned after the last (nonexistent) row. The XDB Server does not alert users to an empty result table when the OPEN statement is executed, but does indicate an empty table by returning an SQLCODE value of +100 upon execution of the first FETCH statement on that result table.

USING

Before the OPEN statement is executed, each target parameter marker in the cursor query is assigned the value of its corresponding host variable. The USING clause introduces a list of host variables whose values are substituted for the parameter markers (question mark characters) appearing in a prepared SELECT statement. The number of host variables must equal the number of parameter markers. The USING clause must be specified if the DECLARE CURSOR statement names a prepared statement containing parameter markers. If the prepared statement has no parameter markers, the XDB Server ignores the USING clause.

The USING clause is intended primarily for cursors declared with prepared select statements containing parameter markers. When the prepared select statement of the cursor is evaluated, each parameter marker is replaced by its corresponding host variable listed in the USING clause. The USING clause also functions in those cases when the DECLARE CURSOR statement contains the actual select statement, which typically includes host variables rather than parameter markings. In these cases, the OPEN statement is executed as if each host variable in the cursor select statement is a parameter marker. The values of the cursor select statement host variables are replaced by the values of the host variables specified in the USING clause.

If an SQLDA is specified (preceded by the keyword DESCRIPTOR), the user must have already set the value of certain SQLDA fields. The SQLN field must contain a value indicating the number of values in the SQLVAR array variable. Additionally, the SQLDABC field must indicate the bytes of storage allocated for the SQLDA, while the SQLD field value must denote the total number of variables used in the SQLDA when processing the OPEN statement. Lastly, each entry in the SQLVAR array must describe the attributes of an individual variable. If LOBs or distinct types are present in the results, there must be additional SQLVAR entries for each input host variable.

The value stored in SQLDABC must be calculated according to the formula SQLN*44+16, in order for the SQLDA to contain enough storage for all SQLVAR array values. Additionally, the SQLD field must be set to a value greater than or equal to zero, and less than or equal to the value of the SQLN field. This field value must equal the number of parameter markers in the prepared statement.

Note:

FETCH statements retrieve rows from the result table of a cursor when the cursor is open. The only way to open a closed cursor is by executing an OPEN statement. All cursors in an application process are in a closed state when the application process is started or when a new unit of work for the application process is commenced (unless WITH HOLD is specified in the DECLARE CURSOR statement). Additionally, performing a CONNECT closes any open cursors in an application.

Example:

The parameter host-variables is a list of host variables defined in the Working-Storage Section.

Assume that CUSTBL is a cursor opened on a command that was previously prepared. This prepared command will have one substitution parameter. Note that HOSTVAR1 must be defined in the Working-Storage Section of your COBOL program.

EXEC SQL
    OPEN custbl
END-EXEC
EXEC SQL
    OPEN custbl USING :hostvar1
END-EXEC
Parent topic: SQL Statements
Related reference
DECLARE CURSOR
DESCRIBE
PREPARE


PREPARE

The PREPARE statement (embedded SQL only) transforms a character string form of an SQL statement into an executable form of the same statement. The resulting executable statement is known as a prepared statement, while the original character string is known as the statement string.

Invocation

PREPARE is an executable command that can only be embedded in a host language. PREPARE cannot be dynamically prepared.

Authorization

Users must have authorization to execute the command in the PREPARE statement.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

PREPARE statement-name
    [INTO descriptor-name [USING {NAMES | LABELS | ANY | BOTH}]]
    {[ATTRIBUTES attr-host-variable] FROM host-variable |
     FROM string-expression}

attr-host-variable

{{ASENSITIVE | INSENSITIVE | SENSITIVE [DYNAMIC | STATIC]} |
{SCROLL | NOSCROLL} |
holdability |
returnability |
rowset-positioning |
fetch-first-clause |
{read-only-clause | update-clause} |
optimize-clause |
isolation-clause |
{FOR MULTIPLE ROWS | FOR SINGLE ROW} |
{ATOMIC | NOT ATOMIC CONTINUE ON SQLEXCEPTION} [...] }

holdability

[WITH HOLD | WITHOUT HOLD]

returnability

[WITH RETURN [TO CALLER] | WITHOUT RETURN]

rowset-positioning

[WITH ROWSET POSITIONING | WITHOUT ROWSET POSITIONING]

Parameters:

statement-name | Names the prepared statement. If a prepared statement by that name already exists, then that prepared statement is destroyed and replaced by the newer version specified in this PREPARE statement.
descriptor-name | Preceded by the keyword INTO, identifies an SQLDA containing a valid description of host variables. See Overview for information about SQLDA.
host-variable | Preceded by the keyword FROM, must identify a variable (containing an SQL statement) described in the application program in accordance with the rules for declaring character string variables in the host language.

Description

The PREPARE statement is used by application programs to dynamically prepare an SQL statement for later use by an EXECUTE statement. Any SQL statement other than CLOSE, COMMIT, DECLARE CURSOR, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, FETCH, INCLUDE, OPEN, PREPARE, ROLLBACK, and WHENEVER may be prepared.

The prepared statement may not begin with an EXEC SQL or end with a statement terminator. Neither may the prepared statement contain references to host variables nor include comments. Although a statement may not contain host variables, it may include parameter markers. A parameter marker is a question mark character that will be replaced by a host variable at execution time.

INTO

The optional INTO clause places information about the prepared statement into the SQLDA specified in descriptor-name. This optional clause has the same effect as executing an extra DESCRIBE statement for the SQLDA (see DESCRIBE statement).

USING

Indicates what value to assign to each SQLNAME variable in the SQLDA when INTO is used. If the requested value does not exist, SQLNAME is set to length 0.

NAMES | Assigns the name of the column. This is the default.
LABELS | Assigns the label of the column. (Column labels are defined by the LABEL ON statement.)
ANY | Assigns the column label, and, if the column has no label, the column name.
BOTH | Assigns both the label and name of the column. In this case, two or three occurrences of SQLVAR per column, depending on whether the result set contains distinct types, are needed to accommodate the additional information. To specify this expansion of the SQLVAR array, set SQLN to 2¦n or 3¦n, where n is the number of columns in the object being described. For each of the columns, the first n occurrences of SQLVAR, which are the base SQLVAR entries, contain the column names. Either the second or third n occurrences of SQLVAR, which are the extended SQLVAR entries, contain the column labels. If there are no distinct types, the labels are returned in the second set of SQLVAR entries. Otherwise, the labels are returned in the third set of SQLVAR entries.

Parameter markers

The two types of parameter markers are typed and untyped:

Typed parameter marker

A parameter marker that is specified with its target data type. A typed parameter marker has the general form:

CAST(? AS data-type)

This notation is not a function call, but rather is a "promise" that the data type of the host variable at run time will be the same as, or can be converted to, the data type that was specified.

In the following example, the value of the argument that is provided for the TRANSLATE function at run time must be VARCHAR(12) or a data type that can be converted to VARCHAR(12).

UPDATE EMPLOYEE
    SET LASTNAME = TRANSLATE(CAST(? AS VARCHAR(12)))
    WHERE EMPNO = ?

Untyped parameter marker

A parameter marker that is specified without its target data type. An untyped parameter marker has the form of a single question mark. The context in which the parameter marker appears determines its data type. For example, in the above UPDATE statement, the data type of the untyped parameter marker in the predicate is the same as the data type of the EMPNO column.

Typed parameter markers can be used in dynamic SQL statements wherever a host variable is supported and the data type is based on the promise made in the CAST function.

Example:

In COBOL the host-variable must be a varying-length string variable defined in working storage of the code.

EXEC SQL
    PREPARE getcust
        FROM 'SELECT cno, name FROM cust'
END-EXEC

Another example of PREPARE also involving EXECUTE:

EXEC SQL
    PREPARE inscust FROM INSERT
        INTO cust(cno, name)
        VALUES (?, ?)
END-EXEC
.
. assign values to CNO and CNAME
.
EXEC SQL
    EXECUTE inscust
        USING :CNO, :CNAME
END-EXEC

Alternatively, it is possible to move an SQL string into a host variable and prepare that:

MOVE 'INSERT INTO cust (cno, name) VALUES (?, ?)'
    TO HOLD
EXEC SQL
    PREPARE inscust FROM :HOLD END-EXEC
.
. assign values to CNO and CNAME
.
EXEC SQL
    EXECUTE inscust
        USING :CNO, :CNAME
END-EXEC
Parent topic: SQL Statements
Related reference
DESCRIBE
Related information
Syntax Support Only


REFRESH LOCATIONS

REFRESH LOCATIONS is an XDB Server utility command (not supported in DB2 mode) that re-reads the SYSIBM.SYSLOCATIONS catalog table and updates the system with any new location changes. The REFRESH LOCATIONS command is necessary only if a location has been manually inserted into SYSIBM.SYSLOCATIONS. If a new location is created using the CREATE LOCATION command, the system is automatically reset (and the catalog tables updated) to include the new location information.

Invocation

REFRESH LOCATIONS is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

REFRESH LOCATIONS requires no special privilege or authority. However, only a super user can edit the SYSIBM.SYSLOCATIONS catalog table.

Syntax

REFRESH LOCATIONS

Description

In order for the XDB Server to take advantage of Remote Unit of Work (RUW) or Distributed Unit of Work (DUW) processing, location information must be recorded in the SYSIBM.SYSLOCATIONS catalog table. This location information is read into memory the first time any application or user logs into the XDB Server.

If new location information is manually inserted into SYSIBM.SYSLOCATIONS (after the initial logging on), a REFRESH LOCATIONS command must be issued to reset the system to recognize this newly recorded location. The CREATE LOCATION command, however, automatically resets the system with the new location information.

Parent topic: SQL Statements


REFRESH TABLE

The REFRESH TABLE statement refreshes the data in a materialized query table. The statement deletes all rows in the materialized query table, executes the fullselect in the table definition to recalculate the data from the tables specified in the fullselect, inserts the calculated result into the materialized query table, and updates the catalog for the refresh timestamp and cardinality of the table. The table can exist at the current server or at any DB2 subsystem with which the current server can establish a connection.

This command is only implemented syntactically in the XDB Server operating environment.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set for REFRESH TABLE must include at least one of the following authorities:

  • Ownership of the materialized query table
  • DBADM or DBCTRL authority on the database that contains the materialized query table
  • SYSADM or SYSCTRL authority

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statements dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke).

Syntax

Bold text indicates clauses or options that are supported only syntactically.

REFRESH TABLE table-name [QUERYNO integer]

Description

table-name

Identifies the table to be refreshed. The name must identify a materialized query table. REFRESH TABLE evaluates the fullselect in the materialized-query-definition clause to refresh the table. The isolation level for the fullselect is the isolation level of the materialized query table recorded when CREATE TABLE or ALTER TABLE was issued.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO column of the plan table for the rows that contain information about this SQL statement. This number is also used in the QUERYNO column of the SYSIBM.SYSSTMT and SYSIBM.SYSPACKSTMT catalog tables.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Note:
  • Automatic query rewrite using materialized query tables is not attempted for the fullselect in the materialized query table definition during the processing of REFRESH TABLE statement.
  • After successful execution of a REFRESH TABLE statement, the SQLCA field SQLERRD(3) will contain the number of rows inserted into the materialized query table.
  • The EXPLAIN output for REFRESH TABLE table-name is the same as the EXPLAIN output for INSERT INTO table-name fullselect where fullselect is from the materialized query table definition.
  • The REFRESH TABLE statement is supported over DRDA protocol, but not supported over DB2 private protocol.
  • If the materialized query table has a security label column, the REFRESH TABLE statement does not do any checking for multilevel security with row-level granularity when it deletes and repopulates the data in the table by executing the fullselect. Instead, DB2 performs the checking for multilevel security with row-level granularity when the materialized query table is exploited in automatic query rewrite or is used directly.
Parent topic: SQL Statements


RELEASE (connection)

The RELEASE statement places one or more connections in the release pending state.

Invocation

This statement can only be embedded in an application program, except in REXX programs. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

RELEASE {location-name | host-variable | CURRENT | ALL [SQL] | ALL PRIVATE}

Description

location-name or host-variable

Identifies an SQL connection or a DB2 private connection by the specified location name or the location name contained in the host variable. If a host variable is specified:

  • It must be a character string variable with a length attribute that is not greater than 16. (A C NUL-terminated character string can be up to 17 bytes.)
  • It must not be followed by an indicator variable.
  • The location name must be left-justified within the host variable and must conform to the rules for forming an ordinary location identifier.
  • If the length of the location name is less than the length of the host variable, it must be padded on the right with blanks.

The specified location name or the location name contained in the host variable must identify an existing SQL connection or DB2 private connection of the application process.

If the RELEASE statement is successful, the identified connection is placed in the release pending status and will therefore be ended during the next commit operation. If the RELEASE statement is unsuccessful, the connection state of the application process and the states of its connections are unchanged.

CURRENT

Identifies the current SQL connection of the application process. The application process must be in the connected state.

If the RELEASE statement is successful, the identified connection is placed in the release pending state and will therefore be ended during the next commit operation. If the RELEASE statement is unsuccessful, the connection state of the application process and the states of its connections are unchanged.

ALL or ALL SQL

Identifies all existing connections (including local, SQL, and DB2 private connections) of the application process and places these connections in the release pending status. These connections are ended during the next commit operation. An error or warning does not occur if no connections exist when the statement is executed.

ALL PRIVATE

Identifies all existing DB2 private connections of the application process and places these connections in the release pending status. These DB2 private connections are ended during the next commit operation. An error or warning does not occur if no DB2 private connections exist when the statement is executed.

Example:

The SQL connection to TOROLAB1 is not needed in the next unit of work. The following statement causes it to be ended during the next commit operation:

EXEC SQL RELEASE TOROLAB1
Parent topic: SQL Statements


RELEASE SAVEPOINT

The RELEASE SAVEPOINT statement releases the identified savepoint and any subsequently established savepoints within a unit of recovery.

Invocation

This statement can be imbedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

RELEASE [TO] SAVEPOINT svpt-name

svpt-name

A savepoint identifier that identifies the savepoint to release. If the named savepoint does not exist, an error occurs. The named savepoint and all the savepoints that were subsequently established in the unit of recovery are released. After a savepoint is released, it is no longer maintained and rollback to the savepoint is no longer possible.

Example:

Assume that a main routine sets savepoint A and then invokes a subroutine that sets savepoints B and C. When control returns to the main routine, release savepoint A and any subsequently set savepoints. Savepoints B and C, which were set by the subroutine, are released in addition to A.

RELEASE SAVEPOINT A;
Parent topic: SQL Statements


RENAME

The RENAME statement renames an existing table.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared. However, if the bind option DYNAMICRULES(BIND) applies, the statement cannot be dynamically prepared.

Authorization

The privileges set defined below must include at least one of the following:

  • Ownership of the table
  • DBADM, DBCTRL, or DBMAINT authority for the database that contains the table
  • SYSADM or SYSCTRL authority

Privilege Set: If the statement is embedded in an application program, the privilege set is the privileges held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is the union of the privilege sets held by each authorization ID of the process.

If the name of the existing table includes a qualifier that is different from the authorization ID of the statement, the privileges held by the authorization ID of the statement must include administrative authority.

Syntax

RENAME [TABLE] source-table-name TO target-table-name

Parameters:

source-table-name | Identifies the table to be renamed.
target-table-name | Is the new table name.

Description

The source table name, including the implicit or explicit qualifier, must identify a table that already exists at the current server. The name must not identify a table that has a trigger defined on it, a declared temporary table, a catalog table, an active RLST table, a view, or a synonym. The new table name must be a legal table name that does not already exist in the location. The specified source table is renamed to the new name. All privileges and indexes on the table are preserved.

Parent topic: SQL Statements


REVOKE (Database Privileges)

The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. The XDB Server cannot functionally utilize these types of privileges, although future catalog support is planned. DB2 users should consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

REVOKE is an executable statement that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

In most instances, the authority needed to revoke a specific privilege must be identical to the authority that originally issued the privilege -- which means that privileges individually granted by a specific AuthID are generally revoked individually by the same AuthID.

Syntax

This format is used to revoke privileges on specified databases. One or more of the privilege option keywords defined below (separated with commas) may be specified after REVOKE, allowing multiple privileges to be revoked in one statement. In every case, the privileges chosen are revoked only from the logical database(s) named in the REVOKE command.

REVOKE
        [DBADM[, ]]
        [DBCTRL[, ]]
        [DBMAINT[, ]]
        [CREATETAB[, ]]
        [CREATETS[, ]]
        [DROP[, ]]
        [STARTDB[, ]]
        [STATS[, ]]
        [STOPDB[, ]]
    ON DATABASE database-name[,...]
    FROM AuthID[,...][PUBLIC]
    [BY AuthID[,...][ALL]]

This format is used to revoke privileges on specified databases. One or more of the privilege option keywords defined below (separated with commas) may be specified after REVOKE, allowing multiple privileges to be revoked in one statement. In every case, the privileges chosen are revoked only from the logical database(s) named in the REVOKE command.

REVOKE
        [DBADM[, ]]
        [DBCTRL[, ]]
        [DBMAINT[, ]]
        [CREATETAB[, ]]
        [CREATETS[, ]]
        [DROP[, ]]
        [STARTDB[, ]]
        [STATS[, ]]
        [STOPDB[, ]]
    ON DATABASE database-name[,...]
    FROM AuthID[,...][PUBLIC]
    [BY AuthID[,...][ALL]]

Parameters:

DBADM | Database administrator authority.
DBCTRL | Database control authority.
DBMAINT | Database maintenance authority.
CREATETAB | Privilege to create new tables.
CREATETS | Privilege to create new table spaces.
DROP | Privilege to issue the DROP or ALTER DATABASE statements for the designated databases.
STARTDB | Privilege to issue the START DATABASE command.
STOPDB | Privilege to issue the STOP DATABASE command.
Note:

The DISPLAYDB, IMAGCOPY, LOAD, RECOVERDB, REORG, REPAIR, and STATS database grant/revoke privileges are specific to the DB2 mainframe environment, and control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, the XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.

database-name | Identifies a database on which privileges are to be revoked. Each database named must exist at the current location. The XDB Server does not support cascading revoke.
AuthID | Identifies a user authorization ID from which the specified privilege(s) are being revoked. The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), revoking the specified privileges from all valid AuthIDs at the current location.

Description

The REVOKE command is used to remove system, database, table, and view privileges from designated AuthID(s). There are three formats for the REVOKE command, depending on the type of privilege being revoked. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

For a TEMP database, you cannot revoke the privilege from PUBLIC. When a TEMP database is created, PUBLIC implicitly receives the CREATETAB privilege (without GRANT authority); this privilege is not recorded in the DB2 catalog, and it cannot be revoked.

Individual grants (or groups of grants) are removed from the catalog tables by executing REVOKE command statements. Each individual revoke (as registered in the catalog tables) involves the removal of one privilege by one revoker from one revokee. The removal of privileges with the REVOKE statement is recorded in the system catalog for the current location. The status of each individual granted or revoked privilege (for each AuthID) is recorded in the catalog tables.

Note:

Since the same privilege can be granted to a single grantee AuthID by several different grantor AuthIDs, the grantee AuthID retains the privilege as long as one (or more) of these grants remains recorded in the system catalog.

Privileges may be revoked from a specific set of users by listing their AuthIDs in the FROM clause of the REVOKE statement. To revoke privileges from all AuthIDs in the current location, use the keyword PUBLIC in the FROM clause. When a privilege is revoked from PUBLIC, the system catalog continues to maintain the list of AuthIDs that were individually granted the privilege.

Example:

The following example revokes DBADM authority for a database named PICTURES from the individual(s) with AuthID usera.

REVOKE DBADM
    ON DATABASE pictures
    FROM usera
Parent topic: SQL Statements
Related reference
REVOKE (Table or View Privileges)
REVOKE (System Privileges)
REVOKE (Function or Procedure Privileges)


REVOKE (Function or Procedure Privileges)

This form of the REVOKE statement revokes privileges on user-defined functions, cast functions that were generated for distinct types, and stored procedures.

Syntax

REVOKE EXECUTE ON
       {FUNCTION {function-name [(parameter-type[,...])] | * } |
        SPECIFIC FUNCTION specific-name[,...] |
        PROCEDURE {procedure-name[,...] | *}
    FROM {authorization-name[,...] | PUBLIC} [BY {authorization-name[,...] | ALL}]
    RESTRICT

Description

EXECUTE

Revokes the privilege to run the identified user-defined function, cast function that was generated for a distinct type, or stored procedure.

FUNCTION or SPECIFIC FUNCTION

Identifies the function on which the privilege is granted. The function must exist at the current server, and it must be a function that was defined with the CREATE FUNCTION statement or a cast function that was generated by a CREATE DISTINCT TYPE statement.

If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name

Identifies the function by its name. You can identify a function by its name only if there is exactly one function with function name in the schema. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified on unqualified function-name. An * (or schema-name.*) indicates that the privilege is revoked for all the functions in the schema. You (or the indicated grantors) must have granted the privilege on FUNCTION * to all identified users (including PUBLIC if specified). Privileges granted on specific functions are not affected.

FUNCTION function-name (parameter-type,...)

Identifies the function by its function signature, which uniquely identifies the function.

function-name Specifies the name of the function. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.
(parameter-type,...) Identifies the number of input parameters of the function and their data types.

The data type of each parameter must match the data type that was specified in the CREATE FUNCTION statement for the parameter in the corresponding position. The number of data types and the logical concatenation of the data types is used to uniquely identify the function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that DB2 ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

    The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that DB2 ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name

Identifies the function by its specific name.

PROCEDURE procedure-name

Identifies a stored procedure that is defined at the current server. If you do not explicitly qualify the procedure name with a schema name, the procedure name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified or unqualified procedure-name. An * (or schema-name.*) indicates that the privilege is revoked for all the procedures in the schema. You (or the indicated grantors) must have granted the privilege on PROCEDURE * to all identified users (including PUBLIC if specified). Privileges granted on specific procedures are not affected.

RESTRICT

Prevents the EXECUTE privilege from being revoked on a user-defined function or stored procedure if the revokee owns any of the following objects:

  • A function that is sourced on the function
  • A view that uses the function
  • A trigger package that uses the function or stored procedure
  • A table that uses the function in a check constraint or user-defined default clause

Example:

Revoke the EXECUTE privilege on function CALC_SALARY for user JONES. Assume that there is only one function in the schema with function CALC_SALARY.

REVOKE EXECUTE ON FUNCTION CALC_SALARY FROM JONES RESTRICT;

Revoke the EXECUTE privilege on procedure VACATION_ACCR from all users at the current server.

REVOKE EXECUTE ON PROCEDURE VACATION_ACCR FROM PUBLIC RESTRICT;

Revoke the privilege of the administrative assistant to grant EXECUTE privileges on function DEPT_TOTAL to other users. The administrative assistant will still have the EXECUTE privilege on function DEPT_TOTALS.

REVOKE EXECUTE ON FUNCTION DEPT_TOTALS
    FROM ADMIN_A RESTRICT;

Revoke the EXECUTE privilege on function NEW_DEPT_HIRES for HR (Human Resources). The function has two input parameters with data types of INTEGER and CHAR(10), respectively. Assume that the schema has more than one function that is named NEW_DEPT_HIRES.

REVOKE EXECUTE ON FUNCTION NEW_DEPT_HIRES (INTEGER, CHAR(10))
    FROM HR RESTRICT;

You can also code the CHAR(10) data type as CHAR().

Parent topic: SQL Statements
Related information
REVOKE (Table or View Privileges)
REVOKE (System Privileges)
REVOKE (Database Privileges)


REVOKE (Sequence Privileges)

This form of the REVOKE statement revokes the privileges on a user-defined sequence.

Syntax

REVOKE {ALTER | USAGE} [,...] ON SEQUENCE sequence-name [,...]
FROM {authorization-name | PUBLIC} [,...]
[BY {authorization-name | ALL} [,...]]
[RESTRICT]
Note: The keyword SELECT is an alternative keyword for USAGE.

Description

ALTER

Revokes the privilege to alter a sequence or record a comment on a sequence.

USAGE

Revokes the USAGE privilege to use a sequence. This privilege is needed when the NEXT VALUE or PREVIOUS VALUE expression is invoked for a sequence name.

SEQUENCE sequence-name

Identifies the sequence. The name, including the implicit or explicit schema qualifier, must uniquely identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs. sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column.

FROM

Specifies from what authorization IDs the privileges are revoked.

authorization-name,...

Lists one or more authorization IDs. Do not use the same authorization ID more than once. The value of CURRENT RULES determines if you can use the ID of the REVOKE statement itself (to revoke privileges from yourself). When CURRENT RULES is:

DB2 | You cannot use the ID of the REVOKE statement.
STD | You can use the ID of the REVOKE statement.

PUBLIC

Revokes a grant of privileges to PUBLIC.

PUBLIC AT ALL LOCATIONS

Revokes a grant of privileges to PUBLIC AT ALL LOCATIONS.

BY

Lists grantors who have granted privileges and revokes each named privilege that was explicitly granted to some named user by one of the named grantors. Only an authorization ID with SYSADM or SYSCTRL authority can use BY, even if the authorization ID names only itself in the BY clause.

authorization-name,...

Lists one or more authorization IDs of users who were the grantors of the privileges named. Do not use the same authorization ID more than once. Each grantor listed must have explicitly granted some named privilege to all named users.

ALL

Revokes each named privilege from all named users who were explicitly granted the privilege, regardless of who granted it.

RESTRICT

Prevents the USAGE privilege from being revoked on a sequence if the revokee owns one of the following objects and does not have the USAGE privilege from another source:

  • A trigger that specifies the sequence in a NEXT VALUE or PREVIOUS VALUE expression
  • An inline SQL function that specifies the sequence in a NEXT VALUE or PREVIOUS VALUE expression
Parent topic: SQL Statements


REVOKE (System Privileges)

The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. The XDB Server cannot functionally utilize these types of privileges, although future catalog support is planned. DB2 users should consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

REVOKE is an executable statement that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

In most instances, the authority needed to revoke a specific privilege must be identical to the authority that originally issued the privilege -- which means that privileges individually granted by a specific AuthID are generally revoked individually by the same AuthID.

Syntax

This format is used to revoke system privileges. In every case, the system privileges chosen are revoked only for those AuthID(s) specified in the FROM clause. One or more of the privilege option keywords defined below (separated with commas) may be specified after REVOKE, allowing multiple system privileges to be revoked in one REVOKE statement.

Bold text indicates clauses or options that are supported only syntactically.

REVOKE
        [CREATEALIAS[, ]]
        [CREATEDBA[, ]]
        [CREATEDBC[, ]]
        [CREATETMTAB[, ]]
        [CREATESG[, ]]
        [SYSADM[, ]]
        [SYSCTRL[, ]]
    FROM AuthID[,...][PUBLIC]
    BY {AuthID[,...] | ALL}

Parameters:

CREATEALIAS | Privilege to use the CREATE ALIAS statement.
CREATEDBA | Privilege to issue the CREATE DATABASE statement and acquire DBADM authority over those databases.
CREATEDBC | Privilege to issue the CREATE DATABASE statement and acquire DBCTRL authority over those databases.
CREATETMTAB | Privilege to issue the CREATE GLOBAL TEMPORARY TABLE statement.
CREATESG | Privilege to create new storage groups.
SYSADM | Revokes system administrator authority for the location.
SYSCTRL | Revokes the system control authority for the location.
Note:

The ARCHIVE, BINDADD, BINDAGENT, BSDS, DISPLAY, MONITOR1, MONITOR2, RECOVER, STOPALL, STOSPACE, SYSOPR, and TRACE system privileges control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, The XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.

AuthID Identifies a user authorization ID for which the specified privilege(s) are being revoked. The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), revoking privileges from each valid AuthID at the current location.

Description

The REVOKE command is used to remove system, database, table, and view privileges from designated AuthID(s). There are three formats for the REVOKE command, depending on the type of privilege being revoked. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

Individual grants (or groups of grants) are removed from the catalog tables by executing REVOKE command statements. Each individual revoke (as registered in the catalog tables) involves the removal of one privilege by one revoker from one revokee. The removal of privileges with the REVOKE statement is recorded in the system catalog for the current location. The status of each individual granted or revoked privilege (for each AuthID) is recorded in the catalog tables.

Note:

Since the same privilege can be granted to a single grantee AuthID by several different grantor AuthIDs, the grantee AuthID retains the privilege as long as one (or more) of these grants remains recorded in the system catalog.

FROM

Privileges may be revoked from a specific set of users by listing their AuthIDs in the FROM clause of the REVOKE statement. To revoke privileges from all AuthIDs in the current location, use the keyword PUBLIC in the FROM clause. When a privilege is revoked from PUBLIC, the system catalog continues to maintain the list of AuthIDs that were individually granted the privilege.

DISPLAY

Revokes the privilege to use the following commands:

  • The DISPLAY ARCHIVE command for archive log information
  • The DISPLAY BUFFERPOOL command for the status of buffer pools
  • The DISPLAY DATABASE command for the status of all databases
  • The DISPLAY FUNCTION SPECIFIC command for statistics about accessed external user-defined functions
  • The DISPLAY LOCATION command for statistics about threads with a distributed relationship
  • The DISPLAY PROCEDURE command for statistics about accessed stored procedures
  • The DISPLAY THREAD command for information on active threads with in DB2
  • The DISPLAY TRACE command for a list of active traces
Parent topic: SQL Statements
Related reference
REVOKE (Database Privileges)
REVOKE (Table or View Privileges)
REVOKE (Function or Procedure Privileges)
Related information
Syntax Support Only


REVOKE (Table or View Privileges)

The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. The XDB Server cannot functionally utilize these types of privileges, although future catalog support is planned. DB2 users should consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

REVOKE is an executable statement that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

In most instances, the authority needed to revoke a specific privilege must be identical to the authority that originally issued the privilege -- which means that privileges individually granted by a specific AuthID are generally revoked individually by the same AuthID.

Syntax

This format is used to revoke privileges on tables or views. In every case, the privileges chosen are revoked only from the tables or views named in the ON [TABLE] clause. One or more of the privilege keywords (separated with commas) defined below and/or the optional keyword(s) ALL [PRIVILEGES] may be specified after REVOKE, allowing multiple privileges to be revoked in one REVOKE statement.

Bold text indicates clauses or options that are supported only syntactically.

REVOKE
{       [ALTER[, ]]
        [DELETE[, ]]
        [INDEX[, ]]
        [INSERT[, ]]
        [SELECT[, ]]
        [TRIGGER[, ]]
        [UPDATE] | ALL [PRIVILEGES]
}
    ON [TABLE] {table-name[,...] | view-name[,...]}
    FROM AuthID[,...][PUBLIC [AT ALL LOCATIONS]]
    [BY {AuthID[,...] | ALL}]

Parameters:

ALTER | Privilege to use the ALTER TABLE statement (cannot specify a view).
DELETE | Privilege to use the DELETE statement.
INDEX | Privilege to use the CREATE INDEX statement (cannot specify a view).
INSERT | Privilege to use the INSERT statement.
SELECT | Revokes the privilege to create a view or read data from the specified table or view. A view or a materialized query table is dropped when the SELECT privilege that was used to create it is revoked, unless the owner of the view or materialized query table was directly granted the SELECT privilege from another source before the view or materialized query table was created.
TRIGGER | Revokes the privilege to use the CREATE TRIGGER statement
UPDATE | Privilege to use the UPDATE statement on all columns of the tables named in the ON [TABLE] clause. When followed by (column-name[,...]), the update privileges are revoked only from the columns specified in parentheses. Note that (unlike the corresponding GRANT command) the UPDATE privilege can only be revoked from a list of individual column names in XDB mode.
column-name | Specifies an individual column in a table from which the UPDATE privilege is being revoked.
table-name or view-name | Preceded by the keyword(s) ON [TABLE], identifies a table or view from which privileges are being revoked.
AuthID | Identifies a user authorization ID from which the privilege(s) specified are being revoked. The optional PUBLIC [AT ALL LOCATIONS] keyword(s) can be specified along with (or in place of) an AuthID (or a list of AuthIDs). The PUBLIC AT ALL LOCATIONS keyword option revokes the specified table privileges from all users at every location.

ALL [PRIVILEGES]

If the ALL or ALL PRIVILEGES keywords are specified, all table or view privileges (for which the issuer has REVOKE authority) are revoked for the objects identified in the ON [TABLE] clause.

Description

The REVOKE command is used to remove system, database, table, and view privileges from designated AuthID(s). There are three formats for the REVOKE command, depending on the type of privilege being revoked. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

Individual grants (or groups of grants) are removed from the catalog tables by executing REVOKE command statements. Each individual revoke (as registered in the catalog tables) involves the removal of one privilege by one revoker from one revokee. The removal of privileges with the REVOKE statement is recorded in the system catalog for the current location. The status of each individual granted or revoked privilege (for each AuthID) is recorded in the catalog tables.

For a declared temporary table, no privileges can be revoked because none can be granted. When a declared temporary table is defined, PUBLIC implicitly receives all table privileges (without GRANT authority) for the table. These privileges are not recorded in the DB2 catalog.

Note: Since the same privilege can be granted to a single grantee AuthID by several different grantor AuthIDs, the grantee AuthID retains the privilege as long as one (or more) of these grants remains recorded in the system catalog.

FROM

Privileges may be revoked from a specific set of users by listing their AuthIDs in the FROM clause of the REVOKE statement. To revoke privileges from all AuthIDs in the current location, use the keyword PUBLIC in the FROM clause. When a privilege is revoked from PUBLIC, the system catalog continues to maintain the list of AuthIDs that were individually granted the privilege.

Examples:

The following example revokes authority for the individuals with the AuthIDs userb and userc to update the PART and SUPPLIER tables.

REVOKE UPDATE
    ON part, supplier
    FROM userb, userc

To revoke privileges from PUBLIC to select, update, delete and insert records in the PART table, use the command:

REVOKE SELECT, UPDATE, DELETE, INSERT
    ON part
    FROM PUBLIC

To revoke the select privilege on all tables from AuthID usera, you might use a command like:

REVOKE SELECT
    ON ALL
    FROM usera

To revoke privileges (XDB mode only) on a subset of the columns in the EMPLOYEE table from AuthID usera, issue the command:

REVOKE UPDATE(address, city, state, zip, phone)
    ON employee
    FROM usera
Parent topic: SQL Statements


ROLLBACK

ROLLBACK is used to mark the end of a transaction and back out of all changes made by the transaction at the current location. The XDB Server does not rollback data definition language (DDL) commands such as CREATE, DROP, ALTER; data control language (DCL) commands such as GRANT, and REVOKE; or utility commands such as SET and COPY. When working in a production environment, it is recommended that you backup your location before and after such commands.

Invocation

ROLLBACK is an executable command that can be issued interactively or embedded in a host language. ROLLBACK can be dynamically prepared.

Authorization

No special authorization is required for ROLLBACK.

Syntax

ROLLBACK [WORK] [TO SAVEPOINT [svpt-name]]

Description

A transaction begins when a previous transaction ends. A transaction is terminated by a COMMIT or ROLLBACK command. Only the results of SQL commands executed within a single, uncommitted transaction are affected by the ROLLBACK command. When the ROLLBACK command is issued, all changes caused by INSERT, UPDATE and DELETE commands of the transaction are undone. All locks acquired during a transaction are released by the ROLLBACK command. If AUTOCOMMIT is on, a user-invoked ROLLBACK has no effect. However, the system will rollback a failed command.

Backward Logging

If you are using XDB Server Version 5.0 or higher, the ROLLBACK command is available. Previous versions of XDB required a feature called Backward Logging to be turned on in order to use the ROLLBACK command. The functionality provided by the old Backward Logging feature has been incorporated into the XDB Server logging system as a permanent default.

TO SAVEPOINT

Specifies that the unit of recovery is not to be ended and that only a partial rollback (to a savepoint) is to be performed. If a savepoint name is not specified, rollback is to the last active savepoint. For example, if in a unit of recovery, savepoints A, B, and C are set in that order and then C is released, ROLLBACK TO SAVEPOINT causes a rollback to savepoint B.

svpt-name A savepoint-identifier that identifies the savepoint to which to roll back. If the named savepoint does not exist, an error occurs.

All database changes (including changes made to a declared temporary tables but excluding changes made to created temporary tables) that were made after the savepoint was set are backed out. Changes that are made to created temporary tables are not logged and are not backed out; a warning is issued instead. (A warning is also issued when a created temporary table is changed and there is an active savepoint.)

In addition, none of the following items are backed out:

  • The opening or closing of cursors
  • Changes in cursor positioning
  • The acquisition and release of locks
  • The caching of the rolled back statements

Any savepoints that are set after the one to which rollback is performed are released. The savepoint to which rollback is performed is not released.

ROLLBACK with or without the TO SAVEPOINT clause has no effect on connections.

Parent topic: SQL Statements


ROLLFORWARD

ROLLFORWARD allows users to roll forward the transactions stored in supplied log files to a specified location. This command must be run while in exclusive use mode.

Invocation

ROLLFORWARD can be executed interactively, embedded in a host language, or dynamically prepared.

Authorization

To use the ROLLFORWARD command you must be a super user.

Syntax

ROLLFORWARD location-name USING log-file-path

Parameters

location-name | Identifies the location to be recovered.
log-file-path | Specifies the directory containing the log files that need to be applied to the appropriate location. These log files must have been created as the result of a standard or incremental BACKUP command.

Description

The ROLLFORWARD command is used to roll forward transactions contained in log files for a specified location. These log files must have been created by a standard or incremental BACKUP command.

The ROLLFORWARD command is used when a media or disk failure has occurred. After placing a backup of a location back on disk, ROLLFORWARD commands specifying the appropriate log files can bring the backup location up to date, so that its state is consistent with the location at the time of the crash.

After performing a standard backup (which is mandatory for all recovery scenarios), which type of backup you perform is up to you. Always performing standard backups takes longer than performing incremental backups but the recovery process from them is much easier and quicker. Performing incremental backups is quicker than performing standard backups but more ROLLFORWARD steps might be necessary to recreate your location.

Resetting Logging System

The XDB Server's logging system automatically creates a series of log files when a new location is created. For an existing location, logging should be manually reset as a part of the location backup process.

Follow the steps below to manually reset location logging:

  1. Shut down server.
  2. Copy log files from the location logging directory to a separate archive directory.
  3. Depending on whether you are using the BACKUP LOCATION command or an operating system backup command, do one of the following:
    • Bring the server back up and run the BACKUP LOCATION command from SQLWizard (be sure you execute the BACKUP LOCATION command from a location other than the one you are backing up).
    • Run your operating system (or other) backup utility as appropriate (be sure to archive all directories associated with the XDB Server location).
  4. Shut down the server (if using BACKUP LOCATION).
  5. Delete all log files (*.LOG) from your location logging directory. The next time the location is accessed, a fresh series of log files will automatically be created by the logging system.

COMPACT Commands

Since using a COMPACT command on a location renders that location's current log files useless, a location should be backed up (and the log files for that location reset) immediately after any COMPACT commands are issued against that location. Log files contain internal information that maps to a particular table structure. COMPACT commands alter the table structure of the location, changing this log-to-table mapping, and making ROLLFORWARD with the previous log files impossible.

Example

The following command rolls forward the transactions in MYLOC, using the log files specified in d:\backuplocs\xdb20051017151315000001:

ROLLFORWARD MYLOC USING D:\BACKUPLOCS\XDB20051017151315000001
Parent topic: SQL Statements


SAVEPOINT

The SAVEPOINT statement sets a savepoint within a unit of recovery to identify a point in time within the unit of recovery to which relational database changes can be rolled back.

Invocation

This statement can be imbedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SAVEPOINT svpt-name [UNIQUE]
    ON ROLLBACK RETAIN CURSORS
    [ON ROLLBACK RETAIN LOCKS]

Description

svpt-name

A savepoint identifier that names the savepoint. (A savepoint identifier is like an SQL identifier except that it has maximum length of 128 bytes.)

UNIQUE

Specifies that the application program cannot reuse the savepoint name within the unit of recovery. An error occurs if a savepoint with the same name as svpt-name already exists within the unit of recovery.

Omitting UNIQUE indicates that the application can reuse the savepoint name within the unit of recovery. If svpt-name identifies a savepoint that already exists within the unit of recovery and the savepoint was not created with the UNIQUE option, the existing savepoint is destroyed and a new savepoint is created. Destroying a savepoint to reuse its name for another savepoint is not the same as releasing the savepoint.

Reusing a savepoint name destroys only one savepoint. Releasing a savepoint with the RELEASE SAVEPOINT statement releases the savepoint and all savepoints that have been subsequently set.

ON ROLLBACK RETAIN CURSORS

Specifies that any cursors that are opened after the savepoint is set are not tracked, and thus, are not closed upon rollback to the savepoint.

Although these cursors remain open after rollback to the savepoint, they might not be usable. For example, if rolling back to the savepoint causes the insertion of a row upon which the cursor is positioned to be rolled back, using the cursor to update or delete the row results in an error.

ON ROLLBACK RETAIN LOCKS

Specifies that any locks that are acquired after the savepoint is set are not tracked, and thus, are not released upon rollback to the savepoint.

Example:

Assume that you want to set three savepoints at various points in a unit of recovery. Name the first savepoint A and allow the savepoint name to be reused. Name the second savepoint B and do not allow the name to be reused. Because you no longer need savepoint A when you are ready to set the third savepoint, reuse A as the name of the savepoint.

SAVEPOINT A ON ROLLBACK RETAIN CURSORS;
 . . .
SAVEPOINT B UNIQUE ON ROLLBACK RETAIN CURSORS;
 . . .
SAVEPOINT A ON ROLLBACK RETAIN CURSORS;
Parent topic: SQL Statements


SELECT (SQL Statements)

SELECT

SELECT commands (or queries) all retrieve information from data tables and display this information in a results table. For purposes of classification, SELECT commands can be subdivided into three general categories including, subselects (and subqueries), fullselects and select statements.

Invocation

SELECT is an executable command that can be issued interactively or embedded in a host language. SELECT can be dynamically prepared.

Authorization

In order to select data from a table or view, users must possess either SELECT authority on the table or view accessed, DBADM authority on the database, SYSADM or SYSCTRL authority for the location, or be the owner of the table or view.

Syntax

SELECT command statements can be composed of six different types of clauses. The SELECT clause and the FROM clause are required for all SELECT commands.

WHERE clauses are permitted in all SELECT commands. You can force the use of an index for a particular indexed column or force the system to not use an index in the query. To force the use of an index when constructing the query, enter an asterisk (*) in parentheses after the name of the indexed column in the WHERE clause.

To force the system to ignore the index, enter a hyphen (-) in parentheses after the name of the indexed column. The (*) and (-) options are valid only for column names that appear in a WHERE clause. You cannot use the (*) and (-) options in GROUP BY, HAVING or ORDER BY clauses (see SELECT Clause for examples).

Depending on the other clauses they contain, SELECT commands may be grouped into the following three classes:

Subselect

A subselect specifies a result table derived from the tables or views identified in the FROM clause of the query.

The subselect syntax appears below:

select-clause from-clause [where-clause] [group-by-clause] [having-clause]

Parameters

select-clause | Required component of a subselect. See SELECT Clause Syntax and Description for a complete syntax analysis of SELECT clauses.
from-clause | Required component of a subselect. See FROM Clause Syntax and Description for a complete syntax analysis of FROM clauses.
where-clause | Optional clause of a subselect. See WHERE Clause Syntax and Description for a complete syntax analysis of WHERE clauses.
group-by-clause | Optional clause of a subselect. See GROUP BY Clause for a complete syntax analysis of GROUP BY clauses.
having-clause | Optional clause of a subselect. See GROUP BY Clause for a complete syntax analysis of HAVING clauses.

Description

In addition to standing on its own, a subselect can be a component of the fullselect or incorporated into CREATE TABLE, UPDATE, INSERT, DELETE, and CREATE VIEW statements. Subselects can also be components of certain predicates, in which case they can be called subqueries. Subselects can contain GROUP BY or HAVING clauses, and the WHERE clause of a subselect can also contain nested subselects. Subselects cannot contain the UNION operator or an ORDER BY clause.

Subselects and Locations

The subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

SELECT * FROM tutorial.tutorial.employeeWHERE e_no IN SELECT e_no FROM debloc.debbie.employee WHERE st = "MD";

Valid:

SELECT * FROM tutorial.tutorial.employeeWHERE e_no IN SELECT e_no FROM tutorial.debbie.employee WHERE st = "MD";

Fullselect

A fullselect can consist of one or more subselects connected with one or more UNION operators. Fullselects can also be issued from SQLWizard -- causing a result table to be displayed. See SELECT Clause for examples of fullselect queries.

Syntax:

The fullselect syntax appears below:

subselect [(fullselect)] [UNION | UNION ALL] [subselect [(fullselect)]]

Description

A fullselect that contains no UNION or UNION ALL clauses is simply a subselect. A fullselect can combine multiple subselects (and fullselects) by repeated use of the UNION and UNION ALL keywords. Only the final query in a fullselect ends with a semicolon. The absence of semicolons after the preceding queries is what makes SQL cognizant that these queries are part of a UNION.

UNION

Combines the results output of columns from two separate tables as though they were one. The column headings are omitted in the result because no columns produced by a union are directly extracted from a single table. In order for two or more queries to undergo a union, their output columns must be union compatible. This means that the queries must each specify the same number of columns and in such an order that the first, second, third, and so on, of each is of a compatible data type with the first, second, third, and so on, of all the others.

UNION ALL

Same as UNION, but includes all duplicate data rows in the output (UNION eliminates all redundant combinations of data values, therefore making every row of result data unique).

AS

The AS clause affects column names in the results of fullselects. If the nth result columns of two queries combined in a UNION have the same result column name (defined with an AS clause), then the nth column of the final UNION result has the same defined column name.

Select Statement

The select statement is the form of a query that can be directly specified in a DECLARE CURSOR statement or prepared and then referenced in a DECLARE CURSOR statement.

Syntax

The select statement syntax appears below:

fullselect [order-by-clause] [update-clause]
    {[FOR FETCH ONLY] [FOR READ ONLY]}
    [optimize-for-clause]
    [with-clause]
    [queryno-clause]
    [fetch-first-clause]

order-by-clause:

ORDER BY {column-name | integer}
    {ASC | DESC}[,...]

update-clause:

FOR UPDATE OF column-name[,...]

optimize-for-clause:

OPTIMIZE FOR integer {ROWS | ROW}

with-clause:

WITH {CS | RR | UR}

queryno-clause:

QUERYNO integer

fetch-first-clause:

FETCH FIRST {1 | integer} {ROW | ROWS} ONLY

Parameters:

column-name | Uniquely identifies a column of the result table. A named column may be identified by an integer or column-name. An unnamed column must be identified by an integer (below).
integer | An integer value greater than zero, and not greater than the number of columns in the result table. The integer n identifies the nth column of the result table.

Description

The table specified by the select statement is the result of a fullselect. The tables or views identified can reside in the currently set location or at any other accessible location under the XDB Server. To access other locations, specify a three-part name (or alias) or issue a CONNECT or SET LOCATION TO command prior to issuing the select statement.

FOR FETCH ONLY

Including this clause or the FOR READ ONLY clause (in DB2 Version 4.1), declares that the result table is read-only. A read-only result table must not be referred to by any UPDATE or DELETE statements. These limitations apply to result tables that are intrinsically read-only (such as those based on read-only views), and those for which the FOR FETCH ONLY or FOR READ ONLY clause is specified by the user.

Cursors with read-only result tables cannot be referred to in positioned UPDATE and DELETE statements, since data is fetched between client and server in large blocks. However, if no positional updates are needed, the FOR FETCH ONLY clause can still be used to improve fetch performance.

Specifying FOR FETCH ONLY activates Bulk Fetching, which improves the performance of FETCH operations. When a query is Bulk Fetched, data is transferred to the client in bulk, instead of one row at a time. The bulk size depends on the number of records that can be transferred, which in turn is influenced by the number of columns selected, data types and the overhead.

ORDER BY

This clause specifies an order for result table rows. If one column-name is identified, the rows are ordered by the data values within the column. If more than one column-name is identified, the rows are ordered by the values of the first column, then by the values of the second column, etc. ASC uses the values of the identified column in ascending order (default), while DESC uses the values of the column in descending order. If the ORDER BY clause is not specified, the rows of the result table have an arbitrary order.

The inclusion of an AS clause in the fullselect allows a named column to be identified by a column name. An unnamed column must be identified by an integer. A column is unnamed if the AS clause is not specified and it is derived from a constant, an expression with operators, or a function. If the fullselect includes a UNION operator, the fullselect rules on named columns apply.

FOR UPDATE OF

The UPDATE clause identifies the columns that can be updated in a later positioned UPDATE statement. The FOR UPDATE OF clause restricts the table columns that can be updated to those specified in the column-name list. These column names must be defined for the table or view appearing in the first FROM clause of the fullselect, and must not be qualified. FOR UPDATE OF cannot be used if the result table is read-only, nor can it be used in a statement containing a FOR FETCH ONLY clause.

OPTIMIZE FOR

This optional clause can be placed either before or after any accompanying FOR FETCH ONLY clause. OPTIMIZE FOR tells the XDB Server to proceed under the assumption that "at most a total of integer rows are to be retrieved from the result table." Without this clause, the XDB Server will assume that all rows of the result table are to be retrieved (and optimized accordingly).

OPTIMIZE FOR does not actually affect the composition or ordering of the result table. Optimizing for a limited (integer) number of rows can improve fetch performance if subsequent fetches are limited to integer rows. Any number of rows can be fetched after using the OPTIMIZE FOR clause, but after a total of integer rows are fetched, subsequent fetch performance may degrade.

WITH

You can override the isolation level for all SQL statements specified in a statement with the ISOLATION option by using the WITH clause on individual SQL statements. The WITH clause overrides the default isolation level only for the statement in which it appears. The WITH clause cannot be used on subselects.

The following three isolation levels can be specified:

CS | Cursor stability
RR | Repeatable read
UR | Uncommitted read

WITH UR can be specified only after SELECT, and only if the result table is read-only. A simple way to assure that a result table is read-only is to specify FOR FETCH ONLY or FOR READ ONLY. More information on isolation levels can be found in the Server Administration Guide.

FETCH FIRST

The FETCH FIRST clause limits the number of rows that can be fetched. It can improve the performance of queries with potentially large result sets when only a limited number of rows are needed. If the clause is specified, the number of rows retrieved will not exceed n, where n is the value of the integer. An attempt to fetch n+1 rows is handled the same way as normal end of data. The value of integer must be positive and non-zero. The default is 1.

If the OPTIMIZE FOR clause is not specified, a default of "OPTIMIZE FOR integer ROWS" is assumed. If both the FETCH FIRST and OPTIMIZE FOR clauses are specified, the lower of the integer values from these clauses is used to influence optimization and the communications buffer size.

If both the FETCH FIRST clause and the ORDER BY clause are specified, the ordering is performed on the entire result set prior to returning the first n rows.

More On SELECT

Due to the relative importance and complexity of SELECT commands (and supporting clauses), this command is described in detail (including numerous examples) in the following topics:

  • SELECT Clause - includes selecting DISTINCT values, retrieving all column values, and selecting constants and expressions.
  • FROM Clause - discusses how to select data from one or more tables or views, and how to use correlation names to qualify the source of data. The newly supported join syntax is also covered.
  • WHERE Clause - describes how to construct simple and complex search conditions using a variety of operators, how to perform string pattern matching using LIKE, how to create join conditions. Covers nested queries using ALL, ANY, EXISTS, etc., and correlated subselects.
  • Other Clauses - include the GROUP BY, HAVING, ORDER BY and FOR UPDATE OF clauses, and the UNION operator.
  • Functions - describes standard SQL functions, as well as special XDB Server functions, including recursive inference functions, aggregate functions, date functions, math functions, and string functions -- most of which can be incorporated into SELECT command statements.
Parent topic: SQL Statements
Related information
SELECT Clause Syntax and Description
FROM Clause Syntax and Description
WHERE Clause Syntax and Description
GROUP BY Clause
Functions Overview


SELECT INTO

The SELECT INTO command (embedded SQL only) retrieves one row of values from a table or view, and then assigns these values to one or more host variables specified in the SELECT INTO command statement.

Invocation

SELECT INTO is an executable command that can only be embedded in a host language. SELECT cannot be dynamically prepared. Tables or views identified in the SELECT INTO statement can exist at the current location or any other location existing under (or accessible from) the XDB Server.

Authorization

In order to select data from a table or view users must possess either SELECT or EXECUTE authority on the table or view accessed, DBADM authority on the database, SYSADM or SYSCTRL authority for the location, or be the owner of the table or view.

Syntax

SELECT projection-list INTO host-var-list
    FROM table-view-list
    [WHERE search-condition]
    [group-by-clause]
    [having-clause]
    [order-by-clause]
    [WITH {RR [lock-clause] | RS [lock-clause] | CS | UR}]
    [QUERYNO integer]
    [FETCH FIRST [1] {ROW | ROWS} ONLY]
order-by-clause
ORDER BY {sort-key [ASC | DESC] [,...] | INPUT SEQUENCE}
sort-key
{column-name | integer | expression}
lock-clause
USE AND KEEP {EXCLUSIVE | UPDATE | SHARE} LOCKS

Parameters:

projection-list | Preceded by the keyword SELECT, lists one or more columns and/or expressions.
host-var-list | Preceded by the keyword INTO, lists one or more host variables (separated by commas) that have been described in the host program according to the rules for describing host variables. See the examples for additional language specific information.
table-view-list | Preceded by the keyword FROM (see FROM Clause Syntax and Description), lists one or more tables or views separated by commas.
search-condition | Preceded by the keyword WHERE (see WHERE Clause Syntax and Description), describes one or more row selection criteria. Multiple selection conditions can be specified together using the AND and OR logical operators.

Description

A SELECT INTO command can retrieve at most one row from a table or view. If the selected table is empty, the SQLCODE indicator field in the SQLCA is assigned a value of +100. If the statement retrieves more than one row of data an error condition results (assigning SQLCODE a value of -811).

The SELECT INTO command statement differs from other types of SELECT commands in that retrieved row values are assigned directly to host variables specified in the INTO clause. Retrieved table values are derived by first evaluating the FROM clause, followed by the WHERE and SELECT clauses.

The INTO clause cannot appear in nested SELECT commands. ORDER BY and UNION are not allowed in SELECT commands containing an INTO clause. When a SELECT command includes an INTO clause, GROUP BY and HAVING are allowed only in nested select statements.

If no rows are retrieved, +100 is placed in SQLCODE, and the host variables are unchanged. If an error occurs when evaluating any column in the projection list a null value is placed in the host variable. To retrieve multiple rows of table values using an embedded SELECT statement, use a DECLARE CURSOR command statement along with the FETCH command.

WITH Clause

Specifies an isolation level with which the statement is executed. You can override the isolation level of the statement using the WITH {CS | RS | RR | UR} clause. You can only specify the isolation levels that specifically apply to a statement. WITH UR can be specified only after SELECT and only if the result table is read-only. The WITH clause overrides the isolation level only for the statement in which it appears.

When you specify WITH RR KEEP UPDATE LOCKS, XDB Server acquires an exclusive (X) lock, instead of a shared (S) lock, on all the pages or rows that fall within the range of the selection expression. All the X locks are retained until the next commit point.

See the Server Administration Guide for information about locking and isolation levels.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Example:

The hostvarlist parameter is a list of host variables, the total of which are equal to the number of columns in projection-list.

Here is an example of a SELECT INTO statement. The record returned will be read into the host variables CNO and NAME (like FETCH):

EXEC SQL
    SELECT cno, name
        INTO :CNO, :NAME
        FROM cust
        WHERE name = :incno
END-EXEC
Parent topic: SQL Statements


SET AUTOCOMMIT

The SET AUTOCOMMIT command is used to turn autocommit on or off. When autocommit is on, a command is automatically committed as soon as it is successfully executed.

Invocation

SET AUTOCOMMIT is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET AUTOCOMMIT can be dynamically prepared.

Authorization

No special authorization is required to set autocommit on or off.

Syntax

SET AUTOCOMMIT {ON | OFF}

Description

You can use autocommit to automatically commit a command as soon as it is successfully executed. If autocommit is on, an implicit COMMIT is issued at command completion or the close of a cursor (for SELECT statements). If Backward Logging is turned on, the autocommit feature causes the contents of the Backward Log to be cleared after each transaction. However, the release of resources such as locks and cursors occurs independently of Backward Logging.

Example:

The command to turn autocommit on is:

SET AUTOCOMMIT ON

To turn autocommit off:

SET AUTOCOMMIT OFF
Parent topic: SQL Statements


SET COMPATIBILITY

The SET COMPATIBILITY command is used to specify a mode of operation. When a particular mode is in effect, SQL commands must adhere to the syntax of that mode.

Invocation

SET COMPATIBILITY is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET COMPATIBILITY can be dynamically prepared.

Authorization

No special authorization is required to specify an XDB Server compatibility mode.

Syntax

SET COMPATIBILITY {DB2 | XDB | ANSI}

Description

This command allows compatibility to change dynamically so you can mix compatible commands only available in certain modes within a particular program. (The functionality of this command is identical to the DB2 command SET CURRENT RULES.) This is useful within an application that executes predominantly in one mode, but in which you need to change to another mode for a particular operation.

Example:

To specify the DB2 compatibility mode enter the following:

SET COMPATIBILITY DB2
Parent topic: SQL Statements


SET CONNECTION

The SET CONNECTION statement establishes the application server of the process by identifying one of its existing connections.

Invocation

This statement can only be embedded in an application program, except in REXX programs. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

SET CONNECTION {location-name | host-variable}

Description

Identifies the SQL connection by the specified location name or the location name contained in the host variable. If a host variable is specified:

  • It must be a character string variable with a length attribute that is not greater than 16. (A C NUL-terminated character string can be up to 17 bytes.)
  • It must not be followed by an indicator variable.
  • The location name must be left-justified within the host variable and must conform to the rules for forming an ordinary location identifier.
  • If the length of the location name is less than the length of the host variable, it must be padded on the right with blanks.

Let S denote the specified location name or the location name contained in the host variable. S must identify an existing SQL connection of the application process. If S identifies the current SQL connection, the state of S and all other connections of the application process are unchanged. The following rules apply when S identifies a dormant SQL connection.

If the SET CONNECTION statement is successful:

  • SQL connection S is placed in the current state.
  • S is placed in the CURRENT SERVER special register.
  • Information about application server S is placed in the SQLERRP field of the SQLCA. If the application server is an IBM product, the information has the form pppvvrrm, where:
    ppp

    One of:

    ARI | DB2 Server for VSE & VM
    DSN | DB2 for OS/390
    QSQ | OS/400
    SQL | all other DB2 products
    vv

    is a two-digit version identifier such as '06'.

    rr

    is a two-digit release identifier such as '01'.

    m

    is a one-digit modification level such as '0'.

For example, if the server is Version 6 of DB2 for OS/390 with the latest maintenance, the value of SQLERRP is 'DSN06011'. Any previously current SQL connection is placed in the dormant state.

If the SET CONNECTION statement is unsuccessful, the connection state of the application process and the states of its SQL connections are unchanged.

Examples:

Execute SQL statements at TOROLAB1, execute SQL statements at TOROLAB2, and then execute more SQL statements at TOROLAB1.

EXEC SQL CONNECT TO TOROLAB1;

(execute statements referencing objects at TOROLAB1)

EXEC SQL CONNECT TO TOROLAB2;

(execute statements referencing objects at TOROLAB2)

EXEC SQL SET CONNECTION TOROLAB1;

(execute statements referencing objects at TOROLAB1)

The first CONNECT statement creates the TOROLAB1 connection, the second CONNECT statement places it in the dormant state, and the SET CONNECTION statement returns it to the current state.

Parent topic: SQL Statements


SET CURRENT DEGREE

This command is supported only syntactically by the XDB Server.

Invocation

SET CURRENT DEGREE is an executable statement that can be embedded in an application program, issued interactively, or dynamically prepared.

Authorization

No special authorization is required.

Syntax

This command is supported only syntactically.

SET CURRENT DEGREE =
    { string-constant | host-variable }

This command is supported only syntactically.

SET CURRENT DEGREE =
    { string-constant | host-variable }

Parameters:

string-constant | When used with DB2, this string constant value must be a character string not longer than three bytes, and enclosed in quotation marks (see DB2 documentation for allowed values).
host-variable | When used with DB2, this host variable value must be a character string not longer than three bytes (see DB2 documentation for allowed values).

Description

On mainframe DB2 systems, this command assigns a value to the CURRENT DEGREE special register. On the XDB Server, this command also places a value in the CURRENT DEGREE special register, although the "degree of parallelism" is not affected. See your DB2 documentation for more information.

Example:

The following example sets the CURRENT DEGREE special register to the string "ANY".

SET CURRENT DEGREE = 'ANY'
Parent topic: SQL Statements
Related information
Syntax Support Only


SET CURRENT LOCALE LC_CTYPE

The SET CURRENT LOCALE LC_CTYPE statement assigns a value to the CURRENT LOCALE LC_CTYPE special register. The special register allows control over the LC_CTYPE locale for statements that use a function that refers to a locale, such as LCASE, UCASE, and TRANSLATE (with a single argument).

This command is supported only syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SET {[CURRENT [LOCALE]] LC_CTYPE | CURRENT_LC_CTYPE}
    [=]
    {string-constant | host-variable}

Description

The value of CURRENT LOCALE LC_CTYPE is replaced by the string constant or host variable specified. The value must be a CHAR or VARCHAR character string that is no longer than 50 bytes.

If a host variable is specified, its value must not be null. If it has an associated indicator, the value of the indicator value must not indicate a null value. The locale must:

  • Be left justified within the host variable
  • Be padded on the right with blanks if its length is less than that of the host variable

The value of CURRENT LOCALE LC_CTYPE is replaced by the value specified. The value must not be longer than 50 bytes and must be a valid locale.

string-constant

A character string constant that must not be longer than 50 bytes and must represent a valid locale.

host-variable

A variable with a data type of CHAR or VARCHAR and a length that is not longer than 50 bytes. The value of host-variable must not be null and must represent a valid locale. If the host variable has an associated indicator variable, the value of the indicator variable must not indicate a null value.

The locale must:

  • Be left justified within the host variable
  • Be padded on the right with blanks if its length is less than that of the host variable

A locale can be specified in uppercase characters, lowercase characters, or a combination of the two.

Some examples of locales include:

  • Fr_BE
  • Fr_FR@EURO
  • En_US
  • Ja_JP

Example:

Set the CURRENT LOCALE LC_CTYPE special register to the locale 'En_US'.

EXEC SQL SET CURRENT LOCALE LC_CTYPE = 'En_US';
Parent topic: SQL Statements


SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION

The SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION statement changes the value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register.

This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET CURRENT MAINTAINED [TABLE] TYPES [FOR OPTIMIZATION]
     [=] {ALL | NONE | SYSTEM | USER | host-variable}

Description

The value indicates which materialized query tables that are enabled for optimization are considered when optimizing the processing of dynamic SQL queries.

ALL

Indicates that all materialized query tables will be considered.

NONE

Indicates that no materialized query tables will be considered.

SYSTEM

Indicates that only system-maintained materialized query tables that are refresh deferred will be considered.

USER

Indicates that only user-maintained materialized query tables that are refresh deferred will be considered.

host-variable

A variable of type CHAR or VARCHAR. The length of the contents of host-variable must not exceed 255 bytes. It cannot be set to null. If host-variable has an associated indicator variable, the value of that indicator variable must not indicate a null value.

The characters of host-variable must be left justified. The content of the host variable must be a string that would match what can be specified as keywords for the special register in the exact case intended as there is no conversion to uppercase characters.

Note:
  • The initial value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register is determined by the value on the CURRENT MAINT TYPES field on installation panel DSNTIP8. The default value of the field is SYSTEM.
  • The CURRENT REFRESH AGE special register needs to be set to a value other than zero in order for the specified types of objects to be considered for optimizing the processing of dynamic SQL queries.
  • The CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register affects dynamic statement cache matching.
Parent topic: SQL Statements


SET CURRENT OPTIMIZATION HINT

The SET CURRENT OPTIMIZATION HINT statement assigns a value to the CURRENT OPTIMIZATION HINT special register.

This command is supported only syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SET CURRENT OPTIMIZATION HINT = {string-constant | host-variable}

Description

The value of special register CURRENT OPTIMIZATION HINT is replaced by the value of the string constant or host variable. The value must be a character string that is not longer than 8 bytes.

The initial value of the CURRENT OPTIMIZATION HINT special register is set to the value that was used for the OPTHINT bind option. The OPTHINT bind option specifies whether optimization hints are used in determining the access path of static statements and identifies which user-defined hint (rows in the authid.PLAN_TABLE) is used. Therefore, if the SET CURRENT OPTIMIZATION HINT statement is not executed to change the value of the special register, DB2 uses the same optimization hint for dynamic statements that it uses for static statements. The default of OPTHINT for BIND PLAN and BIND PACKAGE is all blanks. All blanks indicate that DB2 uses normal optimization techniques and ignores optimization hints.

Example:

Assume that delimited identifier 'NOHYB' identifies a user-defined optimization hint in authid.PLAN_TABLE. Set the CURRENT OPTIMIZATION HINT special register so that DB2 uses this optimization hint to generate the access path for dynamic statements.

SET CURRENT OPTIMIZATION HINT = 'NOHYB'
Parent topic: SQL Statements


SET CURRENT PACKAGE PATH

The SET CURRENT PACKAGE PATH assigns a value to the CURRENT PACKAGE PATH special register.

This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded only in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET CURRENT PACKGE PATH [=]
     {collection-id |
      USER |
      CURRENT PACKAGE PATH |
      host-variable |
      string-constant} [,...]
Note: USER, CURRENT PACKAGE PATH, and CURRENT PATH can be specified only once on the right side of the statement.

Description

The value of CURRENT PACKAGE PATH is replaced by the values specified.

collection-id

Identifies a collection. collection-id must not be a delimited identifier that is empty or contains only blanks.

USER

Specifies the value of the USER special register.

CURRENT PACKAGE PATH

Specifies the value of the CURRENT PACKAGE PATH special register before the execution of the SET CURRENT PACKAGE PATH.

CURRENT PATH

Specifies the value of the CURRENT PATH special register.

host-variable

Specifies a host variable that contains one or more collection IDs, separated by commas. The host variable must:

  • Have a data type of CHAR or VARCHAR. The actual length of the contents of the host variable must not exceed the maximum length of the CURRENT PACKAGE PATH special register.
  • Not be the null value if an indicator variable is provided.
  • Contain an empty or blank string, or one or more collection IDs that are separated by commas.
  • Be padded on the right with blanks if the host variable is fixed-length, or if the actual length of the host variable is longer than the content.
  • Not contain a delimited identifier that is empty or contains only blanks.

string-constant

Specifies a string constant that contains one or more collection IDs, separated by commas. The string constant must:

  • Have a length that does not exceed the maximum length of the CURRENT PACKAGE PATH special register.
  • Contain an empty or blank string, or one or more collection IDs separated by commas.
  • Not contain a delimited identifier that is empty or contains only blanks.
Note:
  • The contents of a host variable or string constant are interpreted as a list of collection IDs if the value contains at least one comma. If multiple collection IDs are specified, they must be separated by commas. Each collection ID in the list must conform to the rules for forming an ordinary identifier or be specified as a delimited identifier.
  • No validation that the collections exist is made at the time that the CURRENT PACKAGE PATH special register is set. For example, a collection ID that is misspelled is not detected, which could affect the way subsequent SQL operates. At package execution time, authorization to the specific package is checked, and if this authorization check fails, an error is issued.
  • The special register string is built by taking each collection ID specified and removing trailing blanks, delimiting with double quotation marks, doubling any double quotation marks within the collection ID as necessary, and then separating each collection ID by a comma. If the same collection ID appears more than once in the list, the first occurrence of the collection is used. The length of the resulting list cannot exceed the length of the special register. For example, assume that the following statements are issued:
    SET CURRENT PACKAGE PATH = MYPKGS, "ABC E", SYSIBM
  SET :HVPKLIST = CURRENT PACKAGE PATH

    These statements result in the value of the host variable being set to: "MYPKGS", "ABC E", "SYSIBM". A collection ID that does not conform to the rules for an ordinary identifier must be specified as a delimited collection ID and must not be specified within a host variable or string constant.

  • A difference exists between specifying a single keyword, such as USER, as a single keyword or as a delimited identifier. To indicate that the current value of a special register that is specified as a single keyword should be used in the package path, specify the name of the special register as a keyword. If you specify the name of the special register as a delimited identifier, it is interpreted as a collection ID of that value. For example, assume that the current value of the USER special register is SMITH and that the following statement is issued:
    SET CURRENT PACKAGE PATH = SYSIBM, USER, "USER"

    The result is that the value of the CURRENT PACKAGE PATH special register is set to: "SYSIBM, "SMITH", "USER".

  • Because a host variable (SQL variable) in an SQL procedure does not begin with a colon, DB2 uses the following rules to determine whether a value that is specified in a SET PACKAGE PATH = name statement is a variable or a collection ID:
    • If name is the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a parameter or SQL variable and assigns the value in name to the package path.
    • If name is not the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a collection ID and assigns and the value in name is the package path.
  • The SET CURRENT PACKAGE PATH statement is executed by the database server and, therefore, is classified as a non-local SET statement in DRDA. The SET CURRENT PACKAGE PATH statement requires a new level of DRDA support. If SET CURRENT PACKAGE PATH is issued when connected to the local server, the SET CURRENT PACKAGE PATH special register at the local server is set. Otherwise, when SET CURRENT PACKAGE PATH is issued when connected to a remote server, the SET CURRENT PACKAGE PATH special register at the remote server is set.
Parent topic: SQL Statements


SET CURRENT PACKAGESET

On mainframe DB2 and XDB Servers, this command assigns a value to the CURRENT PACKAGESET special register. This command is partially supported by the XDB Server, which adopts the CURRENT SQLID as the qualifier for the package.

Invocation

SET CURRENT PACKAGESET is an executable statement that can only be embedded in an application program. It cannot be dynamically prepared.

Authorization

No special authorization is required.

Syntax

SET CURRENT PACKAGESET =
    { USER | string-constant | host-variable }

Parameters:

USER | The value contained in the USER special register.
string-constant | When used with DB2, this string constant value must be a character string not longer than 128 bytes, and enclosed in quotation marks (see DB2 documentation for allowed values).
host-variable | The CURRENT PACKAGESET special register value can be assigned to a host variable in your program using the SET Host Variable command. When used with DB2, this host variable value must be a character string not longer than 128 bytes (see DB2 documentation for allowed values).

Description

In DB2, each program is bound with a default SQLID. Likewise, each package accessed by a program can be bound with a different default SQLID. The AuthID values comprising these various default SQLIDs must somehow be retrieved into the CURRENT SQLID special register within XDB Server whenever package access changes during program execution. The contents of the CURRENT SQLID special register provides the implicit AuthID qualifier support necessary for one-part table names, and this register value must be updated to match the default SQLID of the currently executing package.

The XDB Server does not directly support binding, but emulates this functionality by retrieving default package SQLIDs into the CURRENT SQLID special register. This retrieval needs to happen whenever a SET CURRENT PACKAGESET command switches package access within an executing program. Therefore, the value of the CURRENT SQLID special register in XDB Server can change depending on the name of the executing program, and the contents of the CURRENT PACKAGESET special register.

XDB Server Precompiler

To take advantage of the packageset functionality above, the program must be precompiled using the PKGSET directive. This directive causes the program name to be passed to the engine for all SQL calls within any program precompiled with this directive. The engine, in turn, uses the program name to look up package information in the system tables.

System Tables

Records must also be manually added to the SYSIBM.SYSPACKLIST and SYSIBM.SYSPACKAGE tables for all programs requiring packageset functionality. These tables will be automatically created with the CREATE LOCATION command. Alternatively, they will be created when a package command is issued. To create these system tables in an existing location, issue the following command from SQLWizard:

SET CURRENT PACKAGESET = 'test'

The records for these tables currently need to be added manually (using SQLWizard or Migrate.). Ideally, these records can be imported directly from DB2. The XDB Server software does not add these records automatically at precompile and compile time. Because these are system tables, the user who edits the records must be a super user. The only record fields that must be added to the SYSIBM.SYSPACKAGE table are the LOCATION, COLLID and QUALIFIER column values. All other data is inconsequential. Likewise, the only field values that must be added to the SYSIBM.SYSPACKLIST table are the LOCATION and COLLID column values.

The SET CURRENT PACKAGESET command functional support consists of the following steps:

  1. When a program precompiled with the PKGSET directive accesses the engine the following query is performed:
    SELECT x.qualifier, x.collid, y.seqno
    FROM sysibm.syspackage x, sysibm.syspacklist y
    WHERE y.name IN ('*', program_name)
      AND y.location IN (' ', current_location)
      AND x.collid = y.collid
      AND x.name = program_name
    ORDER BY y.seqno
  2. If the CURRENT PACKAGESET special register is not empty, the following predicate will be added to the query above:
    AND x.collid = current_packageset_special_register
  3. If a record matches the criteria, the CURRENT SQLID special register is updated with the QUALIFIER column contents of the first record retrieved by the query (lowest SEQNO column value). This new value becomes the implicit AuthID for one-part table names.
  4. Once a value is retrieved for a particular program name and package combination, it is cached. Subsequent calls check the cache prior to checking the catalog using the above query.
  5. If either the program name (due to a subroutine call) or CURRENT PACKAGESET special register (due to a SET CURRENT PACKAGESET COMMAND) changes, an automatic lookup is triggered and the CURRENT SQLID is changed accordingly.

special register with stored procedures and user-defined functions

The initial value of the CURRENT PACKAGESET special register in a stored procedure or user-defined function is the value of the COLLID parameter with which the stored procedure or user-defined function was defined. If the routine was defined without a value for the COLLID parameter, the value of the special register is inherited from the calling program. A stored procedure or user-defined function can use the SET CURRENT PACKAGESET statement to change the value of the special register. This allows the routine to select the version of the DB2 package that is used to process the SQL statements in a called routine that is not defined with a COLLID value.

Example:

The following example assigns a value of 'Staff' to the CURRENT PACKAGESET special register.

SET CURRENT PACKAGESET = 'Staff'
Parent topic: SQL Statements


SET CURRENT PATH

The SET CURRENT PATH statement assigns a value to the CURRENT PATH special register.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SET {[CURRENT [FUNCTION]] PATH | CURRENT_PATH} [=]
{   schema-name
    | SYSTEM PATH
    | USER
    | {[CURRENT [FUNCTION]] PATH | CURRENT_PATH}
    | CURRENT PACKAGE PATH
    | host-variable
    | string-constant
} [,...]

Description

The value of CURRENT PATH is replaced by the values specified.

schema-name
Identifies a schema. DB2 does not verify that the schema exists. For example, a schema name that is misspelled is not detected, which could affect the way subsequent SQL operates.
SYSTEM PATH
Specifies the schema names "SYSIBM", "SYSFUN" , "SYSPROC". SYSTEM PATH can be specified only once.
USER
Specifies the value of the USER special register. USER can be specified only once.
CURRENT PATH
Specifies the value of the CURRENT PATH special register before the execution of this statement. CURRENT PATH can be specified only once.
host-variable
A variable with a data type of CHAR or VARCHAR. The value of host-variable must not be null and must represent a valid schema name.

The schema name must:

  • Be left justified within the host variable
  • Be padded on the right with blanks if its length is less than that of the host variable
string-constant

A character string constant that represents a valid schema name.

If the schema name specified in string-constant will also be specified in other SQL statements and the schema name does not conform to the rules for ordinary identifiers, the schema name must be specified as a delimited identifier in the other SQL statements.

Restrictions on SET CURRENT PATH
These restrictions apply to the SET CURRENT PATH statement:
  • If the same schema name appears more than once in the path, the first occurrence of the name is used and a warning is issued.
  • The length of the CURRENT PATH special register limits the number of schema names that can be specified. DB2 builds the string for the special register by taking each schema name specified and removing any trailing blanks from it, adding two delimiters around it, and adding one comma after each schema name except the last one. The length of the resulting string cannot exceed 254 bytes.
Specifying SYSIBM and SYSPROC
Schemas SYSIBM and SYSPROC do not need to be specified in the special register. If either of these schemas is not explicitly specified in the CURRENT PATH special register, the schema is implicitly assumed at the front of the SQL path; if both are not specified, they are assumed in the order of SYSIBM, SYSPROC.
Specifying USER versus "USER"

There is a difference between specifying USER with and without escape characters. To indicate that the value of the USER special register should be used in the SQL path, specify the keyword USER. If you specify USER as a delimited identifier instead (for example, "USER"), it is interpreted as a schema name of "USER". For example, assuming that the current value of the USER special register is SMITH, SET CURRENT PATH = SYSIBM, SYSPROC, USER, "USER" results in SYSIBM, SYSPROC, SMITH, USER being used in the SQL path.

Specifying a schema name in an SQL procedure

Because a host variable (SQL variable) in an SQL procedure does not begin with a colon, DB2 uses the following rules to determine whether a value that is specified in a SET CURRENT PATH=name statement is a variable or a string constant:
  • If name is the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a parameter or SQL variable and assigns the value in name to CURRENT PATH.
  • If name is not the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a string constant and assigns the value name to CURRENT PATH.

Examples:

Set the CURRENT PATH special register to the list of schemas: "SCHEMA1", "SCHEMA#2", "SYSIBM".

SET CURRENT PATH = SCHEMA1,"SCHEMA#2", SYSIBM;

If the special register provides the SQL path, then SYSPROC, which was not explicitly specified in the special register, is implicitly assumed at the front of the SQL path, making the effective value of the path:

SYSPROC, SCHEMA1, SCHEMA#2, SYSIBM
Parent topic: SQL Statements


SET CURRENT REFRESH AGE

The SET CURRENT REFRESH AGE statement changes the value of the CURRENT REFRESH AGE special register.

The CURRENT REFRESH AGE value corresponding to ANY (99 999 999 999 999) cannot be used in timestamp arithmetic operations because the result would be outside the valid range of dates.

This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET CURRENT REFRESH AGE [=] {numeric-constant | ANY | host-variable}

numeric-constant

A DECIMAL(20,6) value representing a timestamp duration. The value must be 0 or 99 999 999 999 999, the microseconds of which is ignored and thus can be any value.

0 | Indicates that query optimization using materialized query tables will not be attempted.
99999999999999 | Indicates that any materialized query tables identified by the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register may be used to optimize the processing of a query. This value represents 9999 years, 99 months, 99 days, 99 hours, 99 minutes, and 99 seconds.

ANY

Shorthand for 99999999999999.

host-variable

A variable of type DECIMAL(20,6) or other type that is assignable to DECIMAL(20,6). It cannot be set to null. If host-variable has an associated indicator variable, the value of that indicator variable must not indicate a null value. The value of host-variable must be 0 or 99 999 999 999 999, the microseconds of which is ignored and thus can be any value.

Note:
  • Materialized query tables created or altered with DISABLE QUERY OPTIMIZATION specified are not eligible for automatic query rewrite. Thus, they are not affected by the setting of this special register.
  • Setting the CURRENT REFRESH AGE special register to a value other than zero should be done with caution. Allowing a materialized query table that may not represent the values of the underlying base table to be used to optimize the processing of a query may produce results that do not accurately represent the data in the underlying table. This situation may be acceptable when you know the underlying data has not changed or you are willing to accept the degree of error in the results based on your knowledge of the data.
Parent topic: SQL Statements


SET CURRENT RULES

The SET CURRENT RULES statement assigns a value to the CURRENT RULES special register.

Invocation

SET CURRENT RULES is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

None required.

Syntax

SET CURRENT RULES = {'DB2' | 'STD' | host-variable}

Parameters:

DB2 | Causes commands to execute according to DB2 rules.
STD | Causes commands to execute according to ANSI/ISO rules.
host-variable | Names a host variable (character string not longer than eight bytes) containing the value to be assigned to the special register CURRENT RULES. The value must be either 'DB2' or 'STD', and must be a character string three bytes in length.

Description

This statement replaces the value of the CURRENT RULES special register with the value of the string constant or host variable. The functionality of this command is identical to the XDB Server command SET COMPATIBILITY. One particular application of this special register value is that it controls the way table check constraints are enforced. The contents of CURRENT RULES chooses one of two distinct SQL rules that will apply to already populated tables containing check constraints. If the value is STD, a check constraint is enforced as soon as it is defined. If a row does not conform, the table check constraint is not added to the table and an error occurs. If the value is DB2, the check constraint is added to the table description but its enforcement is deferred. Because there might be rows in the table that violate the check constraint, the table is placed in check pending status.

Example:

The example below sets the CURRENT RULES special register to a value of DB2.

SET CURRENT RULES = 'DB2'
Parent topic: SQL Statements


SET CURRENT SQLID

The SET CURRENT SQLID statement changes the AuthID value stored in the CURRENT SQLID special register.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared. The value to which special register CURRENT SQLID is set is used as the SQL authorization ID and the implicit qualifier for dynamic SQL statements only if DYNAMICRULES run behavior is in effect. The CURRENT SQLID value is ignored for the other DYNAMICRULES behaviors.

Authorization

In most cases, the CURRENT SQLID value must equal one of the AuthIDs of the session. If one of these session AuthIDs possesses SYSADM authority for the location, then CURRENT SQLID can be set to any valid AuthID within the location.

Syntax

SET CURRENT SQLID = {USER | string-constant | host-variable}

Parameters:

USER | Is the special register USER, containing a valid AuthID of the session.
string-constant | A character string -- not longer than eight bytes and surrounded by quotes -- identifying a valid AuthID of the session.
host-variable | Identifies a host variable containing a character string (not longer than eight bytes) identifying a valid AuthID of the session.

Description

The initial value of the SQL AuthID (SQLID) is established during connection or XDB Server log on. The value specified in the SET CURRENT SQLID statement remains the SQLID until the XDB Server connection is terminated, the SQLID is changed by executing a new SET CURRENT SQLID statement or when a SET LOCATION command is issued. SET LOCATION resets the SQLID to either the Primary AuthID value stored in CONFIG.XDB (if security is off) or the initial Primary AuthID value established during your security login.

The CURRENT SQLID value is the AuthID used for authorization checking on CREATE, GRANT and REVOKE statements. CURRENT SQLID is also used in all other permission situations, such as SELECT statements or any other DML commands.

Additionally, the CURRENT SQLID owns whatever table spaces, databases, storage groups, or synonyms that are created. CURRENT SQLID is also the implicit AuthID qualifier of all table, view, alias, and index names specified in any SQL statements.

Interactive SQL

When you enter an interactive SQL session, the default AuthID becomes the initial value of the CURRENT SQLID special register. The initial value of this register can also be controlled by a SecondaryIDs specified with the SQLWizard Admin Menu commands or a security exit. The CURRENT SQLID special register retains this default value until you issue a SET CURRENT SQLID command -- replacing the initial AuthID value of CURRENT SQLID with another valid primary AuthID.

Changing CURRENT SQLID

During an interactive SQL session, the AuthID value stored within the CURRENT SQLID special register can be changed only by issuing a SET CURRENT SQLID command (or a SET PACKAGESET command). From that point on, the new AuthID value becomes the owner of any databases, tables, or synonyms created within that interactive SQL session. This new AuthID also becomes the implicit qualifier of all table, view, alias, and index names appearing in any SQL statements issued within the interactive SQL session.

Security

Whenever you start an XDB Server session with security off, the Primary AuthID value specified in the Options Utility becomes the CURRENT SQLID for that XDB Server session. If the Primary AuthID specified in the User Profile maps to a SecondaryID, then that SecondaryID becomes the default session SQLID. When security is on and you start an XDB Server session, the UserID entered becomes the CURRENT SQLID. If the UserID entered by the user has a SecondaryID, then the SecondaryID becomes the CURRENT SQLID.

Parent topic: SQL Statements


SET Host Variable

The SET host-variable assignment statement assigns values, either of expressions or NULL values, to host variables.

Invocation

SET Host Variable is an executable statement that can only be embedded in a host program. The statement cannot be dynamically prepared.

Authorization

The privileges that are held by the current authorization ID must include those required to execute any of the expressions.

Syntax

SET host-variable =
{   {CURRENT SERVER | CURRENT PACKAGESET}
    | host-variable = {expression | NULL}
    | (host-variable[,...]) = ({expression | NULL} [,...] | VALUES {{expression | NULL} | ({expression | NULL}[,...])}})}

Parameters

host-variable
Identifies one or more host variables or transition variables that are used to receive the corresponding expression or NULL value on the right side of the statement.

If the SET Assignment statement is used in the triggered action of a CREATE TRIGGER statement, each host-variable must identify a transition variable. If the statement is used in any other context, each host-variable must identify a host variable.

The value to be assigned to each host-variable can be specified immediately following the item reference, for example, host-variable = expression, host-variable=expression. Or, sets of parentheses can be used to specify all the host-variables and then all the values, for example, (host-variable, host-variable) = (expression, expression).

Each host variable must be defined in the program as described under the rules for declaring host variables. A parameter marker must not be specified in place of host-variable.

expression
Specifies the value to be assigned to the corresponding host-variable.

When the host-variables are enclosed within parentheses, for example, (host-variable, host-variable, ...) = (expression, expression, ...), the first value is assigned to the first host variable in the list, the second value to the second host variable in the list, and so on.

NULL
Specifies the null value and can only be specified for host variables that have an associated indicator variable.
VALUES
Specifies the value to be assigned to the corresponding host variable. When more than one value is specified, the values must be enclosed in parentheses. Each value can be an expression or NULL, as described above. The following syntax is equivalent:
(host-variable, host-variable) = (VALUES(expression, NULL))
(host-variable, host-variable) = (expression, NULL)

Special Registers

Local special registers can be referenced only in a VALUES host-variable statement that results in the assignment of a single host variable and not those that result in setting more than one value.

Special registers that can be defined to a host variable include:

CURRENT DATE | CURRENT PACKAGESET
CURRENT TIME | CURRENT SERVER
CURRENT TIMESTAMP | CURRENT SQLID
CURRENT TIMEZONE | USER

For example: SET :your-var-name = CURRENT SERVER

The value of CURRENT SQLID can be changed by issuing a SET CURRENT SQLID command. The CURRENT PACKAGESET special register (and the SET CURRENT PACKAGESET command) currently have limited functional support by the XDB Server.

For information about each of these special registers, see Special Registers.

Parent topic: SQL Statements


SET Transitional Variable

The SET transition-variable assignment statement assigns values, either of expressions or NULL values, to transition variables.

Invocation

This statement can be used as a triggered SQL statement in the triggered action of a before trigger whose granularity is FOR EACH ROW.

Authorization

The privileges that are held by the current authorization ID must include those required to execute any of the expressions or assignments to transition variables.

Syntax

SET transition-variable =
{   {expression | NULL}
    | (transition-variable[,...]) = ({{expression | NULL} | VALUES {{expression | NULL} | ({expression | NULL}[,...])})
}

Description

Identifies a column in the set of affected rows for the trigger that is used to used to receive the corresponding expression or NULL value on the right side of the statement.

The value to be assigned to each transition-variable can be specified immediately following the transition variable, for example, transition-variable = expression, transition-variable=expression. Or, sets of parentheses can be used to specify all the transition-variables and then all the values, for example, (transition-variable, transition-variable) = (expression, expression).

correlation-name | Identifies the correlation name given for referencing the NEW transition variables. The name must match the correlation name specified following NEW in the REFERENCING clause of the CREATE TRIGGER statement.
 | If OLD is not specified in the REFERENCING clause, correlation-name defaults to the correlation name following NEW.
column-name | Identifies the column to be updated. The name must identify a column of the triggering table. The name can identify an identity column that is defined as GENERATED BY DEFAULT but not one defined as GENERATED ALWAYS. You must not specify the same column more than once.
 | The effect of a SET transition-variable statement is equivalent to the effect of an SQL UPDATE statement.

Specifies the value to be assigned to the corresponding transition-variable. A reference to a local special register is the value of that special register at the server when the trigger body is activated.

An expression can contain references to OLD and NEW transition variables that are qualified with a correlation name.

All expressions are evaluated before any result is assigned to a transition variable. If an expression refers to a transition variable that is used in the list of transition variables, the value of the variable in the expression is the value of the variable prior to any assignments.

Assignments are made in sequence through the list. When the transition-variables are enclosed within parentheses, for example, (transition-variable, transition-variable, ...) = (expression, expression, ...), the first value is assigned to the first transition variable in the list, the second value to the second transition variable in the list, and so on.

Specifies the null value and can only be specified for nullable transition variables.

Specifies the value to be assigned to the corresponding transition variable. When more than one value is specified, the values must be enclosed in parentheses. Each value can be an expression or NULL, as described above. The following syntax is equivalent:

  • (transition-variable, transition-variable) = (VALUES(expression, NULL))
  • (transition-variable, transition-variable) = (expression, NULL)

Assume that you want to create a before trigger that sets the salary and commission columns to default values for newly inserted rows in the EMPLOYEE table and that you will define the trigger only with NEW in the REFERENCING clause. Write the SET statement that assigns the default values to the SALARY and COMMISSION columns.

SET (SALARY, COMMISSION) = (50000, 8000);
Parent topic: SQL Statements


SET ISOLATION

The SET ISOLATION command is used to set the isolation level for locking in multi-user versions.

Invocation

SET ISOLATION is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET ISOLATION can be dynamically prepared.

Authorization

SYSADM or SYSCTRL authority for the location is required for setting isolation level to EU (exclusive use).

Syntax

SET ISOLATION { EU | RR | CS | LC | DR | SR }

Parameters:

EU (Exclusive Use) | Locks the database for the exclusive use of the user issuing the command.
RR (Repeatable Read) | Guarantees identical results if the user issues the same SQL query more than once in a transaction. This isolation level provides minimum concurrency and maximum consistency.
CS (Cursor Stability) | Creates a lock on a record that allows the record to be read but not modified. This lock is held only while the record is the current record. Locks on modified records are held until the transaction is committed. Shared table locks can be unlocked before the end of a transaction using the UNLOCK TABLE command. The CS isolation level provides more concurrency and less consistency than RR.
LC (Lock Current) | Holds a lock on a record only while it is the current record. The LC isolation level provides a high degree of concurrency, and a very low degree of consistency, unless used for read-only operations, or with autocommit on.
DR (Dirty Read) or UR (Uncommitted Read) | Does not acquire locks on records, but reads records regardless of the locks held by others. This isolation level is be used strictly for read-only operations.
SR (Snapshot Read) | Causes a snapshot of the data to be made at the time of execution. Other users can make changes to the data without waiting for the transaction to complete, and the user is ensured that the data will be the same for the life of the transaction. The transaction is limited to read-only operations.

Description

The XDB Server permits you to set an isolation level to control the concurrency and consistency within a multi-user environment.

As described above, six isolation levels are supported. Both Repeatable-Read (RR) and Cursor Stability (CS) provide the following data isolation from other users:

  • An active transaction cannot modify or read any data which other active transactions have modified.
  • A transaction cannot modify a record currently being read by another transaction.

In addition, under Repeatable-Read (RR) no active transaction can modify a record which has been read by another active transaction specifying an RR level of isolation.

Cursor Stability (CS) is used if your application will generate or encounter many lock conflicts.

Exclusive Use (EU) locks are used for those procedures that require that the database be in a quiet state.

Lock Current (LC) locks are used for read-only operations or with autocommit set on. With autocommit on, this level of isolation is very useful for interactive sessions.

Example:

Some sample SET ISOLATION commands appear below:

SET ISOLATION EU
SET ISOLATION RR
SET ISOLATION CS
SET ISOLATION LC
SET ISOLATION DR
SET ISOLATION SR
Note:

If the isolation level is set to any setting other than Repeatable Read, for optimization the isolation level is changed to Dirty Read whenever an ORDER BY or GROUP BY is performed. In future versions of the XDB Server, the isolation level optimization will be configurable by the user.

Parent topic: SQL Statements


SET LOCATION TO

The SET LOCATION command logs a user onto a new location, creating an implied connection between the user's sessions and the specified location. The value of the CURRENT SERVER special register is also updated to reflect the new active location.

Invocation

SET LOCATION is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET LOCATION can be dynamically prepared.

Authorization

Users must have the CONNECT privilege on the new location, as well as authority to access and/or modify objects stored at that location.

Syntax

SET LOCATION TO location-name

Parameters:

location-name Identifies a location accessible to the XDB Server.

Description

All XDB Server operations are performed and recorded under the currently set (or default) XDB Server location. The default value of the CURRENT SERVER special register is maintained in the XDB Server configuration file CONFIG.XDB. To create objects in a location other than the current location, use the SET LOCATION statement prior to entering other SQL statements.

Use of this command does not permanently change the user's current location, but only sets the location for the commands that immediately follow. The location remains set until the user either issues another SET LOCATION command or exits the utility where the SET LOCATION command was issued.

The SET LOCATION command differs in several respects from the CONNECT command. The CONNECT command can be used only in embedded SQL, and refers solely to locations recorded in the SYSIBM.SYSLOCATIONS catalog table (which includes remote locations). The SET LOCATION command, also refers to locations recorded in the SYSXDB.SYSLOCALS catalog table (which must be local).

XDB Link Locations

If you issue a SET LOCATION command to an XDB Link location, you cannot return to your XDB Server by issuing another SET LOCATION command (DB2 cannot read XDB Server catalog tables). If your application needs this type of functionality, use the CONNECT and CONNECT RESET commands from embedded SQL.

Example:

Take a typical scenario where the user is connected to LOC1 as the current default location, but the user needs to temporarily access another location (LOC2) in order to create a database object there. This user could access SQLWizard and issue the following command:

SET LOCATION TO loc2

All transactions for that user in the current (old) location are automatically committed and acquired locks released. Any SQL commands issued next (object creation or otherwise) operate on the new location specified above. When the user exits SQLWizard, the original default location (LOC1) returns.

Note:

The XDB Server 2.4x (and earlier) SET DATABASE command syntax can still be used to change the active location. However, a location name must be used for the argument.

Parent topic: SQL Statements


SET LOCATION

Use this command to prevent all users, except for those with SYSADM privileges, from logging on to a location on the XDB Server. This command does not affect users who are already using the location.
Note:

The XDB Server does not allow you to take a location offline while it is in use. You can use the DISABLE LOGIN command to prevent new users from logging on to the server. If you need to take the location offline immediately, you can force active users off the location using the XDB Server Monitor.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSADM privileges

Syntax

SET LOCATION location-name {OFFLINE | ONLINE}

Parameters:

location-name Identifies the location that you want to place online or offline.
Parent topic: SQL Statements


SET LOG

The SET LOG command allows Database Administrators (with SYSADM authority or higher) to suspend logging system operation during an administrative session, and change the path where location log files are stored.

Invocation

SET LOG is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET LOG can be dynamically prepared.

Authorization

Database Administrator, Install or SYSADM authority is required to turn the logging system on or off or to set the path where logging files are stored.

Syntax

SET LOG {ON | OFF}
SET LOG FOR location-name TO path-name WITH {MOVE | COPY}

SET LOG FOR location-name TO path-name
         ( ROLLFORWARD [OFF | ON] |
           LOG FILE SIZE n        |
           ROLLFORWARD {OFF | ON} LOG FILE SIZE n }
    WITH RESTART}

SET LOG FOR location-name
         ( ROLLFORWARD [OFF | ON] |
           LOG FILE SIZE n        |
           ROLLFORWARD {OFF | ON} LOG FILE SIZE n }
    WITH REPLACE}

Parameters:

location-name | Identifies an existing XDB Server location.
path-name | New path for the location log files.
n | An integer specifying the new maximum size (in kilobytes) of an individual log file..

Description

The XDB Server automatically maintains a series of log files for each XDB Server location for use in recovery. This new logging system is normally always defaulted to on. The SET LOG command accommodates the location structure of the XDB Server. Log files operate on a specified XDB Server location, recording all changes made to any objects in that location. The directory path where the log files are stored can be changed using the TO path-name option.

Log files record all changes made to the location since the last back up. In the event of a media failure, the log files can be replayed against a backup copy of the location tables, reconstructing the location data to the state immediately preceding the system failure.

The SET LOG command automatically commits the current transaction. See the Server Administration Guide for more information about backup and recovery options.

Interactive SQL

If you have SYSADM authority or higher and exclusive use of the location, you can temporarily turn the logging system off. When issued from SQLWizard, the SET LOG OFF command temporarily suspends logging for the location during the remainder of the current session. Turning logging off for a particular location is a temporary expedient for an exclusive user that does not want to incur the overhead of logging during administrative tasks.

Logging is turned off for the current session, only. Logging can be activated again in the current session by issuing a SET LOG ON command. Exiting the session toggles the status of location logging back to on (the default). The next session that accesses the location therefore has logging turned on. Setting the logging system on or off from an interactive SQL session does not affect the logging configuration settings in your XDBSRVCO.INI file.

ROLLFORWARD [ OFF | ON ]

If set to Off, this keyword deletes old, unneeded logs automatically. If set to On, this keyword keeps log files.

MOVE

This keyword copies (deleting the originals) all logs files from the named location to the path indicated by path-name, and also changes the current log path for the location to the new path named.

COPY

This keyword copies all logs files from the named location to the path indicated by path-name, and also changes the current log path for the location to the new path named.

RESTART

This keyword closes all log files on the current location log file path and opens new log files in the path indicated by path-name. The log path for the named location is also changed to the new path.

REPLACE

This keyword replaces all log files in the current log file path with new log files. The log path for the log file location stays the same.

Discontinued Commands

Because XDB Server Version 5.0 and above no longer support Forward or Backward logs, the old SET FORWARD LOG and SET BACKWARD LOG commands have been discontinued and replaced with the new SET LOG command. The FWDLOGON field in the SYSXDB.SYSLOCALS system table is no longer used.

Comments

If you are setting the value of LOG FILE SIZE or ROLLFORWARD, you cannot specify WITH COPY or WITH MOVE. If the TO path has not been specified, you must specify WITH REPLACE; in this case, the old logs will be removed and replaced with new logs. If the TO path is specified, you must specify WITH RESTART when moving the logs; in this case, the old logs will be left in the old path and the new log files will be created in the new path.

The XDBSTAT.LOGINFO table is available in all local locations. Querying this table gives the current settings for the log files in that particular location. The columns within the table are:

LOG_PATH | Contains the path to the log files for the location.
LOG_STATE | Shows the state of the logs as either CLEAN or DIRTY to indicate whether a transaction has modified the log files.
LOG_VERSION | Internal XDB logging version.
ROLLFORWARD_STATUS | Shows either OFF or ON, where OFF means that logs no longer required for transaction rollback will be purged at the next checkpoint, and ON means that logs will never be purged by the XDB Server.
LOG_FILE_SIZE | Maximum size in bytes of an individual log file. New log files will be created once this limit has been reached.

ExampleS:

The SET LOG command only requires the name of the location when changing the log file path using the MOVE, COPY or RESTART keywords. To turn OFF logging for the current location, issue the following command:

SET LOG OFF

To turn logging back ON for the current location, issue the following command:

SET LOG ON

You can also use the SET LOG command to change the directory where the location's log files will be stored. For example:

SET LOG FOR tutorial TO d:\recover WITH COPY
SET LOG FOR tutorial TO d:\log-path2 WITH MOVE
SET LOG FOR tutorial TO d:\log-path2 WITH RESTART
Parent topic: SQL Statements


SET SCHEMA

The SET SCHEMA statement assigns a value to the CURRENT SCHEMA special register. If the package is bound with the DYNAMICRULES BIND option, this statement does not affect the qualifier that is used for unqualified database object references.

Restriction: This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET {SCHEMA | CURRENT SCHEMA | CURRENT_SCHEMA} [=]
     {schema-name |
      USER |
      host-variable |
      string-constant |
      DEFAULT}

Description

schema-name
Identifies a schema. No validation that the schema exists is made at the time the CURRENT SCHEMA is set. For example, if a schema name is misspelled, it could affect the way subsequent SQL operates.
USER
Specifies the value of the USER special register.
host-variable
Specifies a host variable that contains a schema name. The content is not folded to uppercase. The host variable must:
  • Be a CHAR, VARCHAR, GRAPHIC, or VARGRAPHIC variable. The actual length of the contents of the host-variable must not exceed the length of a schema name.
  • Not be set to null. If host-variable has an associated indicator variable, the value of that indicator variable must not indicate a null value.
  • Include a schema name that is left justified and conforms to the rules for forming an ordinary identifier or delimited identifier. If the identifier is delimited, it must not be empty or contain only blanks.
  • Be padded on the right with blanks if the host variable is fixed length.
  • Not contain USER or DEFAULT.
string-constant
Specifies a string constant that contains a schema name. The content is not folded to uppercase. The string constant must:
  • Have a length that does not exceed the maximum length of a schema name.
  • Include a schema name that is left justified and conforms to the rules for forming an ordinary identifier or delimited identifier. If the identifier is delimited, it must not be empty or contain only blanks.
  • Not contain USER or DEFAULT.
DEFAULT
Specifies that CURRENT SCHEMA is to be set to its initial value, as if it had never been explicitly set during the application process.
Note:
  • There is a difference between specifying a single keyword (such as USER or DEFAULT) as a single keyword or as a delimited identifier. To indicate that the current value of the USER special register should be used for setting the current schema, specify USER as a keyword. To indicate that the special register should be set to its default value, specify DEFAULT as a keyword. If USER or DEFAULT is specified as a delimited identifier instead (for example, "USER"), it is interpreted as a schema name of that value ("USER").
  • The SET SCHEMA statement is not a commitable operation. ROLLBACK has no effect on CURRENT SCHEMA.
  • The value of the CURRENT SCHEMA special register, as set by this statement, is used as the schema name in all dynamic SQL statements. The QUALIFIER bind option specifies the schema name for use as the qualifier for unqualified database object names in static SQL statements.
  • Setting the CURRENT SCHEMA special register does not affect any other special register. Therefore, the CURRENT SCHEMA is not be included in the SQL path that is used to resolve the schema name for unqualified references to function, procedures and user-defined types in dynamic SQL statements. To include the current schema value in the SQL path, whenever the SET SCHEMA statement is issued, also issue the SET PATH statement including the schema name from the SET SCHEMA statement.
Parent topic: SQL Statements


SET SORTSPACE

Use this command to dynamically reset the size of the sort space on the XDB Server. Active sorts are not affected by this command.

The new sort space size remains in effect until you restart the server or execute another SET SORTSPACE command.

Note:

This command does not write the SORTSPACE value to the server's configuration file, so that when you restart the server, sort space is reset to its original size.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSCTRL or SYSADM privileges

Syntax

SET SORTSPACE=Kbytes
SET SORTSPACE=1000

Parameters:

bytes Is the size of the sort space in kilo-bytes. See the Server Administration Guide for guidelines on setting an appropriate size.

For example, the following command sets the sort space to roughly one megabyte (1 million bytes):

SET SORTSPACE=1000
Parent topic: SQL Statements


SHUTDOWN

Use the SHUTDOWN command to close the XDB Server program at a specified time. You can also use a variant of this command to cancel a SHUTDOWN request that you have issued.

Invocation

This command can embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSADM or SYSCTRL privileges

Syntax for SHUTDOWN AT

Use this command to shut down the server at a specific time or on a specific date. The syntax appears below:

SHUTDOWN AT {date-constant | time-constant | timestamp-constant}

For example:

SHUTDOWN AT 23:30:10
SHUTDOWN AT 10/09/1991
SHUTDOWN AT "1991-10-09-23.30.10.0"

Note that the timestamp value must be in double quotes. All users will be rolled back before shutdown.

Syntax for SHUTDOWN IN

Use this command to shut down the server in a specified length of time. The syntax appears below:

SHUTDOWN IN integer-constant duration
integer-constant | Represents any short or long integer.
duration | Represents a time duration descriptor.

For example:

SHUTDOWN IN 10 seconds
SHUTDOWN IN 2 hours
SHUTDOWN IN 6 months

All users will be rolled back before shutdown.

Syntax for SHUTDOWN ON LAST DISCONNECT

Use this command to shut down the server when the last user logs off the system. SHUTDOWN ON LAST DISCONNECT does not prevent new users from logging on to the server while the SHUTDOWN command is pending-- contrast this command with SHUTDOWN QUIESCE, below. If any new users log on to the server while the command is pending, the server will not shut down until after those users disconnect.

The syntax appears below:

SHUTDOWN ON LAST DISCONNECT

Syntax for SHUTDOWN QUIESCE

Use this command to disable new login requests and shut down the server when the last user logs off the system. SHUTDOWN QUIESCE prevents new users from logging on to the server while the SHUTDOWN command is pending-- contrast this command with SHUTDOWN ON LAST DISCONNECT, above.

The syntax appears below:

SHUTDOWN QUIESCE

Syntax for SHUTDOWN CANCEL

Use this command to cancel a SHUTDOWN command that is pending. The syntax appears below:

SHUTDOWN CANCEL
Parent topic: SQL Statements


SIGNAL SQLSTATE

The SIGNAL SQLSTATE statement is used to signal an error. It causes an error to be returned with the specified SQLSTATE and error description.

Invocation

This statement can only be used in the triggered action of a trigger.

Authorization

None required.

Syntax

SIGNAL SQLSTATE sqlstate-string-constant
    (diagnostic-string-constant)

sqlstate-string-constant

Represents an SQLSTATE. It must be a character string constant with exactly 5 characters that follow these rules for application-defined SQLSTATEs:

  • Each character must be from the set of digits ('0' through '9') or non-accented uppercase letters ('A' through 'Z').
  • The SQLSTATE class (first two characters) cannot be '00', '01' or '02' because these are not error classes.
  • If the SQLSTATE class (first two characters) starts with the character '0' through '6' or 'A' through 'H', the subclass (last three characters) must start with a character in the range 'I' through 'Z'.
  • If the SQLSTATE class (first two characters) starts with the character '7', '8', '9', or 'I' through 'Z', the subclass (last three characters) can be any of '0' through '9' or 'A' through 'Z'.

diagnostic-string-constant

A character string of up to 70 bytes that describes the error condition. If the string is longer than 70 bytes, it is truncated.

Example:

Consider a trigger for an order system that allows orders to be recorded in an ORDERS table (ORDERNO, CUSTNO, PARTNO, QUANTITY) only if there is sufficient stock in the PARTS tables. When there is insufficient stock for an order, SQLSTATE '75001' is returned along with an appropriate error description.

CREATE TRIGGER CK_AVAIL
    NO CASCADE BEFORE INSERT ON ORDERS
    REFERENCING NEW AS NEW_ORDER
    FOR EACH ROW MODE DB2SQL
    WHEN (NEW_ORDER.QUANTITY > (SELECT ON_HAND FROM PARTS
                                    WHERE NEW_ORDER.PARTNO = PARTS.PARTNO))
        BEGIN ATOMIC
            SIGNAL SQLSTATE '75001' ('Insufficient stock for order');
        END
Parent topic: SQL Statements


START DATABASE

The START DATABASE command allows users access to the contents of a named database.

Invocation

START DATABASE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the START DATABASE command, users must possess either overall SYSADM, SYSCTRL for the location, DBADM authority on the database, or the STARTDB privilege for the database.

Syntax

START DATABASE (database-name) [ACCESS (RW | RO)]

Parameters:

database-name Identifies the database to be started.

Description

The START and STOP DATABASE commands are used primarily in conjunction with setting up and accessing Read Only Shared (ROSHARE) databases. A START DATABASE command must be issued after a STOP DATABASE command in order to make the tables in a ROSHARE database accessible to other locations.

The START DATABASE command is permanent until a STOP DATABASE command is executed, even if the user logs out or the Server is brought down. When a START DATABASE command is issued to start a database in RW mode, a value of "W" is placed in the IBMREQ column of the SYSIBM.SYSDATABASE table.

The ACCESS clause introduces either the default read-write (RW) option or the read-only (RO) option. ACCESS (RO) must be added to the START DATABASE command to start a ROSHARE database in read-only mode. Read-only mode allows users at other locations to directly read (select) data in the ROSHARE database.

ROSHARE database owners must issue a START DATABASE command (RW option default) before attempting to insert, update or delete records in the database.

Parent topic: SQL Statements


START PROCEDURE

The START PROCEDURE command checks the argument list for a stored procedure already defined to the SQL engine. If the stored procedure meta-data has been imported from another system, this command can be used to check that the argument list is compatible with XDB syntax rules.

Invocation

START PROCEDURE is an executable command that can be issued interactively.

Authorization

To execute the START PROCEDURE command, users must possess one (or more) privileges listed in the SYSADM or SYSCTRL authority.

Syntax

START PROCEDURE (Proc-item-list)

Proc-item-list:

Proc-item [, Proc-item]

Proc-item:

{ Procedure-name | * }

Parameters:

Procedure-name The procedure name is any long identifier that names the procedure. The procedure name can be a partial name followed immediately by an asterisk. The partial name will identify a set of stored procedures to be checked. If an asterisk is used by itself, all procedures defined to the location will be checked. The SQL engine will stop when it encounters the first error.
Parent topic: SQL Statements


STOP DATABASE

The STOP DATABASE command restricts all access to the named database.

Invocation

STOP DATABASE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the STOP DATABASE command, users must possess either overall SYSADM or SYSCTRL authority for the location, DBADM authority on the database, or the STOPDB privilege for the database.

Syntax

STOP DATABASE (database-name)

Parameters:

database-name Identifies the database to be stopped.

Description

The STOP and START DATABASE commands are used primarily in conjunction with setting up and accessing Read Only Shared (ROSHARE) databases. A STOP DATABASE command must be issued on the "dummy" database before the owner of the physical (ROSHARE) database can create or alter tables. A STOP command must also be issued against the physical database and all related dummy databases before the ROSHARE database owner can drop tables.

The STOP DATABASE command can also be used by any database owner to restrict access (of any kind) to the database -- perhaps before a backup operation. Users must remember to issue a START command on the "stopped" database, when normal access is desired.

Parent topic: SQL Statements


TRUNCATE TABLE

The TRUNCATE TABLE command performs the same function as the DELETE command, except TRUNCATE TABLE removes all records from a table without recording the changes in the Forward and Backward Log files.

Invocation

TRUNCATE TABLE is an executable command that can be issued interactively or embedded in a host language. TRUNCATE TABLE can be dynamically prepared.

Authorization

To execute the TRUNCATE TABLE command, users must possess either DBADM authority for the database containing the table, the DELETE privilege on the table, overall SYSADM authority for the location, or be the owner of the table to be truncated.

Syntax

TRUNCATE TABLE table-name

Parameters:

table-name Identifies the table to be truncated.

Description

The TRUNCATE TABLE command has the same functionality as DELETE FROM table-name, but is faster since deletes will not be logged and indexes are not incrementally maintained. The system will not be able to rollback the deleted records. This command is not allowed on a table containing a primary key, since it may be referenced by another table. Additionally, use of the TRUNCATE TABLE command alleviates the need to issue a COMPACT command on the table after records are deleted (to reclaim and reuse storage space).

Note:

The "records deleted" message produced after issuing the TRUNCATE TABLE command can indicate more records removed than originally present in the table. TRUNCATE TABLE does not stop to determine if a record was previously deleted from the table, it just truncates the table file -- counting all records equally, including those marked for deletion.

Parent topic: SQL Statements


UNLOCK TABLE

UNLOCK TABLE is used in multi-user versions to release table locks acquired using the LOCK TABLE command.

Invocation

UNLOCK TABLE is an executable command that can be issued interactively or embedded in a host language. UNLOCK TABLE can be dynamically prepared.

Authorization

You must be the user who locked the table.

Syntax

UNLOCK TABLE table-name

Parameters:

table-name Identifies the table or view that was locked using a LOCK TABLE command.

Description

The UNLOCK TABLE command is available in both single and multi-user environments; however it is effective only in multi-user environments.

All table locks acquired by the user with the LOCK command can be held until COMMIT or ROLLBACK is issued. If a table is locked in Exclusive Use mode, no record level locks will be recorded by the system. Be sure to COMMIT or ROLLBACK before unlocking a table that has an Exclusive Use lock. Otherwise, uncommitted changes to the database may be lost.

Parent topic: SQL Statements


UPDATE (Searched)

The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.

Invocation

UPDATE is an executable command that can be issued interactively or embedded in a host language. UPDATE can be dynamically prepared.

Authorization

Authority requirements for the UPDATE command depend on whether a table or view is being modified. If modifying a table, users need either UPDATE privileges on (or ownership of) the table, DBADM authority on the database containing the table, or overall SYSADM or SYSCTRL (some catalog tables only) authority for the location. If updating a view, users need UPDATE privileges on the view or SYSADM authority for the location.

The SELECT privilege is required on a searched update if the option for the SQL standard is set as follows:

  • For static SQL statements, if the SQLRULES(STD) bind option was specified
  • For dynamic SQL statements, if the CURRENT RULES special register is set to STD

If an expression that refers to a function is specified, the privilege set must include any authority that is necessary to execute the function.

Syntax

UPDATE {table-name | view-name}[correlation-name]
    SET assignment-clause
    [WHERE search-condition]
    [WITH {CS | RR | RS}]
    [QUERYNO integer]

assignment-clause:

{column-name = {expression | NULL | scalar-subselect}
| (column-name[,...] = {{expression | NULL} [,...] | row-select}}[,...]

Parameters:

table-name or view-name Identifies the table or view to be updated. If a view, the view must be updatable. The name must not identify:
  • An auxiliary table
  • A created temporary table or a view of a created temporary table
  • A catalog table with no updatable columns or a view of a catalog table with no updatable columns
  • A read-only view.
correlation-name Can be used within search-condition or a positioned UPDATE to designate the table or view.

When updating tables with subselects, the subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

UPDATE tutorial.tutorial.practice
    SET pay = pay + 5 WHERE e_no IN
        SELECT e_no FROM debloc.debbie.employee
            WHERE st = "MD";

Valid:

UPDATE tutorial.tutorial.practice
    SET pay = pay + 5
    WHERE e_no IN
        SELECT e_no FROM tutorial.debbie.employee
            WHERE st = "MD";

Description

The Searched UPDATE, command locates all records that satisfy the conditions specified in the WHERE clause (providing all index, integrity and check conditions are met and reverified). If the WHERE clause is omitted in a Searched UPDATE all records in the table will be updated. The WHERE search condition may be an expression or a nested query. Note that the UPDATE command cannot include an ORDER BY clause.

When performing a Positioned UPDATE, the WHERE CURRENT OF clause must specify the name of an open cursor. Only the current record (as defined in the opened cursor) will be updated, with the SET clause specifying the new values for the indicated columns.

Introduces a list of one or more column names and the values to be assigned to the columns.

column-name Identifies a column to be updated. column-name must identify a column of the specified table or view, but must not identify a ROWID column, an identity column that is defined as GENERATED ALWAYS, or a view column that is derived from a scalar function, constant, or expression. The column names must not be qualified, and the same column must not be specified more than once.

For a positioned update, allowable column names can be further restricted to those in a certain list. This list appears in the FOR UPDATE OF clause of the SELECT statement for the associated cursor. If the SELECT statement is dynamically prepared, the FOR UPDATE OF clause must always be present.

A view column derived from the same column as another column of the view can be updated, but both columns cannot be updated in the same UPDATE statement.

expression Indicates the new value of the column. Specifies an expression made up of constants, column-names, and arithmetic operators +, -, *, / (or the keyword NULL) that will become the new value of column-name. It must not include a column function.

A column-name in an expression must identify a column of the table or view. For each row that is updated, the value of the column in the expression is the value of the column in the row before the row is updated.

NULL | Specifies the null value as the new value of the column. Specify NULL only for nullable columns.
scalar-subselect Specifies a subselect that returns a single row with a single column. The column value is assigned to the corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.
The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect. For example, the following syntax is valid:
UPDATE TABLE T1
    SET COL1 = (SELECT COUNT(*)
        FROM TABLE2 T2
        WHERE T2.COL5 = T2.COL3)
    WHERE COL3 = 'ABC'
row-subselect Specifies a subselect that returns a single row. The number of columns in the row must match the number of column-names that are specified. The column values are assigned to each corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.

The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect.

search-condition | Preceded by the keyword WHERE, specifies a search condition for the optional WHERE clause.

Specifies an isolation level with which the statement is executed during a Searched UPDATE. You can override the isolation level of the statement using the WITH {RR | CS} clause. Because WITH UR only applies to read only operations, you cannot use it in an UPDATE statement. The WITH clause overrides the isolation level only for the statement in which it appears.

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Unless appropriate locks already exist, one or more exclusive locks are acquired by the execution of a successful UPDATE statement. Until a commit or rollback operation releases the locks, only the application process that performed the insert can access the updated row. If LOBs are not updated, application processes that are running with uncommitted read can also access the updated row. The locks can also prevent other application processes from performing operations on the table. However, application processes that are running with uncommitted read can access locked pages and rows.

When a view is updated, the changes are reflected in the underlying database table. For a view to be updatable, the query used to define the view must satisfy the following criteria:

  • The query cannot contain DISTINCT.
  • The SELECT clause can contain only column names (no expressions or functions).
  • The FROM clause can contain only one table name.
  • No GROUP BY or HAVING clauses are permitted.

Examples:

The following are examples of Searched UPDATE commands. The first example changes the value of the COLOR column for part number P2 to BROWN, and then adds 5 to its WEIGHT column value.

UPDATE part
    SET color = "BROWN", weight = weight + 5
    WHERE pno = "P2"

The next command doubles the STATUS column value of all London suppliers:

UPDATE supplier
    SET status = status * 2
    WHERE city = "LONDON"

The WHERE clause may also include a nested query, as in the following example, which updates the PARTSUPP table records containing the part numbers of any part made in Paris:

UPDATE partsupp
    SET qty = qty-100
    WHERE pno IN
        SELECT pno
            FROM part
            WHERE city = "PARIS"

While an update command can only update one table, its WHERE clause may consist of a nested query that is a join of several tables. For example:

UPDATE supplier
    SET status = 30
    WHERE sno IN
        SELECT sno
            FROM partsupp, part
            WHERE partsupp.pno = part.pno
              AND qty > 50
Parent topic: SQL Statements
Related reference
UPDATE (Positioned)


UPDATE (Positioned)

The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.

Invocation

UPDATE is an executable command that can be issued interactively or embedded in a host language. UPDATE can be dynamically prepared.

Authorization

Authority requirements for the UPDATE command depend on whether a table or view is being modified. If modifying a table, users need UPDATE privileges on (or ownership of) the table, DBADM authority on the database containing the table, or overall SYSADM or SYSCTRL (some catalog tables only) authority for the location. If updating a view, users need UPDATE privileges on the view or SYSADM authority for the location.

Syntax

The Positioned UPDATE command can only be used with embedded SQL. In DB2 mode the cursor must have been defined with a FOR UPDATE OF clause (or the program precompiled with the NOFOR directive).

The syntax for the Positioned UPDATE appears below:

UPDATE {table-name | view-name} [correlation-name]
    SET assignment-clause WHERE CURRENT OF cursor-name
    [FOR ROW {host-variable | integer-constant} OF ROWSET]

assignment-clause:

{column-name = {expression | NULL | scalar-subselect}
| (column-name[,...] = {{expression | NULL} [,...] | row-select}}[,...]

Parameters:

table-name or view-name Identifies the table or view to be updated. If a view, the view must be updatable. The name must not identify:
  • An auxiliary table
  • A created temporary table or a view of a created temporary table
  • A catalog table with no updatable columns or a view of a catalog table with no updatable columns
  • A read-only view.
correlation-name Can be used within search-condition or a positioned UPDATE to designate the table or view.

Explicit Update to Null (DB2 Mode)

In DB2 mode, you cannot perform an explicit update to null on a table column defined as NOT NULL WITH DEFAULT. For example:

UPDATE empl SET perf = NULL

returns an error message if the column named perf was originally declared as NOT NULL WITH DEFAULT.

Description

The Searched UPDATE, command locates all records that satisfy the conditions specified in the WHERE clause (providing all index, integrity and check conditions are met and reverified). If the WHERE clause is omitted in a Searched UPDATE all records in the table will be updated. The WHERE search condition may be an expression or a nested query. Note that the UPDATE command cannot include an ORDER BY clause.

When performing a Positioned UPDATE, the WHERE CURRENT OF clause must specify the name of an open cursor. Only the current record (as defined in the opened cursor) will be updated, with the SET clause specifying the new values for the indicated columns.

SET Clause

Introduces a list of one or more column names and the values to be assigned to the columns.

column-name Identifies a column to be updated. column-name must identify a column of the specified table or view, but must not identify a ROWID column, an identity column that is defined as GENERATED ALWAYS, or a view column that is derived from a scalar function, constant, or expression. The column names must not be qualified, and the same column must not be specified more than once.

For a positioned update, allowable column names can be further restricted to those in a certain list. This list appears in the FOR UPDATE OF clause of the SELECT statement for the associated cursor. If the SELECT statement is dynamically prepared, the FOR UPDATE OF clause must always be present.

A view column derived from the same column as another column of the view can be updated, but both columns cannot be updated in the same UPDATE statement.

expression Indicates the new value of the column. Specifies an expression made up of constants, column-names, and arithmetic operators +, -, *, / (or the keyword NULL) that will become the new value of column-name. It must not include a column function.

A column-name in an expression must identify a column of the table or view. For each row that is updated, the value of the column in the expression is the value of the column in the row before the row is updated.

NULL | Specifies the null value as the new value of the column. Specify NULL only for nullable columns.
scalar-subselect Specifies a subselect that returns a single row with a single column. The column value is assigned to the corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.

The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect. For example, the following syntax is valid:

UPDATE TABLE T1
    SET COL1 = (SELECT COUNT(*)
        FROM TABLE2 T2
        WHERE T2.COL5 = T2.COL3)
    WHERE COL3 = 'ABC'
row-subselect Specifies a subselect that returns a single row. The number of columns in the row must match the number of column-names that are specified. The column values are assigned to each corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.

The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect.

cursor-name | Preceded by the keywords WHERE CURRENT OF, identifies a previously declared and opened cursor.

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Unless appropriate locks already exist, one or more exclusive locks are acquired by the execution of a successful UPDATE statement. Until a commit or rollback operation releases the locks, only the application process that performed the insert can access the updated row. If LOBs are not updated, application processes that are running with uncommitted read can also access the updated row. The locks can also prevent other application processes from performing operations on the table. However, application processes that are running with uncommitted read can access locked pages and rows.

When a view is updated, the changes are reflected in the underlying database table. For a view to be updatable, the query used to define the view must satisfy the following criteria:

  • The query cannot contain DISTINCT.
  • The SELECT clause can contain only column names (no expressions or functions).
  • The FROM clause can contain only one table name.
  • No GROUP BY or HAVING clauses are permitted.

Example:

The following Positioned UPDATE statement changes the current PART table record (pointed to by the cursor PARTCUR) by setting the COLOR column to "BROWN" and the WEIGHT column to 25.

    MOVE "BROWN" TO NEWCOLOR
    MOVE 25 TO NEWWGT
    EXEC SQL
        UPDATE part
            SET color = :NEWCOLOR, weight = :NEWWGT
            WHERE CURRENT OF partcur
    END-EXEC

The following Positioned UPDATE command changes the status of the supplier record (pointed to by the cursor supcur) to a value of ten:

newstatus = 10;
    EXEC SQL
        UPDATE supplier
            SET status = :newstatus
            WHERE CURRENT OF supcur;
Parent topic: SQL Statements
Related reference
UPDATE (Searched)


VALUES

The VALUES statement provides a method for invoking a user-defined function from a trigger. Transition variables and transition tables can be passed to the user-defined function.

Invocation

This statement can only be used in the triggered action of a trigger.

Authorization

EXECUTE authority is needed on any user-defined function that is referenced in the VALUES clause.

Syntax

VALUES {expression | (expression[,...])}

Description

Specifies one or more expressions. If more than one expression is specified, the expressions must be enclosed within parentheses.

The expressions are evaluated, but the resulting values are discarded and are not assigned to any output variables.

If a user-defined function is specified as part of an expression, the user-defined function is invoked. If a negative SQLCODE is returned when the function is invoked, DB2 stops executing the trigger and rolls back any triggered actions that were performed.

Example:

Create an after trigger EMPISRT1 that invokes user-defined function NEWEMP when the trigger is activated. An insert operation on table EMP activates the trigger. Pass transition variables for the new employee number, last name, and first name to the user-defined function.

CREATE TRIGGER EMPISRT1
    AFTER INSERT ON EMP
    REFERENCING NEW AS N
    FOR EACH ROW
    MODE DB2SQL
    BEGIN ATOMIC
        VALUES(NEWEMP(N.EMPNO, N.LASTNAME, N.FIRSTNAME));
    END
Parent topic: SQL Statements


VALUES INTO

The VALUES INTO statement assigns one or more values to host variables.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

EXECUTE authority is needed on any user-defined function that is referenced in the VALUES statement.

Syntax

VALUES {{expression | NULL} | {expression | NULL}[,...]} INTO host-variable[,...]

Description

VALUES

Introduces one or more values. If more than one value is specified, the list of values must be enclosed within parentheses.

expression | Must not include a column name.
NULL | The null value. NULL can only be specified for host variables that have an associated indicator variable.

INTO

Introduces one or more host variables. The values that are specified in the VALUES clause are assigned to these host variables. The first value specified is assigned to the first host variable, the second value to the second host variable, and so on.

host-variable Identifies a variable that is described in the program according to the rules for declaring host variables.

Example:

Assign the value of the CURRENT PATH special register to host variable HV1.

EXEC SQL VALUES(CURRENT PATH)
    INTO :HV1;
Parent topic: SQL Statements


WHENEVER

The WHENEVER statement (embedded SQL only) has three different forms, each of which changes the execution of a host language program according to the occurrence of specified exception conditions.

Invocation

WHENEVER is not an executable command. It can only be embedded in a host language. WHENEVER cannot be dynamically prepared.

Authorization

No special type of authorization is required.

Syntax

WHENEVER {NOT FOUND | SQLERROR | SQLWARNING}
    {CONTINUE | GO TO host-label}

Parameters:

host-label Preceded by the keywords GO TO (or GOTO), specifies a host language statement to which program execution is transferred.

Description

The NOT FOUND, SQLERROR or SQLWARNING clauses are used to look for a certain types of exception conditions resulting from the execution of an SQL statement. The NOT FOUND construction looks for a returned SQL code of +100, while SQLERROR looks for an SQL statement that has returned a negative error code. SQLWARNING looks for a return code value occurring in SQLWARN1 through SQLWARN7 of the SQLCA to determine the type of warning. For more information, see XDB Server SQL Communications Area (SQLCA).

Each occurrence of a WHENEVER statement applies to all SQL statements that follow in the source listing, until the next WHENEVER statement (of that type) is encountered. In a COBOL application, if a single WHENEVER statement is placed at the beginning of the PROCEDURE DIVISION, that statement applies to all SQL statements executed by the application program. Once the WHENEVER statement determines that an error condition has occurred, the CONTINUE option transfers program control to the next sequential statement, while the GO TO clause transfers program control to the application paragraph named in host-label.

Example:

The host-label parameter is a valid section name or unqualified paragraph name.

This assumes that error-proc is a named procedure in your COBOL program.

EXEC SQL
    WHENEVER SQLERROR
        GO TO error-proc
END-EXEC
Parent topic: SQL Statements


Clauses

  • SELECT Clause Syntax and Description
  • FROM Clause Syntax and Description
  • WHERE Clause Syntax and Description
Parent topic: SQL Reference


SELECT Clause Syntax and Description (SQL)

SELECT Clause Syntax and Description

Each SQL query statement must contain both a SELECT and a FROM clause. The combination of these two clauses determine the table columns that are searched by the query. The WHERE clause and other advanced clauses further limit data retrieval to specific table rows. The sample queries presented throughout this reference utilize the training tables contained in the TUTORIAL location. See FROM Clause, WHERE Clause, Other Clauses, and XDB Server Tutorial Location for more information.

The SELECT clause specifies the columns from which data values are to be retrieved by the query. Data retrieval is limited to the columns specified. When selecting from two or more tables having duplicate column names, it may be necessary to qualify column names with table or view names. Prefixing column names with a table or view name ensures that the query retrieves the correct column (in the correct table).

Syntax

The SELECT clause format appears below:

SELECT [ALL | DISTINCT] {* | projection-list[,...]}

projection-list:

 {
        expression [[AS] name] | (CASE-statement) AS name |
        {table-name | view-name | correlation-name}.*
   }

CASE-statement:

 (CASE WHEN condition THEN expression [WHEN condition THEN expression] [...]
        ELSE expression END) AS name

Parameters:

ALL

Option (default) which selects all rows that satisfy the WHERE condition. Duplicates are not eliminated.

DISTINCT

Option that eliminates duplicate rows from the result.

* Represents a list of names that identify the columns of the final result table. The first name in the list identifies the first column, the second name identifies the second column, and so on. To retrieve all columns in a table or view, enter a single asterisk in place of projection-list.
expression | A list of one to 750 column names (separated by commas) and possibly including constants, functions, host-variables, special registers, labeled durations and various operators. If duplicate column names from different tables must appear in the list, prefix the column name in the SELECT clause with that column's table name to resolve any ambiguity. To force the use of an index on a particular column during a query, append an asterisk enclosed in parentheses (*) to the name of the indexed column. See the XDB Server Administration Guide for guidelines on using indexes with queries.

AS

The XDB Server includes support for the keyword AS, which can be used to name result columns in a SELECT clause. This is particularly useful for a column derived from an expression or from a function applied to a column value. You can use the name in a GROUP BY clause.

The name of a result column of a subselect is determined as follows:

  • If the AS clause is specified, the name of the result column is the name specified on the AS clause.
  • If the AS clause is not specified and the result column is derived from a column name, the result column name is the unqualified name of that column.
  • All other result columns are unnamed.
CASE-statement XDB Mode only. Allows an item to be conditionally specified in the projection list. For example the CASE statement,
SELECT (CASE
  WHEN A=2
    THEN FIRST_NAME
  ELSE
    LAST_NAME
  END)

inserts the column name FIRST_NAME or LAST_NAME into the projection list, depending on the value of the variable A.

condition | An expression that evaluates to TRUE or FALSE,
expression | (In the CASE statement.) An expression specifying a projection list item. (See expression description above). When condition is TRUE, expression is resolved,
name | A name you assign to the column produced by the CASE statement. (When you include the CASE statement, you must include the AS clause.)
name.* | When selecting columns from one or more tables or views, you can select all columns from a particular table by qualifying the special asterisk character with the table name. name.* represents a list of names that identify the columns of name. name can be a table-name, view-name, or correlation-name, and must designate a table or view named in the FROM clause. The first name in the list identifies the first column of the table or view, the second name in the list identifies the second column of the table or view, and so on.
  • Select Clause Examples
  • SELECT ALL vs. DISTINCT
  • Retrieving All Columns with the SELECT Clause
  • SELECT Expressions
Parent topic: Clauses


Select Clause Examples

In the sample query statement below, the prefix "part" in front of the CITY column (separated with a period) tells the system to use the CITY column from the PART table, rather than from the SUPPLIER table.

SELECT pno, part.city, qty, sname
FROM partsupp, supplier, part
WHERE part.pno = partsupp.pno
  AND partsupp.sno = supplier.sno

If columns are not prefixed with the name of the owner table, the XDB Server queries the first column with that name that the system encounters.

The next sample query adds a five percent surcharge on all outstanding customer balances in the state of Maryland, and then lists the new adjusted balance for each affected company.

SELECT company,
  balance + balance * .05 AS New_Balance
FROM customer
WHERE state = MD

The AS clause expression calculates the adjusted balance, which it displays under the heading New_Balance.

Parent topic: SELECT Clause Syntax and Description


SELECT ALL vs. DISTINCT

The SELECT clause of a query statement can include two optional keywords -- ALL or DISTINCT, followed by the projection-list. If the ALL keyword is specified, duplicate rows are not removed from the query result. If the DISTINCT option is specified, all duplicate rows of data values are excluded from the query result. If neither ALL nor DISTINCT are specified, the SELECT clause defaults to ALL.

For example, the query below selects all of the supplier numbers SNO from the PARTSUPP table, including duplicate numbers.

SELECT ALL sno
FROM partsupp

The query results are displayed below:

sno
S1
S1
S2
S3
S1
S1
S1
S1
S2
S4
S4

If we replaced the ALL keyword with DISTINCT, the query retrieves the following set of records:

sno
S1
S2
S3
S4

The DISTINCT keyword, along with the aggregate function COUNT, can be used to tally the distinct records satisfying a WHERE clause condition. See Functions and WHERE Clause for more information. The DISTINCT option keyword may only be used once in a SELECT clause.

Parent topic: SELECT Clause Syntax and Description


Retrieving All Columns with the SELECT Clause

When an * character is used in the projection-list portion of a SELECT statement, the system retrieves all columns from the tables appearing in the FROM clause. For example, suppose we need to display all columns in the SUPPLIER table. The SELECT statement below would accomplish this objective:

SELECT *
FROM supplier

The result for this query is shown in the table below:

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S2 | JONES | 10 | PARIS
S3 | BLAKE | 30 | PARIS
S4 | CLARK | 20 | LONDON
S5 | ADAMS | 30 | ATHENS

The last query above returns the same result as the longer query statement shown below:

SELECT sno, sname, status, city
FROM supplier

When selecting columns from one or more tables or views, users may select all columns from a particular table by qualifying the special asterisk character with the table name. The sample query statement below demonstrates this approach:

SELECT supplier.*, pno, qty
FROM supplier, partsupp
WHERE supplier.sno = partsupp.sno

The result of the query statement above is the same as the statement below:

SELECT sno, sname, status, city, pno, qty
FROM supplier, partsupp
WHERE supplier.sno = partsupp.sno
Parent topic: SELECT Clause Syntax and Description


SELECT Expressions (SQL)

SELECT Expressions

The projection-list of a SELECT clause may contain column names, constants and/or expressions. It is sometimes advantageous to use an expression that incorporates data values from one or more columns. Any legal arithmetic expression involving column values, numeric or string constants, functions, and arithmetic operators is permitted in an expression. See Functions In SELECT Clauses. Parentheses may be used as necessary to define evaluation order.

Column names generally match those specified in the SELECT clause. In the case of expressions or column names made up of multiple words (column names over 30 characters long), the XDB Server substitutes the special name Columnn where the second n is the column number -- counting from the left side of the result display.

Numeric constants and string constants can be "selected" just like column names. String constants can be enclosed in single or double quotes. For instance, the query below uses a string constant in the SELECT statement:

SELECT "Supplier", sname, "is located in", city
FROM supplier

The previous query produces the following results display:

Supplier | sname | Column3 | city
Supplier | SMITH | is located in | LONDON
Supplier | JONES | is located in | PARIS
Supplier | BLAKE | is located in | PARIS
Supplier | CLARK | is located in | LONDON
Supplier | ADAMS | is located in | ATHENS

The query below uses an arithmetic expression in the SELECT clause to display shipping costs for each part received from London:

SELECT pno, weight * 1.15
FROM part
WHERE city = "LONDON"

The column rename feature can assign a name to a new column of output computed from an arithmetic expression. For example, the results of the following query would appear under two separate columns named PNO and shipcost:

SELECT pno, shipcost = weight * 1.15
FROM part
WHERE city = "LONDON"
Note:

A NULL value generates a NULL result when used in arithmetic expressions other than aggregate functions. Consider the expression x * y, where the "x" value is NULL. For any "y" value, the XDB Server evaluates this entire expression as NULL. In contrast, NULL values are ignored when determining the results of aggregate functions. For example, consider the query:

SELECT SUM(qty)
FROM partsupp

If the ith record data value in the qty column contains a NULL value, the SUM(qty) function is calculated as if the ith record does not exist.

More:

  • CASE Expressions
  • Concatenation
  • Functions In SELECT Clauses
  • Examples
  • CASE Expressions
  • Concatenation
  • Functions In SELECT Clauses
  • Examples
Parent topic: SELECT Clause Syntax and Description


CASE Expressions

Use CASE expressions to create conditional logic.

Syntax

CASE {searched-when-clause | simple-when-clause}
  [ELSE NULL | ELSE result-expression]
  END
searched-when-clause:
WHEN search-condition THEN
{result-expression | NULL} ...
simple-when-clause:
expression WHEN expression THEN
  {result-expression | NULL} ...

where:

searched-when-clause | Specifies a search condition that is applied to each row or group of table data presented for evaluation and the result when that condition is true.
simple-when-clause | Specifies that the value of the expression prior to the first WHEN keyword is tested for equality with the value of each expression that follows a WHEN keyword. Also, specifies the result for each WHEN keyword when the expressions are equal.
result-expression | Specifies the result of a case-expression if no case is true. Also, specifies the result of a searched-when-clause or a simple-when-clause when true. There must be at least one result-expression in the CASE expression.
search-condition | Specifies a condition that is true, false, or unknown about a row or group of rows. The search-condition in a searched-when-clause cannot contain a subselect.

Example

Assume that in the a table named EMPLOYEE, the first character of a department number represents the division in the organization. Use a CASE expression to list the full name of the division to which each employee belongs:

SELECT EMPNO, LASTNAME
  CASE SUBSTR(WORKDEPT,1,1)
  WHEN 'A' THEN 'Administration'
  WHEN 'B' THEN 'Human Resources'
  WHEN 'C' THEN 'Design'
  WHEN 'D' THEN 'Operations'
  END
FROM EMPLOYEE
Parent topic: SELECT Expressions


Concatenation

The special symbol || (also called the concatenation operator) is used to attach string constants and data values appearing in query results. The output rows have the same length as the sum of the individual string constants and data values attached. If any component of the concatenation expression is null (such as a data value from a column), the entire expression is null. The following query uses the concatenation operator to displays last names, followed by a comma and space, and then first names.

SELECT lname||", "||fname
FROM employee
Parent topic: SELECT Expressions


Functions In SELECT Clauses

The XDB Server provides both ANSI standard and special XDB Server functions that can be used in SELECT clause expressions. Functions (mathematical, string, and date) supported by the XDB Server are listed in Functions.

For example, the XCONCAT function (similar to the || operator) can be nested within itself to concatenate two or more string and column values, as shown by the following query:

SELECT XCONCAT(XCONCAT(color, " "), pname)
FROM part

This query produces the following results:

column1
RED NUT
GREEN BOLT
BLUE CAM
RED SCREW
BLUE CAM
RED COG

When a SELECT clause combines aggregate functions (sum, count, avg, etc.) with column names, the query statement must include a GROUP BY clause. (See Other Clauses for more information on the GROUP BY clause.) Additionally, the column-list of the GROUP BY clause must include all column names that appear in the SELECT clause.

Parent topic: SELECT Expressions


Examples

The query statement below would generate an error message because there is no GROUP BY clause that instructs the XDB Server to group records on the selected SNO column -- for purposes of calculating average quantities:

SELECT sno, AVG(qty)
FROM partsupp

The next query of the PARTSUPP table is corrected to include the GROUP BY clause:

SELECT sno, AVG(qty)
FROM partsupp
GROUP BY sno

The query results follow:

sno | avg(qty)
S1 | 216.67
S2 | 350.00
S3 | 200.00
S4 | 300.00

If there is no GROUP BY clause, only aggregate functions may be selected in queries that include a HAVING clause.

Note: The GROUP BY and HAVING clauses are covered in Other Clauses. Aggregate functions are covered in Functions.
Parent topic: SELECT Expressions


FROM Clause Syntax and Description

The FROM clause (like the SELECT clause) must appear in every SQL query statement. See SELECT Clausefor more information. While the SELECT clause specifies from which columns data values are retrieved during query execution, the FROM clause specifies the table(s) in which these data columns are located.

The FROM clause names one or more tables (or views) from which data values are retrieved by the query. Data retrieval is limited to the tables (or views) specified. The XDB Server also allows you to explicitly specify right, left, and full outer joins, and use subselects or nested table expressions. The FROM clause either names a single table or view or produces an intermediate result table that is the result of a subselect or an inner or outer join operation.

The FROM clause is required in a SELECT statement to identify the tables and/or views that are being queried. When more than one table or view is specified in the FROM clause, each of these object names can also be assigned a correlation name. In XDB mode, the FROM clause is extended to allow explicit expression of inner and outer join operations and a subselect or nested table expression.

Syntax

The FROM clause format appears below:

FROM table-ref [,...]

table-ref:

{
  [{table-name | view-name} [[AS] correlation-name]
  | [(subselect) [AS] correlation-name]
  | [joined-table]}
}

joined-table:

table-ref [INNER] | [{LEFT | RIGHT | FULL} [OUTER]]
  JOIN table-ref join-condition
| [(joined-table)]

join-condition:

ON join-expression { = | <> | > | < | >= | <= }
  join-expression AND [...]

join-expression:

column-name [{VALUE | COALESCE} (column-name [,...])]

Parameters:

table-name or view-name | A list of one or more table or view names (separated by commas), from which data values are to be retrieved. Must identify a table or view described in the system catalog of the database subsystem identified by the implicitly or explicitly specified location name.
correlation-name | Can be specified for a table reference, either immediately following the table reference or after the AS keyword which follows the table reference. A correlation name must be specified for a nested table expression that is enclosed in parentheses.
joined-table | Specifies an intermediate result table that is the result of either an inner equi-join or an outer join. The table is derived by applying one of the join-operators; INNER, RIGHT OUTER, LEFT OUTER, or FULL OUTER, to its operands. If a join-operator is not specified, INNER is implicit. The order in which a LEFT OUTER or RIGHT OUTER JOIN is performed can affect the result. A joined-table can be used in any context in which any form of the SELECT statement is used. Both a view and a cursor is read-only if its SELECT statement includes a joined-table.
joined-condition | Defines a search condition in which predicates can be combined only with the keyword AND, and each predicate has the form 'expression operator expression'. The '=' operator is the only operator allowed for a FULL OUTER JOIN or a FULL JOIN.
join-expression | Must include a column name. Only columns and the VALUE and COALESCE functions are allowed in the expression. VALUE and COALESCE are allowed only when the join operator is FULL JOIN or FULL OUTER JOIN. One expression of the predicate must reference only columns of one of the operand tables of the associated join operator, and the other expression of the predicate must reference only columns of the other operand table. Before this rule is applied, column references are resolved using the rules for resolution of column name qualifiers.
  • Correlation Names
  • INNER JOIN
  • FULL [OUTER] JOIN
  • LEFT [OUTER] JOIN
  • RIGHT [OUTER] JOIN
  • VALUE
  • Nested Table Expressions
  • Querying Views
Parent topic: Clauses


Correlation Names

Correlation names are used in place of the actual table or view name when qualifying columns within a query statement. The correlation name appears immediately after the corresponding table or view name in the FROM clause (separated by a single space). Correlation names must satisfy the same naming conventions as table names, and must be unique among all table, view and other correlation names within a query. The correlation name qualifies columns that appear in either SELECT or WHERE clauses. See WHERE Clause for more information.

The following query shows a correlation name of "p" being assigned to the PART table, and a correlation name of "ps" being assigned to the PARTSUPP table.

SELECT pname, qty
  FROM part p, partsupp ps
  WHERE p.pno = ps.pno

More information on joins and correlation names appears in WHERE Clause and Other Clauses.

  • Using AS
Parent topic: FROM Clause Syntax and Description


Using AS

The AS keyword is available before correlation names, and after the following:

  • Nested table expressions
  • Table names
  • View names
  • Aliases
  • Synonyms
Parent topic: Correlation Names


INNER JOIN

When a FROM clause contains two or more tables (or views), that FROM clause is said to join the data values appearing in the two or more tables listed. Up to ten table or view names may be listed in a FROM clause, with each object name separated with a comma. The familiar operation of joining two or more tables, as carried out in XDB Server Versions 5.0 and earlier, can now be called an inner join. This distinction is made in order to distinguish inner joins syntactically from left, right, and full (outer) joins. For example, the inner join queries below (on the PART and PARTSUPP tables) produce the same results:

SELECT part.pno, pname, qty
  FROM part, partsupp
  WHERE part.pno = partsupp.pno

or

SELECT part.pno, pname, qty
  FROM part INNER JOIN partsupp
  ON part.pno = partsupp.pno

In both of these queries the PART and PARTSUPP tables are joined on their commonly named PNO columns. Notice that the second query explicitly defines this query as an inner join, not an outer join. You can use the key words INNER JOIN in the from clause instead of the traditional comma (the comma still works for an inner join). To be consistent with this syntax, you should also use an ON clause when you explicitly state a join condition (however, the WHERE clause will work).

The results of these inner joins cannot contain any unmatched rows from either table. For example, if the PART table contained a record for a RIVET with a PNO column value of P8, this RIVET information would not be retrieved in either of the previous queries, since there is no matching record in the partsupp table with a PNO column value of P8.

Parent topic: FROM Clause Syntax and Description


FULL [OUTER] JOIN

In contrast to inner joins, outer joins can contain some or all nonmatching rows from both joined tables. Missing values in a row of the result table are filled with nulls. The following sample query creates a full outer join between the PART and PARTSUPP tables:

SELECT part.pno, pname, qty
  FROM part FULL OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The results of this full outer join (the keyword OUTER is optional) contain all matched as well as unmatched rows from either table. For example, if the PART table contained a nonmatching record for a RIVET with a PNO column value of P8, this RIVET information would be part of the result, even though there is no matching record in the PARTSUPP table (with a PNO column value of P8). Likewise, if the PARTSUPP table contained a nonmatching record with a PNO column value of P7, this record information would also appear in the result even though there is no matching P7 PNO column value in the PART table.

Using the FULL [OUTER] JOIN syntax includes nonmatched rows from both joined tables. Full outer joins can only use the equal (=) comparison operator in the join condition (left and right outer joins can use all the comparison operators).

Parent topic: FROM Clause Syntax and Description


LEFT [OUTER] JOIN

Left outer joins (the keyword OUTER is again optional) include nonmatching rows only from the table named before the LEFT [OUTER] JOIN clause. Missing values in a row are filled with nulls. The following sample query creates a left outer join between the PART and PARTSUPP tables:

SELECT part.pno, pname, qty
  FROM part LEFT OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The results of this query contains all matched rows, plus unmatched rows from the PART table (or, the table on the left hand side of the LEFT OUTER JOIN clause). For example, if the PART table contained a nonmatching record for a WASHER with a PNO column value of P9, this WASHER information would be part of the result, even though there is no matching record in the PARTSUPP table with a PNO column value of P9. If, however, the PARTSUPP table also contained an unmatched record, this record information would not appear in the result rows. Using the LEFT [OUTER] JOIN syntax includes nonmatched rows from only the joined table on the left of the LEFT OUTER JOIN clause.

Parent topic: FROM Clause Syntax and Description


RIGHT [OUTER] JOIN

Right outer joins (the keyword OUTER is optional) include nonmatching rows only from the table named after the RIGHT [OUTER] JOIN clause. Missing values in a row are filled with nulls. The following sample query creates a right outer join between the PART and PARTSUPP tables:

SELECT part.pno, pname, qty
  FROM part RIGHT OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The results of this query contains all matched rows, plus nonmatched rows from the PARTSUPP table (or, the table on the right hand side of the RIGHT OUTER JOIN clause). For example, if the PARTSUPP table contained a nonmatching record for a PNO column value of P9, this information would be part of the result. If, however, the PART table also contained an nonmatched record, this record information would not appear in the result rows. Using the RIGHT [OUTER] JOIN syntax includes nonmatched rows from only the joined table on the right of the RIGHT OUTER JOIN clause.

  • ON Clause
Parent topic: FROM Clause Syntax and Description


ON Clause

Clause that can be used in place of the WHERE clause when explicitly stating an INNER JOIN condition (however, the WHERE clause still works). For LEFT and RIGHT OUTER JOIN clauses, however, the join condition must begin with the ON clause.

Parent topic: RIGHT [OUTER] JOIN


VALUE

The VALUE or COALESCE function (COALESCE is the keyword specified by the ANSI/ISO standard of 1992 as a synonym for the VALUE function of IBM SQL), by either name, can be particularly useful in join operations. Suppose, for example, that in the full outer join sample query below, the PARTSUPP table contained a nonmatched row entry of P9 in the PNO column:

SELECT part.pno, pname, qty
  FROM part FULL OUTER JOIN partsupp
  ON part.pno = partsupp.pno

In this case, the P9 entry would not appear in the first column of the result. The problem is that the PNO column is in the PARTSUPP table, and is not included in the SELECT list of the query. We can, however, capture the PNO column of the PARTSUPP table by using the VALUE (or COALESCE) function as shown in the following query:

SELECT VALUE(part.pno, partsupp.pno) AS
    partnum, pname, qty
  FROM part FULL OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The VALUE clause forces the query to first search the PNO column in the PART table for result data; and if none is found, search the PNO column of the PARTSUPP table. In the example above, the AS clause (AS partnum) provides a synonym for the result of the VALUE function. (See AS clause in SELECT Clause).

Parent topic: FROM Clause Syntax and Description


Nested Table Expressions

An operand of a join can be more complex than the name of a single table or view. A subselect can be used as a complex operand in the FROM clause. Such an operand is called a nested table expression. Suppose we wanted to join the result of the last sample query with the SUBPART table, which includes a column named SUBPART (containing data similar to the commonly named PNO columns in the PART and PARTSUPP tables). The SUBPART table contains several rows with part numbers (SUBPART column) values that do not appear in either the PART or PARTSUPP tables.

The following sample query joins the SUBPART table with the result of the outer join of the PART and PARTSUPP table (three way join), displaying the nonmatching part number values from SUBPART in the result:

SELECT product, VALUE(subpart.subpart, partnum) AS
    partnum, pname, subpart.qty
  FROM subpart LEFT JOIN
  (SELECT VALUE(part.pno, partsupp.pno) AS
    partnum,pname, subpart.qty
    FROM part FULL OUTER JOIN partsupp
    ON part.pno = partsupp.pno) AS temp
  ON subpart.subpart = partnum

In this example, the correlation name is temp. The optional keyword AS is useful as an eye catcher for the correlation name that follows.

The following restrictions on nested table expressions apply:

  • Must be enclosed in parentheses
  • Must have a correlation name. In our example, the correlation name is temp.
Parent topic: FROM Clause Syntax and Description


Querying Views

You may query a view just like a table, provided you have SELECT authority on the view. For example, assume that the redparts view was originally defined as follows:

CREATE VIEW redparts
  AS SELECT *
  FROM part
  WHERE color = 'RED'

The following query retrieves a subset of column values from this view (the view itself being a subset of the original PART table):

SELECT pno, city
  FROM redparts

The query result appears below:

pno | city
P1 | LONDON
P4 | LONDON
P6 | LONDON

The next example also queries the redparts view:

SELECT *
  FROM redparts
  WHERE weight < 15

The query results appear below:

pno | pname | color | weight | city
P1 | NUT | RED | 12 | LONDON
P4 | SCREW | RED | 14 | LONDON
Parent topic: FROM Clause Syntax and Description


WHERE Clause Syntax and Description

Relational databases typically contain many rows of data, with each row constituting a separate record. Most relational database queries retrieve only a portion of the records contained in a table. The WHERE clause qualifies the query command statement to limit the data retrieved to specific rows in the table

The WHERE clause is generally used with a SELECT statement to specify search criteria for retrieving rows of data from a table or group of tables. The WHERE clause can also appear in DELETE and UPDATE command statements.

The optional WHERE clause sets conditions that each record must meet before that record is retrieved by a query. If the SELECT command statement does not include a WHERE clause, every row in the table or tables queried appears in the result.

A predicate states selection criteria that is applied to each row of data values in the table being queried by the SELECT statement. If the data in a particular record matches the selection criteria, then that record is retrieved by the query, otherwise the record is passed over. See Predicates for more information.

WHERE clause selection criteria may include nested subqueries or may connect two or more tables together in a join condition.

Syntax

The WHERE clause format appears below:

WHERE search-condition

where:

search-condition Specifies a predicate (or one or more predicates connected with the AND, OR, or NOT operators).

More:

  • Predicates
  • Joins
  • Predicates
  • Overriding the XDB Optimizer
  • Joins
  • Nested Queries
  • GROUP BY Clause
  • HAVING Clause
  • OPTIMIZE FOR Clause
  • ORDER BY Clause
  • FOR UPDATE OF Clause
  • UNION Clause
Parent topic: Clauses


Predicates

This topic identifies the many different kinds of predicates that can appear in WHERE clauses. The XDB Server uses the test conditions defined in WHERE clause predicates to qualify table row (record) retrieval in a SELECT command statement. Any of the following predicates may also qualify records in UPDATE and DELETE command statements.

More:

  • Simple Predicates
  • Compound Predicate
  • BETWEEN Operator
  • IN Operator
  • IS [NOT] NULL Operator
  • LIKE Operator
  • SOUNDS LIKE Operator
  • WHERE Clause Expressions
  • CASE Expressions
  • Simple Predicates
  • Compound Predicate
  • BETWEEN Operator
  • IN Operator
  • IS [NOT] NULL Operator
  • LIKE Operator
  • SOUNDS LIKE Operator
  • WHERE Clause Expressions
  • CASE Expressions
Parent topic: WHERE Clause Syntax and Description


Simple Predicates

Predicates using the following operators in their selection conditions are called simplepredicates:

Operator | Evaluated as
= | equal to
<> | not equal to
!= | not equal to
^= | not equal to
> | greater than
>= | greater than or equal to
!> | not greater than
< | less than
<= | less than or equal to
!< | not less than

The following query displays all rows in the SUPPLIER table containing a value of 20 in their STATUS column:

SELECT *
  FROM supplier
  WHERE status = 20

The query results appear below:

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S4 | CLARK | 20 | LONDON

The WHERE clause in the next example compares a character string "PARIS" with the CITY column. The query below retrieves SNO (supplier number) and STATUS column data for all suppliers in Paris:

SELECT sno, status
  FROM supplier
  WHERE city = "PARIS"

Note that character strings can be enclosed in either double (") or single (') quotes. The display result appears below:

sno | status
S2 | 10
S3 | 30

When one column value is compared against another column value in a query -- and the column data types are different, the XDB Server tries to convert one of the data values to a data type compatible with the other data value before performing the comparison. For example, if integer and float column values are compared, the INT data value is converted to a FLOAT value before the XDB Server performs the comparison.

Spaces in data values are considered when evaluating retrieval conditions. Right justified data with leading spaces does not equal left justified data with trailing spaces. For example, the string "Jones" is read as a completely different value, depending on the number of preceding or trailing blank spaces attached. The LIKE predicate operator (see the LIKE Operator) allows string pattern matching without strict adherence to character string content and order.

All three of the < > or ! = or ^ = predicate operators specify records for retrieval that do not meet the specified condition. For example, the following query retrieves the PNO (part number) column values of all PART table records with a COLOR column value other than "RED."

SELECT pno
  FROM part
  WHERE color != "RED"
Parent topic: Predicates


Compound Predicate

Compound predicates use the operators OR and AND. For example, to display the SNO column values for all suppliers in "PARIS" with a STATUS column value greater than 20, use the following query:

SELECT sno
  FROM supplier
  WHERE city = "PARIS"
    AND status > 20

Shown next is the same query written with the OR operator rather than the AND operator. This SELECT command statement retrieves PNO column values for those parts that are either "RED" or weigh more than 15 pounds.

SELECT pno
  FROM part
  WHERE color = "RED"
    OR weight > 15

In complex queries, parentheses can be used to indicate the order of evaluation. The condition(s) surrounded by the innermost pair of parentheses are applied first.

SELECT pno, pname
  FROM part
  WHERE color = "green"
    OR (city = 'LONDON'
    AND weight < 15)

This last query retrieves PNO and PNAME column values of all parts that are either green or are both made in London, and have a weight less than 15.

The query result is displayed below:

pno | pname
P1 | NUT
P2 | BOLT
P4 | SCREW
Parent topic: Predicates


BETWEEN Operator

The BETWEEN operator allows the XDB Server to evaluate whether or not data values sort between a range of values indicated in the predicate.

The format for a predicate with a BETWEEN operator is shown below:

expres1 [NOT] BETWEEN expres2 AND expres3

Each occurrence of the expression expres1 is evaluated to determine if it sorts between and including the range values indicated by expres2 and expres3 (the range values in the BETWEEN clause are also part of the result set). The three variable expressions above can consist of any combination of column data values, constants, etc.

The next query selects all PART table records with WEIGHT column values between 15 and 18:

SELECT pno, pname
  FROM part
  WHERE weight BETWEEN 15 AND 18

The following records are retrieved:

pno | pname
P2 | BOLT
Parent topic: Predicates


IN Operator

The IN (and NOT IN) operators cause an enumerated list of values appearing in the WHERE clause predicate to be evaluated for a true condition.

SELECT sno, sname
  FROM supplier
  WHERE sno IN ("S1", "S2", "S3")

All data values in the SNO column must match one of the three string constants in order for their corresponding records to be retrieved. This query retrieves the following data values:

sno | sname
S1 | SMITH
S2 | JONES
S3 | BLAKE
Parent topic: Predicates


IS [NOT] NULL Operator

The IS NULL operator can be used in WHERE clause predicates to match null values occurring in a specified data column. For example, the query below retrieves all PART table records that do not have a NULL value in their COLOR data column:

SELECT *
  FROM part
  WHERE color IS NOT NULL

When used in a predicate, the NULL operator keyword must be preceded with either the IS or IS NOT keywords. Operators such as =, != or ^= can not be used with NULL.

Parent topic: Predicates


LIKE Operator

The XDB Server supports the DB2 implementation of the LIKE string pattern matching operator. The syntax for a LIKE pattern match predicate appears below:

expression [NOT] LIKE
{special-register | host-variable | string-constant}
[ESCAPE {host-variable | string-constant}]

where:

expression | The expression parameter string value is compared to the pattern string, and can be any valid expression-- as long as the result of the expression is a string. The expression can consist of a single table column name or contain a column name as part of the expression.
special-register | Indicates that the string is stored in the named special register.
host-variable | Indicates that the string is in the named host variable. The host variable must be already be defined in accordance with the rules for declaring string host variables.
string-constant | Includes the pattern as a string constant within the predicate.

In each case, the pattern string value represented by either the special-register, host-variable or string-constant parameter is matched against the string value of expression -- for each table record specified by the query.

Pattern Strings

The host-variable and string-constant parameters can utilize two special reserved characters (wild card characters) -- the percent sign ( % ) and the underscore ( _ ) to perform pattern match searches against the string values in expression. The percent sign character matches any string (of any length), while the underscore character matches any single string character.

ESCAPE

The optional ESCAPE clause designates a special escape character, which if placed immediately before a percent ( % ) or underline ( _ ) character causes that percent or underline character to be literally interpreted as part of the pattern string. The escape character value can be specified with either a string-constant (enclosed in quotes) or host-variable (must not be a structure).

  • LIKE Examples
Parent topic: Predicates


LIKE Examples

The query shown next retrieves data for those PART table records containing a PNAME column value that begins with "C":

SELECT pno, pname, weight
  FROM part
  WHERE pname LIKE "C%"

In the following example, the query match string "% of Total" is used to search the statistic column of a table called stats:

SELECT *
  FROM stats
  WHERE statistic LIKE "\% of Total"
    ESCAPE "\"

Note that in DB2 mode (for purposes of LIKE operator string comparison) trailing blanks are significant for data values located in fixed length CHAR data type columns. For example, if a character data type column with the a field length of ten contains a data value of "Sales ", a query containing the LIKE operator string "%s " would return a match. However, a LIKE operator string of "%s" in the same query would not return a match.

Parent topic: LIKE Operator


SOUNDS LIKE Operator

The XDB Server supports a SOUNDS LIKE operator that uses a soundex algorithm to pattern match strings that sound alike. The syntax for a SOUNDS LIKE condition is:

field-name SOUNDS LIKE string

where:

field-name | Refers to a specific column containing the data values to be searches for a match.
string | Is any character string (enclosed in quotes) to be matched against the value of the field-name column in each data record.

For example, the following query retrieves all records from the EMPLOYEE table where the LNAME column value sounds like "herwood":

SELECT fname, lname
  FROM employee
  WHERE lname SOUNDS LIKE "herwood"

The query results appear next:

fname | lname
Roger | Hurwood
Susan | Hurwood
Parent topic: Predicates


WHERE Clause Expressions

Expressions that compute values from one or more columns can be used advantageously in the WHERE clause of a query. Any legal arithmetic expression involving columns, constants, functions and arithmetic operators (+, -, * and /) is permitted in a WHERE clause. Parentheses may be used as necessary to define evaluation order.

Note:

If null values appear in an expression the result will be null.

The following query is an example of an expression appearing in the WHERE clause of a query:

SELECT pno, weight FROM part
  WHERE city = "LONDON"
    AND weight * 2 > 25
Parent topic: Predicates


CASE Expressions

Use CASE expressions to create conditional logic.

Syntax

CASE {searched-when-clause | simple-when-clause}
  [ELSE NULL | ELSE result-expression]
  END
searched-when-clause:
WHEN search-condition THEN
{result-expression | NULL} ...
simple-when-clause:
expression WHEN expression THEN
  {result-expression | NULL} ...

where:

searched-when-clause | Specifies a search condition that is applied to each row or group of table data presented for evaluation and the result when that condition is true.
simple-when-clause | Specifies that the value of the expression prior to the first WHEN keyword is tested for equality with the value of each expression that follows a WHEN keyword. Also, specifies the result for each WHEN keyword when the expressions are equal.
result-expression | Specifies the result of a case-expression if no case is true. Also, specifies the result of a searched-when-clause or a simple-when-clause when true. There must be at least one result-expression in the CASE expression.
search-condition | Specifies a condition that is true, false, or unknown about a row or group of rows. The search-condition in a searched-when-clause cannot contain a subselect.

Example

From a table named EMPLOYEE, find all employees who earn more than 25 percent of their income from commission, but who are not fully paid on commission.

SELECT EMPNO, WORKDEPT, SALARY+COMM FROM EMPLOYEE
WHERE (CASE WHEN SALARY=0 THEN 0
  ELSE COMM/(SALARY+COMM) END >0.25;

Note that this example uses the CASE expression to avoid "division by zero" errors.

Parent topic: Predicates


Overriding the XDB Optimizer

Usually, it is faster to execute a query using one or more indexes than to examine every record in the tables involved in the query. XDB Server's query optimization algorithms automatically examine the indexes available and pick which indexes, if any, to use for a particular query. The user normally does not need to specify which indexes to use.

You can force the use of an index for a particular query or force the system to not use an index. To force the use of an index, enter an asterisk (*) in parentheses after the name of the indexed column when you construct the query. To force the system to ignore the index, enter a hyphen (-) in parentheses after the name of the indexed column when you construct the query.

For example, assuming that an index exists on C_NO:

This query uses the C_NO index.

SELECT c_no, o_no, o_date
  FROM orders
  WHERE c_no(*)<20

This query does not use the index.

SELECT c_no, o_no, o_date
  FROM orders
  WHERE c_no(-)<20

The (*) and (-) options are valid only for column names that appear in a WHERE clause. You cannot use the (*) and (-) options in SELECT, GROUP BY, HAVING or ORDER BY clauses.

Parent topic: WHERE Clause Syntax and Description


Joins

A join is a form of query that occurs any time more than one table or view name appears in the FROM clause of a query statement -- resulting in column data being retrieved from each table. The XDB Server allows up to 10 table names to appear within each level of a query.

More:

  • Equijoin
  • Non-equijoin
  • Correlation Names
  • Multi-table Joins
  • Outer Join
  • Equijoin
  • Non-equijoin
  • Correlation Names
  • Multi-table Joins
  • Outer Join
Parent topic: WHERE Clause Syntax and Description


Equijoin

The equijoin is the most commonly used kind of table join. Equijoins include a join condition requiring the values derived from one column of a table or view to equal the values derived from another column of a different table or view. Join conditions may be created on any combination of columns, provided the qualified column names being compared in the WHERE clause have compatible data types.

For example, suppose the supplier numbers and city names for all suppliers that supply part "P2" are needed. The next query illustrates how this could be accomplished:

SELECT sno, city
  FROM partsupp, supplier
  WHERE partsupp.sno = supplier.sno
    AND pno = "P2"

The query results appear below:

sno | city
S2 | PARIS
S3 | PARIS
S1 | LONDON
S4 | LONDON

As demonstrated in the previous query, when the tables to be joined have a common column name appearing in the WHERE clause join condition, these column names should be prefixed (qualified) with their table names to resolve any ambiguity. In the above query, the qualified column name PARTSUPP.SNO specifies that the SNO column of the PARTSUPP table is to be compared with the SNO column of the SUPPLIER table (SUPPLIER.SNO).

Note:

If you do not qualify a column name that is contained in more than one query statement table, the system uses column data from the first table it finds containing the specified column name. This situation can produce unexpected results, and it is advisable to prefix common column names their specific "owning" table names.

If a join condition (such as, partsupp.sno = supplier.sno) is not included in a equijoin query, the result is a Cartesian product. This type of join concatenates every record from a table with every record from the other tables listed in the FROM clause, producing all this information in the query result. Cartesian products have limited practical value and can result in extremely large and often nonsensical results.

Parent topic: Joins


Non-equijoin

The join condition in the WHERE clause may use operators other than the equal sign (=). For example, to find all employees that are not (!=) managers, the following query can be used:

SELECT lname, fname
  FROM dept, employee
  WHERE employee.e_no != dept.mgr
    AND employee.dept = dept.dept

The query result appears below:

lname | fname
Hurwood | Roger
Gross | Mary
Wilson | Arthur
Chung | Yung
Cox | John
Crisp | Keith
Hurwood | Susan
Haley | Olaf
Parent topic: Joins


Correlation Names

To avoid repeatedly typing a full table name, a substitute correlation name for the same table may be designated, if desired. For example, to avoid repeating the table name qualifiers "supplier" and "partsupp" throughout the query, single letter correlation names can be assigned to replace the original table names henceforth in the same query.

Correlation names are designated in the FROM clause (immediately following the table name, and separated with a space) to serve as substitutes for qualifying table names later on in the WHERE clause. For example, to display the supplier number and city of all vendors who provide part "P2", the correlation names "p" and "s" can be used as qualifying prefixes instead of the table names (SUPPLIER and PARTSUPP).

SELECT sno, city
  FROM partsupp p, supplier s
  WHERE p.sno = s.sno
    AND pno = "P2"

Notice the correlation names appearing as column name prefixes in the WHERE clause join condition above.

It is possible to join a table to itself, if a correlation name is used to qualify each instance of the table appearing in the WHERE clause. For example, consider a table named personnel containing the columns staff_id, salary, and super_id. The result of the self-join query shown next displays all staff members who earn more than their supervisors:

SELECT a.staff_id
  FROM personnel a, personnel b
  WHERE a.salary > b.salary
    AND a.super_id = b.staff_id
Parent topic: Joins


Multi-table Joins

The next query joins four tables in the TUTORIAL location to find the name of the customer, order date, product names, and quantities ordered -- for all orders with order number greater than three:

SELECT company, o_date, description, quantity
  FROM customer c, orders o, products p, items i
  WHERE c.c_no = o.c_no
    AND p.p_no = i.p_no
    AND o.o_no = i.o_no
    AND o.o_no > 3

The XDB Server will choose the optimal order for performing the join. Due to query optimization, a join performed on indexed columns may retrieve records in a different order than a join performed on nonindexed columns.

It is not possible to update, delete or insert into table records retrieved by performing a join. However, UPDATE and DELETE commands may contain joins embedded as subqueries in the WHERE clause to specify the target records in a table.

Parent topic: Joins


Outer Join

An outer join creates two distinct kinds of query output one after the other -- all in the same result (not available in DB2 mode). Records satisfying the join condition appear first in the result, followed immediately by records that do not satisfy the join condition.

For example, an ordinary join between the SUPPLIER and PARTSUPP table could be performed using the following query:

SELECT supplier.sno, sname, pno, qty
  FROM supplier, partsupp
  WHERE supplier.sno = partsupp.sno

However, the output result would not include any information on supplier "S5", since this is the one supplier that does not supply any parts. (See the sample tables in XDB Server TUTORIAL Location.)

By performing an outer join, it is possible to retrieve the information on supplier "S5" from the SUPPLIER table (specifically the SNO and SNAME column values), even though the join condition of the WHERE clause (supplier.sno = partsupp.sno) is not being met for this row of joined output.

SELECT supplier.sno, sname, pno, qty
  FROM supplier, partsupp
  WHERE supplier.sno = partsupp.sno(+)

The sample query above illustrates the syntax for an outer join. Appending a plus sign within parentheses (+) to the PARTSUPP table name in the join condition yields the following results:

sno | sname | pno | qty
S1 | SMITH | P1 | 300
S1 | SMITH | P3 | 400
S1 | SMITH | P2 | 200
S1 | SMITH | P4 | 200
S1 | SMITH | P5 | 100
S1 | SMITH | P6 | 100
S2 | JONES | P2 | 400
S2 | JONES | P1 | 300
S3 | BLAKE | P2 | 200
S4 | CLARK | P2 | 200
S4 | CLARK | P4 | 300
S4 | CLARK | P5 | 400
S5 | ADAMS |  |

Even though the PARTSUPP table contains no rows with a matching "S5" value, the outer join causes the "S5" row of the SUPPLIER table to be output anyway (immediately after all the rows matching the join condition). Since there are no matching PNO or QTY column values from the PARTSUPP table for that joined row of output, the outer join inserts null values in the PNO and QTY columns for this result row.

The outer join conditions must be columns and not expressions. There is a maximum of five outer join conditions per table. Only one master table can be defined.

Parent topic: Joins


Nested Queries

A nestedquery consists of two or more ordinary queries nested in such a way that the results of each inner query (subselect) are used in the comparison test for the selection clause of the next outer query (or another command statement). The three basic formats for nested queries (also called subqueries) are shown below:

WHERE expression [NOT] IN subselect
WHERE expression operator [ALL | ANY] subselect
WHERE [NOT] EXISTS subselect

where:

expression | Consists of any valid expression.
subselect | Consists of any valid subselect (ORDER BY and UNION clauses not allowed).
operator | Is any of the standard relational operators ( =, <>, !=, ^=, <, <=, >, >= ).
IN | Evaluates to true if at least one value retrieved by the subselect matches the predicate condition (operates the same as the =ANY predicate).
NOT IN | Evaluates to true if no matching values are retrieved by the subselect (operates the same as the !=ALL or ^=ALL predicates).
ALL | Is used with the standard relational operators ( =, >, >=, <, <=, <>, != or ^= ), and evaluates to true if every record retrieved by the subselect satisfies the condition.
ANY | Is used with the standard relational operators ( =, >, >=, <, <=, <>, != or ^= ), and evaluates to true if at least one record retrieved by the subselect satisfies the condition.
EXISTS | Evaluates as true if the subselect retrieves at least one value.
NOT EXISTS | Evaluates as true if the subselect retrieves no values.

The number of levels of subselect nesting permitted by the XDB Server is limited only by system storage. The actual number of nested queries that can be executed depends on the complexity of the queries, and the number of concurrently open queries. When accessing the XDB Server, the number of concurrently opened queries can be set with the XDB Server Configuration Utility.

During subselect execution, the innermost query is executed first, with that result determining the outcome of the comparison test in the next higher level query -- and so on for each nested query level. There are a number of comparison tests that can be performed using nested queries.

More:

Subselects and Locations

IN Special Operator

ALL Special Operator

ANY vs. SOME Operators

Single Value Comparisons

EXISTS Special Operator

Multiple Level Nesting

  • Subselects and Locations
  • IN Special Operator
  • ALL Special Operator
  • ANY vs. SOME Operators
  • Single Value Comparisons
  • EXISTS Special Operator
  • Multiple Level Nesting
  • Correlated Subqueries
Parent topic: WHERE Clause Syntax and Description


Subselects and Locations

A subselect cannot reference a location different from the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

SELECT * FROM tutorial.tutorial.employee
WHERE e_no IN
  SELECT e_no FROM debloc.debbie.employee
  WHERE st = "MD";

Valid:

SELECT * FROM tutorial.tutorial.employee
WHERE e_no IN
  SELECT e_no FROM tutorial.debbie.employee
  WHERE st = "MD";
Parent topic: Nested Queries


IN Special Operator

One of the most frequently used nested query comparison tests determines if a value retrieved by a query is IN (or NOT IN) the set of data values retrieved by a lower level subselect. The following sample query retrieves the names of suppliers who carry part number "P2":

SELECT sname
FROM supplier
WHERE sno IN
  SELECT sno
  FROM partsupp
  WHERE pno = "P2"

The inner (or lower) query is referred to as a nested query (or subselect) since it is located within an outer query statement. To execute the nested query, the system first tests for the PNO (part number) column values of records located in the PARTSUPP table that match "P2". The subselect statement (or subselect) next retrieves SNO (supplier number) column values for the records containing the correct part number.

The results of this first nested subselect appear below:

sno
S1
S2
S3
S4

The final result (shown below) is then produced by the outer query, which retrieves the four SNAME column values from the SUPPLIER table corresponding to the supplier numbers retrieved in the inner query.

sname
SMITH
JONES
BLAKE
CLARK

Note that the last nested query could have been written as a table join, as follows:

SELECT sname
  FROM supplier, partsupp
  WHERE supplier.sno = partsupp.sno
    AND partsupp.pno = "P2"

The processing that occurs for a table join is very similar to that occurring during a nested query execution. This processing consists of selecting a subset of records from one of the tables that meet all conditions except the join condition. The records in the other table are then tested for the join condition against the first subset of records.

The major difference between processing a join and a nested query is that the XDB Server can perform query optimization when a join is executed. For example, query optimization allows the system to decide which table to process first to achieve the most efficient performance. When a nested query is executed, however, the innermost query is always performed first.

Algorithms exist for transforming nested queries into joins (or flat queries) before processing. However, these algorithms are complex and time consuming, and therefore have not been implemented by XDB Server.

When nesting queries, the boolean operator NOT can be included to select those records that do not meet the test conditions set forth in selection criteria. For example, the following query returns the SNO and SNAME column values for all suppliers not found in the PARTSUPP table:

SELECT sno, sname
FROM supplier
WHERE sno NOT IN
  SELECT sno
  FROM partsupp

Supplier S5 (or "ADAMS") is the only supplier that meets this condition.

Parentheses can be added to complex SQL statements to enhance clarity or to change the execution order of the various subqueries and table joins. For example, the following statement performs a series of XDB Server operations equivalent to the descriptive text summary below:

Find all parts carried by suppliers, where the suppliers either have a status of 10 or are located in "PARIS".

SELECT DISTINCT pno, pname
FROM part, partsupp
WHERE part.pno = partsupp.pno
  AND sno IN
    SELECT sno
    FROM supplier
    WHERE status = 10
      OR city = "PARIS"

This last query retrieves the following results:

pno | pname
P1 | NUT
P2 | BOLT

If parentheses are added to the previous complex query, the results are interpreted differently.

The following reformatted query statement is equivalent to the descriptive text summary below:

Find all parts carried by suppliers having a status of 10 or a part made in "PARIS".

SELECT DISTINCT pno, pname
FROM part, partsupp
WHERE part.pno = partsupp.pno
  AND sno IN
    (SELECT sno
    FROM supplier
    WHERE status = 10)
  OR city = "PARIS"

This modified query yields the following result:

pno | pname
P1 | NUT
P2 | BOLT
P3 | CAM
P5 | CAM
Parent topic: Nested Queries


ALL Special Operator

When the ALL special operator is used in a nested query, the test condition is true only if every record retrieved by the subselect satisfies the condition. The example nested query that follows illustrates how an ordinary relational operator is used in conjunction with the ALL special operator. This query retrieves the supplier numbers and part numbers of all parts supplied in at least as large a quantity as parts "P1" and "P6":

SELECT sno, pno
FROM partsupp
WHERE qty >= ALL
  (SELECT qty
  FROM partsupp
  WHERE pno = "P1"
    OR pno = "P6")

The result of the previous query appears below:

sno | pno
S1 | P1
S1 | P3
S2 | P2
S2 | P1
S4 | P4
S4 | P5
Parent topic: Nested Queries


ANY vs. SOME Operators

Special care must be taken when performing test conditions with the ANY special operator, since the test may not conform to the common English interpretation. For example, while the English phrase "not equal any" would normally be evaluated as true if there are no values that match, the interpretation of the SQL equivalent operator !=ANY (or ^=ANY) is different. SQL interprets !=ANY to mean that the comparison is true, if there is at least one value that does not match.

The English equivalent for the SQL condition represented by !=ANY is, in fact, "any not equal". Since this test operator is equivalent to the more readily understood NOT IN, we recommend using NOT IN instead of !=ANY. Similar caution is required when using any other operator in conjunction with ANY. We recommended that the SOME special operator be used in place of ANY. The result is the same, however, the query is more intuitively understood.

The difference between the SOME and ALL special operators is illustrated with the nested query below. This query (except for the keyword SOME) is identical to the previous nested query (which used ALL):

SELECT sno, pno
FROM partsupp
WHERE qty > SOME
  (SELECT qty
  FROM partsupp
  WHERE pno = "P1"
    OR pno = "P6")

The following results illustrate how the SOME special operator retrieves a much larger subset of data than the ALL operator:

sno | pno
S1 | P1
S1 | P3
S2 | P2
S3 | P2
S1 | P2
S1 | P4
S2 | P1
S4 | P2
S4 | P4
S4 | P5
Parent topic: Nested Queries


Single Value Comparisons

In those cases where a nested query can only retrieve one value (as with an aggregate function), the special operators SOME, ANY and ALL may be omitted from the comparison condition.

The next sample query finds the names of all suppliers with a status greater than the average supplier status:

SELECT sname
FROM supplier
WHERE status >
  (SELECT AVG(status)
  FROM supplier)

The results of this query follow:

sname
BLAKE
ADAMS
Parent topic: Nested Queries


EXISTS Special Operator

To test whether or not a subselect retrieves any records, the EXISTS or NOT EXISTS special operators are used. The following query retrieves the names of all suppliers only if there is at least one part being supplied in quantities greater than zero:

SELECT sname
FROM supplier
WHERE EXISTS
  (SELECT sno
  FROM partsupp
  WHERE qty > 0)
Parent topic: Nested Queries


Multiple Level Nesting

Queries can be nested up to six levels. For example, retrieve all supplier names -- for suppliers who supply at least one red part -- can be written as the following two level nested query:

SELECT sname
FROM supplier
WHERE sno IN
  (SELECT sno
  FROM partsupp
  WHERE pno IN
    (SELECT pno
    FROM part
    WHERE color = "RED"))

Note that the parentheses around the subqueries are optional. The system first executes the lowest level query to find the part numbers of red parts. The next higher level query is then executed, which finds the supplier numbers for those red parts. Finally, the outer level query (or main query) retrieves the names of the red part suppliers.

Parent topic: Nested Queries


Correlated Subqueries

In all of the other nested query examples in this reference, the subqueries have been evaluated completely before performing the outer query. In some cases, however, it is necessary to test the subselect against each row in the outer query. This type of query is known as a correlatedsubquery.

The correlated subquery is executed once for each row retrieved by the outer query. One or more tables in the outer level query are given a correlation name, which is used to prefix the correlated columns located in the subqueries. The correlation name is an alternate name that is defined immediately after the corresponding table name or view name in the SELECT statement of the outer level query.

One common use of correlated subqueries is to test for existence. The following query first performs the subquery to qualify each SUPPLIER table record by testing whether or not there is a part made in the city where the supplier is located:

SELECT *
FROM supplier x
WHERE EXISTS
  (SELECT *
  FROM part
  WHERE city = x.city)

The correlation name "x" tells the system that the column name "x.city" is actually referring to the CITY column of the SUPPLIER table that appears in the outer level query. The results of this query are as follows:

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S2 | JONES | 10 | PARIS
S3 | BLAKE | 30 | PARIS
S4 | CLARK | 20 | LONDON

The next sample query finds all employees with a pay rate greater than the average pay rate for the department they work in:

SELECT dept, fname, lname, payrate
FROM employee e
WHERE payrate >
  (SELECT AVG(payrate)
  FROM employee
    WHERE dept = e.dept)

In this example, both the inner and outer SELECT command statements query the EMPLOYEE table. The correlation name "e" tells the system that the column name "e.dept" comes from the outer level EMPLOYEE table.

Parent topic: Nested Queries


GROUP BY Clause

When a query statement includes a GROUP BY clause, the SELECT clause for that query may list (in addition to ordinary column names) one or more aggregate functions (SUM, COUNT, AVG, etc.) operating on groups of data values in other columns.

The GROUP BY clause contains a column-list argument that must include all simple column names that appear in the SELECT clause. Columns can also be named using the AS Clause (see SELECT Clause). Simple column names are called grouping columns, since they group together records with identical data in that column. This record grouping allows mathematical operations to be performed on the other columns specified as arguments in the aggregate functions. Records can also be grouped by any valid expression appearing in the SELECT clause argument. In these cases, the expression must also be referenced in the GROUP BY clause by a whole number representing its relative column position in the SELECT clause (or output result).

Syntax

The GROUP BY clause format appears below:

GROUP BY column-list

where:

column-list Consists of an ordered list of column names or numbers, separated by commas.
  • GROUP BY Example
Parent topic: WHERE Clause Syntax and Description


GROUP BY Example

The following query uses functions to produce three output columns in the query results. The query calculates the number of parts made in each city, and the maximum and minimum weight of those parts (in each city):

SELECT city, COUNT(*), MIN(weight), MAX(weight)
FROM part
  GROUP BY city

The query results are as follows:

city | count(*) | min(weight) | max(weight)
LONDON | 3 | 12 | 19
PARIS | 3 | 12 | 17

The next example (not available in DB2 mode) finds the number of orders placed each month, grouping the results by the first output column:

SELECT XMONTH(o_date), COUNT(*)
FROM orders
  GROUP BY 1

The query results are as follows:

column1 | count(*)
9 | 1
10 | 4
Parent topic: GROUP BY Clause


HAVING Clause

Commonly used in conjunction with the GROUP BY clause, the HAVING clause qualifies aggregate record group results that appear in the query output.

The optional HAVING clause is used to qualify groups of records within a query result, and requires the use of aggregate functions. HAVING can be used with or without a GROUP BY clause. If no GROUP BY clause is specified, the SELECT clause in the query statement may only list aggregate functions -- in which case the conditions specified in the HAVING clause are applied to each aggregate group value. Each item in the search-condition must compare one aggregate property of a group with a constant, expression, nested query result, or another aggregate property of the same group. Nested queries are permitted within a HAVING clause.

Syntax

The HAVING clause format appears below:

HAVING search-condition

where:

search-condition A set of one or more conditions that group values must satisfy in order to qualify for retrieval.
  • HAVING Example
Parent topic: WHERE Clause Syntax and Description


HAVING Example

The following sample query finds the average quantity of parts supplied for any part distributed by more than one supplier:

SELECT pno, AVG(qty)
FROM partsupp
  GROUP BY pno
  HAVING COUNT(*) >= 2

The query results appear as follows:

pno | AVG(qty)
P1 | 300
P2 | 250
P4 | 250
P5 | 250

The aggregate property evaluated in a HAVING clause may be an expression involving another aggregate function. Aggregate functions in HAVING clauses are demonstrated in the following query:

SELECT pno, AVG(qty)
FROM partsupp
  GROUP BY pno
  HAVING AVG(qty) * 2 > COUNT(*) * 200

The test condition in a HAVING clause may also include nested queries, as illustrated in the following query:

SELECT pno, AVG(qty)
FROM partsupp
GROUP BY pno
  HAVING AVG(qty) * 2 >
    (SELECT qty
    FROM partsupp
    WHERE pno = "P2"
      AND sno = "S2")
Parent topic: HAVING Clause


OPTIMIZE FOR Clause

This optional clause for a SELECT statement is currently syntactically supported only by the XDB Server. It may appear before or after any accompanying FOR FETCH ONLY clause.

On mainframe DB2 systems, the OPTIMIZE FOR clause allows you to specify how many retrieved rows are to be used when optimizing. If no row limit is specified with the OPTIMIZE FOR clause, the system optimizes according to the total number of rows actually fetched. If more rows are fetched than are specified in this clause, performance could degrade. If the same number or fewer rows are fetched than are specified in this clause, performance should improve. The OPTIMIZE FOR clause does not alter the result table or the order in which the rows are fetched.

Syntax

The OPTIMIZE FOR clause format appears below:

OPTIMIZE FOR integer { ROW | ROWS }

where:

integer Identifies the number of rows expected to be retrieved from the cursor.

See also the OPTIMIZE directive in the precompiler manual for your compiler, and the OPTIMIZE FOR clause under the SELECT command in SQL Commands.

Parent topic: WHERE Clause Syntax and Description


ORDER BY Clause

The ORDER BY clause specifies the order of rows retrieved by a fullselect. It sorts the rows of a query result according to the data values contained in a sort column (or columns). Sort columns are specified in the ORDER BY clause using either column names or column numbers separated by commas. Columns can also be named using the AS Clause (see SELECT Clause). The first column specified in the ORDER BY clause is the primary sort column. Output rows are ordered first according to the value in the primary sort column. If duplicate values occur in the primary sort column, the secondary sort column values are used to provide the final ordering.

The actual row order of the results depends on the data type of the column being sorted. Character columns are ordered according to the sort sequence specified during installation of the XDB Server (the default is a case insensitive ASCII sequence). Optional ordering parameters ASC (ascending) and DESC (descending) may be specified for each sort column.

When appearing in an SQL query statement, the ORDER BY clause is always the very last clause in the statement. Only one ORDER BY clause is permitted per query. ORDER BY clauses are not permitted in queries used to define views.

Please note that the ORDER BY clause only sorts the row output of query results, not the rows of the base table. To physically sort rows of data values in a base table, issue a CREATE table statement (with the same column configuration as the original table) combined with a SELECT query and ORDER BY clause. This single SQL command statement reproduces the original base table with the rows arranged according to the ORDER BY clause. The original base table remains unchanged.

Syntax

The ORDER BY clause format appears below:

ORDER BY sort-list

where:

sort-list Identifies up to 750 sort column names or numbers. The row order of query results can then be arranged according to the values of the sort column (or columns). Items in the sort list must be separated by commas, and may include an ordering parameter -- ASC (ascending) and DESC (descending) -- for each column name in the list. The default ordering parameter is ASC.
  • ORDER BY Example
Parent topic: WHERE Clause Syntax and Description


ORDER BY Example

In the following sample query, the retrieved rows are first ordered by supplier number, and then by descending part number order -- within the same supplier number grouping.

SELECT sno, pno, qty
FROM partsupp
  ORDER BY sno, pno DESC

The query results are as follows:

sno | pno | qty
S1 | P6 | 100
S1 | P5 | 100
S1 | P4 | 200
S1 | P3 | 400
S1 | P2 | 200
S1 | P1 | 300
S2 | P2 | 400
S2 | P1 | 300
S3 | P2 | 200
S4 | P5 | 400
S4 | P4 | 300
S4 | P2 | 200
Parent topic: ORDER BY Clause


FOR UPDATE OF Clause

The FOR UPDATE OF clause identifies the columns that can be updated in a later positioned UPDATE statement. It restricts the table columns that can be updated to those specified in the column-name list. These column names must be defined for the table or view appearing in the first FROM clause of the fullselect, and must not be qualified. FOR UPDATE OF cannot be used if the result table is read-only, nor can it be used in a statement containing a FOR FETCH ONLY clause.

Syntax

The FOR UPDATE OF clause format appears below:

FOR UPDATE OF column-name[,...]

where:

column-name An unqualified column name that must be a column of the table or view identified in the first FROM clause of the fullselect.
  • FOR UPDATE OF Examples
Parent topic: WHERE Clause Syntax and Description


FOR UPDATE OF Examples

The following sample query changes salaries, bonuses, and commissions in a hypothetical table named earnings. These changes are accomplished with positioned updates using a cursor named alter_up, and are limited to departments A1 and H12.

EXEC SQL DECLARE alter_up CURSOR FOR
  SELECT dept, empno, salary, bonus, comm
  FROM earnings
  WHERE dept IN ('A1','H12')
  FOR UPDATE OF salary, bonus, comm

The columns to be updated are indicated in the FOR UPDATE OF clause in the cursor declaration.

Parent topic: FOR UPDATE OF Clause


UNION Clause

The UNION clause combines the results of two or more subselects into a single output. It combines the output of from 2 through 33 subselect statements into a single result. The actual number of subselect results that can be attached with UNION clauses depends on the complexity of the queries, and the number of other queries open at the time of execution. The data types and lengths of each column in any two subselect tables must be identical in order for query results to be merged. The column names displayed in the result are taken from the first subselect table. When processing the subqueries of a UNION clause, the XDB Server removes duplicate rows (unless UNION ALL is specified).

Syntax

The format for UNION clause queries appears below:

subselect [(fullselect)]
  [UNION | UNION ALL]
  [subselect [(fullselect)]]

where:

subselect | Components referring to any valid subselect.
ALL | Causes duplicate rows to be included in the output results.
  • Example: UNION Clause
Parent topic: WHERE Clause Syntax and Description


Example: UNION Clause

The following query retrieves the supplier numbers for all suppliers having a status equal to 30 or more, and then appends to this result the numbers of suppliers who carry green parts.

SELECT sno
FROM supplier
WHERE status >= 30
  UNION
SELECT sno
FROM part p, partsupp ps
WHERE p.pno = ps.pno
  AND p.color = "GREEN"

This query yields the results shown below. Notice that duplicate rows have been omitted from the result since UNION ALL was not specified:

sno
S1
S2
S3
S4
S5

If an ORDER BY clause is used to sort the combined row results of a UNION query, the ORDER BY clause must specify the number of an output column on which to sort the combined output. The first query output column listed in the SELECT clause is column 1, the second column 2, etc.

Also notice in the following sample query how the string "Part" is padded with spaces to make it the same length as the "Supplier" string. Output columns combined with a UNION clause must be of the same data type and character width.

SELECT "Part    ", pno, "Made in England   "
FROM part
WHERE city = "LONDON"
  UNION
SELECT "Supplier", sno, "Located in England"
FROM supplier
WHERE city = "LONDON"
  ORDER BY 2 DESC

The result of this query is:

column1 | pno | column3
Supplier | S4 | Located in England
Supplier | S1 | Located in England
Part | P6 | Made in England
Part | P4 | Made in England
Part | P1 | Made in England

In the final sample query below, two corresponding columns of two hypothetical tables, PART_ON_HAND and PART_ON_ORDER are both defined as Total_Value by the AS clause.

SELECT 'Available', partnum,
  q_on_hn * price AS Total_Value
  FROM part_on_hand
UNION ALL
SELECT 'On Order', partnum,
  q_on_ord * price AS Total_Value
  FROM part_on_order
ORDER BY partno, Total_Value

The corresponding column of the union of the two tables is also named Total_Value, even though it is the result of derived columns.

Parent topic: UNION Clause


Functions Overview

A function is a syntactic structure that returns a value derived from applying the function to its arguments. The XDB Server provides standard SQL functions, including SUM, MIN, MAX, COUNT, and AVG, as well as XDB Server-specific extensions, which usually begin with an "X".

Functions are frequently used in the SELECT clause and WHERE clause of SELECT commands, as well as in the WHERE clause of UPDATE and DELETE commands. Functions may also appear in HAVING clauses. Their use is not limited to these cases, however. For example, functions that involve arguments that can be evaluated as constants can be used in the VALUES clause of INSERT commands.

For maximum flexibility, many of the functions can be nested within one another. In addition, functions can make use of the special keywords (for example, CURRENT DATE, CURRENT TIME).

  • Compatibility Modes
  • Recursive Inference Functions
  • Aggregate Functions
  • Date And Time Functions (XDB Mode)
  • Date And Time Functions (DB2 Mode)
  • Date/Time Arithmetic
  • Numeric Functions
  • String Functions
Parent topic: SQL Reference


Compatibility Modes

The XDB Server functions which are provided in addition to the standard SQL functions are normally available only when running in XDB mode. Check the following table or check the mode key below each function name. A diamond character (X) means the function is supported in that mode. The SQL compatibility mode can be set in your client configuration or with the SET COMPATIBILITY command.

 | ANSI | DB2 | XDB
AGE |  |  | X
ASCII |  |  | X
AVG | X | X | X
CEILING |  |  | X
CHAR |  | X | X
CHR |  |  | X
COUNT | X | X | X
DATE |  | X | X
DAY |  | X | X
DAYOFYEAR |  |  | X
DAYS |  | X | X
DECIMAL |  | X | X
DIGITS |  | X | X
FACTORIAL |  |  | X
FINDANY |  |  | X
FINDNOTIN |  |  | X
FINDSTR |  |  | X
FLOAT |  | X | X
FLOOR |  |  | X
HEX |  | X | X
HOUR |  | X | X
INITCAP |  |  | X
INTEGER |  | X | X
LENGTH |  | X | X
LEVEL |  |  | X
LTRIM |  |  | X
MAX | X | X | X
MICROSECOND |  | X | X
MIN | X | X | X
MINUTE |  | X | X
MOD |  |  | X
MONTH |  | X | X
MONTHBEG |  |  | X
MONTHSBTWN |  |  | X
NULLIF | X | X | X
PI |  |  | X
PREVIOUS |  |  | X
QUARTER |  |  | X
QUARTERBEG |  |  | X
REPLICATE |  |  | X
REVCHAR |  |  | X
ROUND |  |  | X
RTRIM |  |  | X
SECOND |  | X | X
SIGN |  |  | X
STRIP |  | X | X
SUBSTR |  | X | X
SUM | X | X | X
TIME |  | X | X
TIMESTAMP |  | X | X
TODAY |  |  | X
TRUNCATE |  |  | X
VALUE |  | X | X
WEEKDAY |  |  | X
WEEKOFYEAR |  |  | X
WEEKSBTWN |  |  | X
XABS |  |  | X
XCONCAT |  |  | X
XDATE |  |  | X
XEXP |  |  | X
XLEFT |  |  | X
XLN |  |  | X
XLOG |  |  | X
XLOWER |  |  | X
XPOWER |  |  | X
XRIGHT |  |  | X
XSQRT |  |  | X
XSTDDEV |  |  | X
XTRIM |  |  | X
XUPPER |  |  | X
XVAR |  |  | X
YEAR |  | X | X
YEARBEG |  |  | X
Parent topic: Functions Overview


Recursive Inference Functions

Recursive inference is the process of using data already found in a table to infer a relationship with other, related column data (not available in DB2 mode). Recursive inference is frequently used in solving parts assembly problems or the classic "bill-of-materials" problem.

The LEVEL condition is normally used in conjunction with the PREVIOUS function in queries to implement recursive inference. It could be helpful to first read the PREVIOUS function description, before returning to the LEVEL condition description below.

More:

  • LEVEL
  • PREVIOUS
  • LEVEL
  • PREVIOUS
Parent topic: Functions Overview


LEVEL

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The LEVEL condition may be used in conjunction with each PREVIOUS function to qualify the result on the basis of the number of recursions performed. Any of the operators =, <, <=, >, >=, != or ^= may be used in the LEVEL condition, and the right hand side may be either a positive integer (level numbers begin with 0) or the keyword BOTTOM, which indicates the bottom level of each of the recursive branches constructed by the PREVIOUS function.

All other search conditions (except those applied by GROUP BY and HAVING clauses) are applied to the original table before the recursion is performed. After the table has been "exploded" GROUP BY, HAVING and ORDER BY clauses are applied.

For example, if you wanted to know only the second level subparts used in making product P11 (see PREVIOUS function), you could execute the following query. Note that level numbers begin with 0, therefore the second level is level 1.

SELECT subpart
FROM subpart
WHERE product = PREVIOUS(subpart)
  AND LEVEL = 1
  AND product = "P11"

The result of this query is:

subpart
P5
P7
P8
P1
P2

For a graphic depiction of the various levels of recursive inference in the above example, see the figure in the PREVIOUS function description.

Parent topic: Recursive Inference Functions


PREVIOUS

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The PREVIOUS function (XDB mode only) is used in combination with the LEVEL condition to give queries recursive inference capabilities. One PREVIOUS function is permitted per subselect.

The SUBPART table contains the following records:

product | subpart | qty
P7 | P1 | 2
P7 | P2 | 4
P7 | P6 | 6
P8 | P4 | 8
P8 | P7 | 1
P9 | P5 | 3
P9 | P7 | 5
P9 | P8 | 7
P10 | P1 | 9
P10 | P2 | 1
P11 | P9 | 2
P11 | P10 | 3

The SUBPART column lists the part numbers of all subparts used in assembling a complete product, while the part numbers of all products that contain the assembled subparts appear in the PRODUCT column. For instance, product P8 is made up of subparts P4 and P7. However, since product P7 is also made up of subparts P1, P2 and P6, we can infer that subparts P1, P2 and P6 are also required by a completed product P8. Standard SQL cannot easily detect interrelationships between products and subparts in this table.

The following query uses the PREVIOUS function to determine all the subparts which go into the making of a single product P11.

SELECT subpart
FROM subpart
WHERE product = PREVIOUS(subpart)
  AND LEVEL = BOTTOM
  AND product = "P11"

The PREVIOUS function (in combination with the LEVEL condition) uses recursive inference to "explode" the data in the SUBPART column (see the following figure) to match each product with all the subparts required for its assembly.

See the description of the LEVEL condition for a discussion of the BOTTOM keyword. In the example above, BOTTOM causes only the "bottom" level of subpart numbers (only those subparts that are not themselves composed of other subparts) contained in each recursive branch of the figure to appear in the result.

Parent topic: Recursive Inference Functions


Aggregate Functions

The XDB Server supports a number of aggregate functions that are used with the SELECT command to operate on the values from a specified column. The column-name that follows the function must be enclosed in parentheses. The result of an aggregate function is a single value for every group in the query result. If the query result is not grouped, the entire result is treated as a single group, and the result of an aggregate function is a single value.

More:

  • AVG
  • COUNT
  • MAX
  • MIN
  • SUM
  • XSTDDEV
  • XVAR
  • Example: Aggregate Functions
  • AVG
  • COUNT
  • MAX
  • MIN
  • SUM
  • XSTDDEV
  • XVAR
  • Example: Aggregate Functions
Parent topic: Functions Overview


AVG

ANSI | DB2 | SQL/DS | XDB
X | X | X | X

Averages the values in each group of a column. This function is for numeric fields only. Null values will be ignored. The format appears below:

AVG([DISTINCT]x)

where the parameter x is a numeric field. Note that in DB2 mode, performing an AVG on data of type integer or data of type small integer gives a result of an integer with decimal places truncated.

Parent topic: Aggregate Functions


COUNT

ANSI | DB2 | SQL/DS | XDB
X | X | X | X

COUNT is a standard SQL function that counts the number of records in each group satisfying the condition(s) specified. COUNT(*) returns the number of rows in the table.

For all modes except DB2 mode, the formats below return the number of non-NULL values in column-name or expression:

COUNT(column-name)

or:

COUNT(expression)

Allowable formats for all modes appear below:

COUNT(*)

or:

COUNT(DISTINCT expression)

which filters out duplicate values to return the number of distinct values in expression. For example, to discover how many suppliers are currently supplying parts, you could use the query:

SELECT COUNT(DISTINCT sno)
FROM partsupp
Parent topic: Aggregate Functions


MAX

ANSI | DB2 | SQL/DS | XDB
X | X | X | X

Selects the maximum value in each group of a column. Null values will be ignored. The format appears below:

MAX([DISTINCT]x)

where the parameter x is a column name.

Parent topic: Aggregate Functions


MIN

ANSI | DB2 | SQL/DS | XDB
à | à | à | à

Selects the minimum value for each group of a column. Null values will be ignored. The format appears below:

MIN([DISTINCT]x)

where the parameter x is a column name.

Note:

The DISTINCT keyword is ignored in the MAX and MIN functions.

Parent topic: Aggregate Functions


SUM

ANSI | DB2 | SQL/DS | XDB
X | X | X | X

Adds up all the values in each group of a column. Null values will be ignored. The format appears below:

SUM([DISTINCT] x)

where the parameter x is a numeric field or expression, and the keyword DISTINCT is used to filter out duplicate values prior to summing. Note that DISTINCT can be used with either a column name or an expression.

Parent topic: Aggregate Functions


XSTDDEV

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

An XDB Server statistical function for finding the standard deviation of a column. Null values are ignored. The format appears below:

XSTDDEV(x)

where the parameter x is a numeric column.

Note that XSTDDEV(x) is the same as (XVAR(x))E+1/2. The formula used for computing standard deviation is:

Formula for standard deviation

Parent topic: Aggregate Functions


XVAR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

An XDB Server statistical function used for finding the variance of a column of data. The format appears below:

XVAR(x)

where x is a column name. The parameter x must be a numeric field.

Note that XVAR(x) is the same as (XSTDDEV(x))E+2. The formula used for computing variance is:

Formula for variance

Parent topic: Aggregate Functions


Example: Aggregate Functions

All of the aggregate functions are applied only to the set of records retrieved by the SELECT command. Examples of each of the functions are given below.

To find the number of "CAM" parts in the table, enter:

SELECT COUNT(pno) FROM part
WHERE pname = "CAM"

The result is 2. To find the total quantity of P2 supplied, enter:

SELECT SUM(qty) FROM partsupp
WHERE pno = "P2"

The result is 1000. To find the weight of the heaviest part, enter:

SELECT MAX(weight) FROM part

More than one function can be used in a command, as in the query:

SELECT COUNT(pno), AVG(weight), MIN(weight),
  MAX(weight), XSTDDEV(weight)
FROM part

Commands containing both an aggregate function and a simple field-name are not allowed unless the result is grouped by the simple field. For example, the following query is illegal:

SELECT SUM(qty), pno
FROM partsupp

To correct it, add a GROUP BY clause, as shown below:

SELECT SUM(qty), pno
  FROM partsupp
  GROUP BY pno

The next example finds the average weight, and number of parts for every part color that has two or more parts, and displays them in color order.

SELECT color, AVG(weight), COUNT(*)
  FROM part
  GROUP BY color
    HAVING COUNT(*) >= 2
  ORDER BY color

The result is:

color | avg(wt) | count(*)
BLUE | 12 | 2
RED | 15 | 3
Parent topic: Aggregate Functions


Date And Time Functions (XDB Mode)

Date calculations are fully supported in XDB mode using the following date, time and timestamp functions. The XDB Server also supports date-time arithmetic in XDB mode and DB2 mode, although the results in DB2 mode are different. The expressions and functions documented in this topic can appear in a SELECT or WHERE clause any place a column name for the appropriate column type might appear. Date functions operate on dates between 1/1/0001 and 12/31/9999. Historical dates may differ from the dates under the Gregorian calendar used.

More:

  • AGE
  • CHAR
  • DATE
  • DAY
  • DAYOFYEAR
  • DAYS
  • HOUR
  • MICROSECOND
  • MINUTE
  • MONTH
  • MONTHBEG
  • MONTHSBTWN
  • QUARTER
  • QUARTERBEG
  • SECOND
  • TIME
  • TIMESTAMP
  • TODAY
  • WEEKDAY
  • WEEKOFYEAR
  • WEEKSBTWN
  • YEAR
  • YEARBEG
  • XDATE
  • AGE
  • CHAR
  • DATE
  • DAY
  • DAYOFYEAR
  • DAYS
  • HOUR
  • MICROSECOND
  • MINUTE
  • MONTH
  • MONTHBEG
  • MONTHSBTWN
  • QUARTER
  • QUARTERBEG
  • SECOND
  • TIME
  • TIMESTAMP
  • TODAY
  • WEEKDAY
  • WEEKOFYEAR
  • WEEKSBTWN
  • YEAR
  • YEARBEG
  • XDATE
Parent topic: Functions Overview


AGE

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Calculates the difference in years between date1 and date2. The format appears below:

AGE(date1, date2)

For example, the query below retrieves the names of tasks begun less than 5 years as of TODAY:

SELECT task_name FROM tasks
WHERE AGE(startdate, TODAY) < 5

The AGE function also has a single parameter format that calculates the difference in years between today's date and date1. The format appears below:

AGE(date1)

The following query finds the age of each employee in the EMPLOYEE table.

SELECT lname, AGE(birth)
FROM employee
Parent topic: Date And Time Functions (XDB Mode)


CHAR

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The CHAR function can take a mask (XDB mode only) as an optional second parameter. The format appears below:

CHAR(date[,mask])

The parameter mask must be a quoted string that contains a mask for a date or a time, based on existing masking rules.

For example:

SELECT CHAR(datefld, "www") FROM datetable

will give the day of the week (for example, "MON"). For more information on masks, see the SQLWizard User's Guide and the Options User's Guide.

Parent topic: Date And Time Functions (XDB Mode)


DATE

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The DATE function is used to convert a value into a date. The format appears below:

DATE(expres)

The parameter expres can be a character string, a timestamp, a date, a positive number less than 3,652,059, or a null value. If expres is a date, the result is the date. If expres is a timestamp, the result is the date portion of the timestamp. If expres is a character string, it must be in one of the following formats that XDB Server recognizes:

yyyy-mm-dd | ISO or JIS format.
mm/dd/yyyy | USA format.
dd.mm.yyyy | EUR format.

If expres is a number, the result is the number of days since January 1, 0001 (including January 1, 0001). An example of the DATE function is:

UPDATE orders
  SET o_date = DATE("1989245")
  WHERE o_no = 5
Parent topic: Date And Time Functions (XDB Mode)


DAY

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The DAY function (also XDAY) extracts the day of the month from a date or timestamp. The format appears below:

DAY(date-expr)

The following query finds the quantity of parts ordered on the first day of the month:

SELECT p_no, SUM(quantity)
  FROM orders, items
  WHERE DAY(o_date) = 1
  GROUP BY p_no
Parent topic: Date And Time Functions (XDB Mode)


DAYOFYEAR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The DAYOFYEAR function give the number of days (1-366) since the beginning of the year for specified date (a.k.a. Julian date). The format appears below:

DAYOFYEAR(date)

For example:

DAYOFYEAR(06/21/1991) = 173
Parent topic: Date And Time Functions (XDB Mode)


DAYS

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The DAYS function is used to obtain an integer that corresponds to the number of days between January 1, 0001 and the date in date-expr (including January 1, 0001). The format appears below:

DAYS(date-expr)

The parameter date_expr can be a date, timestamp, or a valid string representation of a date. An example is:

SELECT DAYS(TODAY) - DAYS(o_date)
FROM orders
Parent topic: Date And Time Functions (XDB Mode)


HOUR

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The HOUR function is used to extract the hour part of a time or timestamp. The result is an integer between 0 and 24 (or null if time-expr evaluates to a null value). The format appears below:

HOUR(time-expr)

For example:

SELECT HOUR(starttime)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


MICROSECOND

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function is used to extract the microsecond part of a timestamp. The result is an integer between 0 and 999999 (or null if time-expr evaluates to a null value). The format appears below:

MICROSECOND(time-expr)

For example:

SELECT MICROSECOND(audit_time)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


MINUTE

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function is used to extract the minute part of a time or timestamp. The result is an integer between 0 and 59 (or null if time-expr evaluates to a null value).

The format appears below:

MINUTE(time-expr)

For example:

SELECT MINUTE(endtime)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


MONTH

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function (also XMONTH) extracts the month from a date or timestamp. The format appears below:

MONTH(date-expr)

For example, a query lists the quantity of parts ordered in January:

SELECT p_no, SUM(quantity)
  FROM orders
  WHERE MONTH(o_date) = 1
  GROUP BY p_no
Parent topic: Date And Time Functions (XDB Mode)


MONTHBEG

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to extract the first day of the month the date resides in. The format appears below:

MONTHBEG(date)

For example:

MONTHBEG(2/14/1991) = 2/1/1991
Parent topic: Date And Time Functions (XDB Mode)


MONTHSBTWN

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the difference between dates in months. The format appears below:

MONTHSBTWN(date1,date2)

For example:

MONTHSBTWN(07/24/1991,10/13/1991) = 3
Parent topic: Date And Time Functions (XDB Mode)


QUARTER

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the numeric value (1-4) of the quarter in which the date resides. The format appears below:

QUARTER(date)

For example:

QUARTER(2/14/1991) = 1
QUARTER(5/14/1991) = 2
Parent topic: Date And Time Functions (XDB Mode)


QUARTERBEG

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the date of the first day of the quarter in which the date resides. The format appears below:

QUARTERBEG(date)

For example:

QUARTERBEG(2/14/1991) = 1/1/1991
QUARTERBEG(5/14/1991) = 4/1/1991
Parent topic: Date And Time Functions (XDB Mode)


SECOND

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function is used to extract the seconds part of a time or timestamp. The result is an integer between 0 and 59 (or null if time-expr evaluates to a null value). The format appears below:

SECOND(time-expr)

For example:

SELECT SECOND(endtime)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


TIME

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The TIME function is used to convert a value into a time. The format appears below:

TIME(expres)

The parameter expres can be a character string, a timestamp, a time, or a null value. If expres is a time, the result is the time. If expres is null, the result is the null value. If expres is a timestamp, the result is the time portion of the timestamp. If expres is a character string, it must be in one of the following formats that XDB Server recognizes:

hh.mm.ss | ISO, EUR or JIS format
hh:mm: AM | PM | USA format

For example:

UPDATE tasks
SET endtime = TIME(audit_time)
Parent topic: Date And Time Functions (XDB Mode)


TIMESTAMP

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The TIMESTAMP function is used to generate a timestamp. The format appears below:

TIMESTAMP(expres1 [, expres2])

If only one argument is specified, expres1 can be a timestamp or a valid string representation of a timestamp. If two arguments are specified, expres1 must be a date or date string, and expres2 must be a time or time string. If any argument that can be null is null, the result is null.

For example:

UPDATE task
SET audit_time = TIMESTAMP(startdate, starttime)
Parent topic: Date And Time Functions (XDB Mode)


TODAY

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The XDB Server recognizes the keyword TODAY as a reserved name for the current date (data type is date). For compliance with DB2, the XDB Server also recognizes CURRENT DATE as being the same as TODAY within SQL. The XDB Server recognizes the keyword XTIME as a reserved name for the current time (data type is time). For compliance with DB2, The XDB Server also recognizes CURRENT TIME as being the same as XTIME within the SQL Language.

Parent topic: Date And Time Functions (XDB Mode)


WEEKDAY

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to extract the numeric value (1-7) of the day of the week. The format appears below:

WEEKDAY(date)

For example:

WEEKDAY(tuesday) = 2
Parent topic: Date And Time Functions (XDB Mode)


WEEKOFYEAR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the number of weeks (1-53) since the beginning of the year for the specified date. The format appears below:

WEEKOFYEAR(date)

The number of weeks is determined by the number of Sundays. The function starts at week one and adds a week every time a Sunday occurs. For example, if January 6, 1991, is a Sunday:

WEEKOFYEAR(1/5/1991) = 1
WEEKOFYEAR(1/6/1991) = 2
WEEKOFYEAR(1/7/1991) = 2
Parent topic: Date And Time Functions (XDB Mode)


WEEKSBTWN

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the difference between dates in weeks. The format appears below:

WEEKSBTWN(date1, date2)

The difference in weeks is determined by the number of Sundays between the two dates, including the first date but not the second. For example, if January sixth is a Sunday, and January thirteenth is a Sunday:

WEEKSBTWN(01/06/1991, 01/13/1991) = 1
Parent topic: Date And Time Functions (XDB Mode)


YEAR

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The YEAR function (also XYEAR, XDB mode only) extracts the year from a date or timestamp. The format appears below:

YEAR(date-expr)

For example, the following query finds all employees born the same year as employee Smith:

SELECT lname FROM bdaylist
WHERE YEAR(birth) IN
  (SELECT YEAR(birth) FROM bdaylist
  WHERE lname = "SMITH")
Parent topic: Date And Time Functions (XDB Mode)


YEARBEG

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to extract the date of the first day of the year in which the date resides. The format appears below:

YEARBEG(date)

For example:

YEARBEG(2/14/1991) = 1/1/1991
Parent topic: Date And Time Functions (XDB Mode)


XDATE

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The XDATE function takes 3 integers and converts them into a date. The format appears below:

XDATE(m, d, y)

The m parameter is an expression that evaluates to an integer representing a month of the year (1-12). The d parameter is an expression that evaluates to an integer representing a day of the month (1-31). The y parameter is an expression that evaluates to an integer representing a year. For example, the following command creates an employee birthday calendar for the current year.

SELECT "Birthday for", fname, lname,"is",
  XDATE(XMONTH(birth), XDAY(birth), XYEAR(TODAY))
FROM bdaylist
Parent topic: Date And Time Functions (XDB Mode)


Date And Time Functions (DB2 Mode)

XDB Server's Date and Time arithmetic functions have been enhanced to provide full DB2 compatibility when operating in DB2 mode. Included are addition and subtraction of date and time field values as well as durations. When operating in XDB mode, arithmetic operations on dates and times are calculated as explained in the Date And Time Functions (XDB mode) section.

SQL Compatibility Mode is set either in the client configuration or by issuing a SET COMPATIBILITY command. Consult your DB2 documentation for further information on date/time functions and expressions.

Date-Time arithmetic under DB2 mode can involve date, time and timestamp field values or durations. The types of durations supported when running in DB2 mode are:

More:

  • Labeled Duration
  • Date Duration
  • Time Duration
  • Timestamp Duration
  • Labeled Duration
  • Date Duration
  • Time Duration
  • Timestamp Duration
Parent topic: Functions Overview


Labeled Duration

This type of duration represents a specific unit of time as expressed by a number followed by one of the following keywords:

YEAR | YEARS
MONTH | MONTHS
DAY | DAYS
HOUR | HOURS
MINUTE | MINUTES
SECOND | SECONDS
MICROSECOND | MICROSECONDS

The value of the labeled duration can be the result of an expression. It is treated as a DECIMAL(15,0) number. To use a labeled duration in a date-time computation, the other arithmetic operator must be a DATE, TIME or TIMESTAMP data field. Consider the following expression examples where ORDERDATE is a date field being added to two labeled durations (2 MONTHS and 14 DAYS).

ORDERDATE + 2 MONTHS + 14 DAYS
This is a valid entry because the expression is resolved from left to right, with ORDERDATE + 2 MONTHS yielding a DATE. The labeled duration 14 DAYS is then added to the new DATE. This expression is the same as (ORDERDATE + 2 MONTHS) + 14 DAYS.
ORDERDATE + (2 MONTHS + 14 DAYS)
This is not a valid entry because a labeled duration cannot be added to another labeled duration (2 MONTHS cannot be added to 14 DAYS).
Parent topic: Date And Time Functions (DB2 Mode)


Date Duration

In DB2 mode, this type of duration represents a number of years, months or days expressed as a DECIMAL(8,0) number (in XDB mode the number is expressed in days). The number must have the format YYYYMMDD. For example, the result of subtracting one DATE value from another (such as SHIPDATE-ORDERDATE) is a date duration (in XDB mode the units of the result are days).

Parent topic: Date And Time Functions (DB2 Mode)


Time Duration

In DB2 mode, this type of duration represents a number of hours, minutes or seconds as expressed as a DECIMAL(6,0) number (in XDB mode the number is expressed in seconds). The number must have the format HHMMSS. For example, the result of subtracting one TIME value from another is a time duration.

Parent topic: Date And Time Functions (DB2 Mode)


Timestamp Duration

This duration is a DECIMAL(20,6) number that represents an interval of time. In DB2 mode and XDB Modes, the result of subtracting two TIMESTAMP values is a TIMESTAMP duration. The TIMESTAMP duration format yyyyxxddhhmmsszzzzzz defines the years (yyyy), months (xx), days (dd), hours (hh), minutes (mm), seconds (ss), and microseconds (zzzzzz) of the time interval.

Parent topic: Date And Time Functions (DB2 Mode)


Date/Time Arithmetic

If a date-time value is the operand of addition, the other operand must be a duration. The rules for subtracting are different because a date-time value cannot be subtracted from a duration, and subtracting two date-time values differs from subtracting a duration from a date-time value. The rules for date-time arithmetic are shown in the following table.

Addition Rules

If one operand is a... ...the other operand must be a...
Date
  • Date Duration
  • Labeled Duration of years, months or days
Time
  • Time Duration
  • Labeled Duration of hours, minutes or seconds
Timestamp
  • Timestamp Duration
  • Labeled Duration of years, months, days, hours, minutes or seconds

Subtraction Rules

If the FIRST operand is a... ...the SECOND operand must be a...
Date
  • Date
  • Date Duration
  • String representation of a date
  • Labeled duration of years, months or days
Time
  • Time
  • Time Duration
  • String representation of a time
  • Labeled duration of hours, minutes or seconds
Timestamp
  • Timestamp
  • Timestamp Duration
  • Date Duration
  • Time Duration
  • String representation of a timestamp
  • Labeled duration of years, months, days, hours, minutes or seconds
If the SECOND operand is a... ...the FIRST operand must be a...
Date
  • Date
  • String representation of a date
Time
  • Time
  • String representation of a time
Timestamp
  • Timestamp
  • String representation of a timestamp

More:

  • Subtracting Dates
  • Incrementing and Decrementing Dates
  • Subtracting Times
  • Incrementing and Decrementing Times
  • Subtracting Timestamps
  • Incrementing and Decrementing Timestamps
  • Examples: Date/Time Arithmetic
  • Subtracting Dates
  • Incrementing and Decrementing Dates
  • Subtracting Times
  • Incrementing and Decrementing Times
  • Subtracting Timestamps
  • Incrementing and Decrementing Timestamps
  • Examples: Date/Time Arithmetic
Parent topic: Functions Overview


Subtracting Dates

In DB2 mode, when one date is subtracted from another, the result is a date duration that indicates the number of years, months and days. For example, the result of:

DATE('2/25/2000') - '12/20/1999'

is 205 (duration of 0 years, 2 months and 5 days). The data type of the result is DECIMAL(8,0).

The rules that apply to the date subtraction calculation are as follows:

  • If DATE1 is greater than or equal to DATE2, then DATE2 is subtracted from DATE1.
  • If DATE1 is less than DATE2, DATE1 is subtracted from DATE2 and the result is negative.

Using the operation RESULT = DATE1 - DATE2, these rules can be illustrated as follows:

If  DAY(DATE2) <= DAY(DATE1)
  Then  DAY(RESULT) = DAY(DATE1) - DAY(DATE2)
If DAY(DATE2) > DAY(DATE1)
  Then  DAY(RESULT) = N + DAY(DATE1) - DAY(DATE2)
  Where  N is the last day of MONTH(DATE2)
  MONTH(DATE2) is then incremented by 1
If MONTH(DATE2) <= MONTH(DATE1)
  Then  MONTH(RESULT) = MONTH(DATE1) - MONTH(DATE2)
If MONTH(DATE2) > MONTH(DATE1)
  Then  MONTH(RESULT) =
        12 + MONTH(DATE1) - MONTH(DATE2)
  And  YEAR(DATE2) is incremented by 1
YEAR(RESULT) = YEAR(DATE1) - YEAR(DATE2)
Parent topic: Date/Time Arithmetic


Incrementing and Decrementing Dates

When adding durations to dates or subtracting durations from dates, the results are dates between January 1, 0001 and December 31, 9999.

  • Adding/Subtracting Years

    When a duration of years is added or subtracted, only the year portion of the date is affected (except for February 29). If the result of the calculation would be February 29 of a non-leap year, the day portion of the result is set to February twenty-eighth.

  • Adding/Subtracting Months

    When a duration of months is added or subtracted, the month is changed and if necessary, the year. The day portion of the date is changed only if the result would be an invalid date (such as September 31). In this case, the day is set to the last day of the month.

  • Adding/Subtracting Days

    When a duration of days is added or subtracted, the day will change and if necessary the month and year.

    Both positive and negative durations can be added or subtracted when working with date arithmetic. The sequence in which the date is incremented (or decremented) depends on the following:

    • When a positive date duration is added to a date or when a negative date duration is subtracted from a date, the date is incremented by the specified years, months and days in that order.

      For example, entering DATE1+x, where x is a positive decimal number, is equivalent to the expression:

      DATE1 + YEAR(x) YEARS + MONTH(x) MONTHS + DAY(x) DAYS
    • When a positive date duration is subtracted from a date or a negative date duration is added to a date, the date is decremented by the specified number of days, months and years in that order.

      For example, entering DATE1-x, where x is a positive decimal number, is equivalent to the expression:

      DATE1 - DAY(x) DAYS - MONTH(x) MONTHS - YEAR(x) YEARS
Parent topic: Date/Time Arithmetic


Subtracting Times

In DB2 mode, when one time is subtracted from another, the result is a time duration that indicates the number of hours, minutes and seconds between the two times. For example, the result of:

TIME('10:22:16') - '00:34:46'

is 94730, (duration of 9 hours, 47 minutes and 30 seconds). The data type of the result is DECIMAL(6,0).

The rules that apply to the time subtraction calculation are as follows:

  • If TIME1 is greater than or equal to TIME2, then TIME2 is subtracted from TIME1.
  • If TIME1 is less than TIME2, TIME1 is subtracted from TIME2 and the result is negative.

Using the operation RESULT = TIME1 - TIME2, these rules can be illustrated as follows:

If  SECOND(TIME2) <= SECOND(TIME1)
  Then  SECOND(RESULT) =
    SECOND(TIME1) - SECOND(TIME2)
If SECOND(TIME2) > SECOND(TIME1)
  Then  SECOND(RESULT) =
    60 + SECOND(TIME1) - SECOND(TIME2)
  And  MINUTE(TIME2) is then incremented by 1
If MINUTE(TIME2) <= MINUTE(TIME1)
  Then  MINUTE(RESULT) =
    MINUTE(TIME1) - MINUTE(TIME2)
If MINUTE(TIME2) > MINUTE(TIME1)
  Then  MINUTE(RESULT) =
    60 + MINUTE(TIME1) - MINUTE(TIME2)
  And  HOUR(TIME2) is incremented by 1
HOUR(RESULT) = HOUR(TIME1) - HOUR(TIME2)
Parent topic: Date/Time Arithmetic


Incrementing and Decrementing Times

When adding durations to times or subtracting durations from times, the results are always times. Overflow or underflow hours are discarded to ensure that the result is always a valid time.

When adding or subtracting hours, only the hours portion of the time is affected. Adding 24 hours to the time '00:00:00' results in the time '24:00:00' while adding 24 hours to any other time results in the same time (for example, adding 24 hours to the time '12:29:37' results in the time '12:29:37').

When adding or subtracting minutes, minutes are changed and if necessary, the hours are changed. The seconds do not change.

When adding or subtracting seconds, seconds are changed and if necessary, the minutes and hours are changed.

Both positive and negative time durations can be added or subtracted. The result is a time that has been incremented (or decremented) by the specified number of hours, minutes and seconds in that order. For example, entering TIME1+x, where x is a positive decimal number, is equivalent to the expression:

TIME1 + HOUR(x)HOURS + MINUTE(x)MINUTES
  + SECOND(x)SECONDS
Parent topic: Date/Time Arithmetic


Subtracting Timestamps

In DB2 mode and XDB mode, when one timestamp is subtracted from another, the result is a timestamp duration that indicates the number of years, months, days, hours, minutes, and seconds. The data type of the result is DECIMAL(20).

The rules that apply to timestamp subtraction are as follows:

  • If TIMESTAMP1 is greater than or equal to TIMESTAMP2, then TIMESTAMP2 is subtracted from TIMESTAMP1.
  • If TIMESTAMP1 is less than TIMESTAMP2, TIMESTAMP1 is subtracted from TIMESTAMP2 and the result is negative.

Using the operation RESULT = TS1 - TS2, these rules can be illustrated as follows:

If  MICROSECOND(TS2) <= MICROSECOND(TS1)
  Then  MICROSECOND(RESULT) = MICROSECOND(TS1) -
      MICROSECOND(TS2)
If  MICROSECOND(TS2) > MICROSECOND(TS1)
  Then  MICROSECOND(RESULT) = 1000000 +
      MICROSECOND(TS1) - MICROSECOND(TS2)
  And  SECOND(TS2) is incremented by 1
Note:

The rules for subtracting times determine how the time portions of the timestamps are subtracted.

If  HOUR(TS2) <= HOUR(TS1)
  Then  HOUR(RESULT) = HOUR(TS1) - HOUR(TS2)
If  HOUR(TS2) > HOUR(TS1)
  Then  HOUR(RESULT) = 24 + HOUR(TS1) - HOUR(TS2)
  And  DAY(TS2) is incremented by 1
Note:

The rules for subtracting dates determine how the date portions of the timestamps are subtracted.

Parent topic: Date/Time Arithmetic


Incrementing and Decrementing Timestamps

Adding a duration to a timestamp or subtracting a duration from a timestamp returns a timestamp -- while subtracting a timestamp from a timestamp returns a timestamp duration. An overflow or underflow of hours is carried into the date portion of the result.

Parent topic: Date/Time Arithmetic


Examples: Date/Time Arithmetic

The examples appearing below reference a table called tasks created with the following command:

CREATE TABLE tasks(task_no SMALLINT, task_name CHAR(10),
  est_hrs_reqd SMALLINT, startdate DATE, enddate
  DATE,starttime TIME, endtime TIME, audit_time
  TIMESTAMP)

date1-date2

In XDB mode, this expression calculates the difference in days between the two dates date1 and date2 (in DB2 mode, subtraction of two dates results in a date duration). As an example (using the TUTORIAL tables), the query below finds the number of orders placed for part P2 during the past 30 days:

SELECT SUM(quantity)
  FROM orders, items
  WHERE TODAY - o_date < 30

time1-time2

In XDB mode, this expression calculates the difference in seconds between the two times time1 and time2. To find the number of minutes, divide the difference between times by 60. To find the number of hours, divide the difference between times by 3600. For example, to find the total number of hours elapsed between the two stored time values starttime and endtime, you could use the query:

SELECT (endtime-starttime)/3600
FROM tasks
Note:

In DB2 mode the difference between two dates or times is expressed in Date/Time Duration values -- consisting of years/months/days or hours/minutes/seconds.

timestamp1-timestamp2

In XDB mode and DB2 mode, this expression calculates the difference between the two timestamps timestamp1 and timestamp2. This difference is expressed as a timestamp duration, where the format yyyyxxddhhmmsszzzzzz defines the years (yyyy), months (xx), days (dd), hours (hh), minutes (mm), seconds (ss), and microseconds (zzzzzz) of the timestamp duration.

time1 + n

In XDB mode, calculates the time generated by adding n seconds to time time1. The parameter n can be any expression that evaluates to a number. To add minutes to a time, multiply the number of minutes by 60. To add hours to a time, multiply the number of hours by 3600. For example, to find out what the estimated end time will be, given an estimated task time in hours, you could use the query:

SELECT "Estimated hours to completion: ",
  starttime + (est_hrs_reqd * )
FROM tasks
Note:

In DB2 mode, you must specify the duration type. For example, n SECONDS, n HOURS, and so on.

Parent topic: Date/Time Arithmetic


Numeric Functions

These functions can be used any place a numeric value is required. The parameters x and y can be any expression that evaluates to a number. Money fields can only be used in the FLOAT, INTEGER or XABS functions.

The operators +, -, /, and * are also available. In DB2 mode, integer division (/) results in an integer with decimal places truncated.

Note: DB2 truncates expression results. The XDB Server rounds. For example, if result type is 5,2 and expression value is 123.555, DB2 mode retrieves 123.55 while XDB mode retrieves 123.56.

More:

  • CEILING
  • DECIMAL
  • FACTORIAL
  • FLOAT
  • FLOOR
  • INTEGER
  • MOD
  • PI
  • ROUND
  • SIGN
  • TRUNCATE
  • XABS
  • XEXP
  • XLN
  • XLOG
  • XPOWER
  • XSQRT
  • CEILING
  • DECIMAL
  • FACTORIAL
  • FLOAT
  • FLOOR
  • INTEGER
  • MOD
  • PI
  • ROUND
  • SIGN
  • TRUNCATE
  • XABS
  • XEXP
  • XLN
  • XLOG
  • XPOWER
  • XSQRT
Parent topic: Functions Overview


CEILING

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the smallest integer greater than or equal to expr. The format appears below:

CEILING(expr)

For example:

CEILING(12.25) = 13
CEILING(12) = 12
Parent topic: Numeric Functions


DECIMAL

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Transforms a number to the decimal representation of the numeric value having a specified precision and scale. The format appears below:

DECIMAL(x [, precision [, scale]])

The parameter precision, if specified, must be between 1 and 31, inclusive. If precision is omitted, the default precision depends on the data type of the first argument. If x is a floating point number or decimal, the default precision is 15. If the parameter x is an integer the default precision is 11. If x is a small integer, the default precision is 5. The parameter scale, if specified, must be in the range of 0 to precision. If omitted, scale is assumed to be 0. For example:

SELECT DECIMAL(quantity, 5, 2)
FROM items
Parent topic: Numeric Functions


FACTORIAL

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the value of expr factorial. The format appears below:

FACTORIAL(expr)

The value of the parameter expr must be greater than or equal to 0 and less than or equal to 167. For example:

FACTORIAL(6) = 720
Parent topic: Numeric Functions


FLOAT

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Converts a number into the floating point representation of the number, as if the value were assigned to a FLOAT field. The format appears below:

FLOAT(x)

In DB2 compatibility mode, the parameter x cannot be a string. In XDB mode, x can be a string.

Parent topic: Numeric Functions


FLOOR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the largest integer less than or equal to the value of expr. The format appears below:

FLOOR(expr)

For example:

FLOOR(12.25) = 12
FLOOR(12) = 12
Parent topic: Numeric Functions


INTEGER

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Converts a number into an integer value, in the same way that the value would be converted if assigned to an INTEGER field. The format appears below:

INTEGER(x)

In DB2 compatibility mode, the parameter x cannot be a string. In XDB mode, x can be a string.

Parent topic: Numeric Functions


MOD

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the remainder of expr1/expr2. The format appears below:

MOD(expr1,expr2)

For example:

MOD(10,4) = 2
MOD(2,10) = 2
Parent topic: Numeric Functions


PI

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns an approximation of the value of Pi. For example:

PI() = 3.1415926535897936
Parent topic: Numeric Functions


ROUND

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Rounds expr1 to the precision specified in int_expr. The format appears below:

ROUND(expr1,int_expr)

Can also round to negative numbers. For example:

ROUND(549.55,1) = 549.6
ROUND(549.55,-1) = 550.00
ROUND(549.55,-2) = 600.00
Parent topic: Numeric Functions


SIGN

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the sign of the parameter expr. The format appears below:

SIGN(expr)

A value of one is returned if expr is positive, and a value of zero is returned if expr is zero, and -1 is returned if expr is negative. For example:

SIGN(-234.4) = -1
SIGN(234) = 1
SIGN(0) = 0
Parent topic: Numeric Functions


TRUNCATE

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Truncates expr1 to the precision specified in int_expr. The format appears below:

TRUNCATE(expr, int_expr)

Can truncate to negative decimals. For example:

TRUNCATE(549.55,1) = 549.5
TRUNCATE(549.55,-1) = 540.00
TRUNCATE(549.55,-2) = 500
Parent topic: Numeric Functions


XABS

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Calculates the absolute value of parameter x. The format appears below:

XABS(x)
Parent topic: Numeric Functions


XEXP

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the exponential function of parameter x (for example, eE+x). The format appears below:

XEXP(x)
Parent topic: Numeric Functions


XLN

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the natural log of parameter x. The format appears below:

XLN(x)
Parent topic: Numeric Functions


XLOG

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds base 10 logarithm of parameter x. The format appears below:

XLOG(x)
Parent topic: Numeric Functions


XPOWER

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the value of parameter x raised to the power of parameter y. The format appears below:

XPOWER(x, y)
Parent topic: Numeric Functions


XSQRT

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the square root of parameter x. The format appears below:

XSQRT(x)
Parent topic: Numeric Functions


String Functions

A string can consist of any combination of letters, digits or special characters contained in the standard ASCII character set. String functions can return string values from arguments consisting of other data types or manipulate combinations of existing string arguments to return another string value.

More:

  • ASCII
  • CHAR
  • CHR
  • DIGITS
  • FINDANY
  • FINDNOTIN
  • FINDSTR
  • HEX
  • INITCAP
  • LENGTH
  • LTRIM
  • NULLIF
  • REPLICATE
  • REVCHAR
  • RTRIM
  • STRIP
  • SUBSTR
  • VALUE
  • XCONCAT
  • XLEFT
  • XLOWER
  • XRIGHT
  • XTRIM
  • XUPPER
  • ASCII
  • CHAR
  • CHR
  • DIGITS
  • FINDANY
  • FINDNOTIN
  • FINDSTR
  • HEX
  • INITCAP
  • LENGTH
  • LTRIM
  • NULLIF
  • REPLICATE
  • REVCHAR
  • RTRIM
  • STRIP
  • SUBSTR
  • VALUE
  • XCONCAT
  • XLEFT
  • XLOWER
  • XRIGHT
  • XTRIM
  • XUPPER
Parent topic: Functions Overview


ASCII

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the ASCII code value of the leftmost character of char_expr. The format appears below:

ASCII(char_expr)

For example:

ASCII("XDB") = 88
Parent topic: String Functions


CHAR

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Transforms date, time or timestamp value into a character string. The format appears below:

CHAR([x [, format]])

If present, x must evaluate to a date, time or timestamp value. If x is null, the result is null. The parameter format is a string format for date or time, as shown in the table below. If omitted, the system default format is used. The format parameter cannot be specified if x is a timestamp.

Format | Name | Date Format | Time Format
ISO | International Standards Organization Standard | yyyy-mm-dd | hh.mm.ss
USA | IBM USA Standard | mm/dd/yyyy | hh:mm AM or PM
EUR | IBM European Standard | dd.mm.yyyy | hh.mm.ss
JIS | Japanese Industrial Standard Christian Era | yyyy-mm-dd | hh.mm.ss
LOCAL | Configured through the Options Utility. | User Defined | User Defined

Examples are:

CHAR(birth_date, USA)
CHAR(airtime, ISO)
CHAR(auditstamp)
Parent topic: String Functions


CHR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Converts an ASCII code into a character (ASCII code values must be between 0 and 255). The format appears below:

CHR(int_expr)

For example:

CHR(81) = "Q"
Parent topic: String Functions


DIGITS

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Returns a string representation of a number, without decimal points. The x parameter must be an integer or decimal number. The format appears below:

DIGITS(x)

In DB2 compatibility mode, the result is unsigned and padded with leading zeroes so that the string length is 5 if the argument is a small integer, 10 if the argument is an integer, or p if the argument is a decimal number with precision p. In XDB mode the result is a variable length string and may include a sign. An example of the use of DIGITS is:

SELECT DIGITS(o_no)
FROM orders
Parent topic: String Functions


FINDANY

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Searches for any of the characters specified by charexpr2 in charexpr1 and returns the offset from the beginning where the first occurrence is found. The format appears below:

FINDANY(charexpr1, charexpr2)

For example:

FINDANY("abcdef","zd") = 4

because "d" is found at the fourth character. A return value of zero signifies not found.

Parent topic: String Functions


FINDNOTIN

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the offset of the first character in charexpr1 that is not in charexpr2. The format appears below:

FINDNOTIN(charexpr1, charexpr2)

For example:

FINDNOTIN("abdblm","dba") = 5

because "l" is the first character not in the "dba" set. A return value of zero indicates all characters are in the string.

Parent topic: String Functions


FINDSTR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Searches for charexpr2 in charexpr1 and returns the offset from beginning of string when found. The format appears below:

FINDSTR(charexpr1, charexpr2)

For example:

FINDSTR("abcdef", "cd") = 3

A return value of zero means not found, 1 is the first character, etc.

Parent topic: String Functions


HEX

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Returns a string that is the hexadecimal representation of x, where the parameter value x can be any value other than a long string. The format appears below:

HEX(x)

The result is a string of hexadecimal digits, with each consecutive pair of digits representing a byte of the argument, so that the length is twice the length of the argument. In DB2 compatibility mode, bytes are swapped for smallint, integer and date fields. In XDB mode, PC Intel format is used for smallint, int and date fields.

If the location sort sequence is EBCDIC, character fields display in HEX based upon the EBCDIC code page. Also, performing a HEX function on a date field in DB2 mode shows the result as if stored in DB2 format instead of XDB mode format. DB2 format is 4 packed decimal bytes with the year in the first two, the month in the next one, and the day in the next one. For example, the value 19900101 would be displayed if the HEX function was applied to date 01/01/1990.

Parent topic: String Functions


INITCAP

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Capitalizes the first character of each word and makes the rest of each word lower case. The format appears below:

INITCAP(charexpr)

For example:

INITCAP("xdb SYSTEMS") = "Xdb Systems"
Parent topic: String Functions


LENGTH

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Finds the length of x, where x is any field value. XDB mode recognizes either LENGTH or XLENGTH, while DB2 mode only recognizes LENGTH. The format appears below:

LENGTH(x)

The character count returned depends on the compatibility setting in effect at the time the data value was inserted into the table -- not your current compatibility setting. For example, if you inserted the field value when in DB2 mode, the LENGTH function includes trailing blanks in the character count (up to the length of the column). If you inserted the field value when in XDB mode, the LENGTH function does not count trailing blanks.

For example, if the lname column values were inserted while in XDB mode, the following query produces the result shown:

SELECT lname, LENGTH(lname)
FROM employee
lname

length(lname)
Kerin | 5
Wilson | 6
Crisp | 5
Hopkins | 7
Parent topic: String Functions


LTRIM

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Trims leading spaces. The format appears below:

LTRIM(charexpr)

For example:

LTRIM("   XDB") = "XDB"
Parent topic: String Functions


NULLIF

ANSI | DB2 | SQL/DS | XDB
X | X |  | X

Use the NULLIF function wherever an expression is used to return null if the two arguments are equal; otherwise, the value of the first argument is returned. The two arguments must be compatible. The attributes of the result are the attributes of the first argument.

For example, if the result of the first argument is a character string, the result of the other must also be a character string; if the result of the first argument is a number, the result of the other must also be a number.

The format of the NULLIF function appears below:

NULLIF (expression,expression)

where:

expression Specifies a single value.
Parent topic: String Functions


REPLICATE

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Repeats charexpr for integer number of times. The format appears below:

REPLICATE(charexpr,integer)

For example:

REPLICATE("*",10) = "**********"
Parent topic: String Functions


REVCHAR

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Reverses the order of characters in charexpr. The format appears below:

REVCHAR(charexpr)

For example:

REVCHAR("abc") = "cba"

Data returned are character data.

Parent topic: String Functions


RTRIM

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Trims trailing spaces. The format appears below:

RTRIM(charexpr)

For example:

RTRIM("XDB   ") = "XDB"
Parent topic: String Functions


STRIP

ANSI | DB2 | SQL/DS | XDB
 | X | X | X

Use the STRIP function to remove blanks or another specified character from the end, beginning, or both ends of a string expression. The format appears below:

STRIP (expression [,BOTH [,strip-character]|,LEADING |,TRAILING])

where:

expression | A string expression.
strip-character | A single character constant that indicates the character that is to be removed.
Parent topic: String Functions


SUBSTR

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Extracts n characters from x, beginning with the mth character (also written XMID in XDB mode). The format appears below:

SUBSTR(x, m [,n])

The parameter x is any expression that evaluates to a string. The parameter m is a positive integer indicating the offset from the beginning of the string, and the parameter n is a positive integer indicating the number of characters to extract. If two arguments are specified, the implicit length is LENGTH(x)-m+1 for fixed length fields or the larger of 0 or LENGTH(x)-m+1 for varying length fields. If x is null, the result is null.

For example, suppose the serial number for a deluxe widget is SW1234-4356, where the first two characters indicate the department that made it, the next 4 the model, and the rest the specific unit from the lot. To find the model number "1234" for deluxe widgets:

SELECT SUBSTR(serial_no, 3, 4)
  FROM products
  WHERE description = "Deluxe Widget"
Parent topic: String Functions


VALUE

ANSI | DB2 | SQL/DS | XDB
 | X |  | X

If x is evaluated as null, VALUE returns the value of the first non-null y. The format appears below:

VALUE(x, y1 [,...yn])

For example, in the query below, the column named COM is null for some employees; the desired value is then the employee's payrate or, failing that, simply the value 10. For example:

SELECT e_no, VALUE(com * $300, payrate, $10)
  FROM employee
  WHERE st = "VA"
e_no

column2
2 | $17.50
4 | $17.50
7 | $9.00
9 | $17.00
Parent topic: String Functions


XCONCAT

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

String concatenation can be performed using the XCONCAT function (concatenation can also be performed with the "||" operator). The format appears below:

XCONCAT(expres1, expres2)

The parameters expres1 and expres2 are expressions that evaluate two strings to be concatenated.

Parent topic: String Functions


XLEFT

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Extracts the n leftmost characters from a string. The format appears below:

XLEFT(x, n)

The parameter x is any expression that evaluates to a character string, and the parameter n is a positive integer indicating the number of characters to extract. For example, suppose you want to extract the area code from all customer phone numbers, you can use the query:

SELECT company, XLEFT(phone, 3)
FROM customer

If n is longer than the string extracted, the string is right padded with spaces until it is n characters long.

For example:

SELECT XLEFT(color, 10)||pname
FROM part
Column1

RED | NUT
GREEN | BOLT
BLUE | CAM
RED | SCREW
BLUE | CAM
RED | COG
Parent topic: String Functions


XLOWER

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Converts a character string to lower case. The parameter x is any expression that evaluates to a character string. The format appears below:

XLOWER(x)

For example:

SELECT XLOWER(lname)
  FROM employee
  WHERE st = "VA"
xlower(lname)
kerin
wilson
crisp
hopkins
Parent topic: String Functions


XRIGHT

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Extracts the last n characters from x. The format appears below:

XRIGHT(x, n)

The parameter x is any expression that evaluates to a character string and the parameter n is a positive integer indicating the number of characters to extract. For example, the following query retrieves phone numbers without the area codes:

SELECT XRIGHT(phone, 8)
FROM customer

If the value of n is longer than the string extracted, the string will be padded on the left with spaces until it is n characters long. For example, to right justify character strings, use a query like:

SELECT XRIGHT(pname, 14)
FROM part
column1
NUT
BOLT
CAM
SCREW
CAM
COG
Parent topic: String Functions


XTRIM

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Trims trailing spaces from a character string. The format appears below:

XTRIM(x)

The parameter x is any expression that evaluates to a character string. For example:

SELECT XTRIM(lname)
FROM employee
Parent topic: String Functions


XUPPER

ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Converts a character string to upper case. The format appears below:

XUPPER(x)

The parameter x is any expression that evaluates into a character string. For example:

SELECT XUPPER(lname)
  FROM employee
  WHERE st = "VA"
xupper(lname)
KERIN
WILSON
CRISP
HOPKINS
Parent topic: String Functions


System Table Overview

To view the contents of any system table, use the SQL SELECT command as follows:

SELECT * FROM authid.table-name

where authid is the owner of the table. The AuthID for system tables is either sysxdb, sysibm or xdbstat.

Only a super user has authority to edit (update) the system tables. A user with sysadm authority can edit selected columns in some of the tables within the authorized location. These sysadm-editable columns are so noted in the column descriptions.

All locations, including the system location, contain a set of system catalog tables. These are stored in the dsndb06 database in each location. Additional system tables reside in the xdbacf and dsnddf databases in the system location.

Important: For complete information on system tables, see the documentation for DB2 catalog tables located on the IBM Web site.
Parent topic: SQL Reference


Overview of XDB Server Specifications

The tables in this topic show the limits imposed by the XDB Server while in XDB mode. (See also Data Types in Basic Concepts) Some XDB Server tools and utilities may have further restrictions, which are described in the applicable documentation.

More:

  • Maximum Identifier Lengths (in bytes)
  • Maximum String Length Limits
  • Date and Time Values
  • Numeric Limits
  • System and Operational Limits
  • Maximum Identifier Lengths (in bytes)
  • Maximum String Length Limits
  • Date and Time Values
  • Numeric Limits
  • System and Operational Limits
Parent topic: SQL Reference


Maximum Identifier Lengths (in bytes)

Item | Limit
Alias Name | 18
AuthID | 8
Collection ID | 18
Column Name | 18
Correlation Name | 18
Cursor Name | 18
Database Name | 8
Index Name | 18
Location Name | 16
Procedure Name | 18
Referential Constraint Name | 8
Statement Name | 18
Storage Group (stogroup) Name | 8
Synonym Name | 18
Table Name | 18
Table Space Name | 8
View Name | 18
Parent topic: Overview of XDB Server Specifications


Maximum String Length Limits

Item | Limit
Maximum length of a CHAR field (bytes) | 4,056
Maximum length of a VARCHAR field (bytes) | 32,706
Maximum length of a LONGVARchar field (bytes) | 32,706
Maximum length of a GRAPHIC field | 127
Maximum length of a VARGraphic field | 16,353
Maximum length of a LONGVARGraphic field | 16,353
Parent topic: Overview of XDB Server Specifications


Date and Time Values

Item | Limit
Smallest DATE Value (shown in ISO format) | 0001-01-01
Largest DATE value (shown in ISO format) | 9999-12-31
Smallest TIME value (shown in ISO format) | 00.00.00
Largest TIME value (shown in ISO format) | 24.00.00
Smallest TIMESTAMP value | 0001-01-01-00.00.00.000000
Largest TIMESTAMP value | 9999-12-31-24.00.00.000000
Parent topic: Overview of XDB Server Specifications


Numeric Limits

Item | Limit
Smallest SMALLINT value | -32,768
Largest SMALLINT value | 32,767
Smallest INTEGER value | -2,147,483,648
Largest INTEGER value | 2,147,483,647
Smallest DECIMAL value | 1-10E+31
Largest DECIMAL value | 10E+31-1
Largest decimal precision | 31
Smallest 4-byte float value | 1.2E-38
Largest 4-byte float value | 3.4E+38
Smallest 8-byte float value | 2.2E-308
Largest 8-byte float value | 1.8E+308
Largest money value | $10E+12
Smallest money value | -$10E+12
Parent topic: Overview of XDB Server Specifications


System and Operational Limits

Item | Limit
Maximum number of columns in a table or view | 750
Maximum record length (in bytes) (See note 1.) | 32,767
Maximum number of volume IDs in a storage group | 133
Maximum number of queries open at one time | 50 per user
Maximum length of an SQL statement | 32,767
Maximum projected columns in a SELECT list | 750
Maximum UNION operators in a SELECT statement | 32
Maximum number of predicates in a WHERE or HAVING clause | No Limit
Maximum number of columns in a GROUP BY clause | 750
Maximum number of columns in an ORDER BY clause | 750
Maximum number of tables in a FROM clause (number of tables per JOIN) | 15
Maximum bytes in a compound index | 203
Maximum index field length (in bytes) (See note 2.) | 4056
Maximum number of indexes per table | No limit
Maximum number of columns in an index key | 64
Maximum number of records per table | 2 billion +
Maximum number of databases (See note 3.) | No limit
Maximum number of locations open at a time (single user) | 10
Maximum nested query levels | Limited only by system storage
Maximum queries per level | Limited only by system storage
Maximum recursion levels for PREVIOUS function with index (no limit without index) | 20
Maximum sort fields | 750
Maximum number of elements in a SELECT list | 750

Table Notes:

  1. Including 2 byte record overhead plus 1 byte overhead for odd length character fields and 2 byte overhead for other field types.
  2. Only the first 254 characters of a field are actually used in creating the index.
  3. Limited by storage space and operating system.
Parent topic: Overview of XDB Server Specifications


XDB Server Reserved Words

This topic lists reserved words or keywords used by the XDB Server and utilities. Other words which may become reserved are listed as well.

XDB Server SQL reserved words should not be used as object (for example, locations, databases, tables, indexes, columns) names. Some XDB Server tools and utilities may place other restrictions on database object names. In general, XDB Server reserved words are not case sensitive.

More:

  • Reserved Words: DB2 Mode
  • Reserved Words: DB2 Mode
  • Reserved Words: XDB Mode
  • Future Reserved Words
Parent topic: SQL Reference


Reserved Words: DB2 Mode

These words are reserved if you are running in DB2 Mode.

add | delete | grant | obid | stogroup
all | descriptor | group | of | synonym
alter | distinct |  | on |
and | drop | having | optimize | table
any |  |  | or | tablespace
as | editproc | immediate | order | to
audit | end-exec | in |  |
 | erase | index | package | union
between | escape | insert | part | update
bufferpool | except | into | plan | user
by | execute | is | priqty | using
 | exists |  | privileges |
cluster |  | key | program | validproc
collection | fetch |  |  | values
column | fieldproc | like | row | vcat
concat | for | locksize |  | view
count | from |  | secqty | volumes
current |  | not | select |
cursor | go | null | set | where
 | goto | numparts | some | with
database |  |  |  |
Parent topic: XDB Server Reserved Words


Reserved Words: XDB Mode

These words are reserved if you are running in XDB Mode.

add | distinct | key | select | where
all | double |  | set | with
alter | drop | level | some |
and |  | like | sounds | xabs
any | editproc |  | stogroup | xconcat
as | erase | modify | synonym | xdate
audit | escape | money |  | xday
 | except |  | table | xexp
between | exists | not | tablespace | xleft
bottom |  | null | to | xlength
bufferpool | fetch |  | today | xln
by | fieldproc | of |  | xlog
 | for | on | undelete | xlower
cluster | from | or | union | xmid
coalesce |  | order | unique | xmonth
collection | grant |  | unlock | xpower
column | group | package | update | xright
concat |  | previous | user | xsqrt
connect | having | priqty | using | xstddev
count | host | privileges |  | xtime
current |  | program | validproc | xtimestamp
 | in |  | values | xtoday
database | index | rename | variable | xtrim
datetime | insert | row | vcat | xupper
delete | into |  | view | xvar
directories | is | secqty | volumes | xyear
Parent topic: XDB Server Reserved Words


Future Reserved Words

The following words are IBM or ANSI SQL reserved words (or possible SQL future reserved words) that are not reserved by the XDB Server. We recommend you avoid the use of these for object names.

applpath | tmppath
dbpath | xdbpath
sysdbpath |

In addition, note that XDB Server extensions will generally use keywords that begin with the letter X. It is therefore recommended that you avoid names beginning with X.

Parent topic: XDB Server Reserved Words


SQL Communications Area (SQLCA)

The SQL Communications Area (SQLCA) is a data area used to store information on the execution of SQL commands. The SQLCA is used as a diagnostic tool to determine whether an SQL statement executed correctly. The SQLCA is updated after each SQL statement is executed.

  • SQLCA Description
  • SQLCA Structure For COBOL
  • SQLCA Structure For C
Parent topic: SQL Reference
Related information
SQLCA Description
SQLCA Structure For COBOL
SQLCA Structure For C


SQLCA Description

The SQLCA is described in the following table, including the field names used in each language, the data type, and a discussion of the purpose of each field.

COBOL Name | C Name | Data Type | Purpose
SQLCAID | sqlcaid | char(8) | A character string (SQLCA) that identifies the beginning of the SQLCA.
SQLCABC | sqlcabc | integer | Specifies the length of the SQLCA. Value is always 136.
SQLCODE | sqlcode | integer | Contains a return code pertaining to the most recent SQL statement executed. Important values are: 0 Statement executed successfully (may have had warnings). >0 Executed successfully but with an exception condition. <0 An error occurred. 100 End of data reached.
SQLERRML | sqlerrml | smallint | The length of the SQLERRMC string (0 to 70). If 0, the value of SQLERRMC is not pertinent.
SQLERRMC | sqlerrmc | varchar (70) | One or more tokens, separated by x'ff', that are substituted into error messages to provide specific information about an error condition.
SQLERRP | sqlerrp | char(8) | Indicates the product signature in the format pppvvrrm where: ppp = XDB vv = XDB version number rr = XDB release number m = Operating system: N = NT O = OS/2 D = DOS
SQLERRD(1) | sqlerrd[0] | integer | Reserved for internal use.
SQLERRD(2) | sqlerrd[1] | integer | Reserved for internal use.
SQLERRD(3) | sqlerrd[2] | integer | Number of rows affected by an INSERT, UPDATE or DELETE command.
SQLERRD(4) | sqlerrd[3] | integer | Not used by XDB Server.
SQLERRD(5) | sqlerrd[4] | integer | Contains the position or column of a syntax error for a PREPARE or EXECUTE IMMEDIATE statement.
SQLERRD(6) | sqlerrd[5] | integer | Not used by XDB Server.
SQLWARN0 | sqlwarn0 | char(1) | Flag used to signal warning condition. If blank, then all other SQLWARN variables are blank. If value is W, then at least one other SQLWARN has a W.
SQLWARN1 | sqlwarn1 | char(1) | If value is W, then at least one column's value was truncated when stored in a host variable.
SQLWARN2 | sqlwarn2 | char(1) | If value is W, then at least one null value was eliminated from the argument of a column function. May not be set to W for a MIN function because its results are not dependent on the elimination of null values.
SQLWARN3 | sqlwarn3 | char(1) | If value is W, then the number of columns is larger than the number of host variables. Contains Z if fewer locators were provided in the ASSOCIATE LOCATORS statement than the stored procedure returned.
SQLWARN4 | sqlwarn4 | char(1) | If value is W, then a prepared UPDATE or DELETE statement does not contain a WHERE clause.
SQLWARN5 | sqlwarn5 | char(1) | If value is W, your program tried to create an index that contains a field that exceeds the maximum length for an index. This use is XDB Server-specific.
SQLWARN6 | sqlwarn6 | char(1) | Not used by XDB Server.
SQLWARN7 | sqlwarn7 | char(1) | Not used by XDB Server.
SQLWARN8 | sqlwarn8 | char(1) | Not used by XDB Server.
SQLWARN9 | sqlwarn9 | char(1) | Contains Z if the stored procedure returned multiple result sets.
SQLWARNA | sqlwarna | char(1) | Not used by XDB Server.
SQLSTATE | sqlstate | char(5) | Contains SQLSTATE value for this error.
Parent topic: SQL Communications Area (SQLCA)


SQLCA Structure For COBOL

The structure of the SQLCA is defined in the copybook sqlca.cpy. It must be included in every COBOL program that contains embedded SQL.

The SQLCA structure for COBOL is as follows:

 01 SQLCA.
     05  SQLCAID         PIC X(8)         VALUE "SQLCA   ".
     05  SQLCABC         PIC S9(9) COMP-5 VALUE 136.
     05  SQLCODE         PIC S9(9) COMP-5 VALUE 0.
     05  SQLERRM.
         49  SQLERRML    PIC S9(4) COMP-5.
         49  SQLERRMC    PIC X(70).
     05  SQLERRP         PIC X(8).
     05  SQLERRD         PIC S9(9) COMP-5 OCCURS 6 VALUE 0.
     05  SQLWARN.
         10  SQLWARN0    PIC X.
         10  SQLWARN1    PIC X.
         10  SQLWARN2    PIC X.
         10  SQLWARN3    PIC X.
         10  SQLWARN4    PIC X.
         10  SQLWARN5    PIC X.
         10  SQLWARN6    PIC X.
         10  SQLWARN7    PIC X.
         10  SQLWARN8    PIC X.
         10  SQLWARN9    PIC X.
         10  SQLWARN10   PIC X.
         10  SQLWARNA    REDEFINES SQLWARN10 PIC X.
     05  SQLSTATE        PIC X(5).
Parent topic: SQL Communications Area (SQLCA)


SQLCA Structure For C

The structure of the SQLCA is defined in the include file SQLCA.H. It must be included in every C program that contains embedded SQL.

#ifndef SQLCODE
struct sqlca
{
  unsigned char  sqlcaid[8];
  long      sqlcabc;
  long      sqlcode;
  short      sqlerrml;
  unsigned char  sqlerrmc[70];
  unsigned char  sqlerrp[8];
  long      sqlerrd[6];
  unsigned char  sqlwarn[11];
  unsigned char  sqlstate[5];
};
#define SQLCODE  sqlca.sqlcode
#define SQLWARN0  sqlca.sqlwarn[0]
#define SQLWARN1  sqlca.sqlwarn[1]
#define SQLWARN2  sqlca.sqlwarn[2]
#define SQLWARN3  sqlca.sqlwarn[3]
#define SQLWARN4  sqlca.sqlwarn[4]
#define SQLWARN5  sqlca.sqlwarn[5]
#define SQLWARN6  sqlca.sqlwarn[6]
#define SQLWARN7  sqlca.sqlwarn[7]
#define SQLWARN8  sqlca.sqlwarn[8]
#define SQLWARN9  sqlca.sqlwarn[9]
#define SQLWARNA  sqlca.sqlwarn[10]
#define SQLSTATE  sqlca.sqlstate
#endif
struct sqlca sqlca;
Parent topic: SQL Communications Area (SQLCA)


SQL Descriptor Area (SQLDA)

The SQL Descriptor Area (SQLDA) is a data area that holds information about dynamic SQL commands. An SQLDA might be used in a DESCRIBE statement to find out information about columns returned by a query, and then reused for a FETCH statement when the values are actually selected.

The SQLDA consists of four variables, followed by a variable number of SQLVAR structures. SQLVAR structures describe columns if OPEN, FETCH or EXECUTE statements are involved. For DESCRIBE and PREPARE statements, the SQLVAR structures describe host variables.

This topic provides descriptions of the information provided in the SQLDA and shows the structure for COBOL, PL/I and C.

More:

  • SQLDA Elements
  • SQLVAR Elements
  • SQLDA Structure For COBOL
  • SQLDA Elements
  • SQLVAR Elements
  • SQLTYPE Values
  • SQLLEN Values
  • SQLDA Structure For COBOL
  • SQLDA Structure For C
  • SQLDA Structure For PL/I
Parent topic: SQL Reference


SQLDA Elements

The SQLDA consists of the four elements shown in the table below, followed by the number of SQLVAR structures specified in SQLN.

Each occurrence of SQLVAR describes a column (for DESCRIBE and PREPARE statements) or host variable (for OPEN, FETCH and EXECUTE statements), depending on the type of statement being executed. The number of SQLVAR elements appearing in the SQLDA is defined by the SQLN element of SQLDA, thus the SQLDA structure is variable length. The SQLVAR structure is shown in the following table.

COBOL Name | C Name | PL/I Name | Data Type | Usage in DESCRIBE and PREPARE INTO | Usage in FETCH, OPEN or EXECUTE
SQLDAID | sqldaid | sqldaid | char(8) | The character string (SQLDA) that identifies the beginning of the SQLDA structure. | Same.
SQLDABC | sqlabc | sqlabc | integer | Length of the SQLDA. Computed as SQLN*44+16. | Same.
SQLN | sqln | sqln | smallint | Number of occurrences of SQLVAR. (See the SQLVAR Elementsfor more about SQLVAR.) | Same.
SQLD | sqld | sqld | smallint | Number of columns described by occurrences of SQLVAR. If the statement is not a query, the value is zero. (See the SQLVAR Elementsfor more about SQLVAR.) | Number of host variables described by occurrences of SQLVAR.
Parent topic: SQL Descriptor Area (SQLDA)


SQLVAR Elements

COBOL Name | C Name | PL/I Name | Data Type | Usage in DESCRIBE and PREPARE INTO | Usage in FETCH, OPEN or EXECUTE
SQLTYPE | sqltype | sqltype | smallint | Code indicating the data type of the column and if null values are allowed. See the table in SQLTYPE Values for SQLTYPE codes. | Indicates the data type of a host variable and if an indicator variable is provided. See the table in SQLTYPE Values for SQLTYPE codes.
SQLLEN | sqllen | sqllen | smallint | Indicates the length attribute of the columns. For date/time columns, the length of the string representation of the value is used. See the table under SQLLEN Values for SQLLEN values. | Indicates the length attribute of the host variable. See the table under SQLLEN Values for SQLLEN values.
SQLDATA | sqldata | sqldata | pointer to a buffer | Contains the CCSID indicator for bit data Format is x'0000'zzzz' where zzzz is X'FFFF' | Contains the address of the host variable.
SQLIND | sqlind | sqlind | pointer | Undefined. | Contains the address of an associated indicator variable if SQLTYPE is odd.
SQLNAME | sqlname | sqlname | char(30) | Name of the column (or a string of length zero if no name exists). | Not used in XDB Server.

More:

  • SQLTYPE Values
  • SQLLEN Values
Parent topic: SQL Descriptor Area (SQLDA)


SQLTYPE Values

The meanings of SQLTYPE values depend on the type of statement executed, as shown in the table below. The following differences should be noted:

  • For DESCRIBE and PREPARE

    The codes for DB2 mode differ depending on whether or not null values are allowed in the column. An even value for SQLTYPE indicates that the column does not allow nulls. An odd value indicates that the column does allow nulls. In XDB mode, the codes do not differ.

  • For FETCH, OPEN and EXECUTE

    Codes differ depending on whether or not indicator variables are provided for use with the host variable. An even value for SQLTYPE means no indicator variable is provided, an odd value indicates that SQLIND contains the address of an indicator variable.

    In addition, because host variables do not include DATE, TIME or TIMESTAMP data types, these values are usually retrieved using fixed length character strings.

    Data Type | DESCRIBE & PREPARE | FETCH, OPEN & EXECUTE
    DB2 Mode: XDB Mode No Indicator Indicator
    date

    (See note 1.)

             384 385 4 384 385
    time

    (See note 1.)

             388 389 7 388 389
    timestamp

    (See note 1.)

             392 393 11 392 393
    varying-length character string | 448 | 449 | 9 | 448 | 449
    fixed-length character string | 452 | 453 | 6 | 452 | 453
    long varying length character string | 456 | 457 | 10 | 456 | 457
    varying length graphic string | 464 | 465 | 17 | 464 | 465
    fixed length graphic string | 468 | 469 | 16 | 468 | 469
    long varying length graphic string

    (See note 2.)

             472 473 22 472 473
    floating point | 480 | 481 | 3 | 480 | 481
    packed decimal | 484 | 485 | 8 | 484 | 485
    money | 484 | 485 | 5 | 484 | 485
    large integer | 496 | 497 | 2 | 496 | 497
    small integer | 500 | 501 | 1 | 500 | 501

Table Notes:

  1. For host variable, a fixed-length character string representation of the date, time or timestamp is used.
  2. For host variable, a long graphic string.
Parent topic: SQL Descriptor Area (SQLDA)


SQLLEN Values

The value of SQLLEN depends on the data type of the columns. SQLLEN gives the length of data (in bytes), depending on data type.

Data Type | SQLLEN Value for DESCRIBE | SQLLEN Value for FETCH, OPEN and EXECUTE
date (See note 1.) | 10 bytes | length attribute of the host variable
time (See note 1.) | 8 bytes | length attribute of host variable
timestamp (See note 1.) | 26 bytes | length attribute of the host variable
character strings - varying-length - fixed-length - long varying-length | length attribute of the column | length attribute of the host variable
graphic strings - varying-length - fixed length - long varying-length (See note 2.) | length attribute of the column | length attribute of the host variable
floating point | 4 for single precision 8 for double precision | 4 for single precision 8 for double precision
packed decimal | precision in byte 1 scale in byte 2 | precision in byte 1 scale in byte 2
integer | 4 bytes | 4 bytes
small integer | 2 bytes | 2 bytes

Table Notes:

  1. For host variable, a fixed-length character string representation of the date, time or timestamp is used.
  2. For host variable, a long graphic string.
Parent topic: SQL Descriptor Area (SQLDA)


SQLDA Structure For COBOL

The SQLDA structure is provided in the copybook sqlda.cpy. Include this copybook in all COBOL programs that make use of dynamic SQL.

 01 SQLDA sync.
     05 SQLDAID               PIC X(8)  VALUE "SQLDA  ".
     05 SQLDABC               PIC S9(9) COMP-5 value 0.
     05 SQLN                  PIC S9(4) COMP-5 value 0.
     05 SQLD                  PIC S9(4) COMP-5 value 0.
     05 SQLVAR OCCURS 0 TO 1489 TIMES DEPENDING ON SQLD.
         10 SQLTYPE            PIC S9(4) COMP-5.
         10 SQLLEN             PIC S9(4) COMP-5.
         10 SQLDATA            USAGE POINTER.
         10 SQLIND             USAGE POINTER.
         10 SQLNAME.
             15 SQLNAMEL        PIC S9(4) COMP-5.
             15 SQLNAMEC        PIC X(30).

If you are using the Precompiler directive SQLDA-VER = 0, you must copy the file sqlda.old to sqlda.cpy. The structure of this SQLDA is below:

01 SQLDA.
  03 SQLDAID    PIC X(8).
  03 SQLDABC    PIC S9(9) COMP.
  03 SQLN    PIC S9(4) COMP.
  03 SQLD    PIC S9(4) COMP.
  03 SQLVAR OCCURS 300.
    05 SQLTYPE  PIC S9(4) COMP.
    05 SQLLEN  PIC S9(4) COMP.
    05 SQLDATA  PIC X(4).
    05 SQLIND  PIC X(4).
    05 SQLNAME  PIC X(30).
Parent topic: SQL Descriptor Area (SQLDA)


SQLDA Structure For C

The SQLDA structure is provided in the file sqlca.h. Include this file in all C programs that make use of dynamic SQL.

#ifndef SQLDASIZE
struct sqlda
{
  unsigned char  sqldaid[8];
  long      sqldabc;
  short      sqln;
  short      sqld;
  struct sqlvar
  {
    short      sqltype;
    short      sqllen;
    unsigned char    *sqldata;
    short      *sqlind;
    struct sqlname
    {
      short      length;
      unsigned char    data[30];
    } sqlname;
  } sqlvar[1];
};
#define SQLDASIZE(n) (sizeof(struct sqlda)+
      (n-1)*sizeof(struct sqlvar))
#endif
Parent topic: SQL Descriptor Area (SQLDA)


SQLDA Structure For PL/I

The SQLDA structure is provided in the copybook SQLDA.INC. Include this copybook in all PL/I programs that make use of dynamic SQL.

dcl sqlsize fixed binary(15);
dcl sqldaptr ptr;
dcl
   1 sqlda based (sqldaptr),
     2 sqldaid    char(8),
     2 sqldabc    fixed bin(31),
     2 sqln       fixed bin(15),
     2 sqld       fixed bin(15),
     2 sqlvar     (sqlsize refer (sqln)),
       3 sqltype  fixed bin(15),
       3 sqllen   fixed bin(15),
       3 sqldata  ptr,
       3 sqlind   ptr,
Parent topic: SQL Descriptor Area (SQLDA)


SQL Option Server TUTORIAL Location

  • Overview of the Tutorial Tables
  • CONSTANT Table
  • CUSTOMER Table
  • DEPT (Department) Table
  • EMPLOYEE Table
  • ITEMS Table
  • ORDERS Table
  • PART Table
  • PARTSUPP Table
  • PRODUCTS Table
  • QMT_STAFF Table
  • SUBPART Table
  • SUPPLIER Table
Parent topic: SQL Reference


Overview of the Tutorial Tables

Most of the examples in this and other SQL Option Server references are based on the tutorial tables listed below. You can execute the example SQL statements appearing throughout this reference. Any results displayed from these examples should exactly correspond to the results obtained if you execute the same example against the tutorial tables listed below.

  • CONSTANT Table
  • CUSTOMER Table
  • DEPT (Department) Table
  • EMPLOYEE Table
  • ITEMS Table
  • ORDERS Table
  • PART Table
  • PARTSUPP Table
  • PRODUCTS Table
  • QMT_STAFF Table
  • SUBPART Table
  • SUPPLIER Table
Parent topic: SQL Option Server TUTORIAL Location


CONSTANT Table

o_no | c_no | e_no
6 | 22 | 11
Parent topic: SQL Option Server TUTORIAL Location


CUSTOMER Table

c_no | company | address | city | state | zip | phone | balance
1 | Great Software | 123 Main St | Baltimore | MD | 21212 | 301 222-2222 | 828.60
2 | Unique Systems | 111 First St | Atlanta | GA | 30303 | 404 987-6543 | 3434.00
3 | Commuter Communication | 333 Last St | Washington | DC | 20002 | 202 123-4567 | 648.00
4 | Popular Consulting | 321 Home Dr | Berkeley | CA | 94004 | 516 444-5555 | 2209.00
5 | Unlimited Supply | 213 River Rd | Berkeley | CA | 94004 | 516 555-6789 | 772.00
6 | ABC Corp. | 1 Any Place | Somewhere | MD | 12345 | 301 456-7890 | 63.60
7 | Perfect Software | 1 Address St | Citytown | CA | 12345 | 516 222-3333 | 0.00
8 | Business Technology | 123 Main St | College Park | MD | 20740 | 301 222-3333 | 418.70
9 | Performance Software | 1 First St | Baltimore | MD | 21212 | 301 999-9999 | 2244.20
10 | Problem Solver | 123 Broadway St | Chicago | IL | 54321 | 555 888-8888 | 2000.00
11 | Technology Leader | 100 Oneway St | New York | NY | 98765 | 777 555-5555 | 3000.00
12 | New Startup, Inc. | 101 Nosuch Rd | New York | NY | 87654 | 777 777-7777 | 2345.00
13 | Database Experts | 123 Expert Rd | College Park | MD | 20740 | 301 232-3232 | 1234.00
14 | Instant Success Corp | 111 Goodluck Rd | Niceplace | NY | 13579 | 777 246-1357 | 123.00
15 | Ace Debug Co. | 999 Last St | Littletown | NJ | 11111 | 999 888-7777 | 987.00
16 | Non Stop Systems | 100 Running Rd | Computown | CA | 99999 | 516 222-3333 | 5000.00
17 | Reliable Software | 1000 Longlive St | Oldtown | CA | 99999 | 516 555-5555 | 7606.10
18 | Brandname Systems | 1001 Wellknown St | Popular | IL | 54321 | 555 444-3333 | 543.00
19 | Survival Technology | 100 Deadend St | Nowhere | IL | 56789 | 555 666-7777 | 5678.00
20 | Success Business | 123 Lucky St | College Park | MD | 20740 | 301 333-2222 | 3407.90
21 | Advanced Systems | 100 Fast St | Bulletown | CA | 54321 | 516 222-1111 | 100.00
Parent topic: SQL Option Server TUTORIAL Location


DEPT (Department) Table

dept | dname | mgr
1050 | Sales | 9
2020 | Accounting | 2
Parent topic: SQL Option Server TUTORIAL Location


EMPLOYEE Table

e_no | lname | fname | street | city | st | zip | dept | payrate | com
1 | Hurwood | Roger | 1234 Stirrup La | Green Valley | MD | 20441 | 2020 | 16.00 |
2 | Kerin | Linda | 802 Wilderness Dr | Wild Woods | VA | 33256 | 2020 | 17.50 |
3 | Gross | Mary | 303 Stagecoach Rd | Green Valley | MD | 20441 | 2020 | 10.00 |
4 | Wilson | Arthur | 211 Main St | Yellow Fountain | VA | 33210 | 2020 | 17.50 |
5 | Chung | Yung | 422 Maple St | Garden City | MD | 20331 | 1050 | 12.25 | 0.05
6 | Cox | John | 555 Magnolia Dr | Garden City | MD | 20331 | 2020 | 14.70 |
7 | Crisp | Keith | Rt 2, Box 43 | Yellow Fountain | VA | 33210 | 1050 | 9.00 | 0.05
8 | Hurwood | Susan | 1234 Stirrup La | Green Valley | MD | 20441 | 2020 | 11.25 |
9 | Hopkins | James | 345 Forest Dr | Yellow Fountain | VA | 33210 | 1050 | 17.00 | 0.03
10 | Haley | Olaf | 334 Market St | Green Valley | MD | 20441 | 1050 | 13.70 | 0.06
Parent topic: SQL Option Server TUTORIAL Location


ITEMS Table

o_no | p_no | quantity | price
1 | 101 | 1 | 50.00
2 | 102 | 1 | 279.00
2 | 103 | 2 | 125.00
3 | 101 | 2 | 50.00
4 | 101 | 2 | 50.00
4 | 103 | 2 | 125.00
5 | 102 | 3 | 279.00
5 | 103 | 3 | 125.00
Parent topic: SQL Option Server TUTORIAL Location


ORDERS Table

o_no | c_no | o_date | s_no
1 | 1 | 09/10/1991 | 5
2 | 2 | 10/10/1991 | 7
3 | 4 | 10/12/1991 | 5
4 | 1 | 10/25/1991 | 5
5 | 9 | 10/30/1991 | 7
Parent topic: SQL Option Server TUTORIAL Location


PART Table

pno | pname | color | weight | city
P1 | NUT | RED | 12 | LONDON
P2 | BOLT | GREEN | 17 | PARIS
P3 | CAM | BLUE | 12 | PARIS
P4 | SCREW | RED | 14 | LONDON
P5 | CAM | BLUE | 12 | PARIS
P6 | COG | RED | 19 | LONDON
Parent topic: SQL Option Server TUTORIAL Location


PARTSUPP Table

sno | pno | qty
S1 | P1 | 300
S1 | P3 | 400
S2 | P2 | 400
S3 | P2 | 200
S1 | P2 | 200
S1 | P4 | 200
S1 | P5 | 100
S1 | P6 | 100
S2 | P1 | 300
S4 | P2 | 200
S4 | P4 | 300
S4 | P5 | 400
Parent topic: SQL Option Server TUTORIAL Location


PRODUCTS Table

p_no | description | price
101 | Floppy Disk Drive | 50.00
102 | 9600B Modem | 279.00
103 | VGA Graphics Card | 125.00
104 | Mouse | 85.00
201 | 304M Hard Disk | 539.00
202 | Sound Card | 189.00
203 | Game Card | 30.00
204 | VGA Monitor | 329.00
301 | CD ROM Drive | 354.00
302 | Math Coprocessor | 199.00
303 | Tape Backup | 269.00
304 | Laser Printer | 1594.00
Parent topic: SQL Option Server TUTORIAL Location


QMT_STAFF Table

EMPID | LNAME | FNAME | DEPARTMENT | JOB | YEARS | SALARY | COMMISSION
110 | SIMPSON | MIKE | 120 | MGR | 7 | 18,380.15 | 000500.00
120 | PETREE | STEVE | 120 | SALES | 8 | 18,193.90 | 01,664.73
130 | MILES | LISA | 138 | MGR | 5 | 17,529.00 |
145 | BACON | CARL | 138 | SALES | 2 | 15,000.00 | 01,008.66
150 | HANSON | KATHY | 115 | MGR | 10 | 20,682.45 |
165 | MYERS | ROGER | 138 | SALES | 3 | 16,830.00 | 01,102.23
170 | RODMAN | CHUCK | 115 | SALES | 7 | 16,525.48 | 02,204.28
180 | JASON | JOHN | 120 | CLERK |  | 13,527.25 | 01,180.48
190 | BEAGLE | HUTCH | 142 | SALES | 6 | 18,024.40 | 02,438.98
200 | WENTZ | STEVEEN | 142 | MGR | 7 | 18,375.45 |
210 | ARNA | ISMETT | 115 | CLERK | 5 | 12,530.85 | 01,258.88
225 | MACKEY | DONNA | 138 | CLERK | 1 | 12,077.00 | 000139.28
230 | YAMAGUCHI | KATRINA | 142 | CLERK | 6 | 10,528.55 | 01,127.88
240 | FRITZE | MARY ANN | 151 | MGR | 6 | 21,172.65 |
250 | WILLIAMS | DOUG | 151 | SALES | 6 | 19,479.15 | 01,689.93
260 | MOLITOR | MITCH | 110 | MGR | 7 | 22,981.85 | 01,500.00
270 | KERMIT | JASON | 115 | CLERK | 4 | 12,281.15 | 01,162.38
280 | ABLE | OTTO | 138 | CLERK | 3 | 12,032.00 | 01,288.78
290 | SNEAD | XIAOLIN | 120 | CLERK | 8 | 14,275.40 | 01,178.78
300 | SCOTT | ARLENE | 142 | CLERK |  | 11,531.25 | 01,136.48
310 | KUANG | CHUNG | 110 | MGR | 10 | 20,032.65 |
320 | SMITHERS | JOHN | 151 | SALES | 7 | 17,677.15 | 02,045.08
330 | LILLY | CRAIG | 151 | CLERK | 3 | 13,392.45 | 01,241.93
340 | DAVISON | DAJUN | 110 | MGR | 5 | 19,282.90 |
350 | WHITEHURS | MIKE | 151 | CLERK | 6 | 14,482.65 | 01,565.58
360 | JANNET | JIM | 110 | MGR | 12 | 21,256.65 |
370 | STROM | RAYMOND | 166 | MGR | 9 | 18,578.15 |
380 | WILLIAMS | ROBERT | 166 | SALES | 9 | 18,697.15 | 01,863.78
390 | QUILT | CHRISTINE | 184 | MGR | 10 | 19,840.65 |
400 | DAVIDSON | STORM | 184 | SALES | 5 | 15,477.15 | 01,858.38
410 | GRASON | BILLY | 166 | SALES | 13 | 21,022.65 | 01,252.58
420 | GONZALES | RENEA | 166 | SALES | 4 | 16,880.85 | 01,896.28
430 | BURRELS | RUSTY | 166 | CLERK | 1 | 11,010.65 | 01,107.78
440 | EDEN | EDDIE | 184 | SALES | 7 | 17,866.65 | 02,337.28
450 | GAGNEY | GREG | 184 | CLERK | 5 | 13,053.15 | 01,240.28
140 | BROOKS | DAVID | 138 | SALES | 6 | 25,000.00 | 02,008.66
160 | MISSON | STEVEN | 138 | SALES | 3 | 16,800.00 | 01,900.23
220 | MASSON | STEFANIE | 138 | CLERK | 5 | 22,077.00 | 02,139.28
142 | STANCEL | WILLIAM | 138 | SALES |  | 12,000.00 | 000088.66
133 | ELDER | NANCY | 138 | MGR | 2 | 16,529.00 |
255 | KENNER | CAL | 151 | SALES | 2 | 13,479.15 | 01,000.00
Parent topic: SQL Option Server TUTORIAL Location


SUBPART Table

product | subpart | qty
P7 | P1 | 2
P7 | P2 | 4
P7 | P6 | 6
P8 | P4 | 8
P8 | P7 | 1
P9 | P5 | 3
P9 | P7 | 5
P9 | P8 | 7
P10 | P1 | 9
P10 | P2 | 1
P11 | P9 | 2
P11 | P10 | 3
Parent topic: SQL Option Server TUTORIAL Location


SUPPLIER Table

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S2 | JONES | 10 | PARIS
S3 | BLAKE | 30 | PARIS
S4 | CLARK | 20 | LONDON
S5 | ADAMS | 30 | ATHENS
Parent topic: SQL Option Server TUTORIAL Location


Objects Used by the SQL Option Server

This topic describes the paths and object names that are created and/or used by the SQL Option Server when you create various data objects in SQL Option Server locations. The storage structure and object names depend on the options you specify in your CREATE statements. In the chart, the first two columns of a given row define the condition that is described in the remaining columns of that row (by reading across).

If stogroup is sysdeflt, the location path is used as the stogroup path. When objects are created, the ..\loc-path\dbname\ path is used.

To generate file names for objects that have names greater than 8 characters (for example, 18-character table names), The SQL Option Server truncates the long name to 8 characters. If the resulting file name would not be unique, a unique file name is generated automatically.

The following list explains the abbreviations used in the chart:

Abbreviation | Meaning
Dbname | Database name
Tsname | Table space name
Sto-name | Storage Group name
Dbsto-path | Disk drive and path defined for the database (DB) stogroup.
Tssto-path | Disk drive and path defined for the table space (TS) stogroup.
Loc-path | Disk drive and path defined for the location.

This chart does not list all possible combinations of creation conditions. Only the more common conditions are shown.

If you create a | And you specify a | The SQL Option Server creates or uses ..
 |  | Path | Stogroup | Database | Table/Index Space
Stogroup | Volumes Vcat (No path defined) | ..\loc-path\dbname\ path is used when objects are created | Sto-name you enter | n/a | n/a
Stogroup | Volumes Vcat XdbVolPath | XdbVolPath you enter in SYSIBM.SYSVOLUMES (for example, c:\sto-path) | Sto-name you enter | n/a | n/a
Database | ------ | c:\loc-path\dbname\ | SYSDEFLT | DBname you enter | n/a
Database | Stogroup | c:\DBsto-path\ | Sto-name you enter | DBname you enter | n/a
Table Space | Database | c:\loc-path\dbname\ | SYSDEFLT | DBname you enter | TSname you enter
Table Space | Database Stogroup (Sto-path for the named stogroup is missing from SYSIBM. SYSVOLUMES) | c:\loc-path\dbname\ | SYSDEFLT | DBname you enter | TSname you enter
Table Space | Database Stogroup (Sto-path exists in SYSIBM. SYSVOLUMES and on op system) | c:\TSsto-path\ | Sto-name you enter | DBname you enter | TSname you enter
Table | ------ | c:\loc-path\DSNDB04\*.tab | SYSDEFLT | DSNDB04 | TSname is first 8 characters of table name (or system generated unique name, if needed)
Table | Database (DB has NO stogroup) | c:\loc-path\dbname\*.tab | SYSDEFLT | DBname you enter | TSname is first 8 characters of table name (or system generated unique name, if needed)
Table | Database (DB has a stogroup) | c:\DBsto-path\*.tab | Same sto-name as the database's stogroup | DBname you enter | TSname is first 8 characters of table name (or system generated unique name, if needed)
Table | Database Tablespace (DB has NO stogroup; TS has NO stogroup) | c:\loc-path\dbname\*.tab | SYSDEFLT | DBname you enter | TSname you enter
Table | Database Tablespace (DB has NO stogroup; TS has a stogroup) | c:\TSsto-path\*.tab | Same sto-name as the table space's stogroup | DBname you enter | TSname you enter
Table | Database Tablespace (DB has a stogroup; TS has NO stogroup) | c:\DBsto-path\*.tab | Same sto-name as the database's stogroup | DBname you enter | TSname you enter
Table | Database Tablespace (DB has a stogroup; TS has a stogroup) | c:\TSsto-path\*.tab | Same sto-name as the table space's stogroup | DBname you enter | TSname you enter
Index | Tablename (DB has NO stogroup) | Same path as associated table..\*.idx and ..\*.ptr | SYSDEFLT | DBname to which associated table belongs | Index space name is same as index name
Index | Tablename (DB has a stogroup) | Same path as associated table..\*.idx and ..\*.ptr | Same sto-name as the database's stogroup | DBname to which associated table belongs | Index space name is same as index name
Index | Tablename Stogroup | Same path as associated table..\*.idx and ..\*.ptr | Sto-name you enter | DBname to which associated table belongs | Index space name is same as index name
Parent topic: SQL Reference


XDB Directive Options

  • ALLOW-HYPHEN
    Enables the preprocessor to allow hyphens in SQL identifiers.
  • APOST
    Causes the preprocessor to recognize apostrophes to delimit literals for quote character in SQL statements.
  • AUTHID
    Causes the preprocessor to include code at SQL initialization that sets the value of your current SQLID to any valid authorization ID.
  • AUTOBIND
    Causes the preprocessor to automatically call the SQL Option Bind utility from within the debugging session after the compiler finishes generating the DBRM if no SQL errors were detected and if the DBRM preprocessor directive was set.
  • AUTOCLOSE
    Causes the SQL Option Server to automatically open and close statements after an insert, update, or delete command.
  • BEHAVIOR
    Causes the SQL Option preprocessor to emulate the behavior of either the DB2 preprocessor or coprocessor.
  • BIND-SQLID
    Sets the current SQLID to this AuthID.
  • BLOCKING
    Specifies the type of block fetching to use.
  • CHANGE-CONTROL
    Controls package creation during the bind process.
  • COLLECTION-ID
    Specifies the collection at the remote DRDA server where the package will be bound.
  • CONCAT
    Specifies the ANSI character code to use for the CONCAT symbol (|).
  • COPY
    Causes the precompiler to expand copybooks included in your source code using standard COBOL COPY statements. Allows EXEC SQL statements and use of host variables to be defined within a COPY statement.
  • CTRACE
    Creates a trace file for submission to technical support if requested.
  • DATE
    Specifies the date format to be used with this program.
  • DB2
    Causes the SQL Option Server to return DB2 error codes and messages when compiling and running, and to close all open cursors at COMMIT and ROLLBACK (the DB2 standard).
  • DB2CLOSE
    Causes the SQL Option Server to close all open statements and cursors at COMMIT and ROLLBACK (the DB2 standard).
  • DB2ERROR
    Causes the SQL Option Server to return DB2 error codes and messages when the program is compiled or executed.
  • DB2VER (Deprecated)
    Specifies the DB2 version used by the SQL Option preprocessor for syntax checking.
  • DBRM
    Causes the SQL Option preprocessor to generate one or more DBRM files.
  • DECLARE
    Tells the preprocessor that host variables are declared in a BEGIN/END DECLARE section of a COBOL program.
  • DEFAULT-CHAR
    Specifies character subtype for all new character columns for which an explicit subtype is not specified.
  • DIRECTIVES
    Causes the SQL Option preprocessor to read the preprocessor directives contained in a separate user-created directives file or in the EXEC SQL options specified in the Build settings.
  • ENCODING
    Overrides character encoding translations.
  • EXIST-CHECK
    Specifies whether to create a package if some DBRM objects do not exist.
  • FILLSYSCAT
    Causes the preprocessor to insert information about EXEC SQL statement in the program into the SYSDBRM and SYSSTMT system catalog tables when the COBOL program is compiled.
  • GENSQLCA
    Generates a SQLCA structure in the program if none is defined.
  • GRANT-EXECUTE
    Specifies AUTHID to grant execute privileges on the package to.
  • HYPHEN-IN-CURSOR
    Permits hyphens in cursor names.
  • IGNORE-NESTED
    Specifies in programs with nested subroutines, the program-id at which to start generating database interface code.
  • ISOLATION-LEVEL
    Controls the way in which locks are acquired and released by the system.
  • LIBINCLUDE
    Causes the precompiler to expand and include copybooks coded with ++INCLUDE or –INC syntax.
  • LOCATION
    Specifies the location to which a DBRM is bound when the AUTOBIND preprocessor directive is used.
  • MAXSQL
    Specifies the maximum number of EXEC SQL statements the preprocessor can handle.
  • NEVERCLOSE
    This directive prevents the closing of open statements or cursors at commit or rollback.
  • NOFOR
    Causes the SQL Option run-time not to require FOR UPDATE clause in DECLARE CURSOR statements when UPDATE CURRENT OF CURSOR is specified.
  • NOT
    Specifies the ASCII character code to use for NOT character (¬).
  • OPTIMIZE
    This directive optimizes the code generated by the precompiler specifically for use on either PC or mainframe.
  • PACKAGE-OWNER
    Specifies the AuthID assigned to the package. This AuthID must have authority to execute all the SQL in the package.
  • PKGSET
    Causes the SQL Option run-time program to send additional information to set the current package set.
  • QUOTE
    Causes the preprocessor to recognize double quotes to delimit literals for quote character in SQL statements.
  • SAVE-RETURN-CODE
    Causes the SQL Option precompiler to save and then restore RETURN-CODE when calling SQL Option functions
  • SQLDA-VER
    The SQLDA structure used in the program for dynamic SQL statements.
  • SQLDS
    Allows the SQL Option Server to accept a PREPARE statement before a DECLARE statement in your source code (which is allowed in SQL/DS)
  • STRICT-DB2
    Enforces strict support for certain DB2 features that are generally permitted in default DB2 mode.
  • TIME
    Specifies the time format to be used with this program.
  • VALIDATE
    Causes the SQL Option preprocessor to verify all data objects referenced in your program's embedded SQL statements against the SQL Option system tables.
  • VALIDATE-ERR-LVL
    Specifies the error level to use for errors produced when the VALIDATE directive is used.
  • VALIDATE-LOGIN
    Causes the SQL Option preprocessor to ensure communications with an SQL Option Server prior to attempting to validate any SQL statements. If the log in fails, a fatal error is generated.
  • VERSION
    Specifies the new version identifier for a replacement package.
  • XDBFUNCS
    Allows use of all SQL Option commands (including SQL Option extensions) in embedded SQL.
Parent topic: Reference


ALLOW-HYPHEN

Enables the preprocessor to allow hyphens in SQL identifiers.

Syntax:

[NO]ALLOW-HYPHEN

Parameters:

None

Properties:

Default: NOALLOW-HYPHEN

Comments:

This directive is only supported in version DB2 V7 or later. Before DB2 V7, hyphens were not allowed in SQL identifiers and caused the token to be flagged as an error.

Parent topic: XDB Directive Options


APOST

Causes the preprocessor to recognize apostrophes to delimit literals for quote character in SQL statements.

Syntax:

[NO]APOST

Parameters:

None

Properties:

Default: NOAPOST

Comments:

Only set APOST if you are using apostrophes to delimit literals in SQL statements and you have set the project BUILD settings for quote character to be QUOTES.

Parent topic: XDB Directive Options


AUTHID

Causes the preprocessor to include code at SQL initialization that sets the value of your current SQLID to any valid authorization ID.

Syntax:

[NO]AUTHID
AUTHID[=authorization-ID#1;authorization-ID#2;...;authorization-ID#10]

Parameters:

authorization-ID | A valid authorization ID defined via SQL Wizard
NOAUTHID | No code will be generated

Properties:

Default: NOAUTHID

Comments:

If AUTHID is used without authorization ID, the current AUTHID is set to the default value specified via Options > SQL for DB2 from the IDE menus.

If you are doing static binding, the AUTHID directive also sets the value of the default qualifier. Mutliple authorization IDs are only supported when doing AUTOBIND, IDs must be delimited by a semi-colon with no spaces in the string. A maximum of 10 IDs are supported but the same number of DBRMs must be specified or the number of IDs greater than DBRMs will be ignored.

Parent topic: XDB Directive Options


AUTOBIND

Causes the preprocessor to automatically call the SQL Option Bind utility from within the debugging session after the compiler finishes generating the DBRM if no SQL errors were detected and if the DBRM preprocessor directive was set.

Syntax:

[NO]AUTOBIND

Parameters:

None

Properties:

Default: NOAUTOBIND

Comments:

If you don't use AUTOBIND, you can use the SQL Option Bind Utility to bind the program. See your SQL Option Link User's Guide for specific procedures.

The LOCATION preprocessor directive can be used with the AUTOBIND preprocessor directive to specify the location to which the DBRM is bound. If the LOCATION directive is not used, the Bind Utility uses the location specified via the IDE Options > SQL menu.

Parent topic: XDB Directive Options


AUTOCLOSE

Causes the SQL Option Server to automatically open and close statements after an insert, update, or delete command.

Syntax:

[NO]AUTOCLOSE

Parameters:

None

Properties:

Default: AUTOCLOSE

Comments:

Under NOAUTOCLOSE (which is not DB2-compatible), the SQL Option Server allows multiple execution of insert/update/delete commands without closing the statement. Closing is done at commit. This option is used for performance reasons.

Parent topic: XDB Directive Options


BEHAVIOR

Causes the SQL Option preprocessor to emulate the behavior of either the DB2 preprocessor or coprocessor.

Syntax:

BEHAVIOR={STACKED | COPROCESSOR}

Parameters:

STACKED | The SQL Option preprocessor behaves as if it were a stacked preprocessor, implying that data elements defined in COBOL COPY statements are not visible with SQL.
COPROCESSOR | The SQL Option preprocessor behaves as if it were a coprocessor, which is another module within the compiler, implying that data elements defined anywhere within the COBOL program are visible and available for use as host variables.

Properties:

Default: STACKED
Parent topic: XDB Directive Options


BIND-SQLID

Sets the current SQLID to this AuthID.

Syntax:

BIND-SQLID=authid

Parameters:

authid Any valid AuthID.

Properties:

Default: None

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


BLOCKING

Specifies the type of block fetching to use.

Syntax:

BLOCKING={FSR | SR | LB}

Parameters:

block-code The code for type of block fetching to perform when program is statically bound:
FSR | (Forced Single Row) does not use block fetching regardless of cursor type
SR | (Single Row) uses block fetching for read-only cursors and fetches a row at a time for ambiguous cursors
LB | (Limited Block) uses block fetching for read-only and ambiguous cursors
Default: LB

Properties:

Default: LB

Comments:

This directive only has meaning when program has been statically bound.

Multiple collection-ids are only supported when doing AUTOBIND, Collection-ids must be delimited by a semi-colon with no spaces in the string. A maximum of 10 collection-ids are supported but the same number of DBRMs must be specified or the number of collection-ids greater than DBRMs will be ignored. Also, you must specify at least one collection-id or a compile error SQL0335 will be generated when using multiple binds.

Parent topic: XDB Directive Options


CHANGE-CONTROL

Controls package creation during the bind process.

Syntax:

CHANGE-CONTROL=[ERROK][NOERR]

Parameters:

ERROK | Creates a package even if an error occurs during the bind process.
NOERR | Does not create a package if an error occurs during the bind process.

Properties:

Default: NOERR

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


COLLECTION-ID

Specifies the collection at the remote DRDA server where the package will be bound.

Syntax:

COLLECTION-ID=collection-id#1;collection-id#2;...;collection-id#10

Parameters:

collection-id The name of the collection to bind package to

Properties:

Default: No bind is done.

Comments:

This directive must be set if the STATIC-DRDA directive is used.

Mutliple collection-ids are only supported when doing AUTOBIND. Collection-ids must be delimited by a semi-colon with no spaces in the string. A maximum of 10 collection-ids are supported but the same number of DBRMs must be specified or the number of collection-ids greater than DBRMs will be ignored. Also, you must specify at least one collection-id or a compile error SQL0335 will be generated when using multiple binds.

Parent topic: XDB Directive Options


CONCAT

Specifies the ANSI character code to use for the CONCAT symbol (|).

Syntax:

CONCAT=(ansi-character-code}

Parameters:

ansi-character-code The ANSI character code to be mapped to the standard CONCAT symbol

Properties:

Default: 33

Comments:

DB2 uses the symbol (|) as the concatenation character. If your source contains a different character it can be mapped to the correct symbol.

Parent topic: XDB Directive Options


COPY

Causes the precompiler to expand copybooks included in your source code using standard COBOL COPY statements. Allows EXEC SQL statements and use of host variables to be defined within a COPY statement.

Syntax:

[NO]COPY

Parameters:

None

Properties:

Default: NOCOPY

Comments:

This directive must be set if you want to use host variables with a COPY statement. Care should be taken since this may cause compilation errors when porting code to the mainframe unless your installation has software that expands copybooks before passing source to the DB2 precompiler.

Parent topic: XDB Directive Options


CTRACE

Creates a trace file for submission to technical support if requested.

Syntax:

[NO]CTRACE

Parameters:

None

Properties:

Default: NOCTRACE

Comments:

The filename of the file that is created is sqltrace.txt. You also may be requested to use Compiler directive CHKECM(TRACE) which will create file ecmtrace.txt.

Parent topic: XDB Directive Options


DATE

Specifies the date format to be used with this program.

Syntax:

DATE={date-format}

Parameters:

date-format
The format in which date information is to be returned. One of:
ISO | yyyy-mm-dd
EUR | dd.mm.yyyy
JIS | yyyy-mm-dd
USA | mm/dd/yyyy
LOCAL | format needs to be defined from the IDE, using Options > SQL for DB2 .

Properties:

Default: Use the default settings defined by the IDE, using Options > SQL for DB2 .

Comments:

Use this directive to override the default settings.

Parent topic: XDB Directive Options


DB2

Causes the SQL Option Server to return DB2 error codes and messages when compiling and running, and to close all open cursors at COMMIT and ROLLBACK (the DB2 standard).

Syntax:

[NO]DB2

Parameters:

None

Properties:

Default: DB2

Comments:

The DB2 directive combines the DB2CLOSE and DB2ERROR directive. If the WITH HOLD clause is included in your SQL statement, cursors remain open after a COMMIT, even if the DB2 preprocessor directive is specified.

Parent topic: XDB Directive Options


DB2CLOSE

Causes the SQL Option Server to close all open statements and cursors at COMMIT and ROLLBACK (the DB2 standard).

Syntax:

[NO]DB2CLOSE

Parameters:

None

Properties:

Default: DB2CLOSE

Comments:

If the WITH HOLD clause is included in your SQL statement, cursors remain open after a COMMIT, even if the DB2CLOSE preprocessor directive is specified.

Parent topic: XDB Directive Options


DB2ERROR

Causes the SQL Option Server to return DB2 error codes and messages when the program is compiled or executed.

Syntax:

[NO]DB2ERROR

Parameters:

None

Properties:

Default: DB2ERROR
Parent topic: XDB Directive Options


DB2VER (Deprecated)

Specifies the DB2 version used by the SQL Option preprocessor for syntax checking.

Syntax:

DB2VER={V7 | V8 | V9}

Parameters:

V7
Use DB2 V7 rules for syntax checking.
V8
Use DB2 V8 rules for syntax checking.
V9
Use DB2 V9 rules for syntax checking.

Properties:

Default: V8

Comments:

Because some syntax checking takes place on the server when using DB2 V7 or later, VALIDATE is turned on by default.

Specify NOVALIDATE if you do not want SQL statements to be validated. Be aware that doing this could cause errors that are reported only after the SQL statement is executed. VALIDATE also requires all referenced tables and columns to be defined.

Parent topic: XDB Directive Options


DBRM

Causes the SQL Option preprocessor to generate one or more DBRM files.

Syntax:

DBRM[=[path\]filename#1[;[path\]filename#2;...;[path\]filename#10]]
NODBRM

Parameters:

path
The full path to an alternative directory where you want to store the DBRM file. If no path is specified, the DBRM file is written to the working directory.
filename
An alternative filename prefix for the generated DBRM file. If no filename is specified, the default filename prefix is the same as the COBOL source filename. All generated DBRM files have a .DBR extension. When AUTOBIND is also specified, you can specify up to ten DBRM files. Otherwise, the limit is one. See Comments below for more information.

Properties:

Default: NODBRM

Dependencies:

When specifying more than one DBRM file, you must also specify AUTOBIND.

Comments:

You must specify the DBRM preprocessor directive to produce a DBRM. When you specify NODBRM (default), no file is generated.

By default, the SQL Option preprocessor produces only expanded source code.

Multiple DBRM files can be generated only if AUTOBIND is also specified. When specifying multiple DBRM files:

  • Delimit DBRM paths/filenames using a semi-colon (;) with no spaces in the string.
  • A maximum of 10 DBRM files are supported.
  • If only one DBRM is specified and more than one collection-id, authid or location is specified, a compile error SQL0334 is generated.
  • If more than one DBRM is specified, then multiple collection-ids, authids, and locations can be specified but are limited to the number of DBRM file names specified. Any number in excess is ignored.
  • If the number of collection-ids, authids, and locations is not the same as the number of DBRM file names, the values used default to the previous value if a new one is not specified.
Parent topic: XDB Directive Options


DECLARE

Tells the preprocessor that host variables are declared in a BEGIN/END DECLARE section of a COBOL program.

Syntax:

[NO]DECLARE

Parameters:

None

Properties:

Default: NODECLARE

Comments:

The default is NODECLARE, which makes the BEGIN/END DECLARE section optional.

Parent topic: XDB Directive Options


DEFAULT-CHAR

Specifies character subtype for all new character columns for which an explicit subtype is not specified.

Syntax:

DEFAULT-CHAR={BITS | SBCS | DBCS | SYSDEFAULT}

Parameters:

default-code
BITS | specifies that the target relational database uses the FOR BITS DATA SQL
SBCS | specifies that the target relational database uses the FOR SBCS DATA SQL
DBCS | specifies that the target relational database uses the FOR MIXED DATA SQL
SYSDEFAULT | (recommended) specifies that the target relational database uses the system default character subtype.
Default: SYSDEFAULT

Properties:

Default: SYSDEFAULT

Comments:

This directive only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


DIRECTIVES

Causes the SQL Option preprocessor to read the preprocessor directives contained in a separate user-created directives file or in the EXEC SQL options specified in the Build settings.

Syntax:

NODIRECTIVES
or
DIRECTIVES=filename

Parameters:

filename Name of file to get preprocessor directives from

Properties:

Default: NODIRECTIVES

Comments:

When you specify NODIRECTIVES, the system uses only preprocessor directives set in Build settings.

The filename parameter can include a full path, or an environment variable pointing to a path.

Parent topic: XDB Directive Options


ENCODING

Overrides character encoding translations.

Syntax:

ENCODING={ASCII | EBCDIC | UNICODE}

Properties:

Default: None

Comments:

Use this directive to override the character set translation type associated with the character set type specified by the CHARSET compiler directive. For example, use ENCODING=UNICODE when you want the program to receive Unicode data into standard (not NATIONAL) variables that would ordinarily contain either ASCII or EBCDIC data.

When not specified, encoding is dictated by the CHARSET compiler directive setting, which is either ASCII or EBCDIC.

Parent topic: XDB Directive Options


EXIST-CHECK

Specifies whether to create a package if some DBRM objects do not exist.

Syntax:

EXIST-CHECK={REQUIRED|OPTIONAL}

Parameters:

REQUIRED | Specifies that a package will be created only if all DBRM objects exist.
OPTIONAL | Specifies that a package will be created even if some DBRM objects do not exist.

Properties:

Default: OPTIONAL

Comments:

This directive is only relevant for a program that has been statically bound.

Parent topic: XDB Directive Options


FILLSYSCAT

Causes the preprocessor to insert information about EXEC SQL statement in the program into the SYSDBRM and SYSSTMT system catalog tables when the COBOL program is compiled.

Syntax:

[NO]FILLSYSCAT

Parameters:

None

Properties:

Default: NOFILLSYSCAT

Comments:

The default is NOFILLSYSCAT, which causes no catalog information to be created or saved. Use of this directive may slow processing while the preprocessor logs on to the SQL Option Server and writes the information to the system tables. You must have SYSADM privileges on the system tables to use this directive. See the SQL Option SQL Reference for a description of the columns in these system tables.

Parent topic: XDB Directive Options


GENSQLCA

Generates a SQLCA structure in the program if none is defined.

Syntax:

[NO]GENSQLCA

Parameters:

None

Properties:

Default: NOGENSQLCA

Comments:

The structure will be defined if the structure SQLCA is not defined or included. If a separate field SQLCODE is defined in the program, the field SQLCODE in structure will be defined as SQLCADE.

Parent topic: XDB Directive Options


GRANT-EXECUTE

Specifies AUTHID to grant execute privileges on the package to.

Syntax:

GRANT-EXECUTE={PUBLIC | NONE |(authorization-ID)}

Parameters:

PUBLIC | Grants execute privileges on the package to public.
NONE | No execute privileges granted.
authorization-ID | Grants execute privileges to the given authorization ID, which must be a valid authorization ID defined via SQL Wizard.

Properties:

Default: PUBLIC

Comments:

  • This directive has meaning only when the program has been statically bound.
  • If you do not specify this directive, execute privileges on the package are automatically granted to PUBLIC.
  • To disable this directive, specify GRANT-EXECUTE=NONE.
Parent topic: XDB Directive Options


HYPHEN-IN-CURSOR

Permits hyphens in cursor names.

Syntax:

[NO]HYPHEN-IN-CURSOR

Parameters:

None

Properties:

Default: | NOHYPHEN-IN-CURSOR
Synonym: | HYPHEN

Comments:

The default is NOHYPHEN-IN-CURSOR (or NOHYPHEN), which does not allow hyphens in cursor names. Specify HYPHEN-IN-CURSOR (or HYPHEN) for backward compatibility with older DB2 mode programs that use hyphenated cursor names.

Parent topic: XDB Directive Options


IGNORE-NESTED

Specifies in programs with nested subroutines, the program-id at which to start generating database interface code.

Syntax:

IGNORE-NESTED={program-id}

Parameters:

program-id Any nested program encountered before the given program-id is ignored and no database interface code is generated for it. You must specify a program-id in the COBOL source code; otherwise, a compile error results.

Properties:

Default: If you specify IGNORE-NESTED without a parameter, database interface code is generated for the outermost program only.

Comments:

You can only generate database interface code in one program in nested programs. If you need to have SQL statements in multiple programs, compile the subroutines as separate programs.

Parent topic: XDB Directive Options


ISOLATION-LEVEL

Controls the way in which locks are acquired and released by the system.

Syntax:

ISOLATION-LEVEL=[CS][ALL][RR][CHANGE][NC]

Parameters:

CS | The execution of SQL statements in the package and the current row in which the database cursor is positioned are protected from the actions of concurrent users for changes the requester makes.
ALL | The execution of SQL statements in the package is protected from the actions of concurrent users for rows the requester reads and changes.
RR | The execution of SQL statements in the package and the current row in which the database cursor is positioned are protected from the actions of concurrent users for rows the requester reads and changes, as well as phantom rows.
CHANGE | The execution of SQL statements in the package is protected from the actions of concurrent users for changes the requester makes.
NC | Commitment control is not used. COMMIT and ROLLBACK statements are not required for changes to be visible to concurrent users.

Properties:

Default: CS

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


LIBINCLUDE

Causes the precompiler to expand and include copybooks coded with ++INCLUDE or –INC syntax.

Syntax:

[NO]LIBINCLUDE

Parameters:

None

Properties:

Default: LIBINCLUDE

Comments:

This directive is automatically turned on if you use the PANVALET or LIBRARIAN directive. If you don't want to allow host variables in a –INC or ++INCLUDE copybook, set the NOLIBINCLUDE directive.

Parent topic: XDB Directive Options


LOCATION

Specifies the location to which a DBRM is bound when the AUTOBIND preprocessor directive is used.

Syntax:

LOCATION=location-name#1;location-name#2;...;location-name#10

Parameters:

location-name Location name to bind DBRM to

Properties:

Default: Use the location specified via the IDE Options > SQL menu.

Comments:

By default, the AUTOBIND preprocessor directive uses the location specified via the IDE Options>SQL menu unless this directive is specified.

Multiple locations are only supported when doing AUTOBIND. Locations must be delimited by a semi-colon with no spaces in the string. A maximum of 10 locations are supported but the same number of DBRMs must be specified or the number of locations greater than DBRMs will be ignored.

Parent topic: XDB Directive Options


MAXSQL

Specifies the maximum number of EXEC SQL statements the preprocessor can handle.

Syntax:

MAXSQL={ number }

Parameters:

number The maximum number of EXEC SQL statements to process.

Properties:

Default: 750

Comments:

The preprocessor can handle up to 750 EXEC SQL statements per program by default. If your program gets a compiler error COBSQL0299S, use this preprocessor directive to increase the maximum.

Parent topic: XDB Directive Options


NEVERCLOSE

This directive prevents the closing of open statements or cursors at commit or rollback.

Syntax:

[NO]NEVERCLOSE

Parameters:

None

Properties:

Default: NONEVERCLOSE

Comments:

Under NEVERCLOSE (which is not DB2-compatible), the SQL Option Server does not close cursors or open statement when a commit or rollback is encountered. This option is used for performance reasons.

Parent topic: XDB Directive Options


NOFOR

Causes the SQL Option run-time not to require FOR UPDATE clause in DECLARE CURSOR statements when UPDATE CURRENT OF CURSOR is specified.

Syntax:

[NO]FOR

Parameters:

None

Properties:

Default: FOR

Comments:

If not specified, UPDATE CURRENT OF CURSOR clause will generate a SQL error when statement executed.

You cannot specify FOR explicitly.

Parent topic: XDB Directive Options


NOT

Specifies the ASCII character code to use for NOT character (¬).

Syntax:

NOT={ansi-character-code }

Parameters:

ansi-character-code The ANSI character value to be mapped to the ¬ symbol.

Properties:

Default: 172

Comments:

For compatibility with DB2 on the mainframe this COBOL system allows the use of the NOT symbol in SQL statements. If your source uses a different ANSI code for the NOT symbol, this directive allows you to specify the ANSI value to be mapped for the NOT symbol.

Parent topic: XDB Directive Options


OPTIMIZE

This directive optimizes the code generated by the precompiler specifically for use on either PC or mainframe.

Syntax:

OPTIMIZE= run-time-environment

Parameters:

run-time-environment Specify OPTIMIZE=MAINFRAME if your program uses COMP as data type for most numeric fields including fields described in SQLCA and SQLDA copybooks.

Specify OPTIMIZE=PC if your program uses COMP-5 as data type for most numeric fields including fields described in SQLCA and SQLDA copybooks.

Properties:

Default: OPTIMIZE=MAINFRAME

Comments:

The precompiler will generate code to swap bytes for all numeric host variables that don't match the optimize setting except for variables defined in an SQLDA. Variables defined in the SQLDA must match the optimize setting or an error message is generated. Obviously, if you intermix defining numeric variables using a mix of COMP/COMP-5 fields, more code is generated by the precompiler to handle this which also affects portability and performance.

Parent topic: XDB Directive Options


PACKAGE-OWNER

Specifies the AuthID assigned to the package. This AuthID must have authority to execute all the SQL in the package.

Syntax:

PACKAGE-OWNER=authid

Parameters:

authid Any valid AuthID.

Properties:

Default: None

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


PKGSET

Causes the SQL Option run-time program to send additional information to set the current package set.

Syntax:

[NO]PKGSET

Parameters:

None

Properties:

Default: NOPKGSET

Comments:

The default is NOPKGSET, which prevents additional information from being sent to the server, and any set current package set SQL command will fail.

Parent topic: XDB Directive Options


QUOTE

Causes the preprocessor to recognize double quotes to delimit literals for quote character in SQL statements.

Syntax:

[NO]QUOTE

Parameters:

None

Properties:

Default: NOQUOTE

Comments:

Only set QUOTE if you are using double quotes to delimit literals in SQL statements and you have set the project BUILD settings for quote character to be APOST.

Parent topic: XDB Directive Options


SAVE-RETURN-CODE

Causes the SQL Option precompiler to save and then restore RETURN-CODE when calling SQL Option functions

Syntax:

[NO]SAVE-RETURN-CODE

Parameters:

None

Properties:

Default: SAVE-RETURN-CODE

Comments:

Use NOSAVE-RETURN-CODE if your COBOL dialect doesn't recognize the COBOL special register RETURN-CODE.

Parent topic: XDB Directive Options


SQLDA-VER

The SQLDA structure used in the program for dynamic SQL statements.

Syntax:

SQLDA-VER={version}

Parameters:

version
Number to identify type of SQLDA structure used.
0 | XDB structure
1 | DB2 mainframe structure

Properties:

Default: 1

Comments:

Set SQLDA-VER=1 when mainframe style SQLDA's are used in the program. Also, all SQLDA structures used in the program must use the same structure. They must all be mainframe style or XDB style or an error message is generated.

Parent topic: XDB Directive Options


SQLDS

Allows the SQL Option Server to accept a PREPARE statement before a DECLARE statement in your source code (which is allowed in SQL/DS)

Syntax:

[NO]SQLDS

Parameters:

None

Properties:

Default: NOSQLDS
Parent topic: XDB Directive Options


STRICT-DB2

Enforces strict support for certain DB2 features that are generally permitted in default DB2 mode.

Syntax:

[NO]STRICT-DB2

Parameters:

None

Properties:

Default: NOSTRICT-DB2

Comments:

Mainframe DB2 does not let you declare a cursor before including the SQLCA (something allowed by the DB2 mode of SQL Option. STRICT-DB2 forces SQL Option (when running in DB2 mode) to generate an error in this circumstance. STRICT-DB2 also ensures that an SQLCA is provided by the program.

Parent topic: XDB Directive Options


TIME

Specifies the time format to be used with this program.

Syntax:

TIME={time-format}

Parameters:

time-format The format in which time information is to be returned. One of:
ISO | hh.mm.ss
EUR | hh.mm.ss
JIS | hh.mm.ss
USA | hh.mm.ss AM or PM
LOCAL | format needs to be defined from the IDE, using Options > SQL for DB2.
Default: Use the default settings defined by the IDE, using Options > SQL for DB2.

Properties:

Default: Use the default settings defined by the IDE, using Options > SQL for DB2.

Comments:

Use this directive to override the default settings.

Parent topic: XDB Directive Options


VALIDATE

Causes the SQL Option preprocessor to verify all data objects referenced in your program's embedded SQL statements against the SQL Option system tables.

Syntax:

[NO]VALIDATE

Parameters:

None

Properties:

Default: VALIDATE

Comments:

When VALIDATE is specified, the SQL Option preprocessor attempts to log on to the SQL Option Server where it checks whether SQL statements can be executed and whether all referenced tables and columns are present. Note that the SQL Option Server must be available when using VALIDATE or a COBSQ0013W error occurs.

Parent topic: XDB Directive Options


VALIDATE-ERR-LVL

Specifies the error level to use for errors produced when the VALIDATE directive is used.

Syntax:

VALIDATE-ERR-LVL = (error-lvl-code)

Parameters:

error-lvl-code A one-byte character code to indicate what error level to generate when an SQL error results from validating an SQL statement. Choose from one of the following codes:
I | Informational
W | Warning
E | Error
S | Severe error
Default: W

Properties:

Default: W
Parent topic: XDB Directive Options


VALIDATE-LOGIN

Causes the SQL Option preprocessor to ensure communications with an SQL Option Server prior to attempting to validate any SQL statements. If the log in fails, a fatal error is generated.

Syntax:

[NO]VALIDATE-LOGIN

Parameters:

None

Properties:

Default: NOVALIDATE-LOGIN

Comments:

The default is NOVALIDATE-LOGIN, which produces a warning message if communications with the SQL Option Server cannot be established. This directive only affects compilation, not run time.

Parent topic: XDB Directive Options


VERSION

Specifies the new version identifier for a replacement package.

Syntax:

VERSION=version-id

Parameters:

version-id A valid version identifier. This can be up to 64 bits in length.

Properties:

Default: None

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


XDBFUNCS

Allows use of all SQL Option commands (including SQL Option extensions) in embedded SQL.

Syntax:

[NO]XDBFUNCS

Parameters:

None

Properties:

Default: NOXDBFUNCS

Comments:

The default is NOXDBFUNCS, which limits the embedded SQL functions to standard DB2 SQL functions, and does not permit SQL Option extensions.

Parent topic: XDB Directive Options


Batch SQL Commands

  • Batch SQL Commands Overview
  • DISPLAY
  • DUMP
  • ERRSTOP
  • IF FAIL
  • IF SUCCEED
  • NODISPLAY
  • NOSTOP
  • SCROLL
  • TERSE
  • VERBOSE
  • WRAP
  • Examples
Parent topic: Reference


Batch SQL Commands Overview

Batch SQL commands are a set of special commands that can be included in a script file to present messages, display results, and detect errors.

Batch commands can be added to your script file using the SQL Edit window or using an ASCII text editor.

Parent topic: Batch SQL Commands


DISPLAY (Batch SQL commands)

DISPLAY

This batch SQL command causes the system to display the query result on the Result window. Since this is the default mode, the DISPLAY command is typically used to return to normal display operation following the execution of a NODISPLAY command (see NODISPLAY command, below).

The syntax is:

DISPLAY;

The DISPLAY command must be placed immediately after the query statement on which you want it to take effect.

For example:

SELECT pno, pname FROM part WHERE color='BLUE';
DISPLAY;

When the system encounters this DISPLAY command, it displays the Result window containing the part number and name for all blue parts.

Once a DISPLAY command is executed, it will remain in effect for the rest of the script, or until a NODISPLAY command is encountered. Together, the DISPLAY and NODISPLAY commands can be used to selectively display or suppress the Result screens at certain points in the batch file.

For example:

SELECT * FROM customer
WHERE state="CA"
NODISPLAY;            --Suppress Result Screen
IF FAIL EXIT;
UPDATE customer SET balance = balance - $50
WHERE state="CA";
SELECT customer.*, orders.o_no, orders.o_date
FROM customer, orders
WHERE state = "CA";
DISPLAY;            --Display Result Screen

This example suppresses the Result window of the first query and displays it for the second.

The Display command only works when the batch script is run from SQLWizard. To see query results when running a script from a command prompt, use the Dump or Print batch SQL command to output the results to files.

Parent topic: Batch SQL Commands


DUMP

This batch SQL command outputs the query result to a file

The syntax is:

DUMP file_name;

The file name specified by this command is the destination of the output of the query result. If the same file name is used in multiple DUMP commands, each query result set is appended to the one that precedes it in that file.

The DUMP command must be placed immediately after each query statement on which you want it to take effect.

For example:

SELECT * FROM customer
WHERE state="CA"
DUMP ResultSet1.out;  --Write result set to a file named ResultSet1.out

SELECT * FROM customer
WHERE state="MD"
DUMP ResultSet1.out;  --Append result set to ResultSet1.out

SELECT * FROM customer
WHERE state="NY"
DUMP ResultSet2.out;  --Write result set to a file named ResultSet2.out

The DUMP command is only effective when the batch script is run from the development environment's command prompt; it has no effect if the batch script is run from SQLWizard.

Parent topic: Batch SQL Commands


ERRSTOP

This batch SQL command causes the system to pause for a keystroke when it encounters an error. Since this is the default mode, the ERRSTOP command is typically used to return to ERRSTOP operation following the execution of a NOSTOP command (see NOSTOP command, below).

The syntax is:

ERRSTOP;

The ERRSTOP command must be placed immediately after the query on which you want it to start taking effect. Once an ERRSTOP command is executed, it will remain in effect for the rest of the script, or until a NOSTOP command is encountered. Together, the ERRSTOP and NOSTOP commands can be used to selectively enable or disable error processing at certain points in the batch file.

For example:

UPDATE employee
SET com = 0
WHERE dept = "2020";
NOSTOP;          --Do not stop on error
UPDATE customer SET balance=0
WHERE balance > 0;
ERRSTOP;          --Stop on error

In this example, the system ignores errors that occur when updating the EMPLOYEE table, but stops on errors that occur when updating the CUSTOMER table.

Parent topic: Batch SQL Commands


IF FAIL

This batch SQL command displays a message or terminates the batch process in the following circumstances:

  • an error occurs.
  • a query retrieves no records.
  • a DELETE, UPDATE or INSERT command affects no records.

The syntax is:

IF FAIL {"message" | EXIT };

where message is the message to be displayed upon failure. After displaying the message, the system waits for the user to press Enter or click OK before continuing with the batch file.

If EXIT is used, the system terminates the batch process when a failure occurs.

The IF FAIL command must be placed after the query statement to which it will apply. If other batch commands are associated with this statement (e.g., DISPLAY, TERSE), IF FAIL must be placed after them.

For example:

UPDATE partsupp
  SET qty=qty*1.25
  WHERE sno IN
(SELECT sno
     FROM supplier
     WHERE city = 'LONDON');
DISPLAY;
IF FAIL "No records updated. Aborting";
IF FAIL exit;

This example updates the partsupp table and displays an error message if the UPDATE command does not update any records. The second IF FAIL terminates the script after the user acknowledges the error message.

Parent topic: Batch SQL Commands


IF SUCCEED

This batch SQL command displays a message or terminates the batch process if the SQL command retrieves or affects at least one record.

The syntax is:

IF SUCCEED {"message" | EXIT};

where message is the message displayed. After displaying the message, the system waits for the user to press Enter or click OK before continuing with the batch file.

If EXIT is used, the system terminates the batch process.

The IF SUCCEED command must be placed after the query statement to which it will apply. If other batch commands are associated with this statement (e.g., DISPLAY, TERSE), IF SUCCEED must be placed after them.

For example:

UPDATE partsupp
  SET qty=qty*1.25
  WHERE sno IN
(SELECT sno
     FROM supplier
     WHERE city = 'LONDON');
NODISPLAY;
IF SUCCEED "Update successful.";

This example updates the partsupp table and displays a message if the UPDATE command updates any record. Processing continues when the user acknowledges the message.

Parent topic: Batch SQL Commands


NODISPLAY

This batch SQL command suppresses the query Result window. When NODISPLAY is in effect, query results are not displayed on the Result window.

The syntax is:

NODISPLAY;

The NODISPLAY command must be placed immediately after the query statement on which you want it to take effect.

For example:

SELECT pno, pname FROM part WHERE color='BLUE';
NODISPLAY;

In this example, the results of the SELECT statement will not be displayed.

Once a NODISPLAY command is executed, it will remain in effect for the rest of the script, or until a DISPLAY command is encountered. Together, the DISPLAY and NODISPLAY commands can be used to selectively display or suppress the Result windows at certain points in the batch file.

For example:

SELECT * FROM customer
WHERE state="CA";
NODISPLAY;            --Suppress Result Screen
IF FAIL EXIT;
UPDATE customer SET balance = balance - $50
WHERE state="CA";
SELECT customer.*, orders.o_no, orders.o_date
FROM customer, orders
WHERE state = "CA";
DISPLAY;            --Display Result Screen

This example suppresses the Result screen of the first query and displays it for the second.

Parent topic: Batch SQL Commands


NOSTOP

This batch SQL command instructs the system to process errors without pausing for user acknowledgment.

The syntax is:

NOSTOP;

The NOSTOP command must be placed immediately after the query on which you want it to start taking effect. Once a NOSTOP command is executed, it will remain in effect for the rest of the script, or until a ERRSTOP command is encountered. Together, the ERRSTOP and NOSTOP commands can be used to selectively enable or disable error processing at certain points in the batch file.

For example:

UPDATE employee
SET com = 0
WHERE dept = "2020";
NOSTOP;          --Do not stop on error
UPDATE customer SET balance=0
WHERE balance > 0;
ERRSTOP;          --Stop on error

This example directs the system to ignore errors that occur when updating the EMPLOYEE table, but to stop on errors that occur when updating the CUSTOMER table.

Parent topic: Batch SQL Commands


SCROLL

The SCROLL batch SQL command is provided for compatibility with scripts created by earlier versions of XDB Server. This command, when executed, will produce the same results as the DISPLAY command. If you are writing a new script, use DISPLAY rather than SCROLL.

Parent topic: Batch SQL Commands


TERSE

The TERSE batch SQL command sets "quiet" mode. In quiet mode, SQLWizard suppresses the display of command and status messages. It also automatically responds to all prompts with a "Y." In quiet mode, only system-generated error messages are displayed. TERSE operation can be turned off by issuing the VERBOSE command.

The TERSE command must be placed immediately after the query on which you want it to start taking effect. Once a TERSE command is executed, it will remain in effect for the rest of the script, or until a VERBOSE command is encountered. Together, the TERSE and VERBOSE commands can be used to selectively enable or disable quiet mode operation at certain points in the batch file.

Parent topic: Batch SQL Commands


VERBOSE

The VERBOSE batch SQL command is used to set "normal" display mode. Under normal mode, all messages, commands and prompts are displayed on the screen. Since VERBOSE is the default mode, this command is typically used to return to normal operation following the execution of a TERSE command (see TERSE command, above).

The VERBOSE command must be placed immediately after the query on which you want it to start taking effect. Once a VERBOSE command is executed, it will remain in effect for the rest of the script, or until a TERSE command is encountered. Together, the TERSE and VERBOSE commands can be used to selectively enable or disable quiet mode operation at certain points in the batch file.

Parent topic: Batch SQL Commands


WRAP

The WRAP batch SQL command is provided for compatibility with scripts created by earlier versions of XDB Server. This command, when executed, produces the same results as the DISPLAY command. If you are writing a new script, use DISPLAY rather than WRAP.

Parent topic: Batch SQL Commands


Examples

The example below shows a batch SQL file prompting for a host variable called hDeptName.

SELECT * from dept WHERE dname = :hDeptName;
CREATE TABLE temp
  SELECT dname, e_no, lname, fname
  FROM dept, employee
  WHERE dept.Dept = employee.Dept
  AND dept.Dname = :hDeptName;
SELECT dname, e_no, lname, fname, o_no
  FROM temp, orders
  WHERE temp.e_no = orders.s_no;
UPDATE employee
  SET payrate = payrate * 1.1
  WHERE e_no IN
  (SELECT e_no
  FROM temp);
DROP TABLE temp;

When this script is executed, the user will be prompted to enter a department name, and this value will be is substituted into the query.

The example below shows the same batch SQL file, but this one includes additional batch commands that provide display and error-processing instructions. Notice that there is a semicolon ';' at the end of each command, including the batch commands.

SELECT * from dept WHERE dname = :hDeptName;
NODISPLAY;            --Suppress Result Screen
CREATE TABLE temp
  SELECT dname, e_no, lname, fname
  FROM dept, employee
  WHERE dept.Dept = employee.Dept
  AND dept.Dname = :hDeptName;
SELECT dname, e_no, lname, fname, o_no
  FROM temp, orders
  WHERE temp.e_no = orders.s_no;
DISPLAY;            --Display Result Screen
IF FAIL "No Records Found";  --If no records selected,
IF FAIL EXIT;          --show Message and Exit
UPDATE employee
  SET payrate = payrate * 1.1
  WHERE e_no IN
  (SELECT e_no
  FROM temp);
DROP TABLE temp;
Parent topic: Batch SQL Commands


Batch Import Commands

  • APPEND_ERR_FILE
  • APPEND_REC_FILE
  • ASCII_CODEPAGE (DSNTIAUL format)
  • BAD_REC_FILE
  • EBCDIC_CODEPAGE (DSNTIAUL format)
  • EBCDIC_TO_ASCII
  • ERR_LOG_FILE
  • FIELDS
  • FILENAME
  • FLD_DELIMITER (Free-format ASCII)
  • FORMAT
  • HEADING
  • INSERT_MODE
  • INS_NULL
  • NULL_PERM
  • ON_ERROR
  • OFFSETS
  • QUOTES
  • REC_DELIMITER
  • REPLACE
  • SPACES
  • SRC_LENS
  • TABLE
  • TYPES
  • USE_PIC
  • Batch Import Examples
Parent topic: Reference


APPEND_ERR_FILE

Appends errors to an existing error log file. The syntax is:

APPEND_ERR_FILE = { Y | N };

If APPEND_ERR_FILE is set to Y, then errors are appended to the existing error message log file. If APPEND_ERR_FILE is set to N (default), then the old error message log file is overwritten.

The log file appended to is the one specified in the ERR_LOG_FILE command. APPEND_ERR_FILE is an optional Batch Import command.

For example:

APPEND_ERR_FILE = Y;

causes any error messages produced as a result of the Batch Import to be appended to the existing error log file.

Parent topic: Batch Import Commands


APPEND_REC_FILE

Appends errors to an existing record log file. The syntax is:

APPEND_REC_FILE = { Y | N };

If APPEND_REC_FILE is set to N (default), then the old record log file is overwritten. If APPEND_REC_FILE is set to Y, then records are appended to the existing log file.

The log file appended to is the one specified in the most recent BAD_REC_FILE command. APPEND_REC_FILE is an optional Batch Import command.

For example:

APPEND_REC_FILE = Y;

causes any error messages produced as a result of the Batch Import to be appended to the existing record log file.

Parent topic: Batch Import Commands


ASCII_CODEPAGE (DSNTIAUL format)

Specifies the destination character set. The syntax is:

ASCII_CODEPAGE = n

where n is the code page number.

By default, Import assumes character data is stored in a DSNTIAUL source file (using the EBCDIC character set) and converts it to the American ASCII character set by inserting it into an XDB Server table.

You can have the Import utility translate character data containing characters from any international EBCDIC character set to any international ASCII character set using the code page feature in Import. For the ASCII code page number, use the default ASCII character set for your country. EBCDIC to ASCII translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM location.

When the Import utility uses code page options, the values entered for EBCDIC_CODEPAGE and ASCII_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert DSNTIAUL data in EBCDIC format to XDB Server data in ASCII.

Parent topic: Batch Import Commands


BAD_REC_FILE

Causes records containing errors to be written to the file (called the record log file) with the file name specified after this command. This command only used for fixed-format ASCII, free-format ASCII, and DSNTIAUL file formats. The syntax is:

BAD_REC_FILE = filename;

where filename is the name of the file, including extension and path, for the record log file. If you don't specify a path, the record log file is put in your current directory.

If a record contains multiple errors, a copy of that record is written to the record log file for each error.

Note:

If this batch command is used for a batch import of a file type other than DSNTIAUL, Free- or Fixed-format ASCII file, then a warning is generated as a reminder that a record log file is not generated for the import of other file types.

For example:

BAD_REC_FILE = C:\LOGFILES\BATCH.BRF;

saves records with errors to the file batch.brf.

Parent topic: Batch Import Commands


EBCDIC_CODEPAGE (DSNTIAUL format)

Specifies the source character set. The syntax is:

EBCDIC_CODEPAGE = n

where n is the code page number.

By default, Import assumes character data is stored in a DSNTIAUL source file using the American EBCDIC character set and converts it to the American ASCII character set before inserting it into an XDB Server table. See "ASCII Table" for a listing of ASCII character sets.

You can have the Import utility translate character data containing characters from any international EBCDIC character set to any international ASCII character set using the code page feature in Import. For the EBCDIC code page number, use the default EBCDIC character set for your country. EBCDIC to ASCII translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM.

When the Import utility uses code page options, the values entered for EBCDIC_CODEPAGE and ASCII_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert DSNTIAUL data in EBCDIC format to XDB Server data in ASCII format.

Parent topic: Batch Import Commands


EBCDIC_TO_ASCII

Specifies whether EBCDIC data should be converted to ASCII during DSNTIAUL imports. The syntax is:

EBCDIC_TO_ASCII = {Y | N | NA} [,{Y | N | NA}]...;

where the number of Ys, Ns and NAs is equal to the number of fields in the table. If EBCDIC_TO_ASCII is set to N, data are not converted to ASCII. If EBCDIC_TO_ASCII is set to Y (default), the data are assumed to be EBCDIC and are converted to the ASCII equivalent. If EBCDIC_TO_ASCII is set to NA, conversion is not applicable for the field type.

EBCDIC_TO_ASCII is an optional Batch Import command.

Note: When saving specifications for DB2 DSNTIAUL format, an EBCDIC_TO_ASCII statement is included with all fields set to Y (yes).

For example:

EBCDIC_TO_ASCII = n,n,n,n;

defines this import command so that none of the fields of a four-column table are converted to ASCII in this transaction.

Parent topic: Batch Import Commands


ERR_LOG_FILE

Causes error messages from the Import batch transaction to be written to the file name specified after this command (called the error log file). The syntax is:

ERR_LOG_FILE = filename;

where filename is the name of the file, including extension and path, for the error log file.

If you don't specify a path, the error log file is put in your current directory. Error messages are still displayed on the screen. ERR_LOG_FILE is an optional batch Import command.

For example:

ERR_LOG_FILE = C:\LOGFILES\BATCH.ELF;

saves error messages to the batch.elf file.

Parent topic: Batch Import Commands


FIELDS

Specifies the names of the fields for the XDB Server table being created. The syntax of the statement is:

FIELDS = field-name1 [, field-name2]. . .;

where the field names are listed in order, and separated by commas (,).

The FIELDS Batch Import command is required for every transaction when importing a file that does not include the table headings (as specified with the HEADING Batch Import command). If field names are provided in the file being imported, those names can be used as default field names. Otherwise the field names must be specified.

For example:

FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;

will import a file into a new table with field names similar to the EMPLOYEE table in the TUTORIAL location.

Parent topic: Batch Import Commands


FILENAME

Specifies the path name of the source file. The syntax of the statement is:

FILENAME = filename

where filename is the full path specification and file of the source file.

For example:

FILENAME = C:\XDB\APPS\employee.asc;

specifies the location of the source file as c:\xdb\apps and the file name employee.asc.

Parent topic: Batch Import Commands


FLD_DELIMITER (Free-format ASCII)

Specifies the delimiter(s) that separate the fields in delimited, free-format ASCII files. You may specify the delimiter(s) as:

  • A Character String. Quotes are optional when specifying a character string for the delimiter If desired, you may enclose the string in double quotes (" "). Quotes in a delimiter specification are ignored by the Import program. For example, "@@" is the same as @@.
  • ASCII Decimal Notation. If you specify the delimiter in ASCII decimal notation, enclose each ASCII code in angle brackets. For example, to use the decimal notation for a semicolon (;), enter the string <059> either with or without quotes.
  • Combination Character String and ASCII Code. You can mix ASCII codes with keyboard characters to form a delimiter. For example: <59>ab<32>c would be a valid delimiter. See "ASCII Table" for a list of ASCII decimal codes.

The syntax of the FLD_DELIMITER command is:

FLD_DELIMITER = {xx|<ascii1>} [xx|<ascii2>] [...];

where :

xx | is one or more keyboard characters
ascii | is an ASCII decimal code. The angle brackets around the ASCII code are required. Quote marks around delimiters are optional.

For example, to instruct the SQLWizard Import utility that your file uses a comma as the delimiter, use the command:

FLD_DELIMITER = ,;
Note:

You must determine the field delimiter prior to executing the Import function. If you specify a field delimiter that is not found in the file, the Batch Import program will abort and an error message will be displayed.

Use the Source File command from the View menu (or a text editor) to examine the file. If the field delimiter is an invisible ASCII character, you may have to use a hexadecimal editor to examine the contents of the file.

Parent topic: Batch Import Commands


FORMAT

Specifies the file type of the file being imported. The syntax is:

FORMAT = source-file-type;

where source-file-type is one of the following options:

Source File Type | Used For
DSNTIAUL | IBM DSNTIAUL files
FIXASC | Fixed-format ASCII files
FREASC | Free-format ASCII files

FORMAT is a required Batch Import command for every transaction.

For example:

FORMAT = dsntiaul;

specifies the importing of a DSNTIAUL file.

Parent topic: Batch Import Commands


HEADING

Specifies that the first row of the source file is a heading that contains field names for the XDB Server table being created. The syntax is:

HEADING = {Y | N}

Set HEADING equal to N if there is no heading in the source file. Set HEADING equal to Y if the first row is to be considered a heading in the source file. All other rows are treated as data.

For example:

HEADING = N;

specifies that there is no heading in the source file.

Parent topic: Batch Import Commands


INSERT_MODE

Specifies use of the NORMAL, ENGINE DIRECT WRITE. The syntax is:

INSERT_MODE = { NORMAL | EDR};

where NORMAL (default) indicates regular import mode and EDR indicates ENGINE DIRECT WRITE import.

The ENGINE DIRECT WRITE import option bypasses all referential integrity and data checking features normally imposed by the XDB Server.

INSERT_MODE is an optional Batch Import command.

For example:

INSERT_MODE = EDR;

causes data to be imported using Engine Direct Write insert mode.

Parent topic: Batch Import Commands


INS_NULL

Specifies whether null character data is to be inserted as null values, or blanks. The correct syntax is:

INS_NULL = { Y | N | NULLABLE };

If INS_NULL is set to NULLABLE, the null character data is imported as a NULL if the field is defined to allow null values, and as a space if the field is defined as NOT NULL.

If INS_NULL is set to N, then empty character fields are imported as a space.

If INS_NULL is set to Y (default), then a null character value is imported as a NULL. If the field is defined as NOT NULL, an error is returned if a null value is encountered.

INS_NULL is an optional Batch Import command.

For example:

INS_NULL = N;

will import null characters as spaces.

Parent topic: Batch Import Commands


NULL_PERM

Specifies null permissions for a field: NULLS ALLOWED, NOT NULL, or NOT NULL WITH DEFAULT. If a table exists then this command is ignored. The syntax is:

NULL_PERM = {Y | N | D} [, {Y | N | D}] ...;

where the specification is listed in the same order as the corresponding field names, and delimited by commas.

If NULL_PERM is Y then null values are permitted in the column. If NULL_PERM is N, then the column is prevented from containing null values. If NULL_PERM is D, then null values are converted to a specified default value for the column (NOT NULL WITH DEFAULT). The default value is dependent on the data type.

For example:

NULL_PERM = n,n,n,y,y,d,d;
Parent topic: Batch Import Commands


ON_ERROR

Specifies the automatic response to an error condition resulting from reading a field in a data file. The syntax is:

ON_ERROR = { SKIP | INS_NULL | QUIT | END_ALL};

If ON_ERROR is set to SKIP, a record that contains invalid data is skipped and import goes on to the next record. If ON_ERROR is set to INS_NULL then a null is placed in the field if the field is nullable. If ON_ERROR is set to QUIT, then the Batch Import will be terminated if invalid data is found. If ON_ERROR is set to END_ALL (default), then all Batch Import processing is terminated.

ON_ERROR is an optional Batch Import command.

For example:

ON_ERROR = NULL;

will cause Batch Import to place a null in a field that has caused an error, and to continue with the import despite the error.

Parent topic: Batch Import Commands


OFFSETS

Specifies the starting positions of fields being imported from fixed-format ASCII files. The syntax is:

OFFSETS = start-pos1 [, start-pos2]. . .;

where the starting positions are listed in the same order as the corresponding field names, and delimited by commas.

To determine the starting positions, it might be necessary to examine the file. (Use the Source File command from the View menu, or use a text editor.) The OFFSETS Batch Import command is required for every transaction when importing a fixed-format ASCII file into XDB Server.

For example:

OFFSETS = 1,11,23,35,57,74,78,85,91,113;

specifies the starting positions of the columns in a fixed-format ASCII source file.

Parent topic: Batch Import Commands


QUOTES

Used when importing free-format ASCII files to specify whether or not character strings are surrounded by double quotes. The syntax is:

QUOTES = {Y | N};

Set QUOTES to N (default) if there are no quotes around character strings in the source file. Set QUOTES to Y if the character strings in the source file are surrounded by quotes. It is common to surround character strings with double quotes in comma-delimited ASCII files. QUOTES is an optional Batch Import command.

For example:

QUOTES = Y;

will import a free-format ASCII file that has character strings enclosed in quotes.

Parent topic: Batch Import Commands


REC_DELIMITER

Specifies the end-of-record delimiter used to separate records in modified free-format ASCII files. The syntax is:

REC_DELIMITER = {"xx" | "<ascii>"...};

where:

xx | is a character string delimiter
ascii | is an ASCII decimal code. The angled brackets around the ASCII code are required. The default delimiter is a space character (ASCII code <032>).

The end-of-record delimiter can be specified as a character string or in ASCII decimal notation. If the delimiter is specified in ASCII decimal notation, enclose each ASCII code in angled brackets. For example, to use the decimal notation for a semicolon, enter the string <059>.

The delimiter cannot be a character found within the data values unless the values are enclosed in quotes. The most common record delimiter found in ASCII files is a carriage return followed by a line feed.

The REC_DELIMITER Batch Import command is required for every transaction when importing free-format ASCII files into XDB Server.

For example:

REC_DELIMITER = "<013><010>";

sets the record delimiter to a carriage return/line feed combination.

Parent topic: Batch Import Commands


REPLACE

Specifies whether the data being imported is to be appended to existing data in the table or is to replace it. The syntax is:

REPLACE = {Y | N};

If REPLACE is set to N (default), the imported data will appended to the existing data. If REPLACE is set to Y, the imported data will replace the data in the table.

This command is ignored if the named table does not exist; a new table is then created. The default is to append the data to the end of existing data in the table if found. REPLACE is an optional Batch Import command.

For example:

REPLACE  = N;

will append data to an existing table.

Parent topic: Batch Import Commands


SPACES

Specifies the number of spaces that separate columns in a fixed-format ASCII data file. The syntax is:

SPACES = {n}

where n is some number between 0-99. The default is 2.

Parent topic: Batch Import Commands


SRC_LENS

S pecifies the maximum number of spaces a field can use in a fixed-format ASCII source file being read. The syntax is:

SRC_LENS = length1 [, length2] ...;

where the lengths are listed in the same order as the corresponding field names, and delimited by commas.

When importing fixed-format ASCII files, the SRC_LENS command is used to determine the source file length. To determine the field length for ASCII files, it might be necessary to examine the files. (Use the Source File command from the View menu or a text editor.)

The SRC_LENS Batch Import command is required for every transaction when importing a fixed-format ASCII file into XDB Server.

For example:

SRC_LENS = 8,10,20,15,2,5,4,20,30;

specifies the column widths of the fixed-format ASCII source file being read.

Parent topic: Batch Import Commands


TABLE

S pecifies the name of the XDB Server table to be created by Import. The syntax is:

TABLE = table-name;

where table-name is the name of the table.

If you have super-user privilege, you can qualify the table name with a different AuthID (of up to eight characters), so the table is created with a different owner. The table will be created in the current location. To create it in a different location, enter a three-part name using the format location.authid.tablename.

TABLE is a required Batch Import command for every transaction.

For example:

TABLE = salaries;

sets the name of the imported table to SALARIES.

Parent topic: Batch Import Commands


TYPES

S pecifies the field types for the XDB Server table being created. The syntax is:

TYPES = field-type1 [, field-type2]. . .;

where field types are listed in the same order as corresponding field names, and delimited by commas. Valid field types are shown below. The two-letter designation defines the field type.

Symbol | Field Type | Symbol | Field Type
CH[(n)] | Char (Character) | LB | Long Varchar For Bit Data
CB[(n)] | Character For Bit Data | LG | Long Vargraphic
DT[(p[s])] | Date | MN | Money
DC | Decimal | SI | Smallint (Small Integer)
SF | Float (4-byte) | TM | Time
FL | Float | TS | Timestamp
GR | Graphic | VC[(n)] | Varchar (Variable Character)
LI | Integer | VB[(n)] | Varchar For Bit Data
LV | Long Varchar | VG[(n)] | Vargraphic
Note:

When importing ASCII files, you can specify a data type of JU (for Julian) to import Julian dates into XDB Server date fields. The system will read dates in the format yyddd (where ddd is the number of days since the beginning of the year) and write them in the regular XDB Server date format.

When specifying fields as DECIMAL, CHARACTER, VARCHAR, CHAR-FOR-BIT-DATA, VARCHAR-FOR-BIT-DATA, GRAPHIC and VARGRAPHIC, include the field length or precision and scale in parentheses immediately after the letter specifying the data type.

TYPES is a required Batch Import command for every transaction.

For example:

TYPES = ch(10),dc(10,2),dt,si;

sets the field types in the imported table to:

  • Character (10 characters field length)
  • Decimal (precision 10, scale 2)
  • Date
  • Small Integer
Parent topic: Batch Import Commands


USE_PIC

S pecifies whether the format picture (specified in Options) for a DATE, TIME, DECIMAL, or MONEY field is to be used when reading source data. The syntax is:

USE_PIC = {Y | N| NA} [, {Y | N | NA}] ...;

where the specification (Y, N, or NA) is listed in the same order as the corresponding field names, and delimited by commas.

If a field specification is set to Y (default), then Import will apply the Option utility's picture format to the data in that field (be sure the data in the source file matches the PIC format you've specified). If a field specification is set to N, then Import will apply the default mask for that data type, as described in the table below.

Type | Default Picture
Time | hh:mm:ss
Date | mm/dd/yyyy
Decimal | <sign><digits>[.<digits>][E[+-]<digits>]
Money | <sign><digits>[.<digits>][E[+-]<digits>]
 | where: <sign> includes any combination of + - $ >=
 | <digits> are 0 through 9; also comma (,) if to the left of the decimal place.

For fields that are not of type DATE, TIME, DECIMAL, or MONEY, the field specification should be set to NA (not applicable).

Note:

If you know that the format of the file is the same as the SQLWizard Import defaults, you do not need to use the USE_PIC statement.

USE_PIC is an optional Batch Import command.

For example:

USE_PIC = n,n,n,n,n,n,n,n,y,y;

specifies that the ninth and tenth fields are to have profile masks applied to them.

Parent topic: Batch Import Commands


Batch Import Examples

The following Batch Import command file contains examples of Batch Import transactions for the more common file formats. The [FREE ASCII] import transaction shows an example of error logging. In this example, all of the transactions are grouped into a single Batch Import file.

[DSNTIAUL]
TABLE = TUTORIAL.TUTORIAL.EMPLOYEE;
FILENAME = C:\XDBWIN\TUTORIAL\EMPLOYEE.DSN;
FORMAT = DSNTIAUL;
FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;
TYPES = si,ch(10),ch(10),ch(20),ch(15),ch(2),ch(5),
  ch(4),dc(15,2),dc(2,2);
NULL_PERM = n,n,n,y,y,y,y,y,y,y;
USE_PIC = na,na,na,na,na,na,na,na,y,y;
INS_NULL = n,n,n,y,y,y,y,y,y,y;
EBCDIC_TO_ACSII = y,y,y,y,y,y,y,y,y,y;
REPLACE = y;
INSERT_MODE = normal;
[FREE ASCII]
TABLE = TUTORIAL.TUTORIAL.EMPLOYEE;
FILENAME = C:\XDBWIN\TUTORIAL\EMPLOYEE.FRE;
FORMAT = FREASC;
FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;
TYPES = si,ch(10),ch(10),ch(20),ch(15),ch(2),ch(5),ch(4),
  dc(15,2),dc(2,2);
NULL_PERM = n,n,n,y,y,y,y,y,y,y;
USE_PIC = na,na,na,na,na,na,na,na,y,y;
INS_NULL = n,n,n,y,y,y,y,y,y,y;
HEADING = y;
QUOTES = y;
FLD_DELIMITER = "@";
REC_DELIMITER = "<013><010>";
REPLACE = y;
INSERT_MODE = normal;
ERR_LOG_FILE = c:\xdbwin\tutorial\errors.log;
APPEND_ERR_FILE = y;
BAD_REC_FILE = c:\xdbwin\tutorial\freerecs.log;
APPEND_REC_FILE = n;
[Fixed ASCII]
TABLE = TUTORIAL.TUTORIAL.EMPLOYEE;
FILENAME = C:\XDBWIN\TUTORIAL\EMPLOYEE.FIX;
FORMAT = FIXASC;
FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;
TYPES = si,ch(10),ch(10),ch(20),ch(15),ch(2),ch(5),ch(4),
  dc(15,2),dc(2,2);
NULL_PERM = n,n,n,y,y,y,y,y,y,y;
USE_PIC = na,na,na,na,na,na,na,na,y,y;
INS_NULL = n,n,n,y,y,y,y,y,y,y;
HEADING = y;
SPACES = 2;
OFFSETS = 1,11,23,35,57,74,78,85,91,114;
SRC_LENS = 8,10,10,20,15,2,5,4,21,4;
REPLACE = y;
INSERT_MODE = normal;
Parent topic: Batch Import Commands


Batch Export Commands

  • APPEND_ERR_FILE
  • ASCII_CODEPAGE (DSNTIAUL format)
  • EBCDIC_CODEPAGE (DSNTIAUL format)
  • ERR_LOG_FILE
  • FIELDS
  • FILENAME
  • FLD_DELIMITER
  • FORMAT
  • HEADING
  • ON_ERROR
  • QUERY
  • QUOTES
  • REC_DELIMITER
  • REPLACE
  • SPACES
  • SQL_OPTS
  • TABLE
  • WHERE
  • Batch Export Examples
Parent topic: Reference


APPEND_ERR_FILE

Appends errors to an existing error log file. The syntax is:

APPEND_ERR_FILE = { Y | N };

If APPEND_ERR_FILE is set to Y, then errors are appended to the existing error log file. If APPEND_ERR_FILE is set to N (default), then the old error log file is overwritten.

The log file appended to is the one specified in the recent ERR_LOG_FILE command. APPEND_ERR_FILE is an optional Batch Export command.

For example:

APPEND_ERR_FILE = Y;

causes any error messages produced as a result of the Batch Export to be appended to the existing error log file.

Parent topic: Batch Export Commands


ASCII_CODEPAGE (DSNTIAUL format)

Specifies the ASCII character set. The syntax is:

ASCII_CODEPAGE = n

where n is the code page number.

By default, Export assumes character data is stored in a DSNTIAUL source file using the American ASCII character set and converts it into the American EBCDIC character set by inserting it into a DSNTIAUL target file.

You can have the Export utility translate character data containing characters from any international ASCII character set to any international EBCDIC character set using the code page feature in Export. For the ASCII code page number, use the default ASCII character set for your country. ASCII to EBCDIC translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM location.

When the Export utility uses code page options, the values entered for ASCII_CODEPAGE and EBCDIC_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert XDB Server data in ASCII format to DSNTIAUL data in EBCDIC format.

Parent topic: Batch Export Commands


EBCDIC_CODEPAGE (DSNTIAUL format)

Specifies the EBCDIC character set. The syntax is:

EBCDIC_CODEPAGE = n

where n is the code page number.

By default, Export assumes character data is stored in a DSNTIAUL source tables using the American ASCII character set and converts it to the American EBCDIC character set inserting it into an XDB Server table.

You can have the Export utility translate character data containing characters from any international ASCII character set to any international EBCDIC character set using the code page feature in Export. For the EBCDIC code page number, use the default EBCDIC character set for your country. ASCII to EBCDIC translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM. See the section titled "Code Page Support" for the structure of the SYSIBM.SYSSTRINGS table.

When the Export utility uses code page options, the values entered for ASCII_CODEPAGE and EBCDIC_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert XDB Server data in ASCII format to DSNTIAUL data in EBCDIC format.

Parent topic: Batch Export Commands


ERR_LOG_FILE

Causes error messages from the Export batch transaction to be written to the filename specified after this command (called the error log file). The syntax is:

ERR_LOG_FILE = filename;

where filename is the name of the file, including extension and path, for the error log file.

If you don't specify a path, the error log file is put in your current directory. Error messages are still displayed on the screen. ERR_LOG_FILE is an optional Batch Export command.

For example:

ERR_LOG_FILE = C:\LOGFILES\BATCH.ELF;

saves error messages to the batch.elf file.

Parent topic: Batch Export Commands


FIELDS

Specifies the names of the fields for the XDB Server table being created. The syntax of the statement is:

FIELDS = field-name1 [, field-name2]. . .;

where the field names are listed in order, and separated by commas (,).

The FIELDS command is optional if you are creating your own Batch Export file and you are querying all fields in a table. If specific fields are being queried, those fields must be specified using the FIELDS command.

For example:

FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;

will export a file into a new table with field names similar to the EMPLOYEE table in the tutorial.

Parent topic: Batch Export Commands


FILENAME

Specifies the destination directory and file name for the target file produced by the export transaction. The syntax is:

FILENAME = filename

where filename is the full path specification and filename for the target file.

For example:

FILENAME= A:\filename;
Parent topic: Batch Export Commands


FLD_DELIMITER

Specifies the delimiter used to separate fields in free-format ASCII files. The default delimiter is a comma. The syntax is:

FLD_DELIMITER = {"xx" | "<ascii>"...};

where:

xx | is a character string delimiter
ascii | is an ASCII decimal code.

Delimiters can be specified as a character string or in ASCII decimal notation. If the delimiter is specified as a character string it must be enclosed in double-quotation marks (" "). If the delimiter is specified in ASCII decimal notation, enclose each ASCII code in angled brackets. For example, to use the decimal notation for a semicolon, enter the string <59>. (The angled brackets around the ASCII code are required.)

Note:

You must determine the field delimiter prior to executing the Export function. If you specify a field delimiter that is not found in the file, the Batch Export program will abort and an error message will be displayed.

Use the Target File command from the View menu (or a text editor) to examine the file. If the field delimiter is an nonvisible ASCII character, you may have to use a hexadecimal editor to examine the contents of the file.

Take care not to choose a character found in your data as a delimiter. For example, do not use a comma as the delimiter if your data contains numeric or money fields grouped with a comma.

For example:

FLD_DELIMITER = ",";

separates the data with a comma.

Parent topic: Batch Export Commands


FORMAT

Specifies the file type you are exporting to. The syntax is:

FORMAT = target-file-type;

where target-file-type is one of the following options:

Target File Type | Used For
FIXASC | Fixed-format ASCII files
FREASC | Free format ASCII files
DSNTIAUL | IBM DSNTIAUL files
SQL | SQL statements

This statement is required for each Batch Export transaction.

For example:

FORMAT = fixasc;

sets the export file type to fixed-format ASCII.

Parent topic: Batch Export Commands


HEADING

Specifies whether the field names are to be included in the first row of free or fixed-format ASCII files. The syntax is:

HEADING = {Y | N};

If HEADING is set to N, then no heading is included in the target file. When HEADING is set to Y (default), the column headings are included as the first record of the file.

For example:

HEADING = N;

will prevent a heading from being included in the target file.

Parent topic: Batch Export Commands


ON_ERROR

Specifies the automatic response to an error condition resulting from reading a field in a data file. The syntax is:

ON_ERROR = {CONTINUE | QUIT | END_ALL};

If ON_ERROR is set to CONTINUE, then Batch Export will try to recover from any error that occurs. If ON_ERROR is set to QUIT (default), then Batch Export will quit if any errors occur. If ON_ERROR is set to END_ALL, then Batch Export terminates.

For example:

ON_ERROR = CONTINUE;

will cause Batch Export to try to recover from any errors.

Parent topic: Batch Export Commands


QUERY

Used to hold an SQL SELECT statement that the export is based on. The syntax is:

QUERY = SELECT dept, dname, mgr FROM dept
WHERE dname = "sales" AND mgr > 5;

In the syntax example above, the dept, dname, and mgr fields are selected from the DEPT table only when the dname field is equal to sales and the mgr field is greater than five. This allows specific information to be exported from the selected table.

Parent topic: Batch Export Commands


QUOTES

Used when exporting free-format ASCII files to specify whether or not character strings are to be surrounded by double quotes. The syntax is:

QUOTES = {Y | N};

If QUOTES is set to N (default), then quotes will not be placed around character strings. If QUOTES is set to Y, then character strings will be surrounded by quotes.

Surrounding character strings with double quotes is a common practice in the creation of comma-delimited ASCII files.

For example:

QUOTES = Y;

will cause the data in the exported file to be enclosed in quotes.

Parent topic: Batch Export Commands


REC_DELIMITER

Specifies the delimiter for free-format ASCII export types. The syntax is:

REC_DELIMITER = {'xx' | "<ascii>"};

where:

xx | is a character string delimiter
ascii | is an ASCII decimal code. The angled brackets around the ASCII code are required. The default delimiter is a space character (ASCII code <032>).

The end-of-record delimiter can be specified as a character string or in ASCII decimal notation. If the delimiter is specified in ASCII decimal notation, enclose each ASCII code in angled brackets. For example, to use the decimal notation for a semicolon, enter the string <059>.

The delimiter cannot be a character found within the data values unless the values are enclosed in quotes. The most common record delimiter found in ASCII files is a carriage-return, followed by a line-feed.

The REC_DELIMITER Batch Export command is required for every transaction when exporting Free ASCII files to XDB Server.

For example:

REC_DELIMITER = "<013><010>";

sets the record delimiter to a carriage-return/line-feed combination.

Parent topic: Batch Export Commands


REPLACE

Specifies that the data being exported is to replace the current contents of the destination file. The syntax is:

REPLACE = {Y | N};

If REPLACE is set to N (default), then if the destination file exists, the data is appended. If REPLACE is set to Y, then the data in the target file will be replaced.

If no file of the same name exists, the data in the table being exported will be placed in a newly created file regardless of the parameter specified with the REPLACE command. If the REPLACE command is not included, and the destination file already exists, the data is appended to the file.

This statement is supported for the following formats:

  • Free ASCII
  • Fixed ASCII
  • SQL

With all other formats, the file is replaced instead of being appended to regardless of how REPLACE is set.

For example:

REPLACE = Y;

will cause the exported file to overwrite any existing file with the same name.

Parent topic: Batch Export Commands


SPACES

Specifies the number of spaces the separate columns in a Fixed ASCII target file. The syntax is:

SPACES = n;

where n is an integer corresponding to the number of spaces (between 0 and 99) to insert between the columns of data. The default is 2.

For example:

SPACE = 1;

will ensure that one space is placed between every field in the exported file.

Parent topic: Batch Export Commands


SQL_OPTS

Used to specify which SQL statements should be generated when the SQL export type is chosen. The syntax is:

SQL_OPTS = statement-type [, statement-type, ...];

where statement-type is one of the types shown in the table below.

Statement type | SQL Statement
CREATE | CREATE TABLE and CREATE VIEW commands
INSERT | INSERT INTO commands
INDEX | CREATE INDEX commands
SYNONYM | CREATE SYNONYM commands
CHECK | ALTER TABLE ... CHECK commands
COMMENT | COMMENT ON commands

For example:

SQL_OPTS = CREATE, INDEX;

selects CREATE TABLE, CREATE VIEW, and CREATE INDEX SQL commands for use in the target file.

Parent topic: Batch Export Commands


TABLE

Specifies the name of the XDB Server table or view to be exported. The syntax is:

TABLE = table-name;

where table-name is the name of the XDB Server table or view.

If you are have super-user privilege, you can qualify the table name with a different AuthID (of up to eight characters), so the table is created with a different owner. The table will be created in the current location. To create it in a different location, enter a three-part name using the format location.authid.tablename.

TABLE is a required command for every transaction.

For example:

TABLE = employee;

causes data from the EMPLOYEE table to be exported.

Parent topic: Batch Export Commands


WHERE

Used with a SELECT statement to specify search criteria for retrieving rows of data from a table or group of tables. The syntax is:

WHERE search-condition;

The WHERE clause can also be used with DELETE and UPDATE. For example:

WHERE city = "Columbia" OR "Annapolis";

will cause all records that have a city of Columbia or Annapolis to be pulled from the table and exported into the desired target file.

Parent topic: Batch Export Commands


Batch Export Examples

The following Batch Export file contains examples of transactions for each file type. All the transactions are contained into a single file.

[FREE ASCII]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.FRE;
FORMAT = FREASC;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
HEADING = y;
QUOTES = y;
FLD_DELIMITER = ",";
REC_DELIMITER = "<013><010>";
ON_ERROR = CONTINUE;
ERR_LOG_FILE = c:\xdbwin\tutorial\errors.log;
APPEND_ERR_FILE = y;
[FIXED ASCII]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.FIX;
FORMAT = FIXASC;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
HEADING = y;
SPACES = 2;
ON_ERROR = CONTINUE;
ERR_LOG_FILE = c:\xdbwin\tutorial\errors.log;
APPEND_ERR_FILE = y;
[DSNTIAUL]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.DSN;
FORMAT = DSNTIAUL;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
[SQL Statement]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.SQL;
FORMAT = SQL;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
SQL_OPTS = INSERT,CHECK,COMMENT;
Parent topic: Batch Export Commands


SQL Option for DB2 Error Messages

  • COBSQ - SQL ECM Preprocessor Error Messages
  • L - Link Error Messages
  • N - Network Error Messages
  • PIC - Picture Error Messages
  • SQL - SQL PL/I Precompiler Error Messages
  • WADM - SQLWizard Administrator Error Messages
  • WCRT - SQL Wizard Create/Alter Table Error Messages
  • WDG - SQL Wizard Declaration Generator Error Messages
  • WE - SQL Wizard Export Error Messages
  • WI - SQL Wizard Import Error Messages
  • WSQL - SQL Wizard Interactive SQL Error Messages
  • X - Engine Error Messages
  • XMIG - Migrate Error Messages
  • XU - Library Error Messages
Parent topic: Reference


COBSQ - SQL ECM Preprocessor Error Messages

  • COBSQ0000 - COBSQ0099
    Lists the SQL ECM error messages from COBSQ0000 through COBSQ0099.
  • COBSQ0100 - COBSQ0149
    Lists the SQL ECM error messages from COBSQ0100 through COBSQ0149.
  • COBSQ0150 - COBSQ0199
    Lists the SQL ECM error messages from COBSQ0150 through COBSQ0199.
  • COBSQ0200 - COBSQ0399
    Lists the SQL ECM error messages from COBSQ0200 through COBSQ0399.
  • COBSQ0400 - COBSQ0499
    Lists the SQL ECM error messages from COBSQ0400 through COBSQ0499.
  • COBSQ0900 - COBSQ0999
    Lists the SQL ECM error messages from COBSQ0900 through COBSQ0999.
Parent topic: SQL Option for DB2 Error Messages


COBSQ0000 - COBSQ0099

Lists the SQL ECM error messages from COBSQ0000 through COBSQ0099.

  • COBSQ0002: token is badly defined
  • COBSQ0003 Program contains more than one definition of token
  • COBSQ0004 Nested or multi-source programs not allowed.
  • COBSQ0005: An error occurred whilst processing the internal dictionary.
  • COBSQ0006 No DB engine could be found.
  • COBSQ0007 Source file name is invalid.
  • COBSQ0012: Host variable used without a colon.
  • COBSQ0013: Login failed. : program-name.
  • COBSQ0015 Host variables data types in UNION do not match.
  • COBSQ0016 This statement will Delete an entire table
  • COBSQ0017 HostVariable is not preceded by a colon.
  • COBSQ0018 SQL statement not currently supported - converted to comment.
  • COBSQ0019 Operation is assumed to apply to Allocate Cursor.
  • COBSQ0021 SQL Option must be selected and available
  • COBSQ0024 EXEC SQL statement found within COPY statement, COPY directive not set. May cause compile error on mainframe.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0100 - COBSQ0149

Lists the SQL ECM error messages from COBSQ0100 through COBSQ0149.

  • COBSQ0101: Expected token1 found token2.
  • COBSQ0102: Host variable mismatch.
  • COBSQ0104: Illegal symbol variable.
  • COBSQ0106: variable Invalid/Not Declared
  • COBSQ0107: INTO not allowed for DECLARE.
  • COBSQ0110: No INTO clause specified.
  • COBSQ0111: No FROM clause specified.
  • COBSQ0112: Invalid positioning of FROM.
  • COBSQ0114: Invalid file name.
  • COBSQ0115: Token array overflow.
  • COBSQ0117: Invalid in data division.
  • COBSQ0118: Invalid WHENEVER.
  • COBSQ0120: Not valid in current compatibility mode.
  • COBSQ0124: Group variable token is not allowed in the WHERE clause.
  • COBSQ0125: Cursor not found.
  • COBSQ0126: A _ is illegal in a host variable.
  • COBSQ0127: A ( is illegal in the INTO clause.
  • COBSQ0131: SQLCA not found OR comp/comp-5 mixup in SQLCA.
  • COBSQ0135: Host variable type mismatch.
  • COBSQ0137: Indicator variable token is not SMALLINT type.
  • COBSQ0138: The length of a host variable on CONNECT is greater than 16.
  • COBSQ0141: PREPARE before DECLARE is illegal.
  • COBSQ0144: Statement not identified.
  • COBSQ0147: Multiple INTO's only allowed with a UNION.
  • COBSQ0149: Illegal token found on CONNECT line.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0150 - COBSQ0199

Lists the SQL ECM error messages from COBSQ0150 through COBSQ0199.

  • COBSQ0151: Cursor already DECLARED.
  • COBSQ0154: Login failed.
  • COBSQ0163: Invalid Cursor name
  • COBSQ0164: Syntax error in INTO Clause
  • COBSQ0170: Login failed. Unable to VALIDATE SQL
  • COBSQ0184 Illegal token ':' found. Check to see if previous token was an indicator variable.
  • COBSQ0185 Syntax error, last symbol read is token.
  • COBSQ0189 'ORDER BY' clause not permitted.
  • COBSQ0190 GROUP BY clause on a SELECT INTO will not bind.
  • COBSQ0191 HAVING clause on a SELECT INTO will not bind.
  • COBSQ0198: DB2 emulation mismatch - SERVER is in DB2 V6 mode
  • COBSQ0199: DB2 emulation mismatch - SERVER is in DB2 V5 mode
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0200 - COBSQ0399

Lists the SQL ECM error messages from COBSQ0200 through COBSQ0399.

  • COBSQ0201 Illegal token variable found on SET line.
  • COBSQ0202 Number of host variables specified in UNION do not match.
  • COBSQ0299 Internal EXEC SQL statement table overflow - use directive MAXSQL to override default.
  • COBSQ0312 Undefined or unusable host variable token
  • COBSQ0324 SQLDA fields defined with incompatible fields for XDB OPTIMIZE directive setting.
  • COBSQ0325 Multiple types of SQLDA's detected - all SQLDA's must use same structure.
  • COBSQ0326 SQL statements not supported in nested subroutine.
  • COBSQ0327 Invalid BLOCKING option specified – valid options are: FSR, SR, or LB.
  • COBSQ0328 Invalid DEFAULT-CHAR option specified – valid options are: BITS, SBCS, DBCS, or SYSDEFAULT.
  • COBSQ0329 Invalid EXIST-CHECK option specified – valid options are: REQUIRED or OPTIONAL.
  • COBSQ0330 Required directive AUTOBIND not specified with directive directive.
  • COBSQ0331 Invalid DATE format specified - valid options are: ISO, EUR, JIS, USA or LOCAL.
  • COBSQ0332 Invalid TIME format specified - valid options are: ISO, EUR, JIS, USA or LOCAL.
  • COBSQ0333 Invalid number of values specified, maximum is 10 per option: token .
  • COBSQ0334 Only one DBRM specified when multiple other directives specified for AUTOBIND.
  • COBSQ0335 No collection-id specified, option required for AUTOBIND.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0400 - COBSQ0499

Lists the SQL ECM error messages from COBSQ0400 through COBSQ0499.

  • COBSQ0401 Statement is too long.
  • COBSQ0402 Statement contains too many host variables.
  • COBSQ0403 variable does not have a suitable definition to be used as a host variable.
  • COBSQ0404 Bad SQL data declaration.
  • COBSQ0405 Syntax error.
  • COBSQ0406 Filename too long.
  • COBSQ0407 File token not found.
  • COBSQ0408 token is non-unique and should be qualified.
  • COBSQ0409: token is not a data item
  • COBSQ0410 Statement contains more than one SQLDA.
  • COBSQ0411 token is not a table of null indicator variables.
  • COBSQ0412 token should not be a defined with an OCCURS clause.
  • COBSQ0413 token should not be a subordinate to an item defined with an OCCURS clause.
  • COBSQ0415 Statement not allowed in the PROCEDURE DIVISION.
  • COBSQ0416 An error occurred whilst processing the trace file.
  • COBSQ0418 Mismatched DECLARE.
  • COBSQ0419 Host variable name is too long.
  • COBSQ0420 Internal error - dictionary handle is too big.
  • COBSQ0422 Nested INCLUDE's not supported.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0900 - COBSQ0999

Lists the SQL ECM error messages from COBSQ0900 through COBSQ0999.

  • COBSQ0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.
  • COBSQ0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


L - Link Error Messages

  • L000 - L099
    Lists the Link error messages from L000 through L099.
  • L100 - L149
    Lists the Link error messages from L100 through L149.
  • L150 - L199
    Lists the Link error messages from L150 through L199.
  • L200 - L299
    Lists the Link error messages from L200 through L299.
  • L300 - L399
    Lists the Link error messages from L300 through L399.
  • L400 - L449
    Lists the Link error messages from L400 through L449.
  • L450 - L499
    Lists the Link error messages from L450 through L499.
  • L500 - L549
    Lists the Link error messages from L500 through L549.
  • L550 - L599
    Lists the Link error messages from L550 through L599.
  • L600 - L649
    Lists the Link error messages from L600 through L649.
  • L650 - L699
    Lists the Link error messages from L650 through L699.
  • L700 - L799
    Lists the Link error messages from L700 through L799.
  • L800 - L899
    Lists the Link error messages from L800 through L899.
  • L900 - L999
    Lists the Link error messages from L900 through L999.
  • L1000 - L1099
    Lists the Link error messages from L1000 through L1099.
  • L30000 - L30099
    Lists the Link error messages from L30000 through L30099.
Parent topic: SQL Option for DB2 Error Messages


L000 - L099

Lists the Link error messages from L000 through L099.

  • L007: Statement contains the illegal character character.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -007, for information.
  • L010: The string constant beginning character is not terminated.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -010, for information.
  • L029: INTO clause required.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -029, for information.
  • L060: Invalid type specification: spec.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -060, for information.
  • L084: UNACCEPTABLE SQL STATEMENT.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -084, for information.
Parent topic: L - Link Error Messages


L100 - L149

Lists the Link error messages from L100 through L149.

  • L101: The statement is too long or too complex.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -101, for information.
  • L102: Size of string constant starting string is too great.
    See the Error SQLCODES section of your IBM Database Messages and Codes Manual, message -102, for information.
  • L103: literal is an invalid numeric literal.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -103, for information.
  • L104: Illegal symbol token. Valid symbols are token-list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -104, for information.
  • L105: Invalid string.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -105, for information.
  • L107: The name name is too long. Maximum allowable size is size.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -107, for information.
  • L108: THE NAME name IS QUALIFIED INCORRECTLY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -108, for information.
  • L109: clause clause is not permitted.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -109, for information.
  • L110: Invalid hex literal beginning string.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -110, for information.
  • L111: A column function does not include a column name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -111, for information.
  • L112: The operand of a column function is another column function.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -112, for information.
  • L113: Invalid character found in name: name. Reason code - reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -113, for information.
  • L114: THE LOCATION NAME location DOES NOT MATCH THE CURRENT SERVER
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -114, for information.
  • L115: A predicate is invalid because operation operation is followed by a list, any or all.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -115, for information.
  • L117: The number of insert values is not the same as the number of object columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -117, for information.
  • L118: The object table or view of the insert/delete/update is in a FROM clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -118, for information.
  • L119: A column in a HAVING clause is not included in the GROUP BY clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -119, for information.
  • L120: A WHERE clause or a SET clause includes a column function.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -120, for information.
  • L121: Column name is used more than once in insert or update.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -121, for information.
  • L122: Select with no GROUP BY has column name/function or a column name not in GROUP BY.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -122, for information.
  • L123: THE PARAMETER IN POSITION n IN THE FUNCTION name MUST BE A CONSTANT OR KEYWORD
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -123, for information.
  • L125: An integer in the ORDER BY clause does not identify a column of the result.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -125, for information.
  • L126: The SELECT statement contains both an UPDATE clause and an ORDER BY clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -126, for information.
  • L127: Distinct is specified more than once in a subselect.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -127, for information.
  • L128: Invalid use of NULL in a predicate.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -128, for information.
  • L129: The statement contains too many table names.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -129, for information.
  • L130: Escape clause with more than one char or string contains invalid esc char.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -130, for information.
  • L131: Statement with LIKE predicate has incompatible data types.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -131, for information.
  • L132: AN OPERAND OF value IS NOT VALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -132, for information.
  • L133: Column function in subquery of HAVING invalid because expression applies op to corr ref.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -133, for information.
  • L134: IMPROPER USE OF LONG STRING COLUMN column-name OR AN EXPRESSION OF MAXIMUM LENGTH GREATER THAN 255.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -134, for information.
  • L136: Sort cannot be executed because sort key length > 4000 bytes.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -136, for information.
  • L137: THE LENGTH RESULTING FROM operation IS GREATER THAN maximum-length
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -137, for information.
  • L138: The second or third argument of the SUBSTR function is out of range.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -138, for information.
  • L142: THE SQL STATEMENT IS NOT SUPPORTED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -142, for information.
  • L144: Invalid section number number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -144, for information.
  • L147: ALTER FUNCTION function-name FAILED BECAUSE SOURCE FUNCTIONS CANNOT BE ALTERED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -147, for information.
  • L148: THE SOURCE TABLE source-name CANNOT BE RENAMED OR ALTERED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -148, for information.
Parent topic: L - Link Error Messages


L150 - L199

Lists the Link error messages from L150 through L199.

  • L150: The INSERT, DELETE or UPDATE object is a view and is not permitted.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -150, for information.
  • L151: Update is invalid because the descr of column name cannot be updated.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -151, for information.
  • L152: THE DROP clause CLAUSE IN THE ALTER STATEMENT IS INVALID BECAUSE constraint-name IS A constraint-type
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -152, for information.
  • L153: The CREATE VIEW statement does not include a required column list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -153, for information.
  • L154: CREATE VIEW failed because definition with union, union all, or remote object.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -154, for information.
  • L156: The statement does not identify a table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -156, for information.
  • L157: name is not the name of a table needed for a foreign key clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -157, for information.
  • L158: Number of columns specified for view is not equal to number of columns in select.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -158, for information.
  • L159: DROP or COMMENT ON token identifies a(n) token.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -159, for information.
  • L160: The WITH CHECK OPTION cannot be used for the specified view.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -160, for information.
  • L161: INSERT or UPDATE not allowed because result row does not satisfy view definition.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -161, for information.
  • L164: authid does not have privilege to create a view with qualification authorization.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -164, for information.
  • L170: The number of arguments specified for function is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -170, for information.
  • L171: The data type, length, or value of argument argument of function is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -171, for information.
  • L173: UR IS SPECIFIED ON THE WITH CLAUSE BUT THE CURSOR IS NOT READ-ONLY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -173, for information.
  • L180: The string representation of a datetime value has invalid syntax.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -180, for information.
  • L181: The string representation of a datetime value is not a valid datetime value.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -181, for information.
  • L182: An arithmetic expression with a datetime value is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -182, for information.
  • L183: Arithmetic operation on date or timestamp has result not in valid range.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -183, for information.
  • L184: Arithmetic expression with a datetime value contains a parameter marker.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -184, for information.
  • L185: Local format option was used with date or time with no local exit.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -185, for information.
  • L186: Local date or time length was increased and the execute program uses old length.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -186, for information.
  • L187: Reference to a current date/time special register is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -187, for information.
  • L188: The string representation of a name is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -188, for information.
  • L189: CCSID ccsid is unknown or invalid for the data type or subtype.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -189, for information.
  • L190: ATTRIBUTES OF column-name IN table-name ARE NOT COMPATIBLE WITH EXISTING COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -190, for information.
  • L191: A string cannot be used because it is invalid mixed data.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -191, for information.
  • L197: QUALIFIED NAMES IN ORDER BY NOT PERMITTED WITH UNION OR UNION ALL
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -197, for information.
  • L198: Operand of the PREPARE or EXECUTE IMMEDIATE statement is blank or empty.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -198, for information.
  • L199: Illegal use of keyword keyword. Token token was expected.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -199, for information.
Parent topic: L - Link Error Messages


L200 - L299

Lists the Link error messages from L200 through L299.

  • L203: A reference to column name is ambiguous.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -203, for information.
  • L204: name is an undefined name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -204, for information.
  • L205: col is not a column of table tablename.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -205, for information.
  • L206: name is not a column of a table in an INSERT, UPDATE or FROM clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -206, for information.
  • L207: ORDER BY invalid because the column name applies to result of UNION or UNION ALL.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -207, for information.
  • L208: ORDER BY invalid because column name is not part of the result table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -208, for information.
  • L212: name IS MULTIPLY SPECIFIED IN TRIGGER REFERENCING CLAUSE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -212, for information.
  • L219: The required explanation table name does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -219, for information.
  • L220: Column name in explanation table name is not defined properly.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -220, for information.
  • L221: "opt cols" in explanation table name is incomplete. Opt col name is missing.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -221, for information.
  • L240: THE PART CLAUSE OF A LOCK TABLE STATEMENT IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -240, for information.
  • L250: Local location name is not defined when procession a 3-part object name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -250, for information.
  • L251: Token name is not valid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -251, for information.
Parent topic: L - Link Error Messages


L300 - L399

Lists the Link error messages from L300 through L399.

  • L301: Value of input host variable number number not used because wrong data type.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -301, for information.
  • L302: Value of input variable number number is invalid for the target column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -302, for information.
  • L303: Cannot assign value to output host variable number number. Types not comparable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -303, for information.
  • L304: Value with data type type cannot go in host variable at position number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -304, for information.
  • L305: Output host variable number number cannot be NULL when there is no indicator.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -305, for information.
  • L309: Predicate is invalid because a referenced host variable has the NULL value.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -309, for information.
  • L310: DECIMAL HOST VARIABLE OR PARAMETER number CONTAINS NON-DECIMAL DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -310, for information.
  • L311: Length of input host variable number number is negative or greater than the max.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -311, for information.
  • L312: Undefined or unusable host variable name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -312, for information.
  • L313: Number of host variables specified "< >" to number of parameter markers.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -313, for information.
  • L314: The statement contains an ambiguous host variable reference.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -314, for information.
  • L327: CANNOT INSERT ROW BECAUSE IT IS OUTSIDE THE BOUND OF THE PARTITION RANGE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -327, for information.
  • L330: String cannot be translated. Reason reason, char code-point, host var number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -330, for information.
  • L331: String cannot be assigned to a host variable. Reason reason, char code-point, pos number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -331, for information.
  • L332: SYSSTRINGS does not define a translation CCSID ccsid to ccsid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -332, for information.
  • L333: String variable subtype not same as bind time and diff cannot be resolved.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -333, for information.
  • L338: AN ON CLAUSE IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -338, for information.
  • L350: INVALID SPECIFICATION OF A LARGE OBJECT COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -350, for information.
  • L351: UNSUPPORTED SQLTYPE IN POSITION position-number OF SELECT-LIST
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -351, for information.
  • L352: UNSUPPORTED SQLTYPE IN POSITION position-number OF INPUT-LIST
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -352, for information.
  • L355: A LOB COLUMN IS TOO LARGE TO BE LOGGED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -355, for information.
  • L372: ONLY ONE COLUMN DEFINED AS ROWID IS ALLOWED IN A TABLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -372, for information.
  • L390: FUNCTION function-name (specific-name), NOT VALID IN THAT CONTEXT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -390, for information.
  • L392: SQLDA PROVIDED FOR cursor HAS BEEN CHANGED FROM PREVIOUS FETCH
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -392, for information.
  • L396: object-typeobject-name EXECUTED SQL STATEMENT DURING FINAL CALL PROCESSING
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -396, for information.
  • L397: GENERATED OPTION SPECIFIED ON COLUMN THAT IS NOT TYPE ROW ID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -397, for information.
  • L398: LOCATOR REQUESTED FOR HOST VARIABLE position-number BUT VARIABLE NOT A LOB
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -398, for information.
  • L399: ATTEMPTED TO INSERT AN INVALID VALUE INTO A ROWID COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -399, for information.
Parent topic: L - Link Error Messages


L400 - L449

Lists the Link error messages from L400 through L449.

  • L400: THE CATALOG HAS THE MAXIMUM NUMBER OF USER DEFINED INDEXES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -400, for information.
  • L401: Operands of an arithmetic or comparison operation are not comparable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -401, for information.
  • L402: Arithmetic function/operator "< >" applied to character/datetime data.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -402, for information.
  • L404: THE SQL STATEMENT SPECIFIES A STRING THAT IS TOO LONG
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -404, for information.
  • L405: Numeric literal literal is out of range.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -405, for information.
  • L406: A calculated or derived numeric value not within range of its object column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -406, for information.
  • L407: COLUMN column-name CANNOT CONTAIN NULL VALUES IN INSERT, UPDATE OR SET
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -407, for information.
  • L408: THE VALUE IS NOT COMPATIBLE WITH THE DATA TYPE OF ITS TARGET
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -408, for information.
  • L409: Invalid operand of a count function.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -409, for information.
  • L410: Floating point literal literal contains more than 30 characters.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -410, for information.
  • L411: Current datetime, SQLID or user keyword cannot be used as specified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -411, for information.
  • L412: The SELECT clause of a subquery specifies multiple columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -412, for information.
  • L413: OVERFLOW OCCURRED DURING NUMERIC DATA TYPE CONVERSION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -413, for information.
  • L414: Numeric or datetime column name is specified in a LIKE predicate.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -414, for information.
  • L415: Cols, number, of the operands of a union do not have comparable col. descr.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -415, for information.
  • L416: An operand of a union contains a long string column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -416, for information.
  • L417: PREPARE string includes parameter markers as operand of same operator.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -417, for information.
  • L418: A string to be prepared contains an invalid use of parameter markers.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -418, for information.
  • L419: Decimal divide operation is invalid because the result has a negative scale.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -419, for information.
  • L420: STRING ARGUMENT VALUE NOT ACCEPTABLE TO FUNCTION function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -420, for information.
  • L421: Operand of a union or union all does not have the same number of columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -421, for information.
  • L423: INVALID VALUE FOR LOCATOR IN POSITION position-number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -423, for information.
  • L426: Dynamic commit not valid at application server where updates not allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -426, for information.
  • L427: Dynamic rollback not valid at application server where updates not allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -427, for information.
  • L430: routine-typeroutine-name (specific-name) HAS ABNORMALLY TERMINATED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -430, for information.
  • L433: VALUE value IS TOO LONG
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -433, for information.
  • L435: INVALID SQLSTATE sqlstate SPECIFIED IN RAISE_ERROR OR IN A SIGNAL SQLSTATE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -435, for information.
  • L438: APPLICATION RAISED ERROR WITH DIAGNOSTIC TEXT: text
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -438, for information.
  • L440: NO routine-type NAMED routine-name WITH COMPATIBLE ARGUMENTS WAS FOUND
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -440, for information.
  • L441: INVALID USE OF 'DISTINCT' OR 'ALL' WITH SCALAR FUNCTION function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -441, for information.
  • L443: function-name (specific-name) RETURNED WITH DIAGNOSTIC TEXT msg-text
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -443, for information.
  • L444: USER PROGRAM name COULD NOT BE FOUND
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -444, for information.
  • L449: INVALID EXTERNAL NAME CLAUSE FOR FUNCTION OR PROCEDURE routine-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -449, for information.
Parent topic: L - Link Error Messages


L450 - L499

Lists the Link error messages from L450 through L499.

  • L450: FUNCTION/STORED PROCEDURE name, PARAMETER NUMBER parmnum, OVERLAYED MEMORY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -450, for information.
  • L451: INVALID data-item DEFINITION IN function-name, INVALID DATA TYPE type
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -451, for information.
  • L453: PROBLEM WITH THE RETURNS CLAUSE FOR FUNCTION function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -453, for information.
  • L454: SIGNATURE FOR FUNCTION function-name NOT UNIQUE WITHIN SCHEMA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -454, for information.
  • L455: function-name, SCHEMA schema-name1 IN SPECIFIC NAME DOES NOT MATCH schema-name2
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -455, for information.
  • L456: FUNCTION function-name, SPECIFIC specific-name EXISTS IN THE SCHEMA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -456, for information.
  • L457: ILLEGAL USE OF name; IT IS RESERVED FOR SYSTEM USE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -457, for information.
  • L458: FUNCTION function-name COULD NOT BE FOUND BY SIGNATURE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -458, for information.
  • L461: VALUE OF TYPE source-data-type CANNOT BE CAST TO target-data-type
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -461, for information.
  • L463: routine-name (specific-name) RETURNED sqlstate, DIAGNOSTIC TEXT text
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -463, for information.
  • L469: CALL STATEMENT NEEDS AN OUTPUT HOST VARIABLE FOR PARAMETER number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -469, for information.
  • L470: CALL STATEMENT SPECIFIED A NULL VALUE FOR INPUT PARAMETER number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -470, for information.
  • L471: INVOCATION OF FUNCTION/PROCEDURE name FAILED DUE TO REASON rc
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -471, for information.
  • L472: CURSOR cursor-name LEFT OPEN BY FUNCTION function-name (specific-name)
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -472, for information.
  • L473: USER DEFINED TYPE CANNOT BE THE SAME NAME AS A BUILT-IN TYPE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -473, for information.
  • L475: type-1 RESULT CANNOT BE CAST TO type-2 RETURN TYPE OF THE function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -475, for information.
  • L476: FUNCTION function-name NAMED WITHOUT SIGNATURE, FUNCTION NOT UNIQUE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -476, for information.
  • L478: ACTION ON type1 CANNOT BE PROCESSED; name OF TYPE type2 DEPENDENT ON IT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -478, for information.
  • L480: PROCEDURE procedure-name HAS NOT YET BEEN CALLED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -480, for information.
  • L482: PROCEDURE procedure-name RETURNED NO LOCATORS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -482, for information.
  • L483: PARMS FOR function-name DOES NOT MATCH NUMBER OF PARMS OF SOURCE FUNCTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -483, for information.
  • L487: object-typeobject-name USED SQL BUT WAS CREATED WITH NOSQL OPTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -487, for information.
  • L491: FUNCTION function-name MUST HAVE RETURNS, AND EITHER EXTERNAL OR SOURCE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -491, for information.
  • L492: function-name PARAMETER number HAS MISMATCH WITH A SOURCE FUNCTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -492, for information.
  • L495: EST COST OF estimate-amount1 PROCESSOR SECONDS EXCEEDS RESOURCE LIMIT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -495, for information.
  • L496: SQL STATEMENT REFERENCES A RESULT SET NOT CREATED BY THE CURRENT SERVER
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -496, for information.
  • L497: INTERNAL IDENTIFIERS LIMIT HAS BEEN EXCEEDED FOR DATABASE database-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -497, for information.
  • L499: CURSOR cursor-name ALREADY ASSIGNED TO procedure-name RESULT SET
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -499, for information.
Parent topic: L - Link Error Messages


L500 - L549

Lists the Link error messages from L500 through L549.

  • L500: IDENTIFIED CURSOR WAS CLOSED WHEN THE CONNECTION WAS DESTROYED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -500, for information.
  • L501: Cursor identified in a FETCH or CLOSE statement is not open.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -501, for information.
  • L502: The cursor identified in an OPEN statement is already open.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -502, for information.
  • L503: Column cannot be updated because it is not in the UPDATE clause of the select.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -503, for information.
  • L504: The cursor name name is not defined.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -504, for information.
  • L507: The cursor identified in the UPDATE or DELETE statement is not open.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -507, for information.
  • L508: Cursor identified in an update or delete is not positioned on a row.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -508, for information.
  • L509: The table in an UPDATE or DELETE is not a table designated by cursor.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -509, for information.
  • L510: Table designated by cursor of UPDATE/DELETE statement cannot be modified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -510, for information.
  • L511: FOR UPDATE clause invalid because cursor cannot be modified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -511, for information.
  • L512: Statement reference to remote object is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -512, for information.
  • L513: The alias name must not be defined by another local or remote alias.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -513, for information.
  • L514: The cursor name is not in a prepared state.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -514, for information.
  • L516: The described statement does not identify a prepared statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -516, for information.
  • L517: Cursor name does not identify a prepared SELECT statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -517, for information.
  • L518: The EXECUTE statement does not identify a valid prepared statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -518 for information.
  • L519: PREPARE identifies SELECT statement of the open cursor name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -519, for information.
  • L525: SQL cannot execute, error at bind for section sectno, package pkgname, consistency token Xcontoken.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -519, for information.
  • L526: REQUESTED FUNCTION DOES NOT APPLY TO GLOBAL TEMPORARY TABLES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -526, for information.
  • L530: The INSERT or UPDATE value of foreign key name is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -530, for information.
  • L531: Primary key in parent has dependent rows in relation name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -531, for information.
  • L532: The relation name restricts the deletion of row with RID X number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -532, for information.
  • L533: Invalid multiple-row insert.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -533, for information.
  • L534: The primary key cannot be updated because of multiple-row update.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -534, for information.
  • L535: Invalid update or delete with WHERE CURRENT OF.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -535, for information.
  • L536: Delete is invalid because table name can be affected by the operation.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -536, for information.
  • L537: Primary key/foreign key identifies column name more than once.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -537, for information.
  • L538: Foreign key name does not match description of primary key of table name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -538, for information.
  • L539: Table name does not have a primary key.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -539, for information.
  • L540: Definition of table name does not have primary index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -540, for information.
  • L541: FOREIGN KEY key-name HAS DUPLICATE REFERENTIAL CONSTRAINT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -541, for information.
  • L542: name cannot be a column of primary key because it can contain NULL values.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -542, for information.
  • L543: CANNOT DELETE ROW IN PARENT TABLE; RESTRICTED BY CONSTRAINT check-constraint
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -543, for information.
  • L544: CANNOT ADD CHECK CONSTRAINT; EXISTING ROW VIOLATES THE CHECK CONSTRAINT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -544, for information.
  • L545: The requested operation is not allowed because of the check constraint CheckConstraint.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -545, for information.
  • L546: CHECK CONSTRAINT constraint-name IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -159, for information.
  • L548: A CHECK CONSTRAINT THAT IS DEFINED WITH column-name IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -548, for information.
  • L549: The Statement statement is not allowed for ObjectType1ObjectName because the bind option dynamicrules in the ObjectType2 is in effect.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -549, for information.
Parent topic: L - Link Error Messages


L550 - L599

Lists the Link error messages from L550 through L599.

  • L551: Authid does not have privileges to perform operation Name on this object.
    If you are using the ODBC Smart Driver to monitor or record SQL, check that the specified authid has permission to access the ODBC_* tables used by the Static Bind Administrator. For a list of these tables and the permissions required to access them, see the GRANT statements in the ODBCSQL.SQL file located in your Micro Focus program directory.
  • L552: authid does not have the privileges to perform operation operation.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -552, for information.
  • L553: authid specified is not one of the valid AuthIDs.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -553, for information.
  • L554: An AuthID cannot grant a privilege to itself.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -554, for information.
  • L555: An AuthID cannot revoke a privilege from itself.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -555, for information.
  • L556: A privilege cannot be revoked because it is not possessed by authid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -556, for information.
  • L557: Inconsistent grant/revoke keyword keyword. Permitted keywords are keyword-list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -557, for information.
  • L558: Invalid clause or combination of clauses on a grant or revoke.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -558, for information.
  • L559: All authorization functions have been disabled.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -559, for information.
  • L567: bind-type AUTHORIZATION ERROR FOR auth-idpackage-nameprivilege
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -567, for information.
  • L571: The statement would result in a multiple site update.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -571, for information.
  • L573: table-name DOES NOT HAVE UNIQUE KEY WITH SPECIFIED COLUMN NAMES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -573, for information.
  • L574: THE DEFAULT VALUE CONFLICTS WITH DEFINITION OF COLUMN column-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -574, for information.
  • L577: DEFINITION OF object-typeobject-name DID NOT SPECIFY MODIFY DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -577, for information.
  • L579: DEFINITION OF object-typeobject-name DID NOT SPECIFY READ OR MODIFY DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -579, for information.
  • L580: THE RESULT-EXPRESSIONS OF A CASE EXPRESSION CANNOT ALL BE NULL
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -580, for information.
  • L581: RESULT-EXPRESSION DATA TYPES OF CASE EXPRESSION ARE NOT COMPATIBLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -581, for information.
  • L582: WHEN-CLAUSE CONDITION CANNOT BE QUANTIFIED, IN, OR EXISTS PREDICATE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -582, for information.
  • L583: INVALID USE OF FUNCTION; function-name NOT DETERMINISTIC/EXTERNAL ACTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -583, for information.
  • L585: SCHEMA NAME schema-name CANNOT APPEAR MORE THAN ONCE IN THE CURRENT PATH
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -585, for information.
  • L586: TOTAL LENGTH OF CURRENT PATH SPECIAL REGISTER CANNOT EXCEED 254 CHARACTERS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -586, for information.
  • L587: A LIST OF ITEM-REFERENCES ARE NOT IN THE SAME FAMILY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -587, for information.-587, for information.
  • L590: PARAMETER parameter-name NOT UNIQUE FOR ROUTINE routine-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -590, for information.
  • L592: NOT AUTHORIZED TO CREATE FUNCTIONS/PROCEDURES IN WLM ENV env-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -592, for information.
Parent topic: L - Link Error Messages


L600 - L649

Lists the Link error messages from L600 through L649.

  • L601: Name of the object to be created identical to existing name name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -601, for information.
  • L602: Too many columns specified in a CREATE INDEX.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -602, for information.
  • L603: Unique index cannot be created. The table has rows with duplicate columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -603, for information.
  • L604: Column definition specifies an invalid length, precision, or scale attribute.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -604, for information.
  • L607: Operation operation is not defined for system tables.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -607, for information.
  • L611: ONLY LOCKMAX 0 CAN BE SPECIFIED WHEN LOCK SIZE IS TABLESPACE OR TABLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -611, for information.
  • L612: name is a duplicate column name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -612, for information.
  • L613: The primary key is too long or has too many columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -613, for information.
  • L614: Cannot create index. Sum of internal lengths of columns > allowable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -614, for information.
  • L615: op is not allowed on a package in use.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -615, for information.
  • L616: obj-typeobj-name CANNOT BE DROPPED; REFERENCED BY obj-typeobj-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -616, for information.
  • L617: TYPE 1 INDEX IS NOT VALID FOR TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -617, for information.
  • L618: Operation operation is not allowed on system databases.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -618, for information.
  • L619: Operation disallowed because the workfile database is not stopped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -619, for information.
  • L620: Keyword keyword not allowed for tablespace in workfile database.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -620, for information.
  • L621: Duplicate dbid dbid was detected and previously assigned to dbname.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -621, for information.
  • L622: FOR MIXED DATA is invalid because MIXED DATA inst opt is NO.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -622, for information.
  • L623: A clustering index already exists on table name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -623, for information.
  • L624: Table name already has a primary key.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -624, for information.
  • L625: TABLE table-name DOES NOT HAVE INDEX TO ENFORCE UNIQUENESS OF PARENT KEY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -625, for information.
  • L626: ALTER statement is not executable because the pageset is not stopped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -626, for information.
  • L627: ALTER statement is invalid because the pageset has user-managed data set.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -627, for information.
  • L628: THE CLAUSES ARE MUTUALLY EXCLUSIVE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -628, for information.
  • L629: No set NULL because foreign key name cannot contain NULL values.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -629, for information.
  • L630: WHERE NOT NULL SPECIFICATION IS INVALID FOR TYPE 1 INDEXES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -630, for information.
  • L631: Foreign key name is too long or has too many columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -631, for information.
  • L632: Cannot define table as dependent of name due to delete rule restriction.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -632, for information.
  • L633: The delete rule must be delete.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -633, for information.
  • L634: The delete rule must not be cascade.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -634, for information.
  • L635: The delete rules cannot be different or cannot be set NULL.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -635, for information.
  • L636: Partitioning keys not specified in ascending/descending order.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -636, for information.
  • L637: Duplicate keyword keyword.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -637, for information.
  • L638: Table name cannot be created. Column definition is missing.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -638, for information.
  • L639: Column of foreign key with delete rule of set NULL cannot be in partition index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -639, for information.
  • L640: LOCKSIZE ROW CANNOT BE SPECIFIED; TABLE HAS TYPE 1 INDEX
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -640, for information.
  • L642: TOO MANY COLUMNS IN UNIQUE CONSTRAINTS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -642, for information.
  • L643: CHECK CONSTRAINT EXCEEDS MAXIMUM ALLOWABLE LENGTH
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -643, for information.
  • L644: INVALID VALUE SPECIFIED FOR KEYWORD keyword IN statement-type STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -644, for information.
  • L646: Cannot create table name in partitioned default tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -646, for information.
  • L647: Bufferpool name cannot be specified. It has not been activated.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -647, for information.
Parent topic: L - Link Error Messages


L650 - L699

Lists the Link error messages from L650 through L699.

  • L650: THE ALTER INDEX CANNOT BE EXECUTED, REASON reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -650, for information.
  • L651: TABLE DESCRIPTION EXCEEDS MAXIMUM SIZE OF OBJECT DESCRIPTOR
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -651, for information.
  • L652: Violation of installation-defined edit or validation procedure proc.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -652, for information.
  • L653: Table name in partitioned tablespace name not available.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -653, for information.
  • L655: CREATE OR ALTER STOGROUP IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -655, for information.
  • L658: object-type CANNOT BE DROPPED USING THE statement STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -658, for information.
  • L660: Cannot create index name on partitioned tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -660, for information.
  • L661: Cannot create index name on partitioned tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -661, for information.
  • L662: Cannot create a partitioned index on a non-partitioned tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -662, for information.
  • L663: Number of key limit values is 0, or > number of columns in key of index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -663, for information.
  • L664: Internal length of limit-key fields for partitioned index name is too long.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -664, for information.
  • L665: The PART clause of an ALTER statement is omitted or invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -665, for information.
  • L666: stmt-verbobject cannot be executed because of something in progress.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -666, for information.
  • L667: Clustering index for partitioned tablespace cannot be explicitly dropped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -667, for information.
  • L668: Cannot add column to the table because the table has an edit procedure.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -668, for information.
  • L669: A table in a partitioned tablespace cannot be explicitly dropped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -669, for information.
  • L670: The record length of the table exceeds the page size limit.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -670, for information.
  • L671: Cannot alter buffpool attr of tablespace because pg size of tablespace would change.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -671, for information.
  • L672: OPERATION DROP NOT ALLOWED ON TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -672, for information.
  • L676: A 32K page bufferpool may not be used for an index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -676, for information.
  • L677: Insufficient virtual storage for bufferpool expansion.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -677, for information.
  • L678: literal specified for index limit key must conform to data type type.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -678, for information.
  • L679: Object name cannot be created. A drop is pending on the object.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -679, for information.
  • L680: Too many columns specified for a table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -680, for information.
  • L681: Column name in violation of installation-defined field procedure name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -681, for information.
  • L682: Field procedure proc could not be loaded.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -682, for information.
  • L683: Invalid column type for fieldproc or bit data option, column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -683, for information.
  • L684: The length of literal list beginning string is too long.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -684, for information.
  • L685: Invalid field type column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -685, for information.
  • L686: Cannot compare column defined by one field procedure to one defined by another.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -686, for information.
  • L687: Field types incomparable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -687, for information.
  • L688: Incorrect data returned from field procedure, column, msgno.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -688, for information.
  • L689: Too many columns defined for a dependent table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -689, for information.
  • L690: Statement is rejected by data def ctrl support, reason reason.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -690, for information.
  • L691: The required registrations table table does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -691, for information.
  • L692: Unique index index-name in table table-name does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -692, for information.
  • L693: Column column is not defined properly.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -693, for information.
  • L694: DDL STMT CANNOT EXECUTE; DROP PENDING ON DDL REGISTRATION TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -694, for information.
  • L696: TRIGGER trigger-name CONTAINS INVALID USE OF NAME name, REASON reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -696, for information.
  • L697: CORR. NAMES NOT ALLOWED IN TRIGGER WITH "FOR EACH STATEMENT" OR "BEFORE"
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -697, for information.
Parent topic: L - Link Error Messages


L700 - L799

Lists the Link error messages from L700 through L799.

  • L713: REPLACEMENT VALUE value FOR special-register IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -713, for information.
  • L715: Prog program dep on function of the release from which fallback has occurred.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -715, for information.
  • L716: Program program precompiled with wrong level for this release.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -716, for information.
  • L717: object dependent on function of release from which fallback has occurred.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -717, for information.
  • L718: REBIND failed because IBMREQD of ibmreqd is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -718, for information.
  • L719: BIND ADD error, package package already exists.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -719, for information.
  • L720: Attempt to replace package package with existing version version.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -720, for information.
  • L721: BIND err CONTOK = contoken X cannot be created because it is not unique.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -721, for information.
  • L722: Package package does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -722, for information.
  • L723: ERROR IN TRIGGER trigger-name, SECTION NUMBER section-number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -723, for information.
  • L724: ACTIVATION OF object-typeobject-name WOULD EXCEED MAXIMUM OF SQL CASCADING
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -724, for information.
  • L725: SPECIAL REGISTER register AT location WAS SUPPLIED INVALID VALUE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -725, for information.
  • L726: Cannot replace package package. Enable or disable entries also with package.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -726, for information.
  • L728: DATA TYPE data-type IS NOT ALLOWED IN DB2 PRIVATE PROTOCOL PROCESSING
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -728, for information.
  • L729: COMMIT ON RETURN STORED PROCEDURE CANNOT BE IN NESTED CALL STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -729, for information.
  • L730: The parent of a table in a read-only database must also be in the database.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -730, for information.
  • L731: User-defined dataset dsname must be defined with SHAREOPTIONS(1,3).
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -731, for information.
  • L732: Table space or index space has not been defined on the owning subsystem.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -732, for information.
  • L733: The description of a table space, index space or ROSHARE READ db must be consistent.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -733, for information.
  • L734: The ROSHARE attr of a database cannot be altered from ROSHARE READ.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -734, for information.
  • L735: Database dbid is not longer a shared database.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -735, for information.
  • L736: Invalid OBID obid specified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -736, for information.
  • L737: Implicit table space not allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -737, for information.
  • L739: ALTER function-name FAILED; PARALLEL PROCESSED FUNCTIONS CANNOT MODIFY DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -739, for information.
  • L740: FUNCTION name THAT MODIFIES SQL DATA IS NOT VALID IN CURRENT CONTEXT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -740, for information.
  • L741: WORK FILE DATABASE IS ALREADY DEFINED FOR MEMBER member-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -741, for information.
  • L742: DSNDB07 IS THE IMPLICIT WORK FILE DATABASE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -742, for information.
  • L746: SQL STATEMENT IN name VIOLATES THE NESTING SQL RESTRICTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -746, for information.
  • L747: table-name NOT AVAILABLE UNTIL AUX TABLES AND INDEXES HAVE BEEN CREATED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -747, for information.
  • L748: AN INDEX ALREADY EXISTS ON AUXILIARY TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -748, for information.
  • L750: TABLE source-name CANNOT BE RENAMED; REFERENCED BY EXISTING DEFINITIONS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -750, for information.
  • L751: object-typeobject-name (specific-name) ATTEMPTED TO EXECUTE statement
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -751, for information.
  • L752: CONNECT statement invalid because the process is not in the connectable state.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -752, for information.
  • L763: INVALID TABLE SPACE NAME table-space-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -763, for information.
  • L764: LOB TABLE SPACE AND ITS BASE TABLE SPACE MUST BE IN SAME DATABASE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -764, for information.
  • L765: TABLE IS NOT COMPATIBLE WITH DATABASE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -765, for information.
  • L766: REQUESTED OPERATION NOT PERMITTED ON AUXILIARY TABLE OF STATEMENT OBJECT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -766, for information.
  • L767: MISSING OR INVALID COLUMN SPECIFICATION FOR INDEX index-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -767, for information.
  • L768: AUXILIARY TABLE ALREADY EXISTS FOR THE SPECIFIED COLUMN OR PARTITION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -768, for information.
  • L769: SPECIFICATION OF AUX TABLE DOES NOT MATCH CHARACTERISTICS OF BASE TABLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -769, for information.
  • L770: TABLE table-name CANNOT HAVE LOB COLUMN UNLESS IT ALSO HAS ROWID COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -770, for information.
  • L771: INVALID SPECIFICATION OF A ROWID COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -771, for information.
  • L797: ATTEMPT TO CREATE TRIGGER trigger-name WITH AN UNSUPPORTED SQL STATEMENT
  • L798: ATTEMPT TO INSERT VALUE INTO ROWID GENERATED ALWAYS COLUMN column-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -798, for information.
Parent topic: L - Link Error Messages


L800 - L899

Lists the Link error messages from L800 through L899.

  • L802: EXCEPTION ERROR exception-type OCCURRED DURING operation-type OPERATION ON data-type DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -802, for information.
  • L803: INSERT/UPDATE INVALID;INDEX SPACE index-space-name RESTRICTS DUP COLUMNS, RID row-id
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -803, for information.
  • L804: Error found in application program input parameters for the SQL statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -804, for information.
  • L805: Program name name not found in plan name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -805, for information.
  • L807: Access denied to package pkg.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -807, for information.
  • L808: CONNECT STATEMENT IS NOT CONSISTENT WITH THE FIRST CONNECT STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -808, for information.
  • L811: Result of embedded select statement is a table with more than one row.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -811, for information.
  • L812: BLANK COLLECTION-ID IN CURRENT PACKAGE SET; PGM program-name.consistency-token USING PLAN plan-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -812, for information.
  • L815: GROUP BY/HAVING clause specified in embedded select statement/subquery.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -815, for information.
  • L817: Cannot execute INSERT/UPDATE/DELETE/DLL/AUTHORIZATION statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -817, for information.
  • L818: Timestamp in load module is not the same as bind timestamp built from the DBRM.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -818, for information.
  • L819: Cannot process view. Length of its parse tree in the catalog is zero.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -819, for information.
  • L820: Cannot process SQL statement. catalog contains a value not valid in version.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -820, for information.
  • L822: SQLDA contains invalid data address or indicator variable address.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -822, for information.
  • L840: Too many items returned in a select or insert list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -840, for information.
  • L842: A CONNECTION TO location-name ALREADY EXISTS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -842, for information.
  • L843: SET CONNECTION OR RELEASE STATEMENT MUST SPECIFY AN EXISTING CONNECTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -843, for information.
  • L870: NUMBER OF HOST VARIABLES IN STATEMENT NOT EQUAL TO NUMBER OF DESCRIPTORS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -870, for information.
  • L872: A VALID CCSID HAS NOT YET BEEN SPECIFIED FOR THIS SUBSYSTEM
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -872, for information.
  • L873: DATA ENCODED WITH DIFFERENT CCSIDS CANNOT BE REFERENCED IN SAME STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -873, for information.
  • L874: object-type ENCODING SCHEME MUST BE SAME AS THE CONTAINING TABLE SPACE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -874, for information.
  • L875: operand CANNOT BE USED WITH THE ASCII DATA REFERENCED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -875, for information.
  • L876: 'object' CANNOT BE CREATED, REASON 'reason'
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message
  • L877: CCSID ASCII IS NOT ALLOWED FOR THIS DATABASE OR TABLE SPACE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -877, for information.
  • L878: THE PLAN_TABLE USED FOR EXPLAIN CANNOT BE ASCII
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -878, for information.
  • L879: object-name CANNOT DEFINE OBJECT MIXED/GRAPHIC WITH ENCODING SCHEME encoding-scheme
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -879, for information.
Parent topic: L - Link Error Messages


L900 - L999

Lists the Link error messages from L900 through L999.

  • L900: Cannot EXEC SQL because application is not connected to application server.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -900, for information.
  • L901: System error caused failed execution so subsequent SQL may be successful.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -901, for information.
  • L902: Pointer to the essential ctrl block (CT/RDA) has value 0, rebind required.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -902, for information.
  • L904: Unavailable resource caused failed exec. type type of resource name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -904, for information.
  • L905: Fail exec due to resource limit, resource name name limit amount.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -905, for information.
  • L906: Cannot execute SQL statement. Function disabled due to a prior error.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -906, for information.
  • L907: Unable to determine if commit of updates made at a remote site failed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -907, for information.
  • L908: bind error using authid authority no bind or rebind are allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -908, for information.
  • L909: The object has been deleted.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -909, for information.
  • L910: SQL statement cannot access object on which a drop/alter is pending.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -910, for information.
  • L911: Rollback due to a deadlock/timeout. Reason code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -911, for information.
  • L913: Failed execution cause by deadlock/timeout. Reason code code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -913, for information.
  • L917: Bind package failed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -917, for information.
  • L918: SQL cannot be executed because connection has been lost.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -918, for information.
  • L919: A ROLLBACK OPERATION IS REQUIRED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -919, for information.
  • L922: AUTHORIZATION FAILURE: error-type ERROR. REASON reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -922, for information.
  • L923: CONNECTION NOT ESTABLISHED: DB2 condition REASON reason-code, TYPE resource-type, NAME resource-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -923, for information.
  • L924: DB2 CONNECTION INTERNAL ERROR, function-code, return-code, reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -924, for information.
  • L925: Commit not valid in IMS/VS or CICS environment.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -925, for information.
  • L926: Rollback not valid in IMS/VS or CICS environment.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -926, for information.
  • L927: Language interface called when the connecting environment was not established.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -927, for information.
  • L929: FAILURE IN A DATA CAPTURE EXIT: token
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -929, for information.
  • L939: ROLLBACK REQUIRED DUE TO UNREQUESTED ROLLBACK OF A REMOTE SERVER
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -939, for information.
  • L947: STATEMENT FAILED;WILL CHANGE TABLE DEFINED BUT DATA CANNOT BE PROPAGATED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -947, for information.
  • L948: DISTRIBUTED OPERATION IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -948, for information.
  • L950: Location name is invalid or not in comm db.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -950, for information.
  • L981: STATEMENT FAILED;CONNECTION DOES NOT ALLOW SQL OPERATIONS, REASON reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -981, for information.
  • L991: CrossAccess Data Access error ErrorNum (ConditionCode) for IMS/VSAM. Consult CrossAccess System Messages documentation.
    CrossAccess experienced the specified data error while processing an SQL request against IMS/VSAM. For additional information about this error, see your CrossAccess User Documentation.
  • L992: CrossAccess System error ErrorNum while accessing IMS/VSAM. Contact mainframe systems programming.
    CrossAccess has experienced the specified system error while attempting to access IMS/VSAM. For additional information about this error, see your CrossAccess User Documentation.
Parent topic: L - Link Error Messages


L1000 - L1099

Lists the Link error messages from L1000 through L1099.

  • L1000: Exec failed. Protocol error: Reason reason (type)
  • L1020: Exec failed with dealloc. Protocol error: reason 1218 (02)
    Manager dependency error detected at other node.
  • L1021: :Execution failed. Manager manager at level level not supported.
    Managers must support certain levels.
  • L1040: Unavail resource caused perm failure. Reason Alloc type type.
    Type = Semaphore
  • L1041: Unavail resource caused perm failure. Reason Alloc type type.
    Type = Semaphore
  • L1050: command command or SQL invalid while bind in progress.
    A binding must be completed before other SQL can be issued.
  • L1051: Bind with specified package name and consistency token not active.
    A section of a package could not be bound because a BEGIN BIND has not been called.
  • L1052: Program preparation assumptions are incorrect.
    The program preparation assumptions in effect for binding a statement (i.e. BINDSQLSTT command) are incorrect.
  • L1053: Owner authorization failure.
    A command could not be executed because the user is not authorized.
  • L1060: RDB authorization failure.
    The user is not authorized to access the location specified.
  • L1061: RDB not found.
    The location name is not valid.
  • L1070: command command not supported.
    The code point indicates a request data stream structure that is not supported.
  • L1071: object object not supported error.
    The code point indicates an object data stream structure that is not supported.
  • L1072: parameter parameter not supported error.
    The code point indicates that a data stream structure parameter is not supported.
  • L1073: value parameter value not supported error.
    The code point indicates that a data stream structure parameter value is not supported.
  • L1074: Reply message with codepoint (severity) not supported.
    The reply message returned from the target is not recognized.
  • L1080: Communication error primary (secondary).
    An unmapped APPC error has occurred.
  • L1090: Remote operation invalid for application execution environment.
    An update operation or a dynamic commit or rollback was attempted at a server that was supporting an application that was in a read-only execution environment (IMS or CICS).
Parent topic: L - Link Error Messages


L30000 - L30099

Lists the Link error messages from L30000 through L30099.

  • L30000: Distribution protocol error: reason reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30000, for information.
  • L30020: Distribution protocol error cause deallocation reason: reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30020, for information.
  • L30021: Distribution protocol error: manager manager at level level not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30021, for information.
  • L30030: Not committed, SQLCODE = orig-sqlcode and SQLSTATE = orig-sqlstate.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30030, for information.
  • L30040: Unavailable resource. Reason reason-code type rsrc-type, name rsrc-name, id pppvvrrm, RDBNAME rdbname.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30040, for information.
  • L30041: Unavailable resource. Reason reason-code type resource-type name resource-name id pppvvrrm RDBNAME rdbname.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30041, for information.
  • L30050: command or SQL statement invalid while bind.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30050, for information.
  • L30051: Bind process with specified package name and consistency token not active.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30051, for information.
  • L30052: Program preparation assumptions are incorrect.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30052, for information.
  • L30053: Owner authorization failure.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30053, for information.
  • L30060: RDB authorization failure.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30060, for information.
  • L30061: RDB not found.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30061, for information.
  • L30070: command command not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30070, for information.
  • L30071: object object not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30071, for information.
  • L30072: parameter: subcode parameter not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30072, for information.
  • L30073: parameter: subcode parameter value not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30073, for information.
  • L30074: Reply message with codepoint (SRVCOD) not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30074, for information.
  • L30080: Communication error code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30080, for information.
  • L30090: Remote operation invalid for application execution.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30090, for information.
Parent topic: L - Link Error Messages


N - Network Error Messages

  • N000 - N099
    Lists the Network error messages from N000 through N099.
  • N300 - N399
    Lists the Network error messages from N300 through N399.
  • N400 - N449
    Lists the Network error messages from N400 through N449.
  • N450 - N499
    Lists the Network error messages from N450 through N499.
  • N500 - N599
    Lists the Network error messages from N500 through N599.
Parent topic: SQL Option for DB2 Error Messages


N000 - N099

Lists the Network error messages from N000 through N099.

  • N001: Illegal buffer length value.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N002: Undocumented NetBIOS error.
    Undocumented NetBIOS error.
  • N003: Invalid network command.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N004: Undocumented NetBIOS error.
    Undocumented NetBIOS error.
  • N005: NetBIOS command timed out.
    If this error was received while trying to log into the server, then the XDB Server name could not be found. Otherwise, an internal NetBIOS error occurred. Contact Micro Focus Technical Support.
  • N006: Incomplete network message.
    Communications packet was larger than the maximum Receive Buffer size specified by user, either at the server or at the client. If the error was received at the server, check the settings in the XDB Server Configuration utility; if received at the client, check the settings in Options.
  • N008: Illegal local session number number.
    Either the NetBIOS connection to the server was broken (an N024 error preceded this or was ignored) or the connection was never established. For example, this error will occur when a COBOL program attempts and fails to successfully log into the server.
  • N009: Resource is not available.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N010: Session # number closed.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N011: Command canceled.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N012: Undocumented NetBIOS error.
    Undocumented NetBIOS error.
  • N013: Duplicate name name in local name table.
    This error should not be reported to the user. Contact Micro Focus Technical Support if you receive this error.
  • N014: Network name table is full.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N015: Command completed, name has active session and is now de-registered.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N017: Local session table is full.
    Either the maximum number of users specified through the XDB Server Configuration utility are logged into the XDB Server, or the maximum number of NetBIOS sessions allowed by the network software has been reached. In case of the latter, check with your LAN supervisor.
  • N018: Cannot open network session.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N019: Illegal session name identification number.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N020: Cannot find name called or no answer.
    Either the XDB Server is not running, or you are trying to log into an XDB Server that does not exist. Access Options and change the server name. See the XDB Server Administration Guide for instructions on configuring the XDB Server. You may need to increase the timeout period on the client. Also check that NetBIOS is loaded and that your NetBIOS settings are compatible between the server and the client.
  • N021: Name name not found.
    Either the XDB Server is not running, or you are trying to log into an XDB Server that does not exist. Access Options and change the server name. See the XDB Server Administration Guide for instructions on configuring the XDB Server. You may need to increase the timeout period on the client. Also check that NetBIOS is loaded and that your NetBIOS settings are compatible between the server and the client.
  • N022: Name name in use on remote adapter.
    Either the specified server name (if error was received on an XDB Server) or the workstation node name already exists on the network. Try using a different node name. See your Setup guide or the XDB Server Administration Guide for information about configuring the node name for a client workstation or an XDB Server, respectively.
  • N023: Name name was deleted.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N024: Session ended abnormally.
    This error message will appear when the connection between the client and the server is broken. Check to see that the server is up and that there is no problem with the network.
  • N025: Name conflict detected.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N026: Incompatible remote device.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N027 - N032: Undocumented NetBIOS errors.
    Undocumented NetBIOS error.
  • N033: Interface busy.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N034: Too many commands outstanding.
    Internal NetBIOS error. Too many NetBIOS request threads were specified in the XDB Server Configuration. Either reduce the number or edit your NET.CFG for Novell and increase NetBIOS and/or Named Pipe sessions (or in the case of a LAN server increase the number of sessions in the NETBEUI_NIF section of PROTOCOL.INI).
  • N035: Invalid number in NCB_LANA_NUM field.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N036: Command completed while cancel occurring.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N037: Attempt to use reserved name as a group name.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N038: Attempt to issue a command out of sequence.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N040 - N049: Unusual network conditions.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N050: NetBIOS is not loaded.
    The XDB Server requires a NetBIOS-compatible network with NetBIOS running. Check with your Network Administrator. Also you must have both IBM and Novell NetWare in your CONFIG.SYS in OS/2.
  • N051 - N254: Unusual network conditions.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
Parent topic: N - Network Error Messages


N300 - N399

Lists the Network error messages from N300 through N399.

  • N300: TCP Error errmsgfunction( ) = errorcode
    The indicated TCP/IP error occurred. The list below shows possible error codes and their associated error messages.
  • N301: SPX Error: errmsgfunction() = errcode
    The indicated IPX/SPX error occurred. The list below shows possible error codes and their associated error messages:
  • N302: NETBIOS Error errmsgfunction = errorcode
    The specified NETBIOS error has occurred. For example, if you attempt to connect to a server using an invalid server name, or if the specified server is not up and running, the following message is displayed:
  • N357: Invalid Named Pipe function call (ERROR_INVALID_FUNCTION).
    Internal Named Pipes Error. Contact Micro Focus Technical Support.
  • N358: Invalid path path specified for Named Pipe (ERROR_FILE_NOT_FOUND).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N359: Cannot find Named Pipe name (ERROR_PATH_NOT_FOUND).
    Make sure that the XDB Server configuration (XDBSRVCO.EXE or XDBSRVBT.EXE) setting for the number of Named Pipes threads is greater than zero, and that the Named Pipes protocol is turned on.
  • N360: Access denied to Named Pipe name (ERROR_ACCESS_DENIED).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N361: Invalid handle to Named Pipe specified (ERROR_INVALID_HANDLE).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N362: Not enough memory for Named Pipe operation (ERROR_NOT_ENOUGH_MEMORY).
    Close or remove some programs from your machine or acquire more RAM.
  • N363: Invalid format specified for Named Pipe (ERROR_BAD_FORMAT).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N364: No more structures available for Named Pipe name (ERROR_OF_STRUCTURES).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N365: Invalid parameter specified for Named Pipe call (ERROR_INVALID_PARAMETER).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N366: Named Pipes system call interrupted (ERROR_INTERRUPT).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N367: Named Pipe name is broken (ERROR_BROKEN_PIPE).
    The connection has been broken between the server and the client. Check to see that the server is up and that there is no problem with the network. Check that your Named Pipes configuration matches that in the XDB Server Configuration utility.
  • N368: Buffer too small for Named Pipe (ERROR_BUFFER_OVERFLOW).
    The communications packet was larger than the maximum. See error N006.
  • N369: Semaphore not found (ERROR_SEM_TIMEOUT).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N370: Invalid name name specified for Named Pipe (ERROR_INVALID_NAME).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N371: Invalid level parameter (ERROR_INVALID_LEVEL).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N372: Invalid name name specified for Named Pipe (ERROR_SEM_NOT_FOUND).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N373: Handle does not refer to Named Pipe (ERROR_BAD_PIPE).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N374: All available instances of Named Pipe name are in use (ERROR_PIPE_BUSY).
    The maximum number of users communicating via Named Pipes is logged into the XDB Server. To correct this problem, try increasing the number of Named Pipe Receive Threads (XDB Server Configuration utility, Multi-user Options). Also, if embedding SQL in COBOL, check your code to be sure you have not used the LOGON and LOGOFF directives in subprograms. See the XDB Server Administration Guide for configuration information.
  • N375: Data unavailable on non-blocking read (ERROR_NO_DATA).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N376: Named Pipe name currently not connected (ERROR_PIPE_NOT_CONNECTED).
    The connection has been broken between the server and the client.
  • N377: Buffer too small for Named Pipe name (ERROR_MORE_DATA).
    The communications packet was larger than the maximum. Check the settings in the XDB Server Configuration utility and in Options.
  • N396: Undocumented Named Pipes error number.
    Internal error. If number = 53, and using Novell NetWare, you must put your server name after NPDAEMON.EXE in your CONFIG.SYS file. You may be starting an OS/2 client against a local OS/2 server (make sure the OS/2 environment variable XDBSERVE is set to LOCAL). Otherwise, contact Micro Focus Technical Support.
Parent topic: N - Network Error Messages


N400 - N449

Lists the Network error messages from N400 through N449.

  • N406: Bad transaction program identifier: identifier.
    The tp_id parameter of the APPC verb is not valid. Either the TP_STARTED verb has failed or the tp_id returned after issuing the TP_STARTED verb was not moved into the current verb control block.
  • N407: Bad conversation identifier: identifier.
    The conv_id parameter used in an APPC verb is invalid. The most likely cause of this error is a failure on the remote system that is severe enough to deallocate the conversation.
  • N408: Bad logical unit alias: alias.
    The local LU alias referenced is not defined. A local LU name in communication manager must be defined with an alias that matches the name of the XDB Server.
  • N409: Allocation failure no retry. Sense code: code.
    A conversation cannot be started due to a permanent error condition requiring intervention. The sense code can be used to isolate the problem.
  • N410: Allocation failure retry. Sense code: code.
    A conversation cannot be started. On a system that has allocated conversations successfully in the past, the error might be recoverable without intervention. The sense code could be used to isolate the problem.
  • N411: Invalid data segment.
    The memory block used to send and receive data is invalid.
  • N412: Bad conversation type parameter.
    The conversation_type APPC verb parameter is invalid. Only basic conversations and mapped conversations are supported.
  • N413: Bad synchronization level parameter.
    The sync_level APPC verb parameter value is invalid. XDB Server uses NONE for DRDA level 1.
  • N414: Bad security parameter.
    The security APPC verb parameter value is invalid. XDB Server uses PGM security.
  • N415: Bad return control parameter.
    The return_control APPC verb parameter value is invalid. XDB Server uses WHEN_SESSION_ALLOCATED.
  • N416: Program initialization parameter length incorrect.
    The pip_data_length APPC parameter value is too large.
  • N417: Use of SNASVCMG or CPSVCMG for mode not allowed.
    The mode names SNASVCMG and CPSVCMG are reserved and should not be used when allocating a conversation.
  • N418: Unknown partner mode/alias:"<".
    The partner LU alias referenced is not defined. A partner LU in communication manager must have an alias that matches the PLU alias name entered when defining a location using XDBGPROF.EXE.
  • N419: Dealloc bad type parameter.
    The type APPC verb parameter value is invalid.
  • N420: Dealloc flush bad state.
    The dealloc APPC verb type parameter value is incorrect for the state of the conversation.
  • N421: Dealloc confirm bad state.
    The dealloc APPC verb type parameter value is incorrect for the state of the conversation.
  • N422: Dealloc not logical length body.
    An incomplete logical record was sent when the dealloc was issued.
  • N423: Dealloc log logical length wrong.
    The log_data_length APPC verb parameter value does not match the LL field.
  • N424: Receive and wait bad state.
    The conversation is not in Receive or Send state.
  • N425: Receive and wait not logical length body.
    An incomplete logical record was sent in Send state when the Receive was issued.
  • N426: Receive and wait bad fill parameter.
    The fill APPC verb parameter value is invalid.
  • N427: Bad return status with data parameter.
    The return_status_with_data APPC verb parameter value is invalid.
  • N428: Bad logical length.
    The Logical record length of the data buffer in invalid. Invalid values are X''0000'', X''0001'', X''8000'', and X''8001''.
  • N429: Send data not in send state.
    An attempt was made to send data when the conversation was in Receive state.
  • N430: Send data invalid type parameter.
    The type APPC verb parameter value is invalid.
  • N431: Send data confirm with synchronization none.
    The type APPC verb parameter value is incorrect for type of the conversation.
  • N432: Send data not logical length body.
    An incomplete record was sent in Send state.
  • N433: Bad type.
    The type APPC verb parameter value is invalid.
  • N434: Undefined transaction program name: name.
    The tp_name referenced was not found. The transaction program must be defined on the host system and match the value configured using XDBGPROF.EXE. When connecting to DB2 using DRDA the tp_name is X07F6C4C2 and the tp runs in the DDF address space.
  • N435: Attach manager already inactive.
    The APPC attach manager is not processing receive_allocate verbs.
  • N436: Allocate not pending.
    A receive_allocate APPC verb was issued and timed out before an incoming allocate request was received.
  • N437: Invalid process.
    A process issued a receive_allocate verb that was not started by the attach manager.
  • N438: Security not valid.
    The partner LU rejected the UserID or password used in the allocate call. Turn on security at the client using the Configuration utility. Make sure the UserID and password are valid for the host environment.
  • N439: Transaction program not available retry.
    The partner LU rejected the allocate call because the transaction program could not be started immediately.
  • N440: Transaction program not available no retry.
    The partner LU rejected the allocate call because the transaction program could not be started.
  • N441: Transaction program name not recognized.
    The partner LU rejected the allocate call because the tp_name was not recognized at the partner location.
  • N442: Program initialization parameter not allowed.
    The partner LU rejected the allocate call because it does not support PIP data or the TP has no PIP variables defined.
  • N443: Program initialization parameter not specified correctly.
    The partner LU rejected the allocate call because the number of PIP variables defined by the local TP does not match the number defined for the remote TP.
  • N444: Conversation type mismatch.
    The partner LU rejected the allocate call because the conversation type of the local TP does not match the conversation type of the remote TP.
  • N445: Synchronization level not supported.
    The sync_level APPC verb parameter value is not supported.
  • N446: Parameter check.
    A verb was issued with an invalid parameter value.
  • N447: State check.
    A verb was issued in a state that was not compatible with the verb.
  • N448: Allocation error.
    APPC failed to allocate a conversation with a remote TP.
  • N449: Dealloc abend.
    The conversation has ended abnormally.
Parent topic: N - Network Error Messages


N450 - N499

Lists the Network error messages from N450 through N499.

  • N450: Dealloc abend program.
    The conversation has ended abnormally and has been cleaned up.
  • N451: Dealloc abend switched virtual circuit.
    The conversation has ended abnormally and has been cleaned up.
  • N452: Dealloc abend timer.
    The conversation has ended abnormally and has been cleaned up.
  • N453: Dealloc normal.
    The conversation has ended normally.
  • N454: Program error no truncation.
    The remote TP has issued a send_error APPC verb.
  • N455: Program error truncation.
    The remote TP has issued a send_error APPC verb and some of the data received locally was truncated.
  • N456: Program error purging.
    The remote TP has issued a send_error APPC verb and some of the data sent to the remote TP was truncated.
  • N457: Conversation failure retry.
    A temporary failure has ended the conversation.
  • N458: Conversation failure no retry.
    A permanent failure has ended the conversation.
  • N459: Switch virtual circuit error no truncation.
    The remote TP has issued a send_error APPC verb.
  • N460: Switch virtual circuit error truncation.
    The remote TP has issued a send_error APPC verb and some of the data received locally was truncated.
  • N461: Switch virtual circuit error purging.
    The remote TP has issued a send_error APPC verb and some of the data sent to the remote TP was truncated.
  • N462: Unsuccessful.
    An APPC verb could not execute.
  • N463: Conversation type mixed.
    The TP has issued both basic and mapped conversation verbs on the same conversation.
  • N464: Transaction program is busy.
    An APPC verb could not execute because Communication Manager is processing another thread.
  • N465: Communication subsystem abended.
    Communication Manager has ended abnormally and will have to be restarted.
  • N466: Communication subsystem is not loaded.
    Either Communications Manager has not been started or it is not properly configured for APPC.
  • N467: Invalid verb segment.
    The verb crosses a segment boundary.
  • N468: Unexpected DOS error.
    An OS/2 system call in Communication Manager has failed unexpectedly.
  • N469: Stack too small.
    APPC has determined that the TP stack size is too small.
  • N476: Security Location Not Configured.
    First, install the Password Expiration Manager (PEM) on the mainframe (see the host installation and configuration instructions). Then, configure access to the remote host PEM software using the Gateway Profile utility. Select location type PEM (APPC) or PEM (TCP).
  • N477: Invalid Host Authorization.
    The AUTHID used to access the host database is not valid. Check your AUTHID and try again.
  • N478: Invalid Host Password.
    The AUTHID is valid, but the password is not. Check your password and try again.
  • N479: Host Authorization Has Expired.
    Your password has expired. See your host system administrator for assistance.
  • N480: Host Authorization Has Been Revoked.
    The AUTHID used to access the host database has been revoked. See your host system administrator for assistance.
  • N486: Nucleus loopback error.
    AS multiple database support problem. Contact Micro Focus Technical Support.
  • N487: AS target not supported.
    AS multiple database support problem.
  • N488: An AS target module failed to load.
    AS multiple database support problem.
  • N489: An AS target module function address was not found.
    AS multiple database support problem.
  • N496: Protocol memory allocation failure.
    Protocol module problem. Contact Micro Focus Technical Support.
  • N497: Transaction identifier is invalid.
    Protocol module problem. Contact Micro Focus Technical Support.
  • N498: Connection identifier is invalid.
    Protocol module problem. Contact Micro Focus Technical Support.
  • N499: Unsupported protocol.
    Protocol module problem.
Parent topic: N - Network Error Messages


N500 - N599

Lists the Network error messages from N500 through N599.

  • N500: A protocol module failed to load.
    Protocol module problem.
  • N501: A protocol module function address was not found.
    Protocol module problem.
  • N506: No available connections.
    In memory module problem.
  • N507: Open semaphore failure.
    In memory module problem.
  • N508: Create semaphore failure.
    In memory module problem.
  • N509: Shared memory failure.
    In memory module problem.
  • N510: Open process failure.
    In memory module problem.
  • N511: Cannot communicate with server.
    The client application cannot establish communications with the specified server. An "accept connection" failure has occurred.
  • N512: Connection is closed.
    In memory module problem.
Parent topic: N - Network Error Messages


PIC - Picture Error Messages

  • PIC000: Error system error: Unknown error errorID.
    The program attempted to display an error that was not found in this error file.
  • PIC001 Syntax error in mask definition.
    The Numeric Format specified in the Options is invalid.
  • PIC002 Grouping character found twice or in illegal position.
    The Numeric Format defined in Options contains two grouping characters (e.g., two commas) or the grouping character is in the wrong position (e.g., after the decimal point).
  • PIC003 No grouping length.
    A serious internal error has occurred in Option's picture parser. Contact Micro Focus Technical Support.
  • PIC004 Decimal character found twice or in illegal position.
    The Numeric Format defined in Options contains two decimal characters (e.g., two decimal points) or the decimal character is in the wrong position (e.g., 99.99,).
  • PIC005 Rounding character in illegal position.
    The Numeric Format defined in Options contains an incorrectly placed rounding character (r). This character, when used, must be the very last character in the picture string (e.g., xxx,9.99+r).
  • PIC006 Illegal character in picture specification.
    A character, other than those allowed, is included in the Date, Time or NumericFormat specified in Options.
  • PIC007 $ character found on both sides of decimal.
    The Numeric Format defined in Options contains a money character (e.g., $) on both sides of the decimal character (e.g., $$$$.$$ is invalid). This character can appear only on the left side of the decimal.
  • PIC008 Sign character found on both sides of the decimal.
    The Numeric Format defined in Options contains a sign character (e.g., +) on both sides of the decimal character (e.g., +$99.99+r is invalid). This character can be placed on the left or the right of the decimal point, but not both.
  • PIC009 Error in substitution portion of picture definition.
    The $=, .=, or ,= clause in the Numeric Format defined in Options is invalid. It may, for example, contain an invalid character or be missing the required delimiters.
  • PIC010 Illegal decimal found in picture.
    The Numeric Format defined in Options contains an invalid decimal sign character. Only a period can be used in the picture portion of a Numeric Format. For example: 999.99 .=',' is valid; 999,99 .=',' is not.
  • PIC011 Illegal rounding character found in picture.
    The Numeric Format defined in Options contains an invalid rounding character. Only an "r" can be used to indicate rounding, and this character must appear at the end of the picture string.
  • PIC012 Illegal dollar sign found in picture.
    The Numeric Format defined in Options contains an invalid money character. Only a dollar sign can be used in the picture portion of the format. For example: $$9.99 .='>=' is valid; >=>=9,99 .='>=' is not.
  • PIC013 Closing single quote not found in substitution string.
    The substitution character string defined in the $=, .=, or ,= clause in the Numeric Format defined in Options does not end with a single quote. For example: $999.99 .$='fl' is valid; $999,99 .='fl is not.
  • PIC014 Value too wide for picture field.
    The numeric value being entered or displayed is larger than the Numeric Format picture defined in Options.
  • PIC015 Error in time/date picture definition.
    The Time Format or the Date Format in Options is incorrectly specified.
  • PIC016: Error trying to identify the picture format type.
    A serious internal error has occurred because the active program received an illegal data type. Contact Micro Focus Technical Support.
  • PIC017 Invalid year value.
    The date value being entered or displayed is inconsistent with the Date Format specified in Options.
  • PIC018 Invalid separator in value.
    The numeric or money value being entered or displayed contains a separator character (e.g., the comma in 1,000) that is inconsistent with the Numeric Format currently specified in Options.
  • PIC019 Invalid character in value.
    A value that is being entered or displayed contains a character that is inconsistent with a picture currently specified in Options.
  • PIC020 Money value error.
    The money value being entered or displayed is inconsistent with the Money Format currently specified in Options.
  • PIC021 Numeric value error.
    The numeric value being entered or displayed is inconsistent with the Numeric Format currently specified in Options.
  • PIC022 Illegal Integer value.
    The integer value that is being entered or displayed is out of range. It contains more digits than specified by the NumericFormat in Options.
  • PIC023 Illegal Time value.
    The time value that is being entered or displayed is inconsistent with the Time Format currently specified in Options.
  • PIC024 Illegal Date value.
    The date value that is being entered or displayed is inconsistent with the Date Format currently specified in Options.
  • PIC025 Scale is bigger than precision.
    The Float Decimal Places value (i.e., scale) specified in Options is larger than the total number of digits allowed for a float value on your system (i.e., precision).
  • PIC026 Invalid separator in time value.
    The time value being entered or displayed contains a separator character (e.g., the colon in 4:00) that is inconsistent with the Time Format currently specified in Options.
  • PIC027 Invalid separator in date value.
    The date value being entered or displayed contains a separator character (e.g., the dash in 03-30-86) that is inconsistent with the Date Format currently specified in Options.
  • PIC028 Invalid separator in timestamp value.
    The timestamp being entered or displayed contains a separator character (e.g., the colon 04:00) that is inconsistent with the Time Format currently specified in Options.
Parent topic: SQL Option for DB2 Error Messages


SQL - SQL PL/I Precompiler Error Messages

  • SQL0001S DECLARE syntax error, last token read: token
    A syntax error has occurred in the DECLARE section. Check at or near token to find the problem.
  • SQL0002S identifier too long
    The current identifier is too long to be a valid identifier.
  • SQL0003S engine check error: message
    Error message message is being returned from the engine. Refer to message to determine the problem and its resolution.
  • SQL0004S identifier token not defined
    An identifier is being used that is not defined.
  • SQL0005S host variable used without colon
    The host variable is defined without a colon in the SQL statement.
  • SQL0006S UNION of SELECT INTO is deprecated feature with undefined results
    A UNION SQL statement that contains a SELECT INTO has been detected. This feature is no longer supported and the results are undefined.
  • SQL0101S error creating DBRM file: file
    Cannot create the DBRM file file. Likely reasons are that the file already exists or there is a permissions/sharing problem.
  • SQL0102S error opening input file: file
    Cannot open the input file file. Likely reasons are that the file does not exist or there is a permissions/sharing problem.
  • SQL0103S error creating output file: file
    Cannot create the output file file. Likely reasons are that the file already exists or there is a permissions/sharing problem.
  • SQL0104S error writing DBRM file
    Cannot write to the DBRM file. Likely reasons are that it does not exist or there is a permissions/sharing problem.
  • SQL0105S error reading input file
    Cannot read the input file. Likely reasons are that it does not exist or there is a permissions/sharing problem.
  • SQL0106S error writing output file
    Cannot write to the output file. Likely reasons are that it does not exist or there is a permissions/sharing problem.
  • SQL0107S scope mismatch
    The scope of a variable is ambiguous. Check to make sure only one variable is visible to a section with the same name.
  • SQL0108S end of file before end of quoted string
    A closing quote is missing.
  • SQL0109S end of file before end of comment
    A comment was not closed before the end of the file.
  • SQL0110S token buffer overflow
    The internal buffer for the lexical analyzer is full due to an object being too large.
  • SQL0111S statement buffer overflow
    The internal buffer for statement parsing is full due to a statement being too large to parse.
  • SQL0112S parser stack overflow
    The internal buffer for generic parsing is full due to an object being too large to parse.
  • SQL0113S include file file not found
    Cannot find the include file file in the current program path.
  • SQL0114S host variable error in sqlda
    Sqlda is reporting either too many or too few host variables.
  • SQL0115S illegal host variable marker '?'
    The '?' character cannot be used as a host variable marker.
  • SQL0116S invalid directives: directive
    The directives currently being used are invalid.
  • SQL0117S same name specified for the input file and the output file
    The same name is being used for both the input and output files. Modify the name of one of them.
  • SQL0118S host variable hostvar not found
    The preprocessor could not find the host variable hostvar.
  • SQL0119S declaration stack overflow
    The internal buffer for declaration parsing is full due to a declaration is too large to parse.
  • SQL0120S SQL syntax error, last token read: token
    The SQL Option generic syntax parser found an error in the SQL statement.
  • SQL0121S cursor cursor not declared
    An OPEN, FETCH or CLOSE statement references a cursor name that was not DECLAREd.
  • SQL0122S cursor cursor already declared
    The current cursor cursor has already been declared. Make sure the cursor name is valid and remove or rename it.
  • SQL0123S invalid host variable: hostvar
    Host variables must be valid PL/I identifiers
  • SQL0124S invalid null indicator variable: hostvar
    A null indicator variable must be a 2-byte integer.
  • SQL0125S statement statement not declared
    The current statement statement has not been declared.
  • SQL0126S statement statement already declared
    The current statement statement has already been declared.
  • SQL0127S host variable hostvar ambiguous
    The same variable name is being used twice in the same scope.
Parent topic: SQL Option for DB2 Error Messages


WADM - SQLWizard Administrator Error Messages

  • WADM002: Passwords don't match.
    The password you re-entered did not match the one entered previously. Make sure you enter the same password twice.
  • WADM003: You must enter a UserID before entering a password.
    A UserID must be entered before you will be permitted to enter a password. Enter a UserID.
  • WADM004: Expected number record(s), got number.
    Internal error. Contact Micro Focus Technical Support.
  • WADM005: Password must have at least number characters.
    The password you have entered does not meet the length criterion required by the password enforcement level specified in the Configuration utility.
  • WADM006: Password must contain at least one digit.
    Each password entered must contain at least one digit in order to meet the criteria required by the password enforcement level specified in the Configuration utility.
  • WADM007: Password must contain the characters character and character.
    Each password entered must contain the specified characters in order to meet the criteria required by the password enforcement level specified in the Configuration utility.
  • WADM008: Incomplete information retrieved from table name.
    Internal error. Contact Micro Focus Technical Support.
  • WADM009: User userid belongs to unregistered group name.
    According to the SYSXDB.SYSACFMEMBERS table in the SYSTEM location, user userid belongs to group name. However, group name is missing from the SYSXDB.SYSACFGROUPS table. Any group in SYSASCMEMBERS must also be in SYSACFGROUPS. You may remedy this situation by inserting group name into SYSACFGROUPS by selecting the Insert Group option under the Groups menu in XADMIN. Or you can delete group name from SYSACFMEMBERS by running the following interactive SQL command:
  • WADM010: userid is not a registered user.
    The user you are attempting to update or delete does not exist. Add the user, or enter another UserID.
  • WADM011: Unknown table format in table name.
    Internal error. Contact Micro Focus Technical Support.
  • WADM012: No password specified.
    There is no password specified for this user. A password is required in order to add or update this user. Enter a password.
  • WADM013: User userid is already registered.
    The user you have specified already has an entry in the SYSXDB.SYSACFUSERS table. UserIDs must be unique. Enter a new UserID.
  • WADM014: No UserID specified.
    You must specify a UserID in order to add, delete or update the user.
  • WADM016: No User Comment specified.
    You must specify a user comment in order to add or update the user.
  • WADM017: Memory allocated insufficient for the number of groups found.
    Memory allocated insufficient for the number of groups found.
  • WADM018: Group name already exists.
    You have attempted to create a new group using a group authorization ID that already exists in the SYSXDB.SYSACFGROUPS table. Group auth-IDs must be unique.
  • WADM019: No Group Authorization ID specified.
    You have attempted to add, update, or delete a group but did not specify a group authorization ID. The auth-ID is required to identify the group.
  • WADM020: Group name does not exist.
    You have attempted to delete or update a group, but no group was found in the SYSXDB.SYSACFGROUPS table whose authorization ID matches the one you entered.
  • WADM022: name is not a valid group name.
    The group name you have entered is not a valid database object name. See the SQLWizard online help for the allowable syntax for database object names.
  • WADM023: The priority name does not exist.
    You must enter an existing priority in order to update or delete.
  • WADM027: The User ID entered is invalid.
    The User ID should conform to Ordinary Identifiers. See the SQL Reference for more details.
  • WADM028: Valid range for value value is > 0 and < number.
    One of the governor values was out of the legal range. Enter a valid value.
  • WADM029: name is not a valid priority name.
    The priority name you have entered is not valid.
  • WADM030: No Priority Name specified.
    You must specify a priority in order to add, delete or update a priority.
  • WADM031: Priority name already exists.
    You have attempted to create a new priority using a priority that already exists in the SYSXDB.SYSGOVERNOR table. Priorities must be unique.
  • WADM032: An error occurred while updating an internal list (name).
    Internal error. Contact Micro Focus Technical Support.
  • WADM033: The SecondaryID name is invalid.
    The SecondaryID should conform to Ordinary Identifiers. See the SQL Reference for more details.
  • WADM034: Cannot delete yourself ('name') as a User.
    You are currently logged in as user 'name', so it is not possible to delete 'name' as a user.
Parent topic: SQL Option for DB2 Error Messages


WCRT - SQL Wizard Create/Alter Table Error Messages

  • WCRT000: Error system error: Unknown error error id.
    SQLWizard attempted to display an error that was not found in the XCRT.XRR error file.
  • WCRT001: Illegal identifier identifier specified for object Name. Last symbol read was symbol.
    An invalid name was specified for the object of type object-type. SQLWizard was only able to validate the name up to the symbol symbol.
  • WCRT004: The data type and/or length of column col1 does not match that of primary key column col2.
    When specifying the foreign key columns of a relationship, you must choose those that match both in data type and length to that of its corresponding primary key column. Check the data type and length of both the foreign key and primary key column to be sure they match.
  • WCRT005: No columns specified for the object.
    Make sure you choose columns for the index or relationship definition. If you are specifying an index, make sure you specify column names in the Index Columns list. If you are specifying a relationship, make sure a foreign key column is specified for each primary key column in the list.
  • WCRT006: Identifier identifier exceeds its maximum length of length for object-type name.
    The identifier specified exceeded its maximum limit of length for an object of type object-type. Enter a shorter name and try again.
  • WCRT007: Incomplete table specification. No object specified.
    A table was incompletely defined. Enter a valid value for the missing item.
  • WCRT008: Referenced table table does not contain a primary key.
    When choosing a referenced table for a relationship, be sure to choose a table that contains a primary key.
  • WCRT009: The index index does not exist for the table table.
    An index with the name index-name was not found in the system catalog for the table table-name.
  • WCRT010: The location name does not exist.
    A location with the name location-name was not found in the SYSXDB.SYSLOCALS catalog table.
  • WCRT011: The synonym/alias name does not exist in the database.
    A synonym/alias with the name name was not found in the system catalog.
  • WCRT012: Incomplete location specification. No object specified.
    A location was incompletely defined. Enter a valid value for the missing item.
  • WCRT013: No name specified for field # fieldnum.
    A field was specified without a name. Specify a valid name for the field.
  • WCRT014: No data type specified for field # fieldnum.
    A field was specified without a data type. Choose a data type from the drop-down list provided in the Data Type entry field.
  • WCRT015: No length specified for field # fieldnum.
    A field was specified without a length. Specify a valid length for the field. Some data types (e.g. Smallint, Integer, Float, Date, Time, etc.) have a fixed length and do not require a length to be entered. Others (e.g. Decimal, Char, Varchar, Graphic, & Vargraphic) require a length to be specified.
  • WCRT016: No column with a matching type found.
    An attempt was made to move a foreign key column to a new position within the Foreign Key Cols -> Referenced Key Cols list. However, no referenced column with a matching data type and length was found in the direction you tried to move. Remember that foreign key columns and referenced key columns must match in data type and length.
  • WCRT017: No foreign key name specified.
    Specify a valid foreign key name and try again.
  • WCRT018: No index name specified.
    Specify a valid index name and try again.
  • WCRT019: No alias name specified.
    Specify a valid alias name and try again.
  • WCRT020: No synonym name specified.
    Specify a valid synonym name and try again.
  • WCRT021: Cannot undo the Drop designation for this primary key index due to the existence of another primary key specification.
    An attempt was made to remove a Drop designation for a primary key index. However, another primary key index has been specified for this table. Since allowing this operation would yield more than one primary key for the table, and only one is allowed per table, this is illegal.
  • WCRT022: No referenced table specified for the relationship.
    The relationship specification is incomplete. Specify a referenced table to complete the specification. Be sure that this referenced table contains a primary key.
  • WCRT023: object name name is already defined for this table.
    An object of type object-type with the name name has already been specified for this table. Choose another name and try again.
  • WCRT024: Location specified in Alias Name.
    There is no need to qualify the alias name with a location, as the location may be chosen from the list. Please enter a one-part (i.e. alias name alone) or a two-part name (i.e. sqlid.alias-name), and specify the locations from the list.
  • WCRT025: No target location(s) specified for the Alias.
    When creating an alias you must specify at least one location where it is to be created. Choose locations from the Target Locations Not Selected list to move over to the Target Locations Selected list.
  • WCRT026: Index creator. index-name already exists in location location.
    All indexes must have unique names within a location. The index name specified already exists in the SYSIBM.SYSINDEXES catalog table for the particular location. Choose another name.
  • WCRT027: Table/View/Synonym/Alias creator. name already exists in location location.
    All tables/views/synonyms/aliases must have unique names within a location. The name specified already exists in the system catalog tables for that particular location. Choose another name.
  • WCRT028: Location name already exists.
    XDB Server locations must be given unique names. The location name specified already exists in the SYSXDB.SYSLOCALS catalog table. Choose another name.
  • WCRT029: Cannot alter/drop table with over number columns using this method.
    This error should not occur under normal circumstances. If you receive this error, please contact Micro Focus Technical Support.
  • WCRT030: The directory directory-name does not exist.
    The directory directory-name does not exist. You have to create this directory before you proceed with the creation of the location.
  • WCRT031: Log cannot be forwarded to a directory-name. It appears to be used by a different location.
    Specify a directory that is not already in use by another location and try again.
  • WCRT032: Invalid format for directory directory-name.
    Specify a valid directory name and try again.
  • WCRT033: Illegal null permission for field Field specified.
    Global temporary tables cannot contain "unique" or "with default" fields.
  • WCRT034: You cannot alter a Global Temporary Table.
    You have tried to alter a global temporary table. This is not allowed.
  • WCRT035: You can not alter a table that contains a distinct type
    An attempt was made to alter a table with a distinct data type. This is not allowed.
  • WCRT036: Altering a table that contains a BLOB column is not supported
    An attempt was made to alter a table with a BLOB column. This is not supported.
Parent topic: SQL Option for DB2 Error Messages


WDG - SQL Wizard Declaration Generator Error Messages

  • WDG001: name is not a legal table name.
    The table name you have entered is invalid. Select a valid table name.
  • WDG005: Unknown field type in table tablename.
    An illegal field type was specified in the table named.
  • WDG008: name is not a legal language name.
    The target language you have entered is invalid. Valid language names are COBOL, PL/I and C. Enter a valid name.
  • WDG010: Illegal computational value.
    The computation value must be > 0 and < 10.
  • WDG015: Error number spawning editor name.
    This error is not used. May be used in future versions.
  • WDG016: Accessing file name.
    The Declaration Generator cannot access the specified file. Please make sure that it exists and is not locked by any other user.
  • WDG017: Invalid location name nameerrortype.
    The specified location does not exist. Please select an existing location.
  • WDG018: No filename on command line.
    The Declaration Generator was run in batch mode with no batch filename on the command line. Please reissue the batch command with a legal batch filename.
  • WDG019: No table on command line.
    The Declaration Generator was run in batch mode with no batch filename or table name on the command line. Please reissue the batch command with a legal batch filename or a table name on the command line.
  • WDG020: Invalid option on command line.
    The Declaration Generator was run in batch mode with an illegal parameter on the command line. Please check you parameters.
  • WDG021: No filename on command line.
    The Declaration Generator was run in batch mode with no batch filename or output file name on the command line. Please reissue the batch command with a legal output filename on the command line.
  • WDG022: Can't create batch file.
    The Declaration Generator cannot create the selected file to contain a batch file. Make sure that the path exists and the destination file is not read only or locked by another user.
  • WDG023: No table name.
    No table name was specified. There is nothing to do.
  • WDG024: No filename.
    No output filename was specified. Declaration Generator needs to know where to put the output.
  • WDG025: No structure name.
    No output structure name was specified. Declaration Generator needs to know the name of the output structure.
  • WDG026: Error updating the status bar.
    Internal error. Declaration Generator could not display a message on its status bar. Please note what operation was being performed and contact Micro Focus Technical Support.
Parent topic: SQL Option for DB2 Error Messages


WE - SQL Wizard Export Error Messages

  • WE000 - WE049
    Lists the SQL Wizard Export error messages from WE000 through WE049.
  • WE050 - WE099
    Lists the SQL Wizard Export error messages from WE050 through WE099.
  • WE100 - WE149
    Lists the SQL Wizard Export error messages from WE100 through WE149.
Parent topic: SQL Option for DB2 Error Messages


WE000 - WE049

Lists the SQL Wizard Export error messages from WE000 through WE049.

  • WE001: Unable to create document window, XVT error error.
    An error occurred while attempting to create a child window. You may be low on resources. Try unloading some programs, or closing other child windows. If you are still having problems, please contact Micro Focus Technical Support.
  • WE002: No query exists on the query screen.
    An internal error has occurred. Please contact Micro Focus Technical Support.
  • WE003: Index is damaged.
    An internal error has occurred. Please contact Micro Focus Technical Support.
  • WE004: Unable to query auth-id.SYSTABLES to get information about item.
    An internal error has occurred. Please contact Micro Focus Technical Support.
  • WE005: Invalid value value for APPEND_ERR_FILE command in group number, groupname.
    The batch file command APPEND_ERR_FILE can only take the values "y" or "n".
  • WE006: No translation table exists with specified INCCSID and OUTCCSID.
    There is no record in the SYSIBM.SYSSTRINGS table whose values in the INCCSID and OUTCCSID fields match the numbers found in XDB.INI. If you are exporting in the DSNTIAUL format, check InCCSID and OutCCSID in the [Export] section of XDB.INI. If you are exporting in a different format, check AscSrcCodePage and AscDstCodePage.
  • WE007: Unable to add field name name to Included list.
    The system was unable to add the specified name to the name of columns that are to be included in the current export specification. You may be out of memory.
  • WE008: Cannot open file filename.
    Couldn't open the specified file.
  • WE009: No more Export windows can be created.
    You have created the maximum allowable number of Export windows. The maximum is 10. To create a new window you must close an existing window.
  • WE010: Table table is empty.
    No data can be exported because the table specified is empty.
  • WE011: Invalid value value for TIMESTAMP command in group number, groupname.
    The batch file command TIMESTAMP can only take the values "y" or "n".
  • WE012: Invalid field type specified for field fieldname.
    An illegal field type was specified for the field named. Check the documentation for a list of valid field types.
  • WE013: Unable to retrieve field information.
    An error occurred when attempting to retrieve field information from a batch specification.
  • WE014: Batch Export file file-name not found.
    Select a batch export file that exists.
  • WE015: Keyboard navigation error.
    An error occurred when trying to resolve the next/previous object in the keyboard navigation list. Contact Micro Focus Technical Support.
  • WE016: No fields in table specification.
    The export cannot proceed because there are no fields in the 'Included' listbox on the screen.
  • WE017: Internal error getting text from screen. Contact Micro Focus Technical Support.
    The system could not process an entry on the screen. Contact Micro Focus Technical Support.
  • WE018: Internal error opening table window. Contact Micro Focus Technical Support.
    The system was unable to open the export specification. Contact Micro Focus Technical Support.
  • WE019: Internal error opening query window. Contact Micro Focus Technical Support.
    The system was unable to open the export specification.
  • WE020: Batch Export file file-name does not contain a group heading
    The first line of a batch export file must be a group heading.
  • WE024: Query result does not contain any records.
    The current query does not retrieve any rows, so there is nothing to export. Check the WHERE condition to make certain it is correct.
  • WE025: Data file filename is empty.
    The file you wish to view does not contain any data.
  • WE026: Float value in field fieldname is larger than the IBM370 limit.
    The float value is not supported by IBM370.
  • WE027: Data exceeds 4K page size.
    The size of a record in the table you are exporting is greater than 4K. When exporting to the DSNTIAUL format, each record must fit within a 4K page size. If the record contains one or more columns of type LONG VARCHAR, the data in those columns is truncated if possible to make the record fit into 4K. However, if the other column lengths are large enough, this won't reduce the size sufficiently.
  • WE028: No output filename specified.
    You have not specified a filename for your export file.
  • WE030: Invalid output file specification filename.
    The file name specified is not a valid file specification.
  • WE031: Invalid table name.
    You have entered a table name that does not satisfy table-naming criterion. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE032: No table name specified.
    You have not specified the name of the table you wish to export. The table name is required when exporting and when saving an export specification to a batch export or batch import file.
  • WE033: Error writing to file filename.
    It was not possible to write to the specified DSNTIAUL file. Your hard disk may be full.
  • WE034: Can't display a join of multiple tables on Export's Design screen.
    You cannot switch to the Design view because the current query contains multiple tables in the FROM clause.
  • WE035: Field fieldname specified in query does not exist in table tablename.
    You have specified a field that is not found in the table named in the FROM clause.
  • WE036: Invalid query.
    The query was not recognized as a valid SQL statement.
  • WE037: Invalid record delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. SQLWizard allows you to specify an alternate end-of-record delimiter to handle other file structures.
  • WE038: Invalid field delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. When selecting a field delimiter, be sure you do not use a character found in your data or in the default masks for the data types in the exported table. For example, do not use a comma as the delimiter if your data contains numeric or money values grouped with a comma.
  • WE039: Invalid value for number of spaces between fields.
    The number of spaces between fields should be an integer from 0 to 99.
  • WE040: Batch file filename is invalid.
    The specified batch file is not a valid batch export file.
  • WE041: Batch file contains more than one transaction.
    Export cannot display a batch file that contains more than one transaction.
  • WE042: Error opening log file filename.
    An attempt to open the specified log file failed.
  • WE043: Invalid error log file name filename.
    The specified name is an invalid file name for the underlying operating system. Check your operating system documentation for a description of valid file names.
  • WE044: Invalid ON_ERROR value value.
    The ON_ERROR value must be PROMPT, CONTINUE, QUIT, or END_ALL.
  • WE045: Invalid batch file name filename.
    The specified file name is not a valid file name for your operating system. See your operating system documentation for a description of valid file names.
  • WE046: Invalid data file name filename.
    The specified file name is not a valid file name for your operating system. See your operating system documentation for a description of valid file names.
  • WE048: Invalid value for DSETPASS.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE049: Invalid STOGROUP name.
    STOGROUP names must follow the rules for short identifiers. The STOGROUP used is invalid.
Parent topic: WE - SQL Wizard Export Error Messages


WE050 - WE099

Lists the SQL Wizard Export error messages from WE050 through WE099.

  • WE050: PRIQTY value must be an integer in the range 12 to 4,194,304.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE051: SECQTY value must be an integer in the range 0 to 131,068.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE052: FREEPAGE value must be an integer in the range 0 to 255.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE053: PCTFREE value must be an integer in the range 0 to 99.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE054: No tables found with authid auth-id in location location-name.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE055: Invalid DATABASE name.
    Database names must follow the rules for short identifiers. The database name used is invalid.
  • WE056: Invalid TABLESPACE name.
    Tablespace names must follow the rules for long identifiers. The Tablespace used is invalid.
  • WE057: Invalid EDITPROC name.
    EDITPROC names must follow the rules for short identifiers. The name used is invalid.
  • WE058: Invalid VALIDPROC name.
    VALIDPROC names must follow the rules for short identifiers. The name used is invalid.
  • WE059: Internal error reading batch file.
    The system was unable to read the batch file. Check to make sure the file is a valid Export batch script.
  • WE060: Unable to access code page information.
    The system encountered an error when attempting to access the specified code page. Make sure that the code page has been defined in SYSTEM.SYSIBM.SYSSTRINGS, and that it has been correctly specified in the batch script.
  • WE061: Invalid error log file name file-name specified in batch file.
    The specified name is an invalid filename for the underlying operating system. Check your operating system documentation for a description of valid filenames.
  • WE062: Float value in field fieldname is smaller than the IBM370 limit.
    The float value is not supported by IBM370.
  • WE063: Unable to open View Batch window, probably out of memory.
    The system tried to open the view window, but was unable to do so. Try closing down other SQLWizard windows, or other applications that are using system resources.
  • WE064: Unable to open View Data window, probably out of memory.
    The system tried to open the view window, but was unable to do so. Try closing down other SQLWizard windows, or other applications that are using system resources.
  • WE065: Unrecognized value value for SQL_OPTS command in group number, groupname.
    Export found an illegal setting in the batch file. The syntax of this command is:
  • WE066: Invalid value value for ASCII_CODEPAGE in group number, groupname.
    Export found an error in the current batch export file. The syntax of this command is:
  • WE067: Invalid value value for EBCDIC_CODEPAGE in group number, groupname.
    Export found an error in the current batch export file. The syntax of this command is:
  • WE068: Invalid value value for FORMAT command in group number, groupname.
    Export found an error in the current batch export file. The syntax of this command is:
  • WE069: Batch file filename is empty.
    The specified file does not contain any batch specifications.
  • WE070: Unknown batch command command in group number, groupname.
    The batch export file contains invalid or unknown commands.
  • WE071: Invalid value value for FLD_DELIMITER command in group number, groupname.
    The syntax of this command is:
  • WE072: Invalid value value for REC_DELIMITER command in group number, groupname.
    The syntax of this command is:
  • WE073: Invalid value value for HEADING command in group number, groupname.
    The syntax of this command is:
  • WE074: Invalid value value for FILENAME command in group number, groupname.
    The syntax of this command is:
  • WE075: Invalid value value for TABLE command in group number, groupname.
    The syntax of this command is:
  • WE076: Invalid value value for PAGE_SIZE command in group number, groupname.
    The syntax of this command is:
  • WE077: Invalid value value for FIELDS command in group number, groupname.
    The syntax of this command is:
  • WE078: Invalid value value for QUOTES command in group number, groupname.
    The syntax of this command is:
  • WE079: Invalid value value for SPACES command in group number, groupname.
    The syntax of this command is:
  • WE080: Unable to get information about fields in table tablename.
    The system failed in an attempt to get information about the columns in the specified table. Make sure you have privileges on the catalog tables or views, and that the SYSIBM and SYSXDB items in the SQL page of the Options are set to the correct AuthID values.
  • WE081: Invalid value value for REPLACE command in group number, groupname.
    The syntax of this command is:
  • WE082: Invalid value value for DATABASE command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE083: Invalid value value for TABLESPACE command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE084: Invalid value value for EDITPROC command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE085: Invalid value value for VALIDPROC command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE086: Invalid value value for AUDIT command in group number, groupname.
    AUDIT value must be one of NONE, CHANGES or ALL.
  • WE087: Invalid value value for VCAT command in group number, groupname.
    VCAT value must be one of WITH, ROOT, PATH or NAME.
  • WE088: Invalid value value for STOGROUP command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE089: Invalid value value for PRIQTY command in group number, groupname.
    PRIQTY value must be a number from 0 to 4,194,309.
  • WE090: Invalid value value for SECQTY command in group number, groupname.
    SECQTY value must be a number from 0 to 131,068.
  • WE091: Invalid value value for ERASE command in group number, groupname.
    ERASE value must be either Y or N.
  • WE092: Invalid value value for FREEPAGE command in group number, groupname.
    FREEPAGE value must be a number from 0 to 255.
  • WE093: Invalid value value for PCTFREE command in group number, groupname.
    PCTFREE value must be a number from 0 to 99.
  • WE094: Invalid value value for DUPQTY command in group number, groupname.
    DUPQTY value must be either 8, 16, 32, 64 or 128.
  • WE095: Invalid value value for CLUSTER command in group number, groupname.
    CLUSTER value must either Y or N.
  • WE096: Invalid value value for SUBPAGES command in group number, groupname.
    SUBPAGES value must be either 1, 2, 4, 8 or 16.
  • WE097: Invalid value value for BUFFERPOOL command in group number, groupname.
    BUFFERPOOL value must be in one of the following formats:
  • WE098: Invalid value value for DSETPASS command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE099: Invalid value value for CLOSE command in group number, groupname.
    CLOSE value must be either Y or N.
Parent topic: WE - SQL Wizard Export Error Messages


WE100 - WE149

Lists the SQL Wizard Export error messages from WE100 through WE149.

  • WE100: Invalid value value for DEFER command in group number, groupname.
    DEFER value must be either Y or N.
  • WE101: Error opening batch file for writing.
    Unable to open file for writing import or export specifications.
  • WE102: Error writing to batch file.
    Unable to write import or export specifications to current batch file.
  • WE103: Invalid value value for SRC_ASCII_CODEPAGE command in group number, groupname.
    Codepage must be a positive integer or 0.
  • WE104: Invalid value value for DST_ASCII_CODEPAGE command in group number, groupname.
    Codepage must be a positive integer or 0.
  • WE105: Warning: No translation table matches the default ASCII source and destination codepages pagenopageno in XDB.INI.
    The values in XDB.INI in the [Export] section for AscSrcCodePage and AscDstCodePage do not correspond to the INCCSID and OUTCCSID values of any record in SYSTEM.SYSIBM.SYSSTRINGS.
  • WE106: Invalid Where clause.
    The WHERE condition specified in the Export window is invalid. Check it for syntax errors.
  • WE107: Export to SQL can't export a query that contains more than one table.
    There is more than one table specified in the FROM clause of your Export query statement. This is not allowed when you are exporting to SQL Statements. In SQL mode, edit the FROM clause so that it contains a single table name, or change to another export format.
  • WE108: Query doesn't start with SELECT.
    The Export query statement doesn't begin with the SELECT keyword. In SQL mode, edit the statement so that it begins with the word SELECT. Make sure that it forms a valid query statement.
  • WE109: Export doesn't understand the query. Last symbol read was symbol.
    SQLWizard could not interpret the SELECT statement in the Export window. Check it for syntax errors. Symbol indicates where the error occurred. See the SQL Reference for a description of the SELECT statement syntax.
  • WE110: Query contains a string that is too long for Export to process.
    The SELECT statement in the Export window contains a name (e.g., field name, table name) that is too long. Names exceeding 1024 characters cannot be processed by Export.
  • WE112: Internal error getting For Bit Data info. Contact Micro Focus Technical Support.
    Export has experienced an internal error while processing the SELECT statement. Contact Micro Focus Technical Support.
  • WE113: Internal error getting Nullable info. Contact Micro Focus Technical Support.
    Export has experienced an internal error while processing the SELECT statement. Contact Micro Focus Technical Support.
  • WE114: Invalid record delimiter – escape character character is not allowed.
    The escape character specified on the SQL tab of Options cannot be used as a record delimiter.
  • WE115: Invalid field delimiter – escape character character is not allowed.
    The escape character specified on the SQL tab of Options cannot be used as a field delimiter.
Parent topic: WE - SQL Wizard Export Error Messages


WI - SQL Wizard Import Error Messages

  • WI000 - WI049
    Lists the SQL Wizard Import error messages from WI000 through WI049.
  • WI050 - WI099
    Lists the SQL Wizard Import error messages from WI050 through WI099.
  • WI100 - WI149
    Lists the SQL Wizard Export error messages from WI100 through WI149.
Parent topic: SQL Option for DB2 Error Messages


WI000 - WI049

Lists the SQL Wizard Import error messages from WI000 through WI049.

  • WI001: Premature end of line found, record record.
    Encountered an unexpected end of line on the record specified.
  • WI002: Number field(s) were found in record number; record should contain number field(s).
    A record containing the wrong number of fields exists in the file you are importing. Check the record in your source file (record n) and make sure that it has the same number of fields as the target table.
  • WI003: The character character in position position in heading line of Fixed ASCII file filename is not allowed in a column name.
    A field name in your fixed-ASCII data file contains a character that is not permitted in a database object name. See your SQL Reference for a list of characters that can be used in a column name.
  • WI004: The maximum number of open Import windows has been reached.
    You have opened the maximum number of Import windows. Close some of the Import windows before you continue.
  • WI005: Table name is not specified.
    You must provide a table name for the target table.
  • WI007: Invalid value number for varchar length; length must be no greater than number.
    The length of a varchar field is greater than the page size set for each record.
  • WI008: No translation table exists with specified INCCSID and OUTCCSID.
    There is no record in the SYSIBM.SYSSTRINGS table whose values in the INCCSID and OUTCCSID fields match the numbers found in XDB.INI. If you are importing in the DSNTIAUL format, check InCCSID and OutCCSID in the [Import] section of XDB.INI. If you are importing in a different format, check AscSrcCodePage and AscDstCodePage.
  • WI009: Keyboard navigation error.
    Internal error. Contact Micro Focus Technical Support.
  • WI010: Invalid value value for DSN_CRLF command in group number, groupname.
    The batch file command DSN_CRLF can only take the values "y" or "n".
  • WI011: No source file name specified.
    You must enter the full pathname of the data file you want to import in the File Name edit box of the Source File Information area.
  • WI012: Unable to open Grid window.
    An internal error is preventing SQLWizard from creating the table area in the Import window. This may be caused by insufficient memory. Close any unnecessary applications, then retry the Import command. If this does not resolve the problem, clear memory by restarting SQLWizard or by rebooting.
  • WI013: Data in field fieldname of record record-name is number characters long but field definition inumber characters.
    The data found in a character field in the source file is longer than the length of that field in the target table.
  • WI014: End-of-line delimiter delimiter not found while counting fields in record.
    The current record in your free format ASCII file does not contain the Field Delimiter specified on the screen.
  • WI015: Invalid value value for APPEND_ERR_FILE command in group number, groupname.
    The batch file command APPEND_ERR_FILE can only take the values "y" or "n".
  • WI016: Invalid value value for APPEND_REC_FILE command in group number, groupname.
    The batch file command APPEND_REC_FILE can only take the values "y" or "n".
  • WI017: DSNTIAUL file file-name does not contain a complete record.
    A record in the DSN file contains a record with size that is smaller than the record size in the destination table.
  • WI018: Invalid value value for TIMESTAMP command in group number, groupname.
    The batch file command TIMESTAMP can only take the values "y" or "n".
  • WI019: Batch import file file-name not found.
    Select a batch import file that exists.
  • WI020: Batch Import file filename does not contain a group heading.
    The first line of a batch import file has to be a group heading.
  • WI021: Record number contains more than the maximum of number fields, or end of record not found.
    Import has detected more fields in the current record than are specified in the table definition. Either your data file contains extra fields in this record, or the record delimiter is missing from this record, causing Import to interpret the data in the next record as part of the data for this record.
  • WI022: Table name is not specified in group number, groupname.
    No value was assigned to the batch file command TABLE.
  • WI023: Error writing to logfile filename, errno = error-number.
    The attempt to write to the specified log file failed. Check your operating system documentation for the meaning of the error specified by the errno value.
  • WI024: Error opening logfile filename.
    An attempt to open the specified log file failed. Either it does not exist or is in use.
  • WI025: End quote missing in field fieldname, record record of data file filename.
    A quote is missing from a character field in a free format ASCII file.
  • WI026: Data exceeds 4K page size.
    The size of a record in a DSNTIAUL file must be no greater than 4096 bytes.
  • WI027: Length specification missing from Char, Varchar, Graphic, or, VarGraphic data type, line line-number.
    Specify these types in the following format:
  • WI029: Number fields were specified, but number fields were found in file.
    There are more fields in the fixed-ASCII source file than there are in the target table. Check the source file to make sure that the length of its records matches that of your destination table.
  • WI030: Unable to open file filename.
    Either the file was not found in the indicated directory, is in use, or is invalid. Check to be sure that you have specified the correct file name and directory.
  • WI031: More field names were found than the number of fields specified.
    The number of fields specified for your table is less than the number of fields found in your data file.
  • WI034: Field name for field number, fieldname, is longer than number characters.
    Field names may not be longer than number characters.
  • WI035: Incorrect field type type in ConvertDataStrToInternal().
    Internal error. Call Micro Focus Technical Support.
  • WI036: Invalid field delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. See your SQLWizard User's Guide for further information on entering delimiters.
  • WI037: Invalid record delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255.
  • WI038: Invalid source file name filename.
    See your operating system documentation for an explanation of valid file names.
  • WI039: Invalid table name.
    See your documentation for an explanation of valid table names. Also see WSQL045.
  • WI040: Invalid value for number of spaces between fields.
    The number of spaces between fields should be an integer from 0 to 99.
  • WI041: Data file filename is empty.
    It is not possible to import the specified data file, as it contains no data.
  • WI044: Invalid character (character) found in field name in field number in header line of data file.
    An illegal column name was found in the source file. See the SQL Reference for rules for identifiers for XDB Server and DB2. Also see WSQL045.
  • WI047: Invalid length in type specification type, field number.
    The length in the specified field is invalid for the field type.
  • WI048: Invalid length in Character or Varchar type specification type, field number.
    Character and Varchar lengths must be no longer than 4048.
  • WI049: Invalid length in Graphic type specification type, field number.
    Graphic length must be no longer than 127.
Parent topic: WI - SQL Wizard Import Error Messages


WI050 - WI099

Lists the SQL Wizard Import error messages from WI050 through WI099.

  • WI050: Invalid length in Vargraphic type specification type, field number.
    Vargraphic length must be no longer than 2028.
  • WI051: Batch file contains more than one transaction.
    SQLWizard cannot create an Import window for a batch file that contains more than one transaction.
  • WI052: Batch file filename is invalid.
    The file does not exist, or the file is not a valid Batch Import file.
  • WI054: Can't get info from fixed ASCII file that doesn't contain a header line.
    You must provide a complete specification for the ASCII file, since the system is unable to use a header line to help build a specification.
  • WI055: Error opening table file filename.
    Import in Local Direct Write mode encountered an error when trying to open the file specified. The file may not exist, you may not have privileges on the file or on the path, or the file may be in use.
  • WI057: Error writing to table file filename.
    Import in Local Direct Write mode encountered an error when trying to write to an underlying table file directly. Make certain that the table file can be accessed from the client machine.
  • WI058: Can't access table file filename, probably locked by the XDB Server.
    The table file may already be in use by the database server. You must have exclusive use of the file in order to proceed.
  • WI059: Invalid error log file name filename.
    The file name is not a valid file name.
  • WI060: Invalid record log file name filename.
    The file name is not a valid file name.
  • WI063: Invalid error log file name filename specified in batch file filename.
    The file name is not a valid file name for the underlying operating system. Check your operating system documentation for valid filename format.
  • WI064: Invalid record log file name filename specified in batch file filename.
    The file name is not a valid file name for the underlying operating system. Check your operating system documentation for valid file name format.
  • WI065: Unable to access code page information.
    You have specified a translation table to use for DSNTIAUL EBCDIC-to-ASCII conversion, or non-DSNTIAUL ASCII-to-ASCII conversion. However, Import was unable to load the translation from the system table SYSIBM.SYSSTRINGS.
  • WI066: Number of records to recalculate must be an integer from 0 to 4,294,967,296.
    The number you specified is not in range.
  • WI067: Commit interval must be an integer from 0 to 4,294,967,296.
    The number you specified is not in range.
  • WI069: Quotes missing around character value string.
    You have specified that character values are enclosed in quotes, but the specified character value is not quoted.
  • WI071: Float value in field number, fieldname of record number is larger than IBM370's limit.
    The float value is not supported by IBM370.
  • WI072: Float value in field number, fieldname of record number is smaller than IBM370's limit.
    The float value is not supported by IBM370.
  • WI073: Unable to open View Batch window, probably out of memory.
    Check system resources. Close down other SQLWizard windows, or other applications to free resources.
  • WI074: Unable to open View Data window, probably out of memory.
    Check system resources. Close down other SQLWizard windows, or other applications to free resources.
  • WI077: Internal error reading batch file.
    An error occurred when trying to read the batch file. It is most likely a memory allocation error.
  • WI078: Invalid value value for PAGE_SIZE command in group number, groupname.
    The syntax of this command is:
  • WI079: Invalid value string for FORMAT command in group number, groupname.
    Valid formats are FREASC, FIXASC, and DSNTIAUL.
  • WI080: Can't import into a non-XDB Server location using Engine Direct Write
    Engine Direct Write mode is only supported against XDB Server locations.
  • WI082: Data file filename does not contain any data.
    The file appears to be empty.
  • WI083: Invalid value value for ASCII_CODEPAGE command in group number, groupname.
    This must be a positive integer or 0.
  • WI084: Invalid value value for EBCDIC_CODEPAGE command in group number, groupname.
    This must be a positive integer or 0.
  • WI085: Invalid value value for FLD_DELIMITER command in group number, groupname.
    The syntax of the FLD_DELIMITER command is:
  • WI086: Invalid value value for REC_DELIMITER command in group number, groupname.
    The syntax of the REC_DELIMITER command is:
  • WI087: Invalid value value for HEADING command in group number, groupname.
    The correct syntax of this command is:
  • WI088: Invalid value value in position number for EBCDIC_TO_ASCII command in group number, groupname.
    The syntax of this command is:
  • WI089: Invalid value value in position number for SRC_LENS command in group number, groupname.
    The syntax of this command is:
  • WI090: Invalid value value in position number for OFFSETS command in group number, groupname.
    The syntax of this command is:
  • WI091: Invalid value value for SPACES command in group number, groupname.
    The syntax of this command is:
  • WI092: Invalid value value for QUOTES command in group number, groupname.
    The syntax of this command is:
  • WI093: Invalid value value for REPLACE command in group number, groupname.
    The syntax of this command is:
  • WI094: Invalid value value for INSERT_MODE command in group number, groupname.
    The syntax of this command is:
  • WI095: Invalid value value in position number for NULL_PERM command in group number, groupname.
    The syntax of this command is:
  • WI096: Invalid value value in position number for USE_PIC command in group number, groupname.
    The syntax of this command is:
  • WI097: Invalid value value in position number for TYPES command in group number, groupname.
    The syntax of this command is:
  • WI098: Invalid value value in position n for FIELDS command in group number, groupname.
    The syntax of this command is:
  • WI099: Invalid value value for TABLE command in group number, groupname.
    The syntax of this command is:
Parent topic: WI - SQL Wizard Import Error Messages


WI100 - WI149

Lists the SQL Wizard Export error messages from WI100 through WI149.

  • WI100: Invalid value value for FILENAME command in group number, groupname.
    The syntax of this command is:
  • WI101: Invalid value value for ON_ERROR command in group number, groupname.
    The syntax of this command is:
  • WI102: Invalid value value for COMMIT_INTERVAL command in group number, groupname.
    The syntax of this command is:
  • WI103: The number of values for the FIELDS command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI104: The number of values for the TYPES command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI105: The number of values for the USE_PIC command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI106: The number of values for the NULL_PERM command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI107: The number of values for the OFFSETS command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI108: The number of values for the SRC_LENS command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI109: The number of values for the EBCDIC_TO_ASCII command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI110: Batch file filename is empty.
    The file does not contain any batch import specifications.
  • WI111: Unknown batch command command in group number, groupname.
    There are invalid commands in the batch file. See your SQLWizard User's Guide for valid batch commands.
  • WI112: Short float value in field number, fieldname of record number is larger than IBM370's limit.
    Float value not supported for IBM370.
  • WI113: Short float value in field number, fieldname of record number is smaller than IBM370's limit.
    Float value not supported for IBM370.
  • WI115: Error opening batch file for writing.
    There is not enough memory to create the internal structure required to write an Import specification file (an IMP file). Close any unnecessary applications, then retry the operation. If this does not resolve the problem, clear memory by restarting SQLWizard or by rebooting.
  • WI116: Error writing to batch file.
    An error has occurred while writing an Import specification file (an IMP file). Check that nothing is preventing a file from being written. For example, check that the drive is operational and that it has sufficient space. Also check that the file is not write protected.
  • WI117: Invalid value value for SRC_ASCII_CODEPAGE command in group Tnumber, Tname.
    The value assigned to a SRC_ASCII_CODEPAGE statement in your Import specification file (IMP file) is incorrect. It must be a positive integer. The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Allowed values are listed in the SQLWizard User's Guide.
  • WI118: Invalid value value for DST_ASCII_CODEPAGE command in group Tnumber, Tname.
    The value assigned to a DST_ASCII_CODEPAGE statement in your Import specification file (IMP file) is incorrect. It must be a positive integer. The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Allowed values are listed in the SQLWizard User's Guide.
  • WI119: Invalid batch file name filename.
    An invalid file name has been given to an Import specification file (IMP file). If you are saving an IMP file, check that you have typed a name allowed by your operating system. If you are running a batch import from the command line, verify that a valid IMP filename was entered on the command line. See your SQLWizard User's Guide for command line syntax.
  • WI121: Can't import data file filename into table tablename because data file has number columns but table has number columns.
    The source file and the target table in your Import operation do not have the same number of fields. If you are running a batch import, verify that the TABLE statement in the IMP file is set to the correct target table. Also verify that the FIELDS, TYPES, NULL_PERM, SRC_LENS, OFFSETS, USE_PIC and EBCDIC_TO_ASCII statements in your IMP file reflect the actual number of columns in your source and destination. See your SQLWizard User's Guide for a complete description of the IMP file and its contents.
  • WI122: Batch specification in group Tnumber, Tname in file filename is not sufficient to create new table tablename.
    A TYPES and/or FIELDS statement for this transaction was not found in the Import specification file (IMP file). The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Edit your IMP file and enter the missing statement(s). See your SQLWizard User's Guide for a complete description of the IMP file and its contents.
  • WI123: Table tablename contains number columns but batch file specifies number columns.
    The target table specified in the Import specification file (IMP file) doesn't contain the same number of fields as the source file. Verify that the TABLE statement in the IMP file is set to the correct target table. Also verify that the FIELDS, TYPES, NULL_PERM, SRC_LENS, OFFSETS, USE_PIC and EBCDIC_TO_ASCII statements in your IMP file reflect the actual number of columns in your source and destination. See your SQLWizard User's Guide for a complete description of the IMP file and its contents.
  • WI124: Invalid value Value for varchar length. Length must be no greater than page size Size.
    The import process has been terminated because the DSNTIAUL file you are importing contains a varchar value that exceeds the current page size.
  • WI125: Invalid record delimiter - escape character character is not allowed.
    The escape character specified on the SQL tab of Options cannot be used as a record delimiter.
  • WI126: Invalid field delimiter – escape character character is not allowed.
    The escape character specified on the SQL tab of the Options utility cannot be used as a field delimiter.
Parent topic: WI - SQL Wizard Import Error Messages


WSQL - SQL Wizard Interactive SQL Error Messages

  • WSQL001: XDB Engine is not loaded.
    The system was unable to load the SQL Engine. Make certain that you have correctly installed and configured SQL RDBMS (or the equivalent) or that you have installed the correct network redirector.
  • WSQL002: Error allocating memory.
    An attempt was made to allocate a block of memory, but that attempt failed. Try removing other programs from memory, and then repeat the task. Try saving your work and exiting from SQLWizard, and then reload it. If the operating system is using a temporary PAGEFILE, make sure there is at least 2MB of free disk space. If attempts to increase available resources fail, contact Micro Focus Technical Support.
  • WSQL003: Error opening file filename.
    An attempt was made to open the file named, but it failed. This usually occurs if the file could not be found. Check that the file exists, and that you have privileges to access it. Make sure the file is not in use by another application. Check to be sure there is enough disk space available, and that the target directory is a valid path.
  • WSQL004: Error creating name window.
    The system was unable to create the window, probably because resources (such as memory) are low. Close down some windows (or other applications) and try again. See WSQL002.
  • WSQL005: Error creating name dialog.
    The system was unable to create the dialog, probably because resources (such as memory) are low. Close down some windows (or other applications) and try again. See WSQL002.
  • WSQL006: Error creating name text editor.
    The system was unable to create the window, or open the specified application. Close down some windows (or other applications) and try again.
  • WSQL007: Error adding line to text editor.
    The system could not add additional text to the current edit control. System resources may be low. Try freeing resources by closing unnecessary programs.
  • WSQL008: Prohibit Cartesian products.
    The system has been set to prohibit Cartesian products. The query you are trying to run has been evaluated as a Cartesian product, and cannot be executed unless you turn off the Prohibit Cartesian Products option through the Query|Current Query Options dialog.
  • WSQL009: Query result cannot be edited.
    The current query result has been evaluated as a non-editable result, and therefore the system cannot switch to edit mode. Reasons for a query to be evaluated as non-editable are that it is/contains a: a) Join b) Union c) GROUP BY clause d) HAVING clause e) Expression or it accesses a read-only view.
  • WSQL010: Error executing menu.
    An error occurred when trying to process the last menu command.
  • WSQL011: Printing failed.
    An error occurred when attempting to print. Check the print manager for additional information.
  • WSQL012: Cannot list windows.
    The system was unable to list the currently open windows.
  • WSQL013: Too many windows.
    The system cannot open another window. Try closing down some of the currently open child windows.
  • WSQL014: Window does not have METRICS data.
    Unable to process window commands.
  • WSQL015: Incomplete line in string.
    Incomplete line in string.
  • WSQL016: No default value in string.
    No default value in string.
  • WSQL017: Prompted number number is out of range, should be 1-100.
    An SQL statement references a variable &n where n is not between 1 and 100. Modify the SQL statement to change &n so that n is within the acceptable range, or change &n to a host variable in the form :hv.
  • WSQL018: Error adding item to prompted list.
    An error occurred attempting to add an item to the prompted query design list. Contact Micro Focus Technical Support.
  • WSQL019: Cannot find the prompted number number.
    An error occurred trying to specify or rebuild a prompted query design. The table SYSXDB.SYSPROMPTQUERY may be damaged or has been incorrectly edited.
  • WSQL020: Invalid characters in string.
    There are illegal characters in the string shown. Correct and try again.
  • WSQL021: Cannot find query.
    The system was unable to find the query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. You may have entered the name incorrectly. The query may have been deleted from the query catalog, or there may be an error reading the catalog tables.
  • WSQL022: Argument is NULL.
    A required argument is NULL. Correct and try again.
  • WSQL023: Cannot open temporary file.
    The system was unable to open a temporary file. Check whether you have privileges to read and write on the temporary path, and that there is enough disk space to write the file.
  • WSQL024: Cannot create temporary file.
    The system was unable to write a temporary file. Check whether you have privileges to read and write on the temporary path, and that there is enough disk space to write the file.
  • WSQL025: You must have a valid connection to use all of SQLWizard's options.
    If you cannot connect to the database engine, you will not be able to access SQLWizard. This error sometimes occurs when you have not connected properly to a remote database server.
  • WSQL026: Invalid entry in field fieldname.
    An attempt was made to enter invalid data in the named field. Modify the data to match the data type.
  • WSQL027: Window does not have METRICS data.
    Unable to process window commands.
  • WSQL028: Cannot open query.
    The system was unable to open a query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. The query may have been partially deleted from the query catalog, or there may be an error reading the catalog tables.
  • WSQL029: Error running batch SQL.
    The system encountered an error in trying to process a batch SQL script.
  • WSQL030: No such Query.
    The system was unable to find the query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. You may have entered the name incorrectly. The query may have been deleted from the query catalog, or there may be an error reading the catalog tables.
  • WSQL031: No column needs order by.
    There are no unsorted columns in the query. Use the Query|Sort option if you want to remove some columns from the query. You cannot sort by a column that is not selected if you are in DB2 mode (this is a restriction of DB2).
  • WSQL032: Cannot create toolbar.
    The system failed in an attempt to create the toolbar. Check whether resources are low.
  • WSQL033: Error saving file filename.
    An error occurred when trying to save the named file. Make certain the path is valid, the file name is valid, that there is enough space for the file, or that the file does not already exist and is locked by another application.
  • WSQL034: Error seeking file.
    A file could not be found. A seek error occurred when trying to locate it. Make certain the file specification is correct, and that the file exists.
  • WSQL035: Error seeking query.
    A query could not be found. You can query the SYSXDB.SYSQUERY table to see if the query exists in the location that you are querying. You may need to make the location where the query exists the current location.
  • WSQL036: Cannot find table name.
    A table by the specified name could not be found.
  • WSQL037: Cannot paste table name.
    The system was unable to paste a table name into the current context.
  • WSQL038: Cannot open init file.
    The system was unable to open one or more initialization files. Run Options to check XDB.INI. Check the command line of XWIZ40N.EXE for the INI file in use.
  • WSQL039: Cannot paste query.
    An attempt was made to paste an SQL statement into a Query Design window, or to paste a Query Design into an SQL Edit window. Try using the Open button to open the query. Change to SQL view if necessary, and copy the query, then paste to the target SQL Edit window.
  • WSQL040: The editor is read-only.
    You cannot edit or paste into the current edit field.
  • WSQL041: Cannot open a synonym under a different location or AuthID.
    Synonyms can only be accessed from the location in which they are created. Make the synonym location your current location before attempting to open the synonym.
  • WSQL042: Error in querying SYSACFUSERS.
    The system encountered an error when attempting to retrieve information on users from the system catalog. This error occurs if you have not been granted privileges against the system catalog tables. You will be allowed to continue if you receive this error, but you will be connected as a regular user, not a super user.
  • WSQL043: Cannot access SYSIBM tables using AuthID authid.
    This error occurs if you attempt to start SQLWizard when you have not been granted privileges for the system catalog tables.
  • WSQL044: Cannot access SYSXDB tables using AuthID authid.
    This error normally occurs if the current user does not have select privileges on the SYSXDB catalog tables, or on the equivalent views. Check the SYSXDB setting in the Options SQL page to see what AuthID the system is trying to use for SYSXDB catalog views, and contact your administrator to see if you have select privileges on the views created with this AuthID. If you do not, have the administrator grant you the privileges you need to access the catalog tables. If the SYSXDB.SYSQUERY table does not exist, you may see this error. You will still be allowed to access SQLWizard, but you may not be able to list or save queries in the catalog tables. You should still be able to save and run queries in SQL script files.
  • WSQL045: Name name is invalid.
    The name shown is not a valid name based on the current SQL mode, or the system requirements. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WSQL046: Cannot save query. Please check if disk is full.
    Something is preventing SQLWizard from saving this query.
  • WSQL047: The query has been corrupted.
    SQLWizard cannot open the selected query because it contains corrupt data. This might happen if the SYSPROMPTQUERY table was edited directly.
  • WSQL049: SELECT error. May not have privileges.
    SQLWizard cannot complete this task because you do not have privileges to the specified object.
  • WSQL050: Cannot edit tables with renamed columns.
    You are attempting to edit a table that contains a renamed column. This is not allowed. This error would occur, for example, if you attempted to edit the result of the following query (which changes the name of the e_no column to xemp):
  • WSQL051: Batch error in command number number.
    SQLWizard has encountered an error while processing a batch SQL script.
  • WSQL052: End of statement delimiter not found.
    SQLWizard could not find an end of statement delimiter.
  • WSQL053: Filters yield no results. Filters are reset.
    The filter value entered for the immediate sub-item (database, or AuthID) beneath the location level returns an empty result set. The Catalog Browser display will be refreshed using the latest valid set of filter values stored in XDB.INI.
  • WSQL054: Cannot display result set containing a LOB field.
    The result set contains a Large Object (LOB), which is not displayable.
  • WSQL055: Invalid value, terminator_character, specified for TERMINATOR.
    The SQL terminator character specified in a --#SET TERMINATOR statement is invalid. The following characters are not allowed to be a SQL terminator: blank, comma, double quote, left parenthesis, right parenthesis, single quote, and underscore.
Parent topic: SQL Option for DB2 Error Messages


X - Engine Error Messages

  • X000 - X049
    Lists the Engine error messages from X000 through X049.
  • X050 - X099
    Lists the Engine error messages from X050 through X099.
  • X100 - X149
    Lists the Engine error messages from X100 through X149.
  • X150 - X199
    Lists the Engine error messages from X150 through X199.
  • X200 - X249
    Lists the Engine error messages from X200 through X249.
  • X250 - X299
    Lists the Engine error messages from X250 through X299.
  • X300 - X349
    Lists the Engine error messages from X300 through X349.
  • X350 - X399
    Lists the Engine error messages from X350 through X399.
  • X400 - X449
    Lists the Engine error messages from X400 through X449.
Parent topic: SQL Option for DB2 Error Messages


X000 - X049

Lists the Engine error messages from X000 through X049.

  • X001: Cannot perform operation (errornum) on file filename.
    An attempt to close/open/read/write/seek on the file specified failed. File mode may conflict. Device may be full or damaged, or file may not exist. Also, make sure that your temporary path is set to an existing path.
  • X002: Empty query string.
    An attempt was made to execute a command that was discovered to be an empty string. You may have accidentally pressed an execute option before issuing a command. You may have used an empty (NULL) string as the input for a PREPARE command, or for an xcommand() or xprepare() function.
  • X003: INI Error errmsg
    The error message returned can be any of the messages listed under Possible Error Messages below. Each possible error message is followed by a typical XDBNET.INI file error that could have caused the error message. The following notation definitions apply for each possible error message:
  • X004: Number value overflow.
    An attempt was made to place a value that is too large or too small into a numeric field (float, int, smallint, etc.). See XDB Server Specifications in the SQL Reference for maximum and minimum values permitted in numeric data types. Check picture specifications.
  • X005: Date value error.
    An attempt was made to place an illegal date in a date field or attempt to perform date arithmetic on an invalid date. XDB Server performs leap year checking, and verifies that month and day are correct. Check picture specifications.
  • X006: String constant too long.
    String constants selected in a query may be up to 4056 characters long. Varchar and long varchar columns can be longer, so you could store a longer value in a table and retrieve it.
  • X007: Incomplete string. Check for missing quotes.
    A quote without a matching quote was found in a command sent to the SQL Engine. You may use either single or double quotes around character strings. If a single quote is to appear within a string, surround the string with double quotes. For example:
  • X008: Version number incompatibility in user exit file.
    The structure being returned by the user exit procedure procedure is incompatible with this version. Contact your system administrator.
  • X009: Illegal field name name.
    A reference was made to a field that does not exist in the table specified by a command. If using a precompiler to catch an error at precompile time, then add VALIDATE directive in XDBCOB.DIR file. Make sure that all fields are defined in the declaration.
  • X010: No more RAM memory available.
    Insufficient memory (RAM) was available to execute a command sent to the SQL Engine. Try running the application from outside the main menu or application menu to see if that gives you enough memory to continue.
  • X011: Type mismatch within expression.
    A data type conflict occurred within an expression. For example, you may have attempted to perform date arithmetic with a character string.
  • X012: Type mismatch while doing comparison.
    An attempt was made to compare two incompatible data types. Numeric types may be compared to other numeric types (including, for example, money and numeric results of date arithmetic or string functions); dates can only be compared to dates, character strings to character strings, times to times.
  • X013: Order by clause invalid on singleton select statement.
    An embedded SQL singleton select might not contain an older BY clause. The statement should be modified to use the OPEN CURSOR construct.
  • X014: Set location can only be used for local locations.
    The system was unable to locate a table or view in the relational directory (.DDT file), or the table/view is not found in the referenced query control block. In order to add a table or view to the relational directory you must create it using the CREATE command. You can copy tables from one location to another using the COPY command. To include a table or view in a query control block, you must include it in the FROM clause of a query.
  • X015: Attempt to close an unopened location directory.
    An attempt was made to close a location directory that was not open at the time. Check for subroutines that close the location, or logout of subprograms.
  • X016: Undefined query identifier or location not open.
    An attempt was made to access a query control block that does not exist, or to run a command against an unopened location. This error condition may occur if you prematurely close a query or (if using an application programming interface) if you forget to open the location. Also a subroutine may have logged out, automatically closing the location.
  • X017: Illegal record position.
    An attempt was made to access a record at a location outside the result of the query. Typically this occurs when using the application programming interface function xdirect() to move the cursor to a record that does not exist in the current table. To find the position of a record, use the xgetpos() function. It is possible that the record has been modified since the position was saved and re-execution of the query did not include the record in the new result set.
  • X018: Duplicate value in unique index name.
    An attempt was made to insert a duplicate value in a field on which a unique index or primary key exists. Possible fixes: Check for a rollback file (.RB extension) and delete it; Delete all indices and rebuild them; Check if the data is wrapped; Delete all files from temporary storage before transferring new data to the storage area.
  • X019: Query too long.
    The system was unable to allocate enough space to process the query. XDB Server uses dynamic allocation for this task, so the length of query permitted depends on the amount of memory available. Reduce the length of the query, or remove unnecessary programs from memory and try again. See X010 and X050.
  • X020: Syntax error. Last symbol read was string.
    The SQL Engine was unable to parse a command it was sent. When this error occurs, the system tries to display the last token it read. Check the command syntax in the SQL Reference. Make sure that all products are using the same character set (ASCII, EBCDIC, etc.). If using the COBOL, look in the errmc element of the SQLCA structure for the error tokens. SQLCA errd[4] contains the column position of the token. In CAPI, call the function xgeterr() to get the error tokens.
  • X021: Pathname too long.
    XDB Server accepts paths of up to 48 characters.
  • X022: Too many queries open at same time.
    There is no room to open additional query control blocks. A user may open up to 50 queries at one time. The actual number of queries open at one time depends on the complexity of the queries. Try rewriting your program so that it is not necessary to hold so many queries open at the same time. In server versions, use the XDB Server Configuration utility to increase the number of available query control blanks.
  • X023: Length of value exceeds length of destination.
    An attempt was made to place a value in a field too small to accommodate it.
  • X024: Index Name has been damaged.
    The index specified cannot be used by the system. You must drop the index and rebuild it before continuing. NOTE: If you compact a table with deleted records or use the AND INDEX clause, all indices are automatically rebuilt for you.
  • X025: Incomplete comment.
    Comments sent to the SQL Engine should begin with the characters /* and end with the characters */. The system found one comment marker, but not the other.
  • X026: Exceeds max number of tables/views permitted in query.
    You may access up to 15 tables or views per FROM clause; the limit depends on the complexity of the query, as well as the number of expressions and multi-table views involved. In addition, the number of queries already open may impact on the number of tables allowed in a query.
  • X027: Maximum of number connected client nodes has been exceeded.
    The XDB Server cannot process your connection request because the maximum number of licensed users is already attached to the server.
  • X028: Cannot find table/view/synonym name.
    The table, view, or synonym specified does not have a readable entry in the database directory. You may have entered an incorrect table name, or be in the incorrect database. The database directory (.DD? file) may have been damaged or overwritten. You cannot simply copy a .TAB file to a database directory and then access it through XDB Server. You must use the CREATE or COPY commands to create a table or move a table between databases.
  • X029: Invalid hex constant.
    The XDB Server cannot execute the current statement because it contains an invalid hex constant. For example, a closing quote may be missing, or the hex value may contain an invalid character.
  • X030: Invalid field number.
    A low level CAPI function call (e.g. Xdbxgetrec or Xdbxputrec) to access a field failed; the specified field number does not exist in the query.
  • X031: Cannot truncate log file.
    Unable to truncate the backward log file; cannot COMMIT or ROLLBACK. Check access privileges on the drive containing the database. Run operating system program CHKDSK on the database drive. Use Options to turn the Backward Log OFF.
  • X032: Lock Conflict.
    Two or more users are accessing the same object.
  • X033: Column name is ambiguous.
    If the column specified is ambiguous, then you must reference it by a two-part column name (i.e., table/view.column).
  • X034: Illegal correlation name name.
    A query references a correlation name not specified in the FROM clause.
  • X035: Length of input host variable number number is invalid.
    The length of the specified host variable is too long or too short.
  • X036: Default specification for field name is invalid.
    An unexpected internal error occurred when accessing the defined default value for column name.
  • X037: Invalid timeout specification.
    Timeout specification should be an integer greater than 0 and less than 32,767.
  • X038: Cannot acquire read/write access on specified path.
    Unable to read or write any files on a path the system has tried to access as result of a command you issued. If using a network file server, check the current user's privileges. If using a multiuser system, make sure another user is not accessing the file.
  • X039: Abort code.
    The system aborted the current operation upon receipt of an abort code. When you press Esc in most environments, programs send an abort code to the SQL Engine, instructing it to terminate the transaction it is currently processing for you. A partial result may be displayed in some modules. Incomplete transactions involving updates, inserts or deletes are rolled back if the backward log is turned on. You can specify the abort characters through Options.
  • X040: Log system couldn't operation.
    An operation in the log system has failed.
  • X041: Left side of expression incompatible with right side.
    The system is unable to compare the left hand side of an expression to the right hand side of the expression. This is generally due to incompatible data types (e.g. comparing a time field to a date field).
  • X042: Field type not compatible with nested query results.
    The field type of a nested query result is not compatible with the field type it is being compared to.
  • X043: Aggregate function on invalid type.
    An attempt was made to find a numeric aggregate function result for a non-numeric field (e.g. AVG of a character field.)
  • X044: Invalid data type indicator.
    The SQL Engine received an invalid data type indicator from the calling program. This problem is generally due to a programming error in user programs that use one of the language interfaces. Refer to interface documentation for valid data type indicators.
  • X045: Invalid element in structure structure in function function.
    The values structure in CAPI function Xdbxputrec() contains invalid information. Length may be out of range, or type may be invalid.
  • X046: Illegal number of fields specified for compound index.
    An attempt was made to create an index on more than 64 columns.
  • X047: Index name too long.
    An index name is currently limited to 18 characters in length, except when using mainframe syntax.
  • X048: Index name already exists.
    An attempt was made to create an index with the same name as an existing index in the current database. You can view index names in the current database using the query:
  • X049: Duplicate name name in create index list.
    A field name can appear only once in a CREATE INDEX statement. When creating foreign keys, a field name can appear only once in the indexed field list of a referenced table, and only once in the indexed field list of the referencing table.
  • X050: No more RAM available to REDIRECTOR.
    The network redirector (network communications) was unable to allocate the necessary memory required (either for packet transmission or reception).
Parent topic: X - Engine Error Messages


X050 - X099

Lists the Engine error messages from X050 through X099.

  • X051: Duplicate key value when creating unique index indexname.
    Unable to create unique index because a value appears more than once in the column(s).
  • X052: Cannot update field to incompatible type.
    An attempt was made to update a field using an incompatible value. Check the field types of the table you are updating.
  • X053: String length is larger than field length.
    An attempt was made to insert a character string into a field too short to hold it. Check to see if you are using DB2 compatibility.
  • X054: Unequal number of fields and values.
    When inserting a record, an attempt was made to insert more values than the table has fields. If you supply too few values, the system automatically places NULL values in the other fields.
  • X055: Duplicate names name in insert/alter/create list.
    A field name appears more than once in an INSERT, ALTER, or CREATE command.
  • X056: Table/View name already exists.
    All tables and views in a database must have unique names. To obtain a list of the tables or views in a database, you can perform the query:
  • X057: Specified more fields or values than the table has.
    The number of values listed in an INSERT command exceeds the number of fields in the table named.
  • X058: Field name type incompatible with type type.
    Unable to perform a command because the type of the field named is incompatible with the type displayed (e.g. a time field is incompatible with a date field for comparison operations).
  • X059: Inserting character constant larger than field length specified.
    A character string in an INSERT command values list is longer than the target character field. Value is truncated.
  • X060: value is outside allowable field length boundary.
    See the SQL Reference for description of data type ranges.
  • X061: number is greater than maximum allowable number of fields.
    Tables are limited to 750 fields.
  • X062: Value value is too large to insert into field name.
    Unable to insert the value into the field specified, because it is larger or longer than maximum value permitted.
  • X063: Index name not found.
    Reference was made to an index not found in the current database. For a list of the currently active indices in the current database, execute the query:
  • X064: Not a proper command or command not implemented.
    An attempt was made to execute a command that is not a valid XDB Server or SQL command, or to execute a command that is not yet implemented.
  • X065: Illegal field name name in order specification.
    A field or column in an ORDER BY clause was not selected in the SELECT clause of the query, or does not exist in the table.
  • X066: Illegal number number in order/group specification.
    There is no matching column number for a column number listed in the ORDER BY or GROUP BY clause of the query.
  • X067: Aggregates not allowed in WHERE clause of query.
    XDB Server does not permit an aggregate function in the WHERE clause of a query. Aggregate functions should appear in a HAVING clause if used as a selection criterion.
  • X068: Selecting an expression with a GROUP BY clause.
    XDB Server does not permit use of expressions (other than aggregate functions) in a query having a GROUP BY clause unless you include the expression in the GROUP BY clause using its column number.
  • X069: Too many set clauses in update command.
    There are more SET clauses in the UPDATE command than there are fields in the table being updated.
  • X070: Ordering by field name that is not selected.
    In DB2 mode, the ORDER BY clause must specify one of the fields in the SELECT clause.
  • X071: Selecting more than one item in a nested query.
    The SELECT clause of a subquery can consist of only one column. If you want to select more than one field, try concatenating the fields using the XCONCAT function.
  • X072: Cannot nest aggregate functions.
    Aggregate functions cannot be nested one inside the other. For example, you cannot select:
  • X073: Fields selected must appear in GROUP BY clause or inside an aggregate function.
    If a query selects an aggregate function, any field appearing outside the aggregate function in the SELECT clause must also appear in the GROUP BY clause of the query. This is a common cause of confusion; although users may think they do not want to group a result by a particular column, they often find that adding the column name to the end of the GROUP BY clause yields the desired result.
  • X074: GROUP BY clause invalid on current query.
    A GROUP BY clause can only be used if the SELECT clause of the query includes one or more column names, or one or more aggregate functions (such as COUNT, and AVG.)
  • X075: Cannot mix fields with aggregates without GROUP BY.
    If a query selects an aggregate function, any field appearing outside the aggregate function in the SELECT clause must also appear in a GROUP BY clause.
  • X076: Luname servername does not exist in tablename SYSLUNAMES table.
    You are inbound/outbound mapping to or from a server name that does not exist in SYSLUNAMES. Insert a record for that server name in the SYSLUNAMES table or insert a dummy generic record with blanks.
  • X077: Cannot include join in table expansion.
    PREVIOUS clause cannot be used on a join.
  • X078: Illegal level value for table expansion.
    LEVEL clause specifies a non-positive or non-integer level, or a level beyond the maximum recursive relationship level.
  • X079: Insert/Delete/Update function not allowed on sorted query.
    You cannot perform a positioned update/insert/delete on a query that requires sorting. Queries that may require sorting are those involving ORDER BY, GROUP BY, DISTINCT, and UNION.
  • X080: Only one DISTINCT clause allowed per query.
    XDB Server only allows one DISTINCT clause per query. For example, you cannot:
  • X081: Exceeds maximum number of UNIONed queries.
    A maximum of 32 subselects may be connected by the UNION operator (i.e. UNION should appear no more than 31 times in a command).
  • X082: Each query in a UNION must have the same number of projected fields.
    The number and type of columns selected in subselects connected with the UNION operator must match exactly.
  • X083: Data types in column name do not match.
    When performing a UNION, the data types of each column in one subselect must be type compatible with the corresponding column in all UNIONed subselects.
  • X084: ORDER BY items must be constants for union of queries.
    When the UNION operator and the ORDER BY clause appear in the same query, the ORDER BY criteria must use column numbers instead of column names.
  • X085: ORDER BY must follow all queries when performing a union.
    The ORDER BY clause should be the last clause in any query containing a UNION operator.
  • X086: NULL not allowed in field name.
    An illegal attempt was made to place a NULL in the field named. The field is specified as NOT NULL. You can obtain information on NULL permission from the SYSCOLUMNS table.
  • X087: Table/View name exceeds maximum length of number.
    Table, view and synonym names are limited to the number of characters shown. Some compatibility modes allow longer table names than others.
  • X088: Field name length exceeds maximum length of number characters.
    Table names are limited to the number of characters shown. Some compatibility modes allow longer field names than others.
  • X089: Cannot open location on path. Check location path setting.
    The system is unable to find or open the location-name.DDT or location-name.DDF files on the path specified. These files contain essential information on location table and field specifications. Check whether there is a location in the path specified. Check whether there is more than one set of .DDT or .DDF files in your location directory. Check to see if the location name matches the location name in the SYSXDB.SYSLOCALS table. Verify whether the path is accessible by the program accessing the location. For example, in multi-user, use the drive specifier.
  • X090: Too many users registered.
    The number of users registered is equal to the maximum number of users permitted to register at one time.
  • X091: User has no privilege privilege on objectname.
    The current user has not been granted the privilege to perform the operation attempted on the table, view or database shown. For a listing of privileges available to a user, query the SYSTABAUTH and SYSDBAUTH tables.
  • X092: User account has been disabled.
    The user name has been deactivated. See your database administrator, who can enable the user account.
  • X093: Unknown user name.
    The user name entered is not found in the system, because it has not been registered on the system. See your database administrator. Query the SYSXDB.SYSACFUSERS table in the system location for a list of valid user names.
  • X094: User userid cannot GRANT/REVOKE on table/view/database name.
    User has no authority to grant or revoke privileges on the database, table or view named. For a list of privileges available to a user, query the SYSTABAUTH and SYSDBAUTH tables.
  • X095: Invalid receipt. (Should register first.)
    User did not obtain a valid process ID before entering a module. Exit to the operating system and try reentering the program. In extreme cases you may need to unload the SQL Engine, or in multi-user environments, kill a user session.
  • X096: Illegal password.
    Password does not match password saved for the user name entered. Repeated attempts to log on with an incorrect password will cause this program to abort. If you have forgotten your password, see your database administrator.
  • X097: Illegal attempt to open more than one location.
    XDB Server permits a user to access only one location at a time. This error condition occurs when a programmer attempts to call the C API Xdbxopen() function before closing the current location.
  • X098: Cannot grant a privilege to yourself.
    A user is not permitted to grant a privilege to him/herself. The privilege must be granted by another user possessing sufficient authority to do so.
  • X099: User already exists.
    A user with the same user name is already entered in the SYSXDB.SYSACFUSERS table. User names must be unique.
Parent topic: X - Engine Error Messages


X100 - X149

Lists the Engine error messages from X100 through X149.

  • X100: Memory Resident Engine not loaded!
    XDB client-side software could not communicate with the XDB Server. Check to make sure that the XDB Server is up. If it is up and listening on the appropriate communications protocol, contact Micro Focus Technical Support.
  • X101: Illegal function code passed to engine.
    Programmer attempted to call the SQL Engine with an illegal function code. Refer to your Application Programming Interface documentation for valid function codes. Another possible cause for this error could be that you are inadvertently trying to access the wrong engine. This can occur if you have been working with a single-user engine on your own computer and then switch to using a multi-user XDB Server.
  • X102: Cannot find view name.
    Unable to find the view named in the SYSVIEWS table, or in the system directory files.
  • X103: Must select aggregates if using HAVING clause with no GROUP BY.
    A HAVING clause can only appear in a query that selects only aggregate functions, or that has a GROUP BY clause.
  • X104: A password is required for connection with LU servername.
    You are trying to connect to a server name that doesn't trust you. You need a password to be connected.
  • X105: Operation not allowed on view name.
    XDB Server cannot perform the operation attempted on the view named. For example, multi-table views are not currently updateable.
  • X106: No translation row in tablename SYSUSERNAMES for LU servername.
    You are trying to do inbound/outbound mapping without specifying a translation row to the AuthID in SYSUSERNAMES.
  • X107: Current AuthID can't be used to reference remote object.
    The XDB Server cannot execute the requested operation because the specified AuthID is not valid for the remote location.
  • X108: Field list must be provided when expressions are selected.
    The SELECT clause of commands that define views can contain expressions only if the resulting columns are explicitly named. For example:
  • X110: Cannot operation logfile filename. Check logpath setting.
    An operation on the logfile named filename has failed. Check the log path in the SYSXDB.SYSLOCALS table to see if it is pointing to the correct directory. Also check to see that there is still disk space left for writing the file.
  • X111: Maximum number records per table in trial version.
    You are running the SQL Engine shipped with Learn, which limits the number of records in tables. The record limit includes deleted records that have not been removed using COMPACT. If you need to add more records to the table you must have a full version of XDB Server.
  • X112: Cannot perform operation (errno) on index index-name.
    An attempt to read/write/seek/open on the files that make up the index named failed. Check to see that the files index-name.IDX and index- name.PTR exist in the database directory. Check whether there is sufficient disk space to write to the index files. Check whether the file has been read or write protected. Increase the number of files in CONFIG.SYS to more than 100. See X001 for a description of operation errors.
  • X113: Cannot perform operation (errno) on table table-name.
    An attempt to read/write/seek on the files that make up the table named failed. Check to see that the file table-name.TAB exists in the database directory. Check whether there is sufficient disk space to write to the index files. Check whether the file has been read or write protected. See X001 for a description of operation errors. Compact the table (or drop it) and rebuild the indices.
  • X114: Cannot close current database. Please exit.
    Internal error code. Please contact Micro Focus Technical Support.
  • X115: Location already exists in the path specified.
    XDB Server permits one location per directory. XDB Server locations must be given unique names. This error condition occurs if you attempt to create a location in a directory that already contains a location, or if you attempt to create a location using a location name found in the SYSXDB.SYSLOCALS table.
  • X116: Time value error.
    An attempt was made to process a command containing an invalid time value. Check time picture specification.
  • X117: Maximum number of open locations exceeded.
    Maximum number of locations open exceeds the number specified through the XDB Server configuration.
  • X118: Location name table already exists.
    XDB Server permits one location per directory. XDB Server locations must be given unique names. This error condition occurs if you attempt to create a location in a directory that already contains a location, or if you attempt to create a location using a location name found in the SYSXDB.SYSLOCALS table.
  • X119: Location name exceeds maximum length of number.
    XDB Server location names are limited to the number of characters specified. Use a shorter location name.
  • X120: Cannot find location name in SYSXDB.SYSLOCALS table.
    An attempt was made to perform an operation on a location not found in the SYSXDB.SYSLOCALS table. Check the location path or location name specified in your command. When a location is created using the CREATE LOCATION command, an entry is inserted into the SYSXDB.SYSLOCALS table. If you are using a location that was not created with the CREATE LOCATION command, you may use the INSERT command to insert a record into the SYSXDB.SYSLOCALS table for the location.
  • X121: Operation requires system level privilege.
    An attempt was made to perform an operation that requires database administrator privileges. Check the authority required for the command you are trying to execute. If you do not have the proper authority, see your database administrator.
  • X122: Incorrect location files on path path.
    This error occurs if a specified location is not found. This might be caused by trying to access files that have been deleted, or by entering a path instead of a location. Otherwise, the problem is with SYSXDB.SYSLOCALS. You might want to check the path selections in Options.
  • X123: Cannot open system location on path path.
    The system was unable to open the system location on the system location path specified. To change the system location path, use the Configuration utility, described in the XDB Server Administration Guide.
  • X124: Illegal operation on system object.
    An illegal attempt was made to alter, insert, update or delete from a system object. XDB Server objects are for system use; they are automatically created and maintained by the system. Users may query the objects but, in general, cannot update or change them except through special commands (e.g. COMMENT ON). See XDB Server System Tables in the SQL Reference for descriptions of the system objects and how they are maintained.
  • X125: Must execute statement before fetch.
    When using dynamic SQL, before issuing a FETCH command you must PREPARE and EXECUTE the command.
  • X126: Cannot GROUP BY an aggregate function.
    Aggregate functions cannot appear in a GROUP BY clause.
  • X127: Pattern matching allowed on character fields only.
    LIKE searches, which use wild card pattern matching, can only be performed on character fields. You may perform range searches on other field types, including date and time. If you want to search a date field by day, month, or year, use XDAY, XMONTH or XYEAR, respectively.
  • X128: Target table cannot also be source table.
    You cannot insert records selected from a table into the same table. In addition, you cannot copy a table to itself.
  • X129: Attempt to insert invalid data into field name.
    An attempt was made to place incompatible data in the field named. Check the command, the data, and the field type, and make any corrections needed.
  • X130: Attempt to drop system location.
    The system location cannot be dropped using the DROP LOCATION command, since it contains the SYSXDB.SYSLOCALS table. If you must drop the system location, use operating system commands to delete all files and remove the location directory.
  • X131: Attempt to drop location in use.
    You cannot drop the current location. Before dropping a location, you must change to another location.
  • X132: Cannot find location name name in SYSXDB.SYSLOCALS table.
    The location named in the command does not have an active entry in the SYSXDB.SYSLOCALS table in the system location. Check the command and the SYSXDB.SYSLOCALS table for the correct location name.
  • X133: Cannot use reserve word word in table/index definition.
    XDB Server and SQL reserved words cannot be used as database object names (e.g. table and field names). For a list of reserved words, see the SQL Reference.
  • X134: error: DOMAIN ERROR.
    A mathematical function contains an argument outside the domain of the function. For example, you cannot use a column containing a negative number as the argument for XSQRT.
  • X135: error: RANGE ERROR.
    The result of a mathematical function is too large to be represented in the data type the system is trying to use.
  • X136: Functionality not available with LITE engine.
    The LITE Server cannot process this statement because it contains commands that are not supported by the LITE software.
  • X137: Cannot perform operation (errno) on location file name.
    The system was unable to perform the operation specified on the location file specified.
  • X138: Illegal operation on view.
    An attempt was made to perform an operation not permitted on a particular view, or not yet implemented in XDB Server. For example, you cannot currently update a multi-table view.
  • X139: Record size exceeds the maximum.
    XDB Server records are limited to 32,767 bytes, including record overhead. For odd length character fields, overhead is one byte; for even length character fields overhead is 2 bytes. For most other data types, overhead is 2 bytes per field in DOS.
  • X140: WITH CHECK OPTION clause not allowed on read only view.
    You cannot specify a CHECK OPTION for a view that is not updateable. For example, you cannot currently update views involving multi-table joins.
  • X141: Record does not satisfy view definition.
    An illegal attempt was made to update or insert an invalid record into a view created using the CHECK OPTION clause. You can see the CHECK OPTION for the view by querying the SYSCHECK table.
  • X142: Operation not allowed on read only view.
    An attempt was made to perform an operation not permitted on a particular view, or not yet implemented in XDB Server. For example, you cannot currently update a multi-table view.
  • X143: Table already has check condition.
    You may only create one CHECK CONDITION per table. However, this CHECK CONDITION may be very complex (to the detriment of performance). If you want to add conditions to the CHECK CONDITION, you must drop and recreate the CHECK CONDITION.
  • X144: Record does not satisfy table name check condition.
    An illegal attempt was made to update or insert an invalid record into a view created using the CHECK OPTION clause. You can see the CHECK OPTION for the view by querying the SYSCHECK table.
  • X145: Key key not found when analyzing referential constraint.
    One of the keys involved in a referential constraint is missing. You must create a key before you can refer to it in a FOREIGN KEY constraint.
  • X146: Violation of constraint between key key1 and key key2.
    An attempt to update, insert or delete a record violates a FOREIGN KEY constraint involving the keys listed. See the ALTER command description in the SQL Reference for a description of FOREIGN KEY.
  • X147: Cannot find key key.
    The command references a key that does not exist. You must create a key before you can refer to it in a FOREIGN KEY constraint.
  • X148: Primary key key already exists on this table.
    Only one PRIMARY KEY is permitted per table; other candidate keys may be defined as UNIQUE.
  • X149: Primary/Unique key fields must be specified as NOT NULL.
    Before creating a PRIMARY KEY, you must specify that the fields involved are NOT NULL. You can do this through the Create/Alter Table module, or by using the ALTER command.
Parent topic: X - Engine Error Messages


X150 - X199

Lists the Engine error messages from X150 through X199.

  • X150: Referenced fields must be specified as NOT NULL.
    Before you can create a FOREIGN KEY, you must specify that the referenced fields involved are NOT NULL. You can do this through the Create/Alter Table module, or by using the ALTER command.
  • X151: Location path exceeds maximum length of 48.
    Path names are restricted to 48 characters in length.
  • X152: Invalid transaction number.
    Internal error code. Contact Micro Focus Technical Support.
  • X153: No space for locks.
    There is no space to record additional record locks. If the transaction requires many locks on the same table, it is a good idea to lock the entire table, instead of attempting to lock each record. In multi-user XDB Server versions the size of lock tables can be configured through the XDB Server Configuration program.
  • X154: Cannot find table/record lock.
    Internal error code. Contact Micro Focus Technical Support.
  • X155: Table/record currently locked by user at node.
    A lock conflict exists. A record or table lock on the object you are attempting to lock is held by the user at the node (workstation) specified.
  • X156: Table/record currently locked by user at node.
    A lock conflict exists. A record or table lock on the object you are attempting to lock is held by the user at the node (workstation) specified. Note: With CICS, you must commit or use the Dirty Read (DR) option.
  • X157: Cannot obtain exclusive lock or drop lock in isolation level 5 or 6.
    When working at isolation level 5 (dirty read) or level 6 (snapshot read), a transaction cannot acquire or drop exclusive locks on any database object. Levels 5 and 6 are intended for read only. You cannot insert, update, delete, or alter database objects at these levels. You can change the isolation level using the following command:
  • X158: Cannot obtain or delete table locks in isolation level 5 or 6.
    When working at isolation level 5 (dirty read) or level 6 (snapshot read), a transaction cannot acquire or drop table locks. Levels 5 and 6 are intended for read only. You cannot insert, update, delete, or alter database objects at these levels. Tables are accessible by other users.
  • X159: Current location is locked by user at node.
    A lock conflict exists. The location you are attempting to access is locked for exclusive use by the user working at the node specified.
  • X160: Cannot obtain isolation level EU due to existing locks.
    The database you are attempting to lock is in use by others. Isolation level EU (exclusive use) not available until all other users close the database.
  • X161: Not enough memory free on XDB Server to process request.
    The minimum contiguous memory block is a configurable parameter (0-64K) for the XDB Server. The XDB Server does not currently have enough memory to process the request. Increase the size of the memory block. Increase the amount of free space on the server.
  • X162: Logging in to XDB Server name requires security on at user node.
    Security has been turned on at the XDB Server named. Security must also be turned on at the user node via the Configuration utility.
  • X163: No network node name specified. Must be set through XDBCONFIG.
    In the multi-user system, each network node must have a unique name, specified via the Configuration utility. The system is shipped without a default name since names must be unique.
  • X164: Operation cannot be performed in isolation level DR or SR.
    The user is trying to perform an operation other than reading a record while in the Dirty Read (DR) or Snapshot Read (SR) isolation level. Change to a different isolation level using the SET ISOLATION LEVEL command, or through Options.
  • X165: Redirector version does not match XDB Server version.
    The LAN redirector you are using does not generate communication packets that the XDB Server understands.
  • X166: Operation requires isolation level EU (Exclusive Use) with this server.
    Compacting database can only be performed at using an exclusive use isolation level (EU).
  • X167: Redirector does not support the selected protocol protocol.
    The communications protocol specified in Options is not supported by the redirector currently in use. For example, a DOS client can use NetBIOS, but cannot use Named Pipes.
  • X168: User has been deleted by DBA at XDB Server.
    The user's account on the XDB Server has been deleted. Please contact your Database Administrator.
  • X169: Attempted to examine the status of an un-executed command.
    An application issued a set of calls to the Server but not all were executed. An error exists in the application being run. Make sure you are using the correct AuthID for your location, and that you are pointing to the correct server. If the application is a Micro Focus program, please contact Micro Focus Technical Support.
  • X170: Referenced key field type(s) must match foreign key field type(s)
    The fields, taken in order, of the PRIMARY or UNIQUE KEY referenced by a FOREIGN KEY must match the type of the fields in the foreign key.
  • X171: Foreign key already exists on field(s) specified.
    Only one FOREIGN key is permitted on any set of fields. For example, if building a foreign key on item (o_no) that references the ORDERS table, you cannot build a another foreign key in the item (o_no) field.
  • X172: Cannot create directory on path path.
    An attempt to create a directory in the path specified failed. The path may already exist, or an attempt may have been made to create a subdirectory for a directory that does not exist.
  • X173: Cannot flush location file contents to disk.
    An attempt to commit a DDL operation (e.g. CREATE) failed. Disk may be full.
  • X174: Synonym/Table name already exists.
    You cannot create a synonym using a name already used by another synonym, table or view.
  • X175: Synonyms cannot be created on other synonyms.
    Synonyms may be created on tables and views only.
  • X176: Synonym name does not exist.
    You cannot drop a synonym that does not exist.
  • X177: Maximum identifier size exceeded.
    Table names, view names, index names, column names and synonyms are limited to 18 characters.
  • X178: Precision must be a value between 1 and 31.
    XDB Server accepts precision between 1 and 31. Precision is the total number of digits, including scale (number of decimal places) permitted in a decimal field.
  • X179: Scale must be a value between 0 and the precision.
    XDB Server accepts precision between 1 and 31. Precision is the total number of digits, including scale (number of decimal places) permitted in a decimal field. Scale cannot exceed the total number of digits permitted in the decimal field.
  • X180: Cannot truncate table file.
    When deleting all records from a table using the DELETE FROM table-name command, the tables and indices are simply truncated. An error occurred when attempting to truncate a file. Check your disk.
  • X181: Cannot truncate index file.
    When deleting all records from a table using the DELETE FROM table-name command, the tables and indices are simply truncated. An error occurred when attempting to truncate a file. Check your disk.
  • X182: Cannot perform table on forward log file name.
    An error occurred when attempting to read, write, search or truncate the forward log file specified. Check your disk. See X001.
  • X183: Cannot perform operation on backward log file name.
    An error occurred when attempting to read, write, search or truncate the backward log file specified. Check your disk. See X001.
  • X184: Illegal outer join conditions.
    Only five outer join conditions per query are currently permitted.
  • X185: FOR UPDATE OF not allowed with GROUP BY or ORDER BY clause.
    The FOR UPDATE OF clause cannot be used on a query that is not updateable. GROUP BY and ORDER BY queries are not updateable.
  • X186: Maximum number of open files exceeded.
    The system cannot process the current command because it is unable to open another file. You may need to close some queries, remove some indices from your table, or change the limit on the number of concurrently open files. In DOS, the number of files that can be concurrently opened by the system is specified in your computer's CONFIG.SYS file, as described in your Installation documentation.
  • X187: Referenced key and foreign key must have same number of fields.
    When defining a FOREIGN KEY, you must reference an existing key with the same number of fields.
  • X188: Attempt to place NULL value in host variable with no indicator variable.
    Embedded SQL only. If you retrieve a NULL value, you must have a special null indicator variable assigned for it. See the SQL Reference for further information.
  • X189: Source and Target locations have the same name.
    This error occurs when two locations with the same name exist in a system, and an attempt is made to copy a table from one to the other. You should rename one of the locations before attempting the copy.
  • X190: Cannot copy table/view to itself.
    XDB Server does not permit the same table to be used as the source and target for a copy operation. This error may occur when two databases with the same name exist in a system, and an attempt is made to copy a table from one to the other. Rename one of the databases before attempting the copy.
  • X191: View definition too large for memory buffer.
    There is not enough memory to process a view definition. If you have multiple queries open, or if you have unnecessary programs loaded into memory, close or remove them, and try again.
  • X192: Error in source view definition.
    Unable to copy view because of an error in the source view definition. You may need to redefine the view in the source database before attempting to copy it.
  • X193: Outer join condition not allowed on expression predicates.
    Outer join conditions are allowed on fields only and not on expression predicates.
  • X194: Attempt to divide by zero.
    An attempt was made to divide by zero within an expression.
  • X195: User does not have privileges necessary for renaming a table.
    You must be the creator of the table or have DBADM privileges on the database in order to rename a table.
  • X196: Expression in GROUP BY/ORDER BY clause not allowed.
    Only a field name or field number is permitted in a GROUP BY clause. Only a field name or column number is permitted in a ORDER BY clause.
  • X197: Expression not allowed on left side of set clause.
    The left-hand side of a SET clause must be a valid keyword, such as DATABASE or BACKWARD LOG. Expressions, when permitted, may appear only on the right-hand side of the SET clause.
  • X198: Expression not allowed for field of insert clause.
    When specifying the target fields for an INSERT command, you must use field names; expressions are not allowed.
  • X199: Illegal foreign key constraint.
    A FOREIGN KEY cannot be referenced by another FOREIGN KEY. If you want A to reference B, and B to reference C, then instead have A reference C and B reference C.
Parent topic: X - Engine Error Messages


X200 - X249

Lists the Engine error messages from X200 through X249.

  • X200: Illegal attempt to log out of parent process when dependents exist.
    Internal error. Contact Micro Focus Technical Support.
  • X201: User does not have privilege necessary for operation.
    The user does not have the privilege required for the attempted operation. Check the SQL Reference for privileges required for specific operations.
  • X202: Check condition does not exist.
    An attempt was made to drop a non-existent check condition.
  • X204: Referenced key must be a primary/candidate key.
    Foreign key must reference a Primary or Candidate (Unique) key.
  • X205: Invalid character representation of numeric data.
    A character string that contains invalid or non-numeric data is used in a location that requires numeric data.
  • X206: Compatibility index must be set to group by number.
    The ability to perform a GROUP BY using column numbers in the specification is not supported in any compatibility modes other than the XDB mode. Change compatibility mode or write specification using column names.
  • X207: Check condition/view name incompatible with current version.
    The structure of underlying tables has changed since the view or check conditions were created. Drop the view or condition and recreate using the new database definitions.
  • X208: Table/View exists in target location. Use WITH REPLACE to overwrite.
    If table exists in target location, you must either drop it before overwriting, or use the COPY command with the WITH REPLACE option.
  • X209: Cannot perform GROUP BY on a view containing a GROUP BY.
    If a view contains a GROUP BY clause, a command using the view cannot also contain a GROUP BY clause.
  • X210: Cannot perform join with a view containing a GROUP BY.
    A view containing a GROUP BY clause cannot be joined to other tables.
  • X211: Cannot perform aggregate function on a view containing a GROUP BY.
    If a view contains a GROUP BY clause, no command using that view may contain an aggregate function.
  • X212: Function not available under current compatibility setting.
    The current compatibility setting set through Options does not permit the function being attempted. The setting must be modified to one that allows the functionality/syntax being attempted. See the Options User's Guide.
  • X213: Internal error encountered in function function. Contact Micro Focus.
    An unexpected internal error occurred. Contact Micro Focus Technical Support.
  • X214: The cursor identified in an open statement is already open.
    The application program attempted to execute an OPEN statement for a cursor that was already open. Correct the logic of the application program to ensure that it does not attempt this action.
  • X215: The cursor identified in a fetch/close statement is not open.
    The application program attempted to either (1) FETCH using a cursor, or (2) CLOSE a cursor at a time when a specified cursor was not open. In DB2 mode commit and rollback implicitly close cursor. After a cursor is closed, FETCHes or CLOSE cursor statements will generate this error code.
  • X216: Exceeded maximum outer join conditions.
    An outer join condition is one that contains a plus sign (+) next to a field. The number of outer join conditions allowed has been exceeded. Currently, five outer joins are allowed per query. To proceed, reduce the number of these conditions.
  • X217: Specified more than one primary key clause.
    The CREATE TABLE specified more than one primary key. By definition, a table may not have more than one primary key. Other candidate keys may be defined as unique keys.
  • X218: Referenced table does not contain a primary key.
    The table nominated as the parent in a FOREIGN KEY clause cannot be defined as a parent because it does not have a primary key defined. Correct the statement so that the table nominated as the parent in the FOREIGN KEY clause references a table with a primary key, or define a primary key for the table nominated as parent.
  • X219: Relationship name name already exists on this table.
    The constraint name specified in the FOREIGN KEY must be unique among all constraint names specified for this table. Change the name to one that is unique.
  • X220: Operation not allowed on table with incomplete definition.
    The reference to the table is invalid because it has a primary key, but no primary index. The reference is in a FOREIGN KEY clause or an SQL manipulative statement. Define a unique primary index on the table before referencing it.
  • X221: ALTER TABLE PRIMARY KEY requires existing unique index.
    The ALTER TABLE statement is invalid because the table does not have a unique index with a key that is identical to the nominated PRIMARY KEY. Make sure the key list specified on the ALTER TABLE statement identifies an existing unique index of the table.
  • X222: Relationship name must be less than 8 characters.
    The relationship name specified in the FOREIGN KEY clause is too long. Shorten the name to 8 characters or less.
  • X223: Self-Referencing tables must use the CASCADE delete rule.
    The delete rule specified in the FOREIGN KEY clause of the ALTER statement is invalid. A self-referencing constraint must specify the delete rule of CASCADE. Change the delete rule in the FOREIGN KEY clause.
  • X224: One or more foreign key fields must be nullable for SET NULL rule.
    The SET NULL clause of the FOREIGN KEY statement is invalid because no column of the key allows NULL values. Change a column of the key to allow NULL values, or change the delete rule.
  • X225: Primary key clause does not exist.
    The ALTER DROP PRIMARY KEY command was attempted on a table that does not contain a primary key.
  • X226: Relationship name name cannot be found in system table SYSREF.
    The ALTER DROP FOREIGN KEY command specified a constraint name that could not be found on the SYSREF table. Check the name to make sure it is a valid constraint name.
  • X227: Attempt to update parent having dependents in relationship name.
    An UPDATE operation attempted to update a primary key in the specified row of the object table; however, the primary key in the specified row had dependent rows associated with it. The value of a primary key in a parent row cannot be updated if the parent row has dependent rows. Examine the primary key of the object table and the foreign key of the dependent table to determine if the value of the primary key should be changed. If this does not solve the problem, examine the contents of the object table and the dependent table to determine the cause of the problem.
  • X228: The relationship name restricts the deletion of row with ID number.
    A DELETE operation attempted to delete a specified parent row in the object table and all related dependent rows in the dependent tables. However, a delete rule of RESTRICT was specified for one or more dependent tables.
  • X229: The insert/update value of foreign key name is invalid.
    An UPDATE or INSERT operation attempted to place a value in a foreign key of the object table; however, this value was not equal to some value of the primary key of the parent table.
  • X230: Index name is not compatible with current version.
    The index was not created with the current version and is incompatible. Rebuild the index with the current version. All indices in the location can be rebuilt using the COMPACT LOCATION AND INDEX command. All indices for a particular table can be rebuilt using the COMPACT TABLE `table-name' and INDEX command.
  • X231: Cursor must be declared as FOR UPDATE OF.
    The application program attempted to execute an UPDATE WHERE CURRENT OF statement on a cursor not defined as FOR UPDATE OF. Declare the cursor FOR UPDATE OF.
  • X232: Index name sort sequence different from current setting.
    An attempt was made to access an index that was created using a sort sequence different from the current sort sequence setting. When an index is created, it is sorted using the sort sequence specified in Options. To access this index, your default sort sequence setting must be consistent with that of the index. Rebuild the index with the default sort sequence setting or modify the setting in Options to be consistent with the index. Alternatively, you can drop the index and then recreate it with the new sort sequence setting.
  • X233: Non-quantified predicate followed by a list of values.
    If using a predicate without an ANY or ALL clause, only one value is allowed.
  • X234: Function not available with engine as database engine.
    DB2 link CAPI function not implemented with this engine.
  • X235: XDBXDIRECT function not supported on GROUP BY cursor.
    The Xdbxdirect function is not supported with queries containing a GROUP BY clause.
  • X236: Must use ALTER TABLE DROP PRIMARY KEY to drop index pending.
    An attempt was made to drop the `pending' index, which is a temporary name for a PRIMARY KEY which has not yet had a unique index created for it. To drop this index, use the ALTER TABLE DROP PRIMARY KEY statement.
  • X237: operation not allowed on table name while in use.
    Another user attempted an operation on the specified table while the table was in use. Skip the operation or retry it later.
  • X238: Attempt to update a deleted record.
    The record you are attempting to update has been deleted.
  • X239: Invalid DEGREE specified.
    The SET CURRENT DEGREE command contains an invalid value.
  • X240: Cannot delete field name which has existing referential key.
    An attempt was made to delete a field containing a referential key. To delete the field, first drop the referential key.
  • X241: Cannot modify field name which has existing referential key.
    An attempt was made to modify a field containing a referential key. To modify the field, first drop the referential key.
  • X242: Maximum number of sort fields exceeded.
    The query has exceeded the maximum number of sort fields allowed. The current maximum number of sort fields is 750.
  • X243: Host variable not allowed in current command.
    The command executed does not support host variables.
  • X244: Object table is referenced in nested query FROM clause.
    In DB2 mode, the table that is the object of an update, insert or delete cannot also be referenced in a nested query FROM clause.
  • X245: Requested packet is larger than max buffer size.
    The amount of data being sent from the application program to the engine is too large. Increase the receive buffer size on both the client-side and the server-side.
  • X246: Primary key cannot be target of multiple-row update.
    In DB2 mode, a primary key cannot be updated if an update clause retrieves more than one record.
  • X247: String representation of a date/time value is invalid.
    The character representation of a date or time value is not being recognized. The engine can recognize ISO, JIS, EUR, USA, and LOCAL formats. Compare your date/time representation with the picture specified in CONFIG.XDB through Options.
  • X248: AuthID not allowed on synonym table reference.
    In DB2 mode, a synonym cannot be referenced in a FROM clause with an AuthID. Remove the AuthID.
  • X249: Invalid picture specification.
    The picture used in the CHAR function is not legal.
Parent topic: X - Engine Error Messages


X250 - X299

Lists the Engine error messages from X250 through X299.

  • X250: Invalid PCTFREE value.
    Valid percent free values are 0 through 99.
  • X251: Only one clustered index allowed per table.
    XDB Server currently supports only one clustered index per table. Make all other indices non-clustered.
  • X252: Truncate not allowed on primary key table.
    The TRUNCATE clause is not allowed on tables that have a PRIMARY KEY.
  • X253: Compact cluster by clause must specify existing clustered index.
    When using the CLUSTER BY clause in a COMPACT statement, and the table has a clustered index, then you must specify the clustered index that already exists. If the table does not have a clustered index, then any index can be specified.
  • X254: DUPQTY value must be 8, 16, 32, 64 or 128.
    The only legal values when using the DUPQTY clause are 8, 16, 32, 64 and 128.
  • X255: Communication Manager out of memory.
    The XDB Server ran out of memory. You may want to reconfigure your system to increase available memory. See the XDB Server Administration Guide for specific performance tuning procedures.
  • X256: Stored Procedure ProcName failed due to reason ReasonCode.
    The XDB Server is not able to execute the CALL statement for the stored procedure ProcName.
  • X257: Engine configuration maximums too large. Reconfigure them smaller.
    The configuration parameters for Windows must fit into 64K. The options selected require more than 64K. Use the XDB Server Configuration utility to reconfigure the options.
  • X258: Out of memory for expressions.
    The total amount of memory required by the query for expressions exceeded the maximum memory that can be supported by XDB Server.
  • X259: Error on Operation (size) Server (server).
    An error has occurred with server-to-server access.
  • X260: Operation cannot be performed on current location version.
    The current location format does not include support for the command. Creating a new location or upgrading the system location will bring the current location version up to date.
  • X261: Redirector not loaded!
    The redirector associated with the selected protocol is not currently running. If your protocol is currently set to NetBIOS, run the NetBIOS redirector.
  • X262: Invalid parameter. A valid window handle was expected.
    A valid window handle is not zero. Pass a valid window handle returned from the CreateWindow() function.
  • X263: XdbWinInit() has not been called. XdbWinInit() must be called first.
    Under Windows, the function XdbWinInit() must be called before all other functions. See your C documentation.
  • X264: A necessary window could not be created.
    A window could not be created due to the number of windows already open or the amount of system resources in use. Close other windows or shut down other applications and try again.
  • X265: User program ProgramName could not be found.
    The XDB Server cannot find the DLL or the function associated with the procedure specified in your SQL CALL statement.
  • X266: Server is shutting down. Accepting no more logins.
    The server has been configured to shut down on last disconnect. No new connections are allowed.
  • X267: Invalid parameter in function function.
    An internal error has occurred. The XDB Server has received an invalid parameter or a different number of parameters than it expected.
  • X268: Server shutdown already in progress.
    Only one server shutdown command may be active at any one time.
  • X269: Illegal shutdown parameter.
    Internal error in shutdown processing. Contact Micro Focus Technical Support.
  • X270: Update/Delete on invalid cursor position.
    An application program tried to update or delete on an invalid cursor position. This is an internal error. If the application is a Micro Focus program, contact Micro Focus Technical Support.
  • X271: The Server failed when trying to begin a thread.
    The maximum number of threads allowed was exceeded. You must reconfigure the number of threads needed to a smaller number. The XDB Server Configuration utility options that affect this are:
  • X272: Cannot open file name. Increase the max number of open files in the XDB Server Configuration utility.
    The specified file could not be opened because the maximum number of open files set in the server configuration was exceeded. Increase the maximum number of open files in XDB Server Configuration utility.
  • X273: AuthID exceeds the maximum length.
    The maximum length of an AuthID is 8 characters.
  • X274: Location name exceeds the maximum length.
    The maximum length of a location name is 16 characters.
  • X275: Column name in explanation table name is not defined properly.
    An error occurred during the insertion of a row into the explanation table. The table is improperly defined for one or both of the following reasons: columns are defined in the wrong order; or a column description is invalid because of its name, data type, length or NULL attributes. Correct the definition of the required explanation table.
  • X276: Invalid number of fields (number) in explanation table name.
    The explanation table does not have a valid number of fields. Correct the definition of the required explanation table.
  • X277: userid does not have privilege to create with qualification authid.
    The specified user attempted to create an object with an invalid AuthID. Only if your AuthID is SYSADM, DBADM or DBCTRL can you create an object with an AuthID other than your valid primary or secondary AuthID. Ensure that AuthID is one of your valid AuthIDs.
  • X278: auth specified is not one of the valid AuthIDs.
    The specified AuthID is not the user's current primary or secondary AuthID. Specify a valid AuthID.
  • X279: Name name is too long. Maximum allowable size is number.
    The specified name has exceeded the maximum allowable length of number characters. Columns, tables, views, indices, aliases and synonyms have a maximum length of 18 characters. Locations have a maximum length of 16 characters. Table qualifiers, view qualifiers, storage group names, database names, tablespace names, and constraint names specified in CREATE or ALTER TABLE statements have a maximum length of 8 characters. Volume serial numbers must contain 6 characters or fewer, and labels must contain 30 characters or fewer. Enter a shorter name for the object.
  • X280: name is an undefined name.
    The object specified by name does not exist in the XDB Server location. Be sure you have entered the correct name.
  • X281: Object name name of object type type already exists.
    There is already an object of the type specified with the name specified. Drop the existing object or enter another name for the new object.
  • X282: Too many volume serial numbers specified.
    The CREATE or ALTER STOGROUP command specified a list of volumes that exceeds the maximum of 133. Shorten the list of volumes specified.
  • X283: The PART clause of an ALTER statement is omitted or invalid.
    The ALTER TABLESPACE command or ALTER INDEX command has an invalid partition clause. Check to be sure that the tablespace or index to be altered is partitioned. If so, be sure you have identified the correct partition; if not, do not include a PART clause.
  • X284: Duplicate keyword keyword.
    The specified keyword has a duplicate specification in the SQL statement. Change the statement so that it only contains one specification for the keyword.
  • X285: Attempt to drop stogroup used by a tablespace.
    An attempt was made to drop a storage group that is being used by one or more tablespaces. You must first alter or drop all tablespaces that use the stogroup before the stogroup itself can be dropped. You can query the STORNAME field of the SYSIBM.SYSTABLEPART system table to find all tablespaces that are dependent on the stogroup.
  • X286: Operation not allowed on system database.
    The attempted operation may not be performed on a system database.
  • X287: Alias name must not be defined on another alias.
    The specified name identifies an alias, which is defined on another alias. Do not use aliases to define other aliases; they should only define base tables or views.
  • X288: Statement reference to remote object is invalid.
    This error can be caused by any of the following conditions:
  • X289: Invalid value specified for keyword keyword.
    The value specified for the keyword is invalid. See the SQL Reference for valid keyword values.
  • X290: Keyword keyword not allowed for tablespace in workfile database.
    The specified keyword cannot be used for a tablespace in the workfile database. Change the SQL statement.
  • X291: Illegal use of keyword keyword.
    A syntax error exists in the SQL statement at the point where the specified keyword appears. Check the statement for errors.
  • X292: Unable to perform operation operation on database name.
    The requested operation is not legal or valid on the specified database.
  • X293: Table/Index ObjectName in use.
    The XDB Server cannot execute the STOP DATABASE command because the specified table or index is being used.
  • X294: Unable to operation stopped database name.
    It is illegal to perform the specified operation on the specified stopped database.
  • X295: Database ROSHARE can only be altered from OWNER to NONE.
    XDB Server only supports the altering of Read-Only Shared Databases from a value of OWNER to a value of NONE. You must create a new ROSHARE database in order to obtain other share options.
  • X296: Location name is not converted. Run location conversion program.
    The location specified is not compatible with the current version of the XDB Server database engine. You must convert the location by running the XDB Server conversion program CONVERT.EXE.
  • X297: FOR FETCH ONLY and FOR UPDATE OF are mutually exclusive clauses.
    You cannot specify both a FOR FETCH ONLY clause and a FOR UPDATE OF clause in your query. If a cursor is to be both fetched and updated you should not specify either clause in the SELECT statement.
  • X298: Synonym target must include an explicit authorization ID.
    The object to which a synonym applies must specify a two-part name that includes a valid AuthID. Modify the table or view name to include an AuthID.
  • X299: A segmented tablespace may not be partitioned.
    The CREATE TABLESPACE statement contains both the SEGSIZE and NUMPARTS specification, but they are mutually exclusive.
Parent topic: X - Engine Error Messages


X300 - X349

Lists the Engine error messages from X300 through X349.

  • X300: Cannot open configuration file CONFIG.XDB. Check XDBCFG setting.
    CONFIG.XDB was not found in the current directory, or in the directory specified by the XDBCFG environment variable.
  • X301: Cannot open configuration file CONFIG.XDB. Check XDBCFG setting.
    CONFIG.XDB was not found in the current directory, or in the directory specified by the XDBCFG environment variable.
  • X302: Cannot read configuration file CONFIG.XDB.
    The system is unable to open CONFIG.XDB. The file may be missing, damaged, or read-locked.
  • X305: Cannot open help file name.
    The file named was not found in the home directory. The `home' directory is set using Options.
  • X306: Syntax error in mask definition.
    The system was unable to parse a mask definition. Check the mask definition against the Options User's Guide.
  • X307: Grouping character found twice or in illegal position.
    The grouping character cannot appear to the right of the decimal point. A money symbol cannot appear between the grouping symbol and any numeric mask characters.
  • X308: No grouping length.
    No grouping character (,) was found in the mask; therefore, the grouping character cannot be reassigned.
  • X309: Decimal character found twice or in illegal position.
    A decimal point can only appear once in a numeric picture. Make sure you are not using a decimal point as a grouping character.
  • X310: Rounding character in illegal position.
    The rounding character (r) should appear as the rightmost character in a picture.
  • X311: Illegal character in picture specification.
    A character other than one of the characters in +-$,.9zr was found in a numeric picture specification.
  • X312: "$" character found on both sides of decimal.
    A dollar sign can only appear on one side of the decimal point in a money picture. Usually the dollar sign appears to the left. If the dollar sign appears to the right of the decimal point, only one dollar sign should appear.
  • X313: Sign character found on both sides of the decimal.
    A negative (-) or plus (+) sign can only appear on one side of the decimal point in a numeric picture. Usually the sign appears to the left of the decimal point. If the sign appears to the right of the decimal point, only one sign should appear in the picture.
  • X314: Error in substitution portion of picture definition.
    The decimal (.), grouping (,) and money ($) symbols are used when creating a numeric picture. You may substitute other characters for the decimal, grouping or money symbols by assigning a new value to these symbols after specifying the mask, for example:
  • X315: Illegal decimal found in picture.
    Cannot reassign the decimal character as requested, or the period character is not used as a decimal point in the mask portion of the picture.
  • X316: Illegal rounding character found in picture.
    Cannot interpret the rounding character r in its current location in the picture.
  • X317: Illegal dollar sign found in picture.
    Cannot reassign the money character as requested, or $ is not used as a money symbol in the mask portion of the picture.
  • X318: Closing single quote not found in substitution string.
    An expression assigning a new decimal, grouping or money symbol is missing a closing quote.
  • X319: Value too wide for picture field.
    An attempt was made to assign a value, or display a value using a picture that is unable to accommodate the value; for example, an attempt to display the value 1234 in a variable or column with a picture of 999.
  • X320: Error in time/date picture definition.
    The system is unable to parse a time or date picture. See the Options User's Guide for information on creating time and date pictures.
  • X321: Invalid CONFIG.XDB. Run XDBPROFI to reconfigure system.
    The configuration file, CONFIG.XDB, which is stored in the Micro Focus directory, has been damaged or is incompatible with the current version. Run Options as described in the Options User's Guide.
  • X322: Invalid year value.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X323: Invalid separator in value.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X324: Invalid character in value.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X325: Money value error.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X326: Numeric value error.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X327: Integer value error.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X328: No more RAM memory available.
    Insufficient RAM available to continue processing. Remove unnecessary programs from memory. For example, bypass the Loader or the Micro Focus application menu.
  • X329: COMMAND.COM not found.
    Please contact Micro Focus Technical Support.
  • X330: Cannot execute program.
    An error occurred when attempting to use the shell facility to temporarily exit to the operating system (possibly insufficient memory). In order to reach the operating system, you will have to exit normally, instead of using the shell facility.
  • X332: Index name does not exist.
    The index named was not found in the current database. Check the database path and the name of your index.
  • X333: Unknown field type in table name.
    An unknown field type was found. A different version of XDB Server may have been used to create the table, or the system path may be set to an earlier version. Check the version.
  • X334: Index name has been damaged.
    Either the named index has been damaged or a different version of XDB Server is running than the one that created the index. Use the version that created the index. The system path may be set to an earlier version. Check the version.
  • X335: Key name does not exist.
    The key named was not found in the current database. Check the database path and the name of your key.
  • X336: Key name has been damaged.
    Either the named key has been damaged or a different version is running than the one that created the key. Use the version that created the key. The system path may be set to an earlier version. Check the version.
  • X337: Synonym name does not exist.
    The synonym named was not found in the current database. Check the database path and the name of your synonym.
  • X338: Table/View name does not exist.
    The table or view named was not found in the current database. Check the database path and the name of your table or view.
  • X339: Error opening file FileName for Page1 to Page2 translation.
    The XDB Server was not able to open this file, which is needed for code page translation.
  • X340: Not enough memory to perform action.
    There was not enough memory to execute the command. A smaller command may be possible. Remove all memory resident tools that you are not currently using and try again.
  • X341: Illegal decimal precision.
    The number has an illegal precision. Check your data and your data type; they are probably not the same.
  • X342: Called function is not compatible with current version.
    This error occurs only when running the COBOL Precompiler. You must precompile and compile your program again for compatibility.
  • X343: An explicit COMMIT is illegal in an IMS/CICS program.
    IMS/CICS performs an implicit COMMIT. This is mainframe-compatible.
  • X344: An explicit ROLLBACK is illegal in an IMS/CICS program.
    IMS/CICS performs an implicit ROLLBACK. This is mainframe-compatible.
  • X345: A negative or zero ABSOLUTE FETCH is illegal.
    An absolute fetch needs a value specifying the offset from the current cursor position, and the offset must be a positive number.
  • X346: Cannot locate files in the directory specified.
    Files needed by the system cannot be found in the path specified by the XDBPATH environment variable. Make sure that you have specified the correct directory in the XDBPATH environment variable. Also make sure that your server names match in Options and the XDB Server Configuration utility.
  • X347: Illegal function code passed to the COBOL interface.
    Internal error. Contact Micro Focus Technical Support.
  • X348: No application path specified.
    There is no application path specified in CONFIG.XDB. IMS/CICS performs an implicit ROLLBACK. This is mainframe-compatible.
Parent topic: X - Engine Error Messages


X350 - X399

Lists the Engine error messages from X350 through X399.

  • X352: Server violation.
    The server experienced a protection exception while processing a user's command. The exception handling code has rolled back the user's current transaction and logged the user out.
  • X354: Error loading server communications DLL(name).
    Make sure you have the DLL named in the correct DLL subdirectory.
  • X355: Error connecting to remote server(name).
    An error has occurred while trying to connect to server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.
  • X356: Error sending to remote server(name).
    An error has occurred while trying to send to server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.
  • X357: Error receiving from remote server(name).
    An error has occurred while trying to receive from server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.
  • X358: Governor limit exceeded.
    One of the governor limits has been exceeded, and the server logged out the user. You could increase the governor limit for that user. The governor will be active only if the server security is ON.
  • X359: Error initializing remote server gateway.
    An error has occurred while trying to connect to a remote server.
  • X360: Incorrect version of the server configuration file.
    You have an old version of SRVCONFG.XDB. Delete your old SRVCONFG.XDB and run the new XDB Server Configuration utility to create a new one.
  • X361: No remote thread available to process request.
    A client has tried to connect to a remote server and the primary server does not have any thread available to handle the request. In these cases, there are no remote threads set for the primary server, or all the remote threads are already in use.
  • X362: Index error during recovery.
    While XDB Server was recovering a location, a fatal error occurred. You must compact and re-index the location immediately. Do not use the location until the compact and re-index has finished.
  • X363: No protocol threads available to process request.
    The number of protocol threads for TCP/IP, SPX, or Named Pipes must equal the number of users using the protocol.
  • X364: The describe statement does not identify a prepared statement.
    In order to describe a query, the query must first be prepared.
  • X365: Log path cannot be set to path.
    The logging system cannot set the log to the path specified. Ensure that the path exists, and that there are no other logs present in the path.
  • X366: Error replacing alias name with actual table name.
    XDB Server encountered an internal error when forming the alias substitution string. Contact Micro Focus Technical Support with the details of the query.
  • X367: GROUP BY/HAVING not allowed in subquery/embedded select.
    XDB Server and DB2 does not allow a GROUP BY or HAVING clause on a nested query.
  • X368: Illegal string string found.
    XDB Server received a different string than it expected. For example: SET CURRENT RULES <parm> must be either DB2 or STD. Using a different parameter will return an x368.
  • X369: Invalid index type.
    The index type must be 1 or 2.
  • X370: The target location needs to be compatible with DB2 version version.
    An attempt was made to perform new DB2 functionality against an XDB Server location that was created with this functionality. See the ALTER LOCATION command and CREATE LOCATION command in the SQL Reference .
  • X371: The selected locksize and lockmax options do not match.
    The DDL is illegal. See the SQL Reference for correct values.
  • X372: Illegal attempt to convert location to a lower version.
    An ALTER LOCATION can only be used to move forward in DB2 functionality, not backwards (i.e., an ALTER LOCATION cannot be used to convert a location to a lower version).
  • X373: Invalid number of parameters (number expected) for stored procedure ProcName.
    The number of parameters specified in your SQL CALL statement exceeds the number of parameters allowed by the ProcName stored procedure.
  • X374: Stored procedure ProcName received a null value for parameter number.
    The SQL CALL statement for stored procedure ProcName contains a null value in its parameter list, and this stored procedure does not accept null values.
  • X375: Stored procedure ProcName has been placed in a must rollback state.
    The stored procedure ProcName issued one of the following operations:
  • X376: Missing OBID clause when creating a table in a ROSHARE READ database.
    The OBID clause was not specified in the CREATE TABLE command. The OBID clause is required whenever the database containing the table is defined as ROSHARE READ.
  • X377: A privilege cannot be revoked because it is not possessed by AuthID authid.
    An AuthID can revoke only the privileges that it has explicitly granted to other AuthIDs, unless the AuthID has SYSADM or SYSCTRL authority and specifies the BY clause.
  • X378: Attempt to disable login with security off.
    A DISABLE LOGIN command was issued while security was off on the XDB Server.
  • X379: The login was rejected due to logins being disabled.
    The database administrator has disabled logins for this XDB Server, so your login command was rejected.
  • X380: The XDB Server has rejected this connection due to load balance requirements.
    Your connection request was rejected because the XDB Server has exceeded the load balancing limits configured by the database administrator.
  • X381: Cannot connect with requested location. Location is offline.
    The location you have requested is currently offline. (Your database administrator may have taken it offline for maintenance purposes.)
  • X382: Cannot take requested location offline. Location is in use.
    The XDB Server cannot take the requested server offline because it is being used. You are allowed to take a location offline only when there are no users attached to it.
  • X383: Sequence error for reason code (ReasonCode) Message.
    The XDB Server has received a request out of order.
  • X384: Invalid handle.
    The XDB Server has received an invalid handle. This is an internal error.
  • X385: Login error with Reason Code ReasonCode Message (returned Number).
    An error has occurred while logging on to the XDB Server through the Direct Flight software.
  • X386: Conflicting definitions for the same variable or parameter. Description
    The SQL Server has received a parameter or host variable from the client application that does not match the data type it expected.
  • X387: Option conflict with location rules
    The statement being executed has an option that is incompatible with the current location type.
  • X388: Invalid token 'token' found in PARMLIST for procedure proc-name
    A Stored Procedure or Trigger definition has a syntax error.
  • X389: Illegal operation on temporary table
    The current operation is not allowed on a temporary table. Temporary tables are not allowed to have primary/unique keys, or to be referenced by foreign keys. Also, update/delete operations on records in temporary tables are not allowed.
  • X390: Check option not allowed on temporary table
    A view of a temporary table must not specify the CHECK OPTION clause.
  • X391: WITH DEFAULT clause not allowed on CREATE GLOBAL TEMPORARY TABLE
    WITH DEFAULT clauses are not allowed on a CREATE GLOBAL TEMPORARY TABLE statement.
  • X392: Your SQL Option (for DB2 emulation) has expired.
    The XDB component (e.g., XDB Server, XDB Link) you are attempting to use does not have a valid license from Micro Focus.
  • X393: Output host variable PositionNumber is incompatible with the query result.
    The XDB Server is not able to return the result of a CALL, FETCH, or SELECT statement because the data type of the variable at PositionNumber in the output SQLDA (to which the result was to be written) does not match the data type of the result.
  • X394: Input host variable PositionNumber is incompatible with the current query.
    The XDB Server is not able to execute the requested SELECT statement because it contains a host variable whose data type is not correct. (For example, the WHERE clause may be using a numeric host variable to select from a DATE field in the database.) The host variable causing the problem is located at PositionNumber in the input SQLDA.
  • X395: Value for data type Type is out of range for host variable PositionNumber.
    The XDB Server cannot return the requested value because the returned value is larger than the host variable at PositionNumber in the output SQLDA (to which the value was to be written) can accept.
  • X396 ColumnName is not a column of specified table or view in the query.
    The specified name is not a column in the table or view referenced. A bad column name in a FOR UPDATE OF clause can generate this error.
  • X397 Decimal host variable or parameter Identifier contains non-decimal data.
    Data could not be used as specified in the statement because the data is not valid for this type.
  • X398 ColumnName is not an updateable column; it is not identified in the update clause.
    In order to update this column, you need to specify its name in the FOR UPDATE OF clause for this cursor.
  • X399 Improper use of long string data, StringValue.
    The operation is not supported on a long string value in DB2 mode.
Parent topic: X - Engine Error Messages


X400 - X449

Lists the Engine error messages from X400 through X449.

  • X400 Named cursor already assigned to a result set locator.
    The named cursor could not be reused.
  • X401 Statement can't be issued until the stored procedure has been called.
    Either a DESCRIBE PROCEDURE or an ASSOCIATE LOCATOR statement has been executed prior to the CALL to the stored procedure.
  • X402 Invalid result set locator.
    The result set locator was never assigned a valid value. Result set locators are returned by the ASSOCIATE LOCATORS statement.
  • X403 Cursor name CursorName was not defined.
    The named cursor was not defined.
  • X404 A Rollback is required.
    The transaction is in a must rollback state.
  • X405 An ON clause in a JOIN operator is invalid.
    An ON clause used to specify a JOIN condition is invalid. VALUE/COALESCE functions are only allowed in FULL OUTER JOINs. Only an '=' operator is valid in FULL OUTER JOINs. Also, column may be inappropriately referenced from within the JOIN clause.
  • X406 Stored procedure StoredProcName parameter ParameterName is larger than declared.
    The stored procedure has used a value that is too large for the definition declared in the SYSIBM.SYSPROCEDURES PARMLIST field.
  • X407 Stored procedure StoredProcName requires a host variable for parameter ParameterName.
    The parameter in the stored procedure PARMLIST definition in SYSIBM.SYSPROCEDURES is defined as OUT or INOUT. A host variable must be supplied in the call for that parameter.
  • X408 Stored procedure StoredProcName did not return result sets.
    The stored procedure has not returned any results sets to the caller. Verify that the stored procedure has been coded correctly.
  • X409: Error in trigger trigger-name, section number trigger-section
    A trigger trigger-name executed during an INSERT, UPDATE, or DELETE statement contained an SQL statement that returned an SQL error. The section number trigger-section identifies the statement in error.
  • X410: Function function-name named without signature, function not unique
    The signature of the user defined function function-name is not unique within its schema. Either the CURRENT PATH must be changed or the SPECIFIC name of the function must be used.
  • X411: Signature for function function-name not unique within schema
    The function function-name that is being created does not have a unique signature within the schema.
  • X412: Set transition variable is used for before trigger per row only
    SET transition-variable can only be used within a before trigger whose granularity is FOR EACH ROW.
  • X413: Invalid insert into column %s defined as generated always
    No input value is allowed for a column defined as GENERATED ALWAYS.
  • X414: Internal error, identity column definition not found
    An internal error has occurred. The identity column definition could not be found.
  • X415: Only one rowid or identity column is allowed in a table
    A table contains more than one row ID or identity column. This is not allowed.
Parent topic: X - Engine Error Messages


XMIG - Migrate Error Messages

  • XMIG000: Error system error: Unknown error errorID.
    Migrate attempted to display an error that was not found in the error file. This usually happens because an obsolete copy of the error file, XMIG.XRR, has somehow been copied into the directory.
  • XMIG001: No more RAM memory available.
    Migrate has experienced an internal error caused by a shortage of memory.
  • XMIG002: No Column in table.
    Migrate has experienced a serious internal error.
  • XMIG003: Cannot open file filename.
    Migrate is not able to open the specified file.
  • XMIG004: Syntax Error.
    Migrate is unable to interpret an SQL command that has been included in your migration.
  • XMIG005: Destination location has not been defined.
    Migrate is attempting to copy records, but a destination location has not been specified.
  • XMIG006: Destination table has not been defined.
    Migrate is attempting to copy records, but a destination table name has not been specified.
  • XMIG007: Error in internal query querystring.
    Migrate is attempting to access the SYSXDB.SYSQUERY table and the table is not in the expected format. Usually this is because the table is in an older format that does not include two fields required by Migrate.
  • XMIG008: Table tablename does not exist.
    The table name was not found in the specified source location.
  • XMIG009: Check source location data consistency.
    Migrate cannot create a foreign key because there is invalid value in the table.
  • XMIG010: Error saving file name.
    Migrate experienced an error when saving the named file.
  • XMIG011: Query window contains more than one query.
    Migrate has found an end-of-statement delimiter in the Query window. Only a single SELECT statement is allowed in this window.
  • XMIG012: Query must be a SELECT statement.
    Migrate has found an invalid SQL statement in the Query window. Only a single SELECT statement is allowed in this window.
  • XMIG013: Table already exists. Illegal with current settings.
    Select Table/Query Options from the Object menu, and check the "If table already exists" settings.
  • XMIG014: Field names in query may not match the field names of the destination table.
    An X009 was returned when the query from a Query window was executed. The database table has been altered since the .MIG file was saved, or there is some other problem with the validity of the SELECT statement in the Query window.
  • XMIG015: No key fields specified in replication query.
    A Query window used for replication must have at least one column defined as the key. Click the Update Rules button, and select True or False under the Key heading for each column returned by the SQL statement defined in the Query window.
  • XMIG017: Cannot find information in system_table for 'table_name'.
    SQL Migrate failed to retrieve information for the specified table from a system table when attempting to add it to the schema viewer.
  • XMIG049: SELECT error. May not have privileges.
    Migrate cannot complete this task because you do not have privileges on the specified object.
  • XMIG053: Filters yield no results. Filters are reset.
    The filter value entered for the immediate sub-item (database, or AuthID) beneath the location level returned an empty result set. The Catalog Browser display will be refreshed using the latest valid set of filter values stored in XDB.INI.
Parent topic: SQL Option for DB2 Error Messages


XU - Library Error Messages

  • XU001: No more RAM memory available to application.
    Insufficient memory (RAM) was available to execute a command sent to the SQL Engine. Try running the application from outside the main or application menu to see if that gives you enough memory to continue. If you have other memory resident programs loaded, remove them and try again. Load network drivers into high memory or remove them. Reduce DOS memory consumption by using fewer FILES= and fewer BUFFERS= in CONFIG.SYS.
  • XU002: No more EXTENDED memory available to application.
    Insufficient extended memory is available to run the application. Try bypassing the XDB Server Main Menu, or removing other programs from memory. See error XU001.
  • XU004: Filename name is too long.
    The filename you have entered exceeded the maximum length. Filenames must be 8 characters or fewer. Enter a shorter filename.
  • XU005: File name not found.
    Cannot find the file specified. Check to make sure that the correct directory is being used, and that the specified file exists there.
  • XU006: Error opening file name. error-descr.
    The system could not open the file named due to the specific operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU007: Error reading file name. error-descr.
    The system could not read from the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU008: Error writing file name. error-descr.
    The system could not write to the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU009: Error closing file name. error-descr.
    The system could not close the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU010: Error deleting file name. error-descr.
    The system could not delete the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU011: Error seeking file name. error-descr.
    The system could not seek the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU014: Incorrect file version in file name.
    The file specified is not the current version. If it is a help file or error file, you must recompile the file using the current version of the help compiler, XDBHELPC. If the file is a message file, you must recompile it using the message compiler, XDBMSGC.
  • XU015: Corrupted file format in file name.
    The file specified could not be entirely read. Check to see if it is the correct file. You may consider trying a backup file name.
  • XU016: Invalid file or path specification.
    The directory you have specified cannot be accessed.
  • XU017: The file FileName does not have correct read/write permissions.
    FileName has permission settings that prevent the software from reading or writing to it.
  • XU018: Invalid drive in search path.
    The drive letter you have specified does not exist.
  • XU020: Maximum of 3 unsuccessful attempts to login.
    You have attempted to log on to a XDB Server using an invalid user ID and/or password three consecutive times, so XDB Server will automatically exit the client application.
  • XU021: More than 15 errors...
    The active program has issued more error messages than this dialog box can display. Only the first 15 are shown.
  • XU022: Invalid server name.
    The string of characters you have entered does not constitute a valid server name. For example, the string contains an illegal character (such as a space) or is too long.
  • XU023: Invalid location name.
    The string of characters you have entered does not constitute a valid location name. For example, the string contains an illegal character (such as a space) or is too long.
  • XU025: Unknown system error. Errno = ErrNumber. Doserrno = DErrNumber.
    An internal error has occurred, and the error number is out of range.
  • XU030: Object name not found in SYSIBM.SYSTABLES while checking if it's an alias.
    An internal operation did not find a record for the requested alias in SYSIBM.SYSTABLES. This usually indicates an inconsistency in your catalog tables.
  • XU031: Object name is not an alias.
    The alias requested by an internal operation is not defined as an alias in the SYSIBM.SYSTABLES. This usually indicates an inconsistency in your catalog tables.
  • XU032: Error Querying SYSTABLES
    An internal operation encountered an error while attempting to get alias information from SYSTABLES.
Parent topic: SQL Option for DB2 Error Messages


User Interface Reference

  • Bind Utility
  • The Declaration Generator Window
  • Link Utility
  • Migrate Utility
  • Options Utility
  • SQL Wizard
Parent topic: Reference


Bind Utility

  • Bind Utility Window
  • Bind Package Dialog Box
  • Bind Options Dialog Box
  • Format Options Dialog Box
  • Rebind Package Dialog Box
  • Rebind Options Dialog Box
  • Drop Package Dialog Box
  • Create Default DBRM Dialog Box
Parent topic: User Interface Reference


Bind Utility Window

The following fields and controls are used in the Bind Utility window:

Remote Location
The drop-down list contains all the registered remote locations on the XDB Link. You cannot bind, rebind or drop a package until you select a location from this list.

Use the Gateway Profile Utility to register remote locations.

Current SQLID
Specifies the AuthID under which the bind will be executed. By default, your AuthID appears here.
Note: Do not change this field if you are creating the default package for XDB Link. The AuthID used to log on with the Bind Utility must match the primary AuthID on DB2, and must have the authority (in DB2) to run the initial bind.
Continue on Error
Enables the Bind Utility to continue processing when an error occurs.
Bind
To create a default package for XDB Link, or to modify an existing package, click the Bind button.
Rebind
To change options for an existing package without reading the DBRM, click the Rebind button.
Drop
To delete a package from the DB2 location, click the Drop button.
Default
To create a default DBRM, which you will need in order to create the default package for XDB Link, click Default.
Parent topic: Bind Utility


Bind Package Dialog Box

The following fields and controls are used in the Bind Package dialog box:

Bind Location
The Remote Location you selected in the Bind Utility main window. You cannot modify this field. Click Cancel to return to the main window if you need to select a different Remote Location.
Collection Identifier
The Collection ID of the DBRM you select from the DBRM File Name drop-down list. You cannot modify this field.
Package Name
The package name of the DBRM you select from the DBRM File Name drop-down list. The Bind Utility assigns this name to the package it creates. You cannot modify this field.
DBRM File Name
The drop-down list contains all of the DBRMs (.DBR files) in the XDB application directory on your workstation.
Package Version
If you are maintaining multiple versions of a program, assign a different number for each version of the package. This field is optional.
Note:

If the host on which you are binding this package does not support package versions, leave this field blank.

Isolation Level
Controls the manner in which locks are acquired and released by the system.
No Commit
Allows your program to read modified records even if they haven’t been committed by another process.
Change
If you are using a read-only cursor:
  • Allows your program to read modified records even if they haven’t been committed by another process.
  • Allows other processes to change a record that your application reads, even if your cursor is on that record.

If you are using a non-read-only cursor:

  • Prevents your program from reading a modified record that hasn’t been committed by another process.
  • Prevents other processes from changing a record while your cursor is on it.
Cursor Stability
Allows other processes to change a row that your application reads, but does not change, as long as your cursor is not on that row.

Prevents other processes from changing records that your application has changed until your program commits them or terminates.

Prevents your program from reading a modified record that hasn’t been committed by another process.

All
Prevents other processes from changing records that are read or changed by your application until your program commits them or terminates.

Prevents your application from retrieving a modified record that hasn’t yet been committed by another process when it opens a read-only database cursor.

If your program opens the same query during a single unit of work under this isolation level, the results table may differ from the previous one because it may include committed changes from other processes.

Repeatable Read
Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates.

Prevents the application from reading a modified record that hasn’t been committed by another process.

If your program opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table. However, it may contain updates made by your program.

No Commit
Allows your program to read modified records even if they haven't been committed by another process.
Change
If you are using a read-only cursor:
  • Allows your program to read modified records even if they haven't been committed by another process.
  • Allows other processes to change a record that your application reads, even if your cursor is on that record.

If you are using a non-read-only cursor:

  • Prevents your program from reading a modified record that hasn't been committed by another process.
  • Prevents other processes from changing a record while your cursor is on it.
Cursor Stability
Allows other processes to change a row that your application reads, but does not change, as long as your cursor is not on that row.

Prevents other processes from changing records that your application has changed until your program commits them or terminates.

Prevents your program from reading a modified record that hasn't been committed by another process.

All
Prevents other processes from changing records that are read or changed by your application until your program commits them or terminates.

Prevents your application from retrieving a modified record that hasn't yet been committed by another process when it opens a read-only database cursor.

If your program opens the same query during a single unit of work under this isolation level, the results table may differ from the previous one because it may include committed changes from other processes.

Repeatable Read
Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates.

Prevents the application from reading a modified record that hasn't been committed by another process.

If your program opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table. However, it may contain updates made by your program.

Action
One of the following options:
  • Replace replaces an existing package with a new package. To replace the version label, enter a new label in the Replace Version field in the Bind Options dialog box.
  • Add creates a new package if one does not already exist. If a package with the current Collection ID already exists, the bind process will fail.
Bind
To set optional parameters for the bind, click the Bind button. This command button is available only when you select a file from the DBRM File Name drop-down list.
Format
To specify data formats associated with the selected DBRM, click the Format button. This command button is available only when you select a file from the DBRM File Name drop-down list.
Parent topic: Bind Utility


Bind Options Dialog Box

The following fields and controls are used in the Bind Options dialog box:

Replace Version | Specifies the new version name for a replacement package. This field is available only when you select the Replace option from the Action drop-down list in the Bind Package dialog box.
Replace Authorization One of the following options:
  • Retain uses the SQLID assigned to the existing package on the host.
  • Revoke uses the current SQLID specified in the Bind Utility window.

This field is available only when you select the Replace option from the Action drop-down list in the Bind Package dialog box.

Creation Control One of the following options:
  • No Error Allowed does not create a package if an error occurs during the bind process.
  • Error Allowed creates a package even if an error occurs during the bind process.
  • Check Only executes the bind without creating a package. Use this option to test the bind operation without actually creating a package.
Existence Checking One of the following options:
  • Optional creates a package even if database objects referenced in the DBRM do not exist. Use this option to create a package prior to defining all data objects.
  • Required creates a package only if all database objects referenced in the DBRM exist.
Blocking Protocol One of the following options:
  • Single Row returns data one row at a time for all cursors that are read-only or are ambiguous. This option provides maximum control of data transfer.
  • Limited Block returns data in blocks (of the size you have specified in the Gateway Profile Utility) for all cursors that are read-only or are ambiguous. This option can improve performance significantly. It provides maximum data-transfer speed. For more information about specifying block size, see your Link Configuration Guide.
  • Forced Single Row returns data one row at a time regardless of the read-only status of the cursor.
Resource Release One of the following options:
  • Commit releases database resources after a commit. Provides a high level of concurrency.
  • Deallocation releases database resources when the connection is terminated.
Explain One of the following options:
  • No Statements disables the EXPLAIN option to create the package without generating descriptive information.
  • All Statements enables the EXPLAIN option to write descriptive information about the package to owner.PLAN_TABLE. This table must exist before you execute the bind.
Package Owner | The AuthID assigned to the package. This DB2 AuthID must have authority to execute all the SQL in the package.
Default Qualifier | The AuthID used to complete any unqualified (one-part) table names in the DBRM file. If you leave this field blank, the Bind Utility uses the current SQLID.
Dynamicrules Controls the behavior of dynamic SQL with regard to one part name qualification and permissions checking:
  • DYNAMIC RULES RUN: The AuthID used for checking permissions of dynamic SQL statements will be the value of the CURRENT SQLID special register. The default value of the CURRENT SQLID special register is the AuthID of the process. Users with SYSADM authority can change their CURRENT SQLID special register to any value and users with secondary AuthIDs can change their CURRENT SQLID special register to be any of their secondary AuthIDs.

    The AuthID used for qualifying one part names of tables, views, etc. will be the value of the CURRENT SQLID special register. As stated above, the special register value can be changed under certain circumstances.

There are no restrictions on commands that can be executed.

  • DYNAMIC RULES BIND: The AuthIDs of the package is used for checking permissions of dynamic SQL statements.

    The value of the Default Qualifier text box will be used for qualifying one part names of tables, views, etc. If the Default Qualifier text box is left blank, the AuthIDs of the package is used for qualifying one part names of tables, views, etc.

    When this option is in effect, you cannot issue the following dynamic SQL statements: ALTER, CREATE, DROP, GRANT, RENAME, and REVOKE.

If left blank, this option defaults to DYNAMIC RULES RUN.

Parent topic: Bind Utility


Format Options Dialog Box

The following fields and controls are used in the Format Options dialog box:

String Delimiter
The type of quotes (single or double) used to represent constant string values that are referenced by the SQL in the DBRM. This option should match the option used to delimit the literal strings referenced by your embedded SQL.
Note: When you are binding the default DBRM for XDB Link, you must use the Single Quote option.
Decimal Delimiter
You must set this field if the DBRM file contains a decimal literal that does not match the host system's default value.
  • Period indicates that the decimal point is represented with a period (for example 3.17).
  • Comma indicates that the decimal point is represented with a comma (for example 3,17).
Default Decimal Precision
One of the following options:
  • 0 uses the system default value.
  • 15 specifies a decimal precision of 15 places.
  • 31 specifies a decimal precision of 31 places.
Default Char Subtype
Options for storing ambiguous character data in the database:
  • System Default specifies the system default value of the DB2 location to which you are binding.
  • SBCS specifies a single-byte character set.
Parent topic: Bind Utility


Rebind Package Dialog Box

The following fields and controls are used in the Rebind Package dialog box:

Bind Location
The Remote Location you selected in the Bind Utility main window. You cannot modify this field. Click Cancel to return to the main window if you need to select a different Remote Location.
Collection Identifier
The Collection ID of the package selected from the Package drop-down list. You cannot modify this field.
Package Name
The name of the package selected from the Package drop-down list. You cannot modify this field.
Package
The drop-down list contains all of the packages on the host that are owned by the current SQLID.
Package Version
If you are maintaining multiple versions of a program, assign a different number for each version of the package. This field is optional.
Note: If the host on which you are binding this package does not support package versions, leave this field blank.
Isolation Level
Controls the manner in which locks are acquired and released by the system.

The options are:

No Commit
Allows your program to read modified records even if they haven’t been committed by another process.
Change
If you are using a read-only cursor:
  • Allows your program to read modified records even if they haven’t been committed by another process.
  • Allows other processes to change a record that your application reads, even if your cursor is on that record.

If you are using a non-read-only cursor:

  • Prevents your program from reading a modified record that hasn’t been committed by another process.
  • Prevents other processes from changing a record while your cursor is on it.
Cursor Stability
Allows other processes to change a row that your application reads, but does not change, as long as your cursor is not on that row.

Prevents other processes from changing records that your application has changed until your program commits them or terminates.

Prevents your program from reading a modified record that hasn’t been committed by another process.

All
Prevents other processes from changing records that are read or changed by your application until your program commits them or terminates.

Prevents your application from retrieving a modified record that hasn’t yet been committed by another process when it opens a read-only database cursor.

If your program opens the same query during a single unit of work under this isolation level, the results table may differ from the previous one because it may include committed changes from other processes.

Repeatable Read
Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates.

Prevents the application from reading a modified record that hasn’t been committed by another process.

If your program opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table. However, it may contain updates made by your program.

Bind
To set optional parameters for the package you are rebinding, click the Bind button.
Parent topic: Bind Utility
Related information
Overview


Rebind Options Dialog Box

The following fields and controls are used in the Rebind Options dialog box:

Existence Checking
One of the following options:
  • Optional creates a package even if database objects referenced in the DBRM do not exist. Use this option to create a package prior to defining all data objects.
  • Required creates a package only if all database objects referenced in the DBRM exist.
Resource Release
One of the following options:
  • Commit releases database resources after a commit. Provides a high level of concurrency.
  • Deallocation releases database resources when the connection is terminated.
Explain
One of the following options:
  • No Statements disables the EXPLAIN option to create the package without generating descriptive information.
  • All Statements enables the EXPLAIN option to write descriptive information about the package to owner.PLAN_TABLE. This table must exist before you execute the bind.
Package Owner
The AuthID assigned to the package. This DB2 AuthID must have authority to execute all the SQL in the package.
Default Qualifier
The AuthID used to complete any unqualified (one-part) table names in the DBRM file. If you leave this field blank, the Bind Utility uses the current SQLID.
Parent topic: Bind Utility


Drop Package Dialog Box

The following fields and controls are used in the Drop Package dialog box:

Bind Location
The Remote Location you selected in the Bind Utility main window. You cannot modify this field. Click Cancel to return to the main window if you need to select a different Remote Location.
Collection Identifier
The Collection ID of the package selected from the Package drop-down list. You cannot modify this field.
Package Name
The name of the package selected from the Package drop-down list. You cannot modify this field.
Package Name
The drop-down list contains all of the packages on the host that are owned by the current SQLID.
Parent topic: Bind Utility


Create Default DBRM Dialog Box

The following fields and controls are used in the Create Default DBRM dialog box:

Collection ID
The Default Collection ID value you specified in the Gateway Profile utility when you configured XDB Link for the mainframe location.
Package Name
The default Package Name you specified in the Gateway Profile utility when you configured XDB Link for the mainframe location.
Host System
The drop-down list contains options for specifying the type of host system to which you want to bind XDB Link.
Dynamic Sections
The number of statements that the XDB Link package can prepare for a single user.
Parent topic: Bind Utility


The Declaration Generator Window

The following fields and controls in the Declaration Generator window are used to create declaration files in COBOL, C or PL/I.

Generate | Generates a declaration file according to the specifications that have been defined in the Declaration Generator window.
Save As Saves the current specifications to a .DGE file. A .DGE file can be used as input to the Declaration Generator when it is run in batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.

If you specify the name of an existing .DGE file, you will be asked whether the current specification should replace the existing file or be appended to it.
Options | Allows you to set options that are specific to the language you have selected.
Exit | Closes the Declaration Generator window.
Location | Specifies the location of the table.
AuthID Specifies the access authority under which you will access the table. In order to create a declaration file, you must have SELECT privileges on the table for which you are generating a declaration, and on the following system tables:
  • SysIBM.SYSLOCATIONS
  • SysIBM.SYSTABLES
  • SysXDB.SYSACFUsers
Table Name | Identifies the table for which the declaration file will be generated.
Declaration | The fields in this group box determine how the declaration file is written.
Output File Specifies the file to which the declaration statements will be written. If you do not specify a path, the file is written to the application path (specified in the PATHS tab in Options) when you select C, or the value of the COBCPY environment variable when you select COBOL or PL/I.

A default file name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.

If you specify a file that already exists, you will be prompted at run time to choose whether you want to replace the existing file or append the statements to it.
Structure Name | Specifies the name of the record definition (COBOL), structure (C) or declaration structure (PL/I) written to the declaration file. A default name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.
Language | The LANGUAGE group box is used to select the programming language in which you want the declaration written. You can select COBOL, C or PL/I.
Text Assign a prefix to each field name as it is written into the declaration file. The following shows how field names would be treated if a prefix of emp_ were used.

Remember to take into account your compiler's variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the programming language or that make the variable's name too long.
Generate | Generates a declaration file according to the specifications that have been defined in the Declaration Generator window.
Save As Saves the current specifications to a .DGE file. A .DGE file can be used as input to the Declaration Generator when it is run in batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.

If you specify the name of an existing .DGE file, you will be asked whether the current specification should replace the existing file or be appended to it.
Options | Allows you to set options that are specific to the language you have selected.
Exit | Closes the Declaration Generator window.
Location | Specifies the location of the table.
AuthID Specifies the access authority under which you will access the table. In order to create a declaration file, you must have SELECT privileges on the table for which you are generating a declaration, and on the following system tables:
  • SysIBM.SYSLOCATIONS
  • SysIBM.SYSTABLES
  • SysXDB.SYSACFUsers
Table Name | Identifies the table for which the declaration file will be generated.
Declaration | The fields in this group box determine how the declaration file is written.
Output File Specifies the file to which the declaration statements will be written. If you do not specify a path, the file is written to the application path (specified in the PATHS tab in Options) when you select C, or the value of the COBCPY environment variable when you select COBOL or PL/I.

A default file name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.

If you specify a file that already exists, you will be prompted at run time to choose whether you want to replace the existing file or append the statements to it.
Structure Name | Specifies the name of the record definition (COBOL), structure (C) or declaration structure (PL/I) written to the declaration file. A default name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.
Language | The LANGUAGE group box is used to select the programming language in which you want the declaration written. You can select COBOL, C or PL/I.
Text Assign a prefix to each field name as it is written into the declaration file. The following shows how field names would be treated if a prefix of emp_ were used.

Remember to take into account your compiler's variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the programming language or that make the variable's name too long.
Numbered | Replaces a field name with a number in the declaration file. This option can be selected only when a field prefix is assigned in the TEXT field. The following example shows how field names would be treated if the NUMBERED option were set with a prefix of emp_.
If the Field name is... | It will be written as...
ssn | emp_ssn
lname | emp_lname
fname | emp_fname
If the Field name is... | It will be written as...
ssn | emp_001
lname | emp_002
fname | emp_003
 | Numbered | Replaces a field name with a number in the declaration file. This option can be selected only when a field prefix is assigned in the TEXT field. The following example shows how field names would be treated if the NUMBERED option were set with a prefix of emp_.
Computation | Specifies the internal storage format assigned to binary integers in a COBOL record description. The choices are COMP, COMP-4 and COMP-5.
Computation Specifies the internal storage format assigned to binary integers in a COBOL record description. The choices are COMP, COMP-4 and COMP-5.
Parent topic: User Interface Reference


Link Utility

  • Gateway Facility Main Window Options
  • Location Configuration Window
  • Workstation Configuration Window
Parent topic: User Interface Reference


Gateway Facility Main Window Options

Select the task you need to perform, or click Close to close this window and exit the Gateway Profile Utility. If you are configuring the Link on a machine where the XDB Server is installed, the Status field shows the status of your connection to the server.

Register... Displays the Location Configuration window, which you use to add, modify, and delete remote locations. Each remote data location (including the location for Password Expiration Manager) must be configured with the Gateway Profile utility before it can be accessed through the Link.
Local... Displays the Workstation Configuration window, which you use to configure the:
  • Code pages the Link uses to translate data
  • Number of clients that can connect to a data source through the Link
  • Settings that control client conversations with the host
Parent topic: Link Utility
Related information
Location Configuration Window
Workstation Configuration Window


Location Configuration Window

Use the Location Configuration window to:

  • Define a new remote location to the Link
  • Modify an existing definition for a remote location
  • Delete an existing definition for a remote location

You must define a remote location to the Link before client applications can access the data in that location. Remote locations include data sources such as DB2 subsystems and other XDB Servers. If you plan to use XDB's Password Expiration Manager (PEM), you must configure a connection between the Link and the PEM module on the mainframe by defining a remote location.

To open the Location Configuration window, click Register on the main window of the Gateway Profile Utility.

The Location Configuration window is divided into the following sections:

  • General controls (those with no label) and Host Code Pages settings apply to all location types.
  • APPC Setup applies only to DRDA(APPC) and PEM(APPC) connection types.
  • TCP/IP Setup applies only to DRDA(TCP/IP), XDBHOST, and PEM(TCP/IP) connection types.
  • DRDA Setup applies only to DRDA(APPC) and DRDA(TCP/IP) connection types.
Parent topic: Link Utility
Related information
Gateway Facility Main Window Options
Workstation Configuration Window


Workstation Configuration Window

Use the Workstation Configuration window to configure settings that XDB Link uses to control conversations between the client application and the host system.

To access the Workstation Configuration window, click Local in the Gateway Profile Utility window.

Workstation Code Pages

The values in this group box specify the code pages that represent the national-language format for client workstations using XDB Link. If you are using English (US) machines, leave these settings at their default values. For any other language, enter the code page value for that language. If you are using the XDB Server as your gateway server, you must restart the XDB Server after changing any code page values.
Single Specify the single-byte code page value for client machines connecting to the host through XDB Link. XDB Link converts single-byte character data received from the host through this code page before sending it to the client workstation. It also uses this as the code page identifier for single-byte character data that it transmits to the host. The default is 850.

If you connect through a gateway server, enter the PC's OEM code page. In the United States, the default is 437.

If you connect as a direct client to DB2, enter the ANSI code page value. In the United States, the default is 1252.

If you use binary data or for bit data fields with COBOL programs, set the single code page setting to 911. If you are using the 911 code page while connected to a DB2 host and want to connect to a DB2 host which uses a different code page than that of the current DB2 host, you must restart the server prior to connecting to the new host.

To determine your PC's OEM and ANSI code page settings: at a DOS prompt, change (cd) to the install directory and type codepage.
Mixed | Specify the mixed-byte code page value for client machines connecting to the host through XDB Link. XDB Link converts mixed-byte character data received from the host through this code page before sending it to the client workstation. It also uses this as the code page identifier for mixed-byte character data that it transmits to the host. The default is 932.
Double | Specify the double-byte code page value for client machines connecting to the host through XDB Link. XDB Link converts double-byte character data received from the host through this code page before sending it to the client workstation. It also uses this as the code page identifier for double-byte character data that it transmits to the host. The default is 301.
Close Conversation | Select the setting that determines when XDB Link closes an LU 6.2 conversation. At Dealloc closes the conversation when the client application terminates. At Commit closes the conversation after the client application executes a COMMIT statement. Use the default value, At Dealloc, unless you are tuning the system for OLTP applications or you want to prevent an application from tying up host resources when a client leaves it idle for an extended period of time.
Maximum Clients | Specify the maximum number of concurrent client sessions that XDB Link can carry. Permitted values are 1 to 128. For an XDB Server, select a value that will comfortably accommodate the number of users that will simultaneously access the host system through XDB Link. In a Direct Configuration, use a small value to reduce XDB Link's memory requirements (unused client sessions needlessly consume memory on your machine).
User Buffer Size Specify the size (in kilobytes) of the bulk packet that XDB Link uses to download data from the host. Permitted values are 1 to 63. For most environments, the default value is sufficient. However, adjusting the value can optimize certain client applications:
  • For client applications that frequently download large amounts of data, a large buffer size can improve response time.
  • For client applications that perform brief, online transactions, a small buffer will maximize memory on the machine where XDB Link is installed.
Parent topic: Link Utility
Related information
Gateway Facility Main Window Options
Location Configuration Window


Migrate Utility

  • The Migrate Window
  • The Table Tab
  • The Query Tab
  • The Migrate Options Dialog Box
  • The Migrate Database Dialog Box
  • The Table Options Dialog Box
  • The Run Dialog Box
  • The Default Options Dialog Box
  • The Query Options Dialog Box
  • The Query Update Rules Dialog Box
  • The Control Menu
  • The File Menu
  • The Edit Menu
  • The View Menu
  • The Object Menu
  • The Commands Menu
  • The Options Menu
  • The Help Menu
  • The Window Menu
Parent topic: User Interface Reference


The Migrate Window

Once a connection to a server is established, the Migrate window appears. This window contains tools and controls for selecting source tables, specifying a destination and setting migration parameters.

The Menu bar contains Migrate commands you can use to specify migrate options and launch a migration. For a description of each command on the Menu bar, see The Migrate Menus.

The Toolbar contains the following icons that provide quick access to a particular command or function.

Icon | Description
* | Opens the Catalog Browser if it is not already open. If the Catalog Browser is open, this button refreshes its contents.
* | Lets you specify options for the selected table or a query.
* | Runs a migration of the specified tables using the specified parameters.
* | Opens Migrate help.

The Catalog Browser is used to select tables and queries that you want to migrate to another location (i.e., specify the source tables or queries). For more information about the Catalog Browser, see The Catalog Browser.

The Schema Viewer graphically displays the source tables that have been selected for migration. From this window, you can set options, and display dependent and referenced tables. For more information about the Schema Viewer, see The Schema Viewer.

Parent topic: Migrate Utility


The Table Tab

*
Use the Table tab in the Catalog Browser to locate and select the tables you want to migrate. To show tables in the Browser, click the Table tab on left side of the Catalog Browser window.

To locate a table, click the + buttons to expand the database hierarchy until the table name appears.

To select a table for migration, do one of the following:

  • double-click the table name in the Catalog Browser, or
  • highlight the table name, then drag it into the Schema Viewer.

If you want to select multiple tables, hold the Ctrl or Shift key when you click the table name. Shift lets you select a group of consecutive names in the listCtrl lets you select multiple, non-consecutive names.

For information about migrating tables that you have placed in the Schema Viewer, see Migrating Tables.

Parent topic: Migrate Utility


The Query Tab

*
Use the Query tab in the Catalog Browser to recall a saved query that has been created with a data management tool such as SQLWizard. For information about using a query during a migration, see Migrating Certain Rows and Columns.

To view a list of the available saved queries, click the Query tab on the left side of the Browser window.

To locate a query, click the + buttons to expand the database hierarchy until the query name appears.

To recall a saved query from the Query tab, do one of the following:

  • double-click the query name, or
  • highlight the query name, then drag it into the Schema Viewer.

The recalled query is displayed in the Query window. You can edit the query or accept it as is.

Note:

If your recalled query contains SQL statements besides SELECT, we recommend that you remove them before running the migration. The Query window should contain only a single SELECT statement to specify the data that is to be migrated to another table. For more information about migrating data from a query, see Migrating Certain Rows and Columns.

Parent topic: Migrate Utility


The Migrate Options Dialog Box

The Migrate Options dialog box is used to set the default migration options that appear in the Run dialog box when you perform a migration.

The Migrate Options dialog box contains the following controls:

The Output group box

Use this to select defaults for migration output. You can also control whether to execute the migration or not.

Impact Analysis Report
Sets the Impact Analysis Report as a default migration option. The Impact Analysis Report provides detailed information on the tables that will be affected by the migration as it is currently specified. This report is used to analyze the effect of a migration without actually executing it.
Attention: If this report is selected, Migrate will not migrate any information.
Generate SQL
Saves the SQL script file that processes your migration as a default migration option. In the field next to the checkbox, type the name of the file to which you want the SQL script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new script.
Post Execution Report
Sets the Post Execution Analysis Report as a default migration option This report generates a listing of the source and destination tables that are a part of the migration. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

Attention: If the Impact Analysis Report checkbox is selected, you can not run a Post Execution Analysis Report.
Error File
Sets the Error File as a default migration option. The error file records migration errors. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

Browse
Use the Browse button to view a list of filenames on your system. If you want to use an existing file for output, you can select its name from the list.

The Input Files group box

Use this to specify SQL files to be executed during your migration.

Prologue
Causes Migrate to process an SQL script file before it processes the specified tables and queries. In the field next to the checkbox, type the name of the SQL script file to be used.
Epilogue
Causes Migrate to process an SQL script file after it processes the specified tables and queries. In the field next to the checkbox, type the name of the SQL script file to be used.
Parent topic: Migrate Utility


The Migrate Database Dialog Box

Database list | Lists all of the databases defined to SQL Option for DB2.
Migrate Tables list | Lists all of the tables defined in the database or databases selected on the Database list.
Exclude button | Click this to exclude any tables selected on the Migrate Tables list, moving the table name down to the Not Included list.
Options button | Click this to set table options for the selected tables.
Add button | Click this to add tables selected on the Not Included list back to the Migrate Tables list.
Save button | Click this to generate a .mig script file containing the migration information set on this dialog box.
Execute button | Click this to invoke the Run dialog box, where you specify a location to migrate to and kick off the migration process.
Parent topic: Migrate Utility


The Table Options Dialog Box

The Table Options dialog box is used to specify destination parameters and define objects you want migrated with the selected table. You can also use this dialog box to determine how to handle duplicate migrations and how to commit data records.

The Table Options dialog box contains the following controls:

Source | Displays information about the selected source table.
AuthID | Displays the owner of the source table.
Table | Displays the name of the source table.
Tbl Space | Displays the table space name for the source table.
Database | Displays the name of the database the source table was selected from.
Destination | Use the Destination group box to specify information about the destination table.
Auth ID Enter the AuthID associated with the destination table. Changing this field assigns a new owner to the destination table.

If you want Migrate to use the source table's Auth ID by default, select the Default To Source checkbox next to the Auth ID text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify an Auth ID by typing it in text box.

Table | Enter a name for the destination table.
Tbl Space Enter the table space name for the destination table.

If you want Migrate to use the name of the source table space by default, select the Default To Source checkbox next to the Tbl Space text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a table space name by typing it in this text box.

Database Enter the database name for the destination table.

If you want Migrate to use the name of the source database from which the source table is selected by default, select the Default To Source checkbox next to the Database text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a database name by typing it in this text box. If this field is left blank, the default database name "DSNDB04" is used.

Primary Key | Select this checkbox if you want primary-key columns in the source table to also be primary-key columns in the destination table.
Unique Keys | Select this checkbox if you want unique-key columns in the source table to also be unique-key columns in the destination table.
Indexes | Select this checkbox if you want the index key in the source table to also be the index key in the destination table.
Foreign Keys | Select this checkbox if you want foreign-key columns in the source table to also be foreign-key columns in the destination table.
Synonyms | Select this checkbox if you want any alternate names for the source table to also be alternate names for the destination table.
Comments | Select this checkbox to migrate comments in the source table to be included on the destination location table.
Privileges | Select this checkbox to migrate privileges. The privileges checkbox lets you place the same security standards on the destination tables as on the source tables.
If Table Already Exists | Use the If Table Already Exists group box to specify what Migrate should do if the table you are migrating already exists at its destination.
Abort | Select this option if you want Migrate to terminate the migration if the destination table already exists.
Append Data Select this option if you want Migrate to append the new table to the existing destination table. If the destination table has no primary key, all records are appended to the destination. You can use this option with the No Data option (see below) to migrate just an index.
Note:

You can end up with duplicate records if you use this option on a table without a primary key.
Replace Data | Select this option if you want Migrate to replace all existing records in the destination table with records from the source table. All data in the existing table will be deleted.
Replace Table | Select this option if you want Migrate to drop the destination table and create a new table containing the result of this migration.
Data Options | Use the Data Options group box to specify how much data should be migrated and to specify a commit rate.
Limit Data To Select the number of records you want to copy.
  • Select All Rows to migrate all data records from the source table to the destination.
  • Select No Data to migrate none of the records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature. Or, you might use it to copy certain table attributes without copying any data.

    The behavior of this option depends on the following:

    • If the destination table does not exist, an "empty" table is created.
    • If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).
    • If the destination table exists, and the Append Data option is used, no records are copied to it (you could use this combination of options to copy just an index).
  • Select First N Rows if you only want to migrate the first N records from the source table to the destination.
  • Select Every Nth Row if you want to copy every N records from the source table to the destination.
Commit Work After

Specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). You can specify any number between 0 and 32,767. High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
Parent topic: Migrate Utility


The Run Dialog Box

Use the Run dialog box to execute the currently specified migration. It also can specify certain options for the migration before you begin, and optionally select scripts that can be executed before and/or after the migration is processed. Clicking OK in this dialog starts the migration.

The Run dialog box contains the following controls:

Migrating | Displays the source and destination of the migration. If the destination is not displayed or is incorrect, change it in the To entry box .
 | From | Displays the location of the source table(s). If you have placed tables in the Schema Viewer, this field displays the location of these tables. Note: If you are migrating tables from the Schema Viewer do not change this field. Changing the From field will clear the Schema Viewer.
 | To | Select the location to which you want the selected tables and/or query results migrated. Note: The destination location must exist in order to migrate a table to it. If it does not, you must first create it using a database management tool such as SQLWizard.
Migrate Options | Use Migrate Options to select the reports and files you want Migrate to produce.
 | Execute Migrate | Determines whether or not any data is migrated when you run a migration. When enabled, Migrate performs a normal migration. When disabled, Migrate executes the migration but does not actually copy any data to the specified destination. This lets you obtain an SQL stream without actually migrating any data. Note: If this checkbox is selected, you cannot generate an Impact Analysis Report.
 | Impact Analysis | Select this checkbox to generate a report that provides detailed information about the migration as it is currently specified. This report lets you analyze the effect of a migration without actually executing it. Type the name of the file to which you want the report written in the field next to the checkbox. Note: When this report is selected, Migrate will not create or copy any information. The entire migration, including queries is executed step-by-step, but no tables are created and no data is written.
 | Generate SQL | Select this checkbox if you want to save the SQL that processes your migration. In the field next to the checkbox, type the name of the file to which you want the SQL script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new script.
 | Post Execution Analysis Report | Select this checkbox to generate a listing of the source and destination tables that are part of the migration. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report. You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.
 | Error File | Select this checkbox to record migration errors in a file. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report. You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.
Parent topic: Migrate Utility


The Default Options Dialog Box

The Default Options dialog box is used to assign default migration options for tables and queries.

The Default Options dialog box contains the following controls:

Destination | The options in this group box specify the default destination information for the selected table or query.
Auth ID Enter the AuthID associated with the destination table. Changing this field assigns a new owner to the destination table.

Select the Default To Source checkbox next to this field to indicate that you want to use the source table's Auth ID by default.

Tbl Space Enter the table space name for the destination table.

Select the Default To Source checkbox next to this field to indicate that you want to use the name of the source table space by default.

Database Enter the database name for the destination table.

Select the Default To Source checkbox next to this field to indicate that you want to use the name of the source database by default.

If Table Already Exists | Use the If Table Already Exists group box to specify what Migrate should do if the table you are migrating already exists at its destination.
Abort | Select this option if you want Migrate to terminate the migration if the destination table already exists.
Append Data Select this option if you want Migrate to append the new table to the existing destination table. If the destination table has no primary key, all records are appended to the destination. You can use this option with the No Data option (see below) to migrate just an index.
Note:

You can end up with duplicate records if you use this option on a table without a primary key.
Replace Data | Select this option if you want Migrate to replace all existing records in the destination table with records from the source table. All data in the existing table will be deleted.
Replace Table | Select this option if you want Migrate to drop the destination table and create a new table containing the result of this migration.
Limit Data To Select the number of records you want to copy.
  • Select All Rows to migrate all data records from the source table to the destination.
  • Select No Data to migrate none of the records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature. Or, you might use it to copy certain table attributes without copying any data.

    The behavior of this option depends on the following:

    • If the destination table does not exist, an "empty" table is created.
    • If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).
    • If the destination table exists, and the Append Data option is used, no records are copied to it (you could use this combination of options to copy just an index).
  • Select First N Rows if you only want to migrate the first N records from the source table to the destination.
  • Select Every Nth Row if you want to copy every N records from the source table to the destination.
Commit Work After | Specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). You can specify any number between 0 and 32,767. High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
Migrate

Use the Migrate group box to select the objects you want to migrate with a table.
Primary Key | Select this checkbox if you want primary-key columns in the source table to also be primary-key columns in the destination table.
Unique Keys | Select this checkbox if you want unique-key columns in the source table to also be unique-key columns in the destination table.
Indexes | Select this checkbox if you want the index key in the source table to also be the index key in the destination table.
Foreign Keys | Select this checkbox if you want foreign-key columns in the source table to also be foreign-key columns in the destination table.
Synonyms | Select this checkbox if you want any alternate names for the source table to also be alternate names for the destination table.
Comments | Select this checkbox to migrate comments in the source table to be included on the destination location table.
Privileges | Select this checkbox to migrate privileges. The privileges checkbox lets you place the same security standards on the destination tables as on the source tables.
Distinct Type | Select this checkbox to migrate distinct types used by the source table.
Parent topic: Migrate Utility


The Query Options Dialog Box

The Query Options dialog box is used to specify how you want the results of a query migrated. For example, you can specify what action Migrate should take if the destination table already exists, or how many total records from the result should be copied.

The Query Options dialog box contains the following controls:

Destination | This group box displays the destination information for the selected query.
Auth ID | Enter the AuthID associated with the table produced by the query.
Table | Enter a table name for the table produced by the query.
Tbl Space Enter the table space name for the result of the query.

If a table space name isn't specified, the destination table name is used.
Database Enter the database name for the table produced by the query.

If a database name isn't specified, the default database name "DSNDB04" is used.
If Table Already Exists | Use the If Table Already Exists group box to determine what to do if the there is an existing table with the same name as the table produced by the query.
Abort | Select this option if you want Migrate to terminate the migration if the destination table already exists.
Append Data Select this option if you want Migrate to append the new table to the existing destination table. If the destination table has no primary key, all records are appended to the destination. You can use this option with the No Data option (see below) to migrate just an index.
Note:

You can end up with duplicate records if you use this option on a table without a primary key.
Replace Data | Select this option if you want Migrate to replace all existing records in the destination table with records from the source table. All data in the existing table will be deleted.
Replace Table | Select this option if you want Migrate to drop the destination table and create a new table containing the result of this migration.
Update No Insert | Select this option if you want Migrate to update data only if the row with they key already exists.
Update Insert | Select this option if you want Migrate to update existing data or insert the row if it doesn't already exist.
Delete Match | Select this option if you want Migrate to delete an existing matching row.
Limit Data To Select the number of records you want to copy.
  • Select All Rows if you want to migrate all data records of the query result.
  • Select No Data to migrate none of the records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature. Or, you might use it to copy certain table attributes without copying any data.

    The behavior of this option depends on the following:

    • If the destination table does not exist, an "empty" table is created.
    • If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).
    • If the destination table exists, and the Append Data option is used, no records are copied to it (you could use this combination of options to copy just an index).
  • Select First N Rows if you only want to migrate the first N records from the source table to the destination.
  • Select Every Nth Row if you want to copy every N records from the source table to the destination.
Commit Work After | Specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). You can specify any number between 0 and 32,767. High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
Parent topic: Migrate Utility


The Query Update Rules Dialog Box

The Query Update Rules dialog box appears when you click the Update Rule button from the Query dialog box. It is available only if you chose the Update No Insert or Update Insert options in the Query Options dialog box. Use this window to specify the key field, and to select specific update rules for each field in the selected row.

Parent topic: Migrate Utility


The Control Menu

Each table in the Schema Viewer has a Control menu you can use to set table options, select referenced tables and remove a table from a migration. Click the table's Control-menu button to select these commands.

The Control menu contains the following commands:

Table Options Specifies the table's destination parameters and to define objects you want migrated with the table. You can also use this command to specify how to handle duplicate migrations and how to commit data records.

Each table in a migration has its own distinct set of table options. You can use the Table/Query Defaults command on the Options menu to set default table options for your migration.

The Table Options command performs the same function as the Table/Query Options command on the Object menu.
Migrate Determines whether the table is migrated or not. A check mark next to the Migrate command includes the table in the migration. If you deselect the Migrate command (i.e., remove the check mark), the table remains in the Schema Viewer, but is excluded from the migration.
Show Dependent Automatically migrates any table that references the selected table. When you select this command, Migrate automatically places this table's dependent tables in the Schema Viewer.

This Show Dependent command performs the same function as the Show Dependent command on the Object menu.
Show Referenced Automatically migrates any table that is referenced by this table. When you select this command, Migrate automatically places this table's referenced tables in the Schema Viewer.

This Show Referenced command performs the same function as the Show Referenced command on the Object menu.
Remove Takes the table out of the Schema Viewer. If a table is removed from the Schema Viewer, it is not included in the migration. (Only tables within the Schema Viewer are migrated.)

This Remove command performs the same function as the Remove command on the Object menu.
Parent topic: Migrate Utility


The File Menu

The File menu contains commands for opening new or existing migrate files, (MIG), and other objects, as well as for printing and saving. The Exit command is located under this menu.

The File menu contains the following commands:

New | Opens a new Schema Viewer window. If a Schema Viewer is already open, it is closed before the new one is opened.
Open Displays a dialog box to open existing migration (MIG) files.

When you open a MIG file, the specifications from the file replace the current migrations specifications. If you want to preserve your current specifications, save them using the Save or Save As command before opening a MIG file.
Close | Closes the active window.
Save Saves your current Migrate specifications to the open MIG file. (A MIG file records your table, query and option choices so that you can rerun a migration without having to respecify it manually.)
Note:

You must activate the Schema Viewer to use the Save command. If the Catalog Browser or a Query window is active, the Save command is grayed.

If Migrate specifications have not yet been saved, the Save command displays the Specify Batch File dialog box for you to specify a directory and file name.

Migrate specifications can be saved only after you have completed the Table Options dialog box.
Save As Displays the Save As dialog box to save the current Migrate specifications to a new MIG file. (A MIG file records your table, query and option choices so that you can rerun a migration without having to respecify it manually.)

The Save As command can also be used to save the contents of a Query window to an SQL file. If a Query window is active when you select Save As, you can select *.SQL in the List Files of Type field to save the active query to an SQL script file, or you can select *.MIG to save all migration specifications to a MIG file.

Migrate specifications can be saved only after you have completed the Table Options dialog box.
Execute Batch Runs a migration that has been saved to a MIG file. This command displays the Select Batch File dialog box from which you can select the MIG file you want to run. When you click OK, the migration is immediately executed.

Running a migration with the Execute Batch command does not affect the current migration specifications.

Print Prints the contents of the active window. The contents of the Query window, the SQL window and Migrate report windows (such as an Impact Analysis Report) can be printed. To print a Migrate report, you must first open it using the report commands on the View menu (e.g., the Post Execution Analysis command).

Selecting Print displays a dialog box, letting you specify the pages and number of copies you want to print.
Exit | Exits the program. Before exiting, Migrate prompts you to save any open windows that have changed.
Parent topic: Migrate Utility


The Edit Menu

The Edit menu allows you to cut, copy and paste data to and from the Query window.

The Edit menu contains the following commands:

Cut | Removes statements from the SQL window or the Query window and copies them to the Clipboard.
Copy | Copies statements from the Query window to the Clipboard.
Paste | Pastes statements from the Clipboard into the Query window.
Parent topic: Migrate Utility


The View Menu

The View menu lets you redisplay the Catalog Browser if it has been closed. It also lets you display Migrate reports. Once a migration report is displayed, you can print it by selecting Print on the File menu.

The View menu contains the following commands:

View Browser | Displays the Catalog Browser. You can also use the View Browser * button on the toolbar to invoke this command.
Refresh Browser | Refreshes the contents of the Catalog Browser. You must do this at the end of a migration to display the names of the newly-migrated tables.
Impact Analysis | Displays the Impact Analysis Report. To display a report other than the last one, specify the file using Migrate on the Options menu before you select Impact Analysis. You can review this report online or print it using Print on the File menu.
Post Execution Analysis | Displays the Post Execution Analysis Report generated by the last migration. This report displays an analysis of the migration after you execute a migration. To display a report other than the last one, specify the file using Migrate on the Options menu before you select Post Execution Analysis. You can review this report online or print it using Print on the File menu.
SQL | Opens and views an SQL script file. Once a script is open, you can print it or cut and paste it to a Query window.
Batch Commands | Enables you to view the contents of a MIG file. A MIG file contains complete specifications for running a migration. A MIG file can be recalled using Open on the File menu; it can be executed using Execute Batch on the File menu or by calling it from your system command line.
Error File | Displays the error file generated by the last migration. To display a report other than the last one, specify the file using Migrate on the Optionsmenu before you select Error File. You can review this report online or print it using Print on the File menu.
Parent topic: Migrate Utility


The Object Menu

The Object menu provides different commands for manipulating tables, such as, defining defaults, displaying related tables, and how tables are to be displayed. It is also used to define a query.

The Object menu contains the following commands:

Define Query | Opens a Query window. Using this window, you can define a specific SELECT statement to migrate certain rows or columns of a table or to combine data from different tables into one result.
Table/Query Options | Displays the Table Options or Query Options dialog box (depending on whether a Query window or a table in the Schema Viewer is active). Use this command to set specific options for the selected table or query window. Note: To set default options for all subsequent tables and queries, use Table/Query Defaults on the Options menu.
Show Dependent | Automatically places in the Schema Viewer all tables that are dependent on the selected table. You can also invoke this command from the table's Control-menu * button.
Show Referenced | Automatically places in the Schema Viewer all tables that are referenced by the selected table. You can also invoke this command from the table's Control-menu * button.
Remove | Removes the selected table from the Schema Viewer. You can also invoke this command from the table's Control-menu * button.
Roll Up | Displays tables in the Schema Viewer in abbreviated form. When rolled-up, tables are represented by just a table name. Column information is not shown.
Roll Down | Displays tables in the Schema Viewer in detailed form. When rolled-down, the names of columns are listed with the table.
Arrange | Arranges the tables within the Schema Viewer so that lines of reference can be easily seen.
Parent topic: Migrate Utility


The Commands Menu

The Commands menu allows you to execute a migration or a query.

The Commands menu contains the following commands:

Run | Migrates the selected tables and query results. The Run command is available only when a table in the Schema Viewer is selected. You can also use the Run * button on the toolbar to invoke the Run command.
Run SQL | Executes the SQL in the open Query windows without migrating tables that are in the Schema Viewer. Queries are executed in Query window order. The Run SQL command is available only when a Query window is selected.
Parent topic: Migrate Utility


The Options Menu

The Options menu lets you set default options for migrations.

The Options menu contains the following commands:

Migrate | Displays the Migrate Options dialog box. Use this dialog box to select default migration options. Choices selected on this dialog box will be reflected in the Run dialog box
Table/Query Defaults | Displays the Default Options dialog box. Use this dialog box to set default migrate options. Note: The Table/Query Defaults command does not affect the option settings for tables already in the Schema Viewer and/or queries that are already open. Defaults are applied only to tables and queries that are specified from this point forward.
Parent topic: Migrate Utility


The Help Menu

The Help Menu command provides access to Migrate's online help system.

The Help menu contains the following commands:

Contents | Displays the table of contents for Migrate's online help system.
Search For Help On | Displays the Search dialog box, which lets you search for a specific topic by keyword.
Getting Started | Gives you an overview of Migrate.
How Do I . . .? | Displays a list of procedures for using Migrate.
About Migrate | Displays the program's version and copyright information.
Parent topic: Migrate Utility


The Window Menu

The Window menu is a standard system menu used to arrange and size windows and icons, as well as to switch between the currently open document windows.

The Window menu contains the following commands:

Tile | Arranges all open windows in side-by-side fashion (no windows overlap one another).
Cascade | Arranges all open windows in a layered fashion, leaving their title bars and left borders visible.
Arrange Icons | Aligns icons for all minimized windows along the bottom of the application window.
Parent topic: Migrate Utility


Options Utility

  • The Paths Tab
  • The Format Tab
  • The Multiuser Tab
  • The Browser Tab
  • The Query Tab
  • The Query Run Tab
  • The SQL Tab
  • The Security Tab
  • The Summary Tab
  • The Connect Tab
Parent topic: User Interface Reference


The Paths Tab

The PATHS tab allows you to specify where SQLWizard files and other executable files are to be found or written.

XDB Executables Path | Full path specification for the directory where the executable files are found. The Executables Path, also referred to as the default directory, is the directory in which the system searches when looking for executable files, help files and error files.
Default Application Path | The default path for all application files, such as SQL scripts and files used by the batch modes of various Micro Focus utilities. This path is also the default path in which output files are placed by the various utilities. When you save or open an application file, SQLWizard gives you the opportunity to choose a different directory.
Temporary Path | This is the path where the system writes temporary files, such as temporary query result files. Do not enter the root directory of your hard disk, as this could cause problems.
Overflow Temporary Path | This is the full path specification to an alternative directory where the system can write temporary files. Do not enter the root directory of your hard disk, as this could cause problems.
Parent topic: Options Utility


The Format Tab

The FORMAT tab allows you to specify the formats for dates, times, numeric fields, etc.

Date Format | Used to create a picture of the date display format that is used when displaying or entering date values. Choose an International Standard from the list box. Choose LOCAL to define your own date format. You can also set special month and weekday formats. For more information on defining pictures, see Picture Definitions Overview.
 | Standard | Description | Format
 | USA | IBM USA Standard | mm/dd/yyyy
 | EUR | IBM European Standard | dd.mm.yyyy
 | JIS | Japanese Industrial Standard Christian Era | yyyy-mm-dd
Date Picture | A display of the date format you selected. If you select LOCAL for the DATE FORMAT, you can type your own format in the DATE PICTURE field.
Months | Select a picture of the month portion of the date format.
Weekdays Select a picture of the day-of-week portion of the date format. Three formats are available: WW, WWW and WWWW:
  • The WW format causes a number between 1 and 7 to be displayed. 1 corresponds to Monday, 2 to Tuesday, etc.
  • The WWW format displays a three-character text abbreviation (Mon, Tue, etc.).
  • The WWWW format is a string of up to 9 characters that displays the full day of the week in text (Monday, Tuesday, etc.)

For more information on defining pictures, see Picture Definitions Overview.
Time Format This section allows you to specify the default format for displaying or printing time fields. The format is also used for data entry input.

Because the format you select is used as the default time format for display and input in most Micro Focus applications, it is important to select the time mask with care. In some utilities you can override the default time mask by defining masks or pictures for specific columns.

Select from a list of predefined formats (ISO, USA, EUR and JIS). To edit your own time picture position select LOCAL. The cursor will be positioned so that you can enter your own time format. For rules on defining time formats, see Time Pictures Overview.

The following table shows the available time formats.
Standard | Description | Format
USA | IBM USA Standard | hh:mm AM or PM
EUR | IBM European Standard | hh.mm.ss
JIS | Japanese Industrial Standard Christian Era | hh.mm.ss
Time Picture | A display of the time format you selected. If you select LOCAL for the TIME FORMAT, you can type your own format in the TIME PICTURE field.
Time Zone | Used to define the time zone offset from Greenwich Mean Time; this is the difference between your system clock and Greenwich Mean Time (GMT). The intent of the field is to simplify conversion of a timestamp to GMT. To standardize times in your geographically-distributed databases, select the offset from the Time Zone list box. Enter the number of hours offset (-24 to 24) from GMT.
Timestamp Format | Displays the timestamp format used when storing this information in system tables. You cannot change this format.
Numeric Formats | Use this section to specify the following numeric formats. Because the formats you select are used as the default formats for display and input in most Micro Focus utilities, it is important to select the masks with care.
Money Format | Used to define money display/input format. This function allows you to specify the default format for use when displaying or printing money fields. The format is also be used for input in some data entry utilities. Money values are always stored in XDB Server databases as decimal(15,2), but you can set the default money display and input format using this option. Money pictures should be defined according to the rules for numeric picture. See Numeric Masks Overview.
Decimal Format | Used to define decimal display/input format. Decimal values are stored in databases according to the precision and scale you specify, but you can set the default decimal input and display format using this option. Decimal pictures should be defined according to the rules for numeric picture. See Numeric Masks Overview.
Float Decimal Places | Used to specify the default number of decimal places when displaying or printing float fields. XDB Server provides precision of up to 15 places for all float calculations, comparisons and displays. The default precision is set at 2. If you need more than 15 decimal places, use a decimal format instead of float. Decimals can have up to 31 decimal places.
Parent topic: Options Utility


The Multiuser Tab

The Multiuser tab allows you to specify options relating to the use of a multiuser, XDB Server in a networked environment.

Isolation Level XDB Server provides six levels of isolation so users can control the tradeoff between concurrency and consistency:
  • Concurrency is the ability for multiple transactions to access database resources simultaneously.
  • Consistency is the degree to which changes made by one user have no negative effects on other transactions in a multiuser environment.

Within the maximum degree of consistency and minimum degree of concurrency, the isolation levels are:

Exclusive Use | The entire database is locked for exclusive use of the current transaction.
Repeatable Read | All locks are held until commit point to guarantee that transactions can be done serially.
Cursor Stability | Exclusive (read-write) locks are held until commit, and shared (read-only) locks are released when the next record is accessed.
Lock Current | Only the current record is locked. This level should be used with AUTOCOMMIT ON, or for read-only operations.
Dirty Read | No locks are obtained. Uncommitted record changes are read regardless of locks (other than database locks). A DR transaction is read-only; records cannot be modified.
Snapshot Read | At this level, a snapshot of the data is made at the time of execution. Other users can make changes to the data without waiting for the transaction to complete and the user is ensured that the data will be the same for the life of the transaction. An SR transaction is read-only
Time-out Interval | This is the length of time (in seconds) to wait before retrying, when a lock conflict occurs.
AutoCommit | With AUTOCOMMIT on, an SQL command is committed as soon as it is successfully completed. If AUTOCOMMIT is off, the user needs to explicitly commit transactions by issuing an SQL COMMIT command or by selecting COMMIT from a menu in an application. AUTOCOMMIT is not supported against XDB Link locations.
Backward Logging This option is used only when accessing XDB Server Versions 3.x and 4.x. If using XDB Server Version 5.0 or higher, logging is automatic and this option is ignored.

To perform a rollback operation when using the older XDB Server versions, it is necessary to maintain a log of before images of all changes made to the database during a transaction. This information is stored in a backward log. The backward log contains only the information necessary to roll back the current transaction. Every time a transaction is committed or rolled back, the backward log is erased. When the log is turned off, rollback is not possible, but changes to the database take less time because before images are not written to the log.

For more about backward logging on the older XDB Server versions, see the Backup and Recover chapter of the XDB Server Administration Guide for the XDB Server version you are using.

Parent topic: Options Utility


The Browser Tab

The Browser tab allows you to specify which database objects you want to display on the Catalog Browser window.

Display | Object types that are checked will appear in the Catalog Browser hierarchy. If unchecked, they are not displayed. Instead the next level in the hierarchy is displayed, if appropriate. The default is to display all objects except databases.
Startup Options | These options specify what the catalog browser will do on startup.
 | AutoRefresh | Not used.
 | AutoStartup | If checked, the Catalog Browser is automatically loaded when SQLWizard is started. If not checked, you can access the Catalog Browser from the View menu or toolbar.
Parent topic: Options Utility


The Query Tab

The Query tab allows you to specify default options for working with Queries. These options can be overridden for a particular query when you are editing the query. See also the section titled Query Run Tab.

3 Part Names | If checked, queries are defined using fully qualified table names in the format location.authid.table-name.
2 Part Names | If checked, queries are defined using 2-part table names in the format authid.table-name.
Unqualified Names | If checked, queries are defined using unqualified table names.
Show Table Names | If checked, a row is added to the Query Conditions Grid on the Query Design window to show the table where each column resides. This feature is especially helpful when your query joins two or more tables.
Foreign Keys | If checked, the Query Design window automatically defines joins between the columns of any tables that are involved in a foreign key relationship
Primary Keys with Like Name | If checked, the Query Design window automatically creates a join condition between the primary-key columns in one table and any set of primary-key columns with the same names in another table in the query.
Like Column Names | If checked, the Query Design window automatically creates a join condition between tables in the query that have columns with the same name.
Prohibit Cartesian Products | If marked, returns an error if you try to run a join that does not have a WHERE condition involving the joined tables. This only applies to queries run from the Query Design Window.
Parent topic: Options Utility


The Query Run Tab

The Query Run tab allows you to specify the following options for running queries with SQLWizard. See also Query Tab.

Execute | These options apply to the SQL Edit window and SQL Scripts. They do not affect the running of queries from the Query Design window.
All Commands | Select if you want to run all commands that appear in the current SQL Edit window or SQL script when you begin a run.
First Command | Select if you want to run only the first command in the current SQL Edit window or SQL script when you begin a run.
Current Command | Select if you want to run the currently selected command in the current SQL Edit window when you begin a run.
Edit Options
Allow Editing | Enables the ALLOW EDITING option on for any query you run. The ALLOW EDITING option lets you to enter and change data on the Results window.
Check Unique Key If checked, enables unique-key checking. When this option is set, SQLWizard automatically searches the SYSINDEX and SYSKEYS tables during an edit-mode query, and adds unique key fields to the query, even if the user has not explicitly selected them.

Such action allows SQLWizard to generate the appropriate WHERE clause should the user subsequently choose to update any of the extracted data. On certain databases (e.g., large DB2 3.x locations without a shadow catalog), the search for unique key fields can result in extremely long query times.

If your database has been designed so that a unique key is always selected, this option can be disabled to eliminate the search for unique keys, thereby improving performance.
Read-Only Alert | Enables a pop-up box warning when a query is not editable. Disables the result set "Allow Editing" feature for the SQL Window.
Result Table | If checked, the default view for a Query Result window is the Result Table format. This format displays multiple records in a grid format that looks similar to a spreadsheet.
Result Form | If checked, the default view for a Query Result window is the Result Form. This format displays one record at a time.
NULL= | Select a color from the drop-down list to specify the color you want to use to represent null values. Once you have specified a color, you can toggle the colorization of null values on and off using the Highlight Nulls option on the Query menu when viewing an SQL window, and on the View menu when viewing a Result Table or Result Form window.
Max Records to Retrieve
All | Enable this option if you want to retrieve all rows that meet the criteria of the query and displays them in a Result window.
First n Records | Enable this option if you want to retrieve only the first n rows that meet the criteria of the query and displays them in a Result window. This allows you to limit the amount of data coming back and is very useful when testing a query. If you choose this option, be sure to enter the number of records you want to set as your limit.
For Bit Data Display
Use Hex Format | If checked, columns that are defined as FOR BIT DATA will be displayed in hex in the result set browser. This allows SQLWizard to build a query with a where clause which uses the hex literals of FOR BIT DATA fields to identify the row you would like to delete or update in the result set browser.
No Display | Will suppress the display of empty result sets. If running in interactive mode, a pop-up box will appear notifying you that no rows were retrieved. If running in interactive batch mode (running a batch SQL script from the menu by clicking Run Batch on the File menu) it will prevent the displaying of empty result windows without any warning.
Parent topic: Options Utility


The SQL Tab

This tab provides a means of setting defaults for various SQL operational parameters, including compatibility and sort sequence defaults.

The SQL tab contains the following settings:

SQL Compatibility Mode Used to set the SQL dialect that XDB Server uses. XDB Server permits you to specify which SQL implementation rules are to be enforced. Options are:
  • XDB
  • DB2
  • ANSI

The XDB mode option has extensions not found in DB2 SQL.

If you are running against an XDB Link gateway to access data on a mainframe or other database system, be sure to select the correct SQL Compatibility Mode. When SQL statements do not provide the results you expect, you should always check your SQL mode to make certain it is correct for your application.
Escape Character In many Micro Focus utilities and client applications, you can use an escape character before some special keys to instruct the system to treat the character as a literal. The default escape character is a backward quote ( ` ). You can redefine the key used as the escape character. For example, to insert a question mark into the database from the Data Entry utility (OS/2), you would type `?. You can also use the escape character in front of % or _ if you want these characters interpreted as literals rather than as pattern matching characters.
Note:

In Micro Focus documentation, the key you select for the escape character is referred to as <EscChar>. For example, the default <EscChar> = `
Embedded COBOL

Specify how you want to treat quoting characters around literals and SQL identifiers (such as column names and table names) when using precompiled COBOL with Embedded SQL.

DEFAULT | Behavior of quoting characters is determined by usage.
APOST | Apostrophe characters are used to quote string literals (and quotation marks are used as escape characters for SQL identifiers)
QUOTE | Quotation marks are used to quote string literals (and apostrophe characters are used as escape characters for SQL identifiers)
By default, SQL Option for DB2 tries to determine the behavior of quoting characters (apostrophe or quotation mark) based upon their usage. In the default mode, either an apostrophe or quotation mark can be used as the string delimiter. If the usage of either quoting character is ambiguous, SQL Option for DB2 assumes that the quoting character is used as a string delimiter surrounding a string literal. Ambiguity typically arises when a one-part object name is quoted and used where either object-names or string literals can be present, as shown in the following example:
SELECT D.'IBMREQD', 'IBMREQD' FROM SYSIBM.SYSDUMMY1 AS D;

In this query, SQL Option for DB2 assumes that the first set of apostrophe characters are being used as SQL escape characters and they surround a column name. This assumption is made because of the two-part dot notation. However, the second set of apostrophe characters are assumed to be string delimiters and the second IBMREQD is assumed to be a literal string.

This can lead to problems when one-part names for database objects are quoted and their usage is not explicit in the statement. For instance, a string literal cannot legally be used in the FROM clause of an SQL statement, so quoting characters in the FROM clause are always considered as escape characters surrounding SQL identifiers. However, as both string literals and SQL identifiers can be present in a SELECT clause, the usage can be ambiguous.

To illustrate this, the following query produces three different results in the three different modes:

SELECT 'IBMREQD', "IBMREQD" FROM SYSIBM.SYSDUMMY1

When using the default, the query returns the following:

-----------------
|IBMREQD|IBMREQD|
-----------------

When using APOST, the query returns the following:

-----------------
|IBMREQD|N |
-----------------

When using QUOTE, the query returns the following:

-----------------
|N |IBMREQD|
-----------------
Default Sort Sequence Choose the default sort sequence to use when creating a location.
Note:

After you define a user defined sort sequence and use it for one or more locations, do not re-define it. The locations using the original sort sequence are likely to have index and other problems.

The sort sequence options are as follows. The first three are standard computer sort sequences.
Case Insensitive ASCII | (A=a, B=b, etc.)
ASCII | Standard ASCII sort
EBCDIC Sensitive | Standard EBCDIC sort where null values sort low
User Defined If you select USER DEFINED, you must specify a sort sequence file that is named with the extension .SEQ. This file is used as the sort sequence for any location that is created with a user defined sort sequence.

To operate with a user-defined sort sequence, you must create a sort sequence file (use any ASCII text editor). The file can be up to 256 lines. Each line represents a rank in the sort sequence. On each line, enter an ASCII decimal code or a character, enclosed in double quotes. (See the US ASCII Table for a list of ASCII decimal codes.) If a rank is shared by multiple characters, enter them on the same line, separated by commas.

Below is a partial sort sequence file. In this example, the decimal code 0 (null) appears on line 1, and is the first element in the sort sequence. The letter A appears on line 2, and is therefore assigned rank 2. Because both upper and lower case A appear on the same line, A is not case-sensitive. The same is true of B, C, etc. The letter E was entered using ASCII decimal codes (69='E' and 101='e'). ASCII decimal codes and characters in quotes can be used interchangeably.

  • 0
  • "A","a"
  • "B","b"
  • "C","c"
  • "D","d"
  • 69,101
  • ...

If characters are missing from your sort sequence file, the missing characters will be treated as null by the system. Save the file with the name of your choosing, and the extension .SEQ.
Classic EBCDIC | Standard EBCDIC sort where null values sort high. This mimics the mainframe sort sequence.
Language EBCDIC | Includes French EBCDIC, Spanish EBCDIC, Italian EBCDIC, UK EBCDIC, Danish (Norwegian) EBCDIC, Swedish (Finnish) EBCDIC, German (Austrian) EBCDIC, US (Portuguese, Dutch) EBCDIC, International EBCDIC, and Turkish EBCDIC. Each sort sequence is the same as the corresponding character set, with null values sorting high.
SysAuthID | These items allow SQLWizard to find the system catalog tables that contain the information to be displayed in the Catalog Browser.
SysXDB Specify the AuthID to be used when issuing queries against system catalog tables owned by SYSXDB. Often you will only have privileges on a view on the system catalog tables. Usually the view is created using the same table name, but a different AuthID than the underlying table. When running against XDB-Link to DB2, you will usually use SYSXDB=XDB instead of SYSXDB=SYSXDB.

If the SYSXDB= setting is incorrect and you get the message:

ISQL043: Cannot access SYSIBM tables using AuthID authid.

then you may not have privileges on the catalog tables. SQLWizard provides script files that grant access to the catalog tables. These scripts must be run by a Database Administrator, or by someone who has SYSADM authority. See your Setup Guide for information about these script files.
Parent topic: Options Utility


The Security Tab

The Security tab allows you to set your security options. The CLIENT SECURITY option is important if you want to turn security on for your copy of the XDB Server.

Only if security is on for the XDB Server will password security be fully enforced. The global security options are only available with XDB Server 4.0 or later.

If security is on at the XDB Server you will be accessing, you must check the CLIENT SECURITY check box. If security at the XDB Server is off, you can check or not check this box as desired. Using CLIENT SECURITY when security is not required by the XDB Server will provide password security at your workstation.

Specifies the rules that must be satisfied by your password. The password enforcement levels are:

  • Level 1: Password must be four or more characters.
  • Level 2: Password must be six or more characters and include at least one digit.
  • Level 3: Password must be six or more characters, include at least one digit and must include the two randomly generated characters that appear in the prompt message when the user creates or modifies their password.

The passwords created or modified by users must meet the criteria for the current password enforcement level.

Parent topic: Options Utility


The Summary Tab

The Summary tab presents a scrollable list of all of the configuration settings that are set through the Options window. You cannot make changes to any of the options from the Summary tab, but you can print it for reference.

Parent topic: Options Utility


The Connect Tab

The Connect tab provides options for configuring the connection between a client application (such as SQLWizard or a program that you have developed) and the XDB Server you will be accessing.

Locations | Specify the name of the default location you want to access when a connection is made (click the BROWSE button if you want to select from a list of locations). You will be able to override this selection at run time if the Connect dialog box is displayed (the AUTOCONNECT option is off and/or CLIENT SECURITY, on the Security tab, is on).
AuthID | Specify the AuthID (user name) you want to appear as the default in the Connect dialog box. You will be able to override this at run time if the Connect dialog box is displayed when you start SQLWizard (i.e., the AUTOCONNECT option is off and/or CLIENT SECURITY, on the Security tab, is on). If security is off, the AuthID entered in Options will automatically become your current SQLID and will be used as the AuthID portion of any database objects you create.
AutoConnect | If AUTOCONNECT is on and CLIENT SECURITY, on the Security tab, is off, the Connect dialog box is suppressed. In this case, you connect to the default Server, Location and AuthID that you specified in Options.
AutoLogoff | Check this to have the user automatically logged off from the system when you exit the Options Utility if you have made any changes to your connection specifications.
Communication Protocol | Specify which protocol you want to use to communicate with the XDB Server specified in Server Name. Options are:
 | Local [or Windows(LOCAL)] | (Windows 3.x only) Communicates with a local XDB Server. If you have an XDB Server on the same machine as your client application, you can use this server to communicate with it using the proprietary internal protocol instead of using the network.
 | Win32Local | (Win32 only) Communicates with a local XDB Server. If you have an XDB Server on the same machine as your client application, you can use this server to communicate with it using the proprietary internal protocol instead of using the network.
 | NetBIOS | Communicates across the network to a remote, multiuser XDB Server using the NetBIOS protocol.
 | Names Pipes | Communicates across the network to a remote, multiuser XDB Server using the Named Pipes protocol. (Also may be used to access a local XDB Server that supports local Named Pipes.)
 | TCP/IP | Communicates across the network to an XDB Server or XDB Link using the TCP/IP protocol. If you choose the TCP/IP protocol, enter the server's IP address in the IP Address text box, and the port number on which the server will receive connection requests in the TCP Port text box. The same port number must be specified on the XDB Server and all clients of the XDB Server. Check with your system administrator if you do not know this information.
 | IPX/SPX | Communicates across the network to an XDB Server or XDB Link using the IPX/SPX protocol. Note: You may need to add information to your xdb.ini file to successfully use some of these protocols. See the PROTOCOL= and PROTOCOLMAP= parameters in the [CONNECTION DEFAULTS] section of the xdb.ini file for more information. Check with your network administrator and your XDB Server Administrator to determine which protocols are supported on your network and on your XDB Server.
Client Node Name | This is the name by which your machine is known to the XDB Server. The name should be unique among all machines that are trying to access any XDB Server or XDB Link on your network.
Parent topic: Options Utility


SQL Wizard

  • SQLWizard Menus Overview
  • Keyboard Navigation Overview
  • Completing the Connect Dialog Box
  • Create/Alter/Drop Location Dialog Box
  • Create/Alter/Drop Table Dialog Box
  • Table Options Dialog Box
  • Catalog Browser Tabs
  • Add/Modify User Dialog Box
  • Groups Dialog Box
  • Define Priority Dialog Box
Parent topic: User Interface Reference


SQLWizard Menus Overview

SQLWizard's menu bar also changes as different windows become active. For example, menus displayed when the Query Design window is active are different from the menus displayed when an Import window is active.

There are several menus that are always present and that remain fairly constant. These are:

  • File Menu
  • Edit Menu
  • View Menu
  • Location Menu
  • Table Menu
  • Admin Menu
  • Window Menu
  • Help Menu
  • File Menu
  • Edit Menu
  • View Menu
  • Location Menu
  • Table Menu
  • Admin Menu
  • Window Menu
  • Help Menu
Parent topic: SQL Wizard


File Menu

The File menu provides commands for opening new or existing queries and other objects, as well as for printing and saving. The Exit command is located on this menu.

New | Provides a submenu for opening various types of SQLWizard documents or Windows.
Open | Displays the Open dialog box for opening queries, import and export specifications, and batch SQL scripts and tables.
Save | Saves the contents of the current window. If the object has not yet been named, the Save As dialog box will be displayed.
Save As | Displays the Save As dialog box you use to specify the name of an object to be saved.
Close | Closes the window that is active.
Close All | Closes all windows that are open, including the active window. If any window contains unsaved data or specifications, a prompt is provided to give you the opportunity to save it.
Run Batch | Displays the Run Batch dialog box, asking you to select an SQL file to load and run.
Print | Prints the contents of the current window or prints the associated report for the current window. When you select Print, the following Print dialog box appears, allowing you to specify the number of copies and the pages you want to print. The Setup button will display the Printer Setup dialog box. When you click OK, SQLWizard formats the data in the active window and sends it to your printer or print queue. Status of the print job is shown in a message box, which constantly updates to indicate the page number that is currently being sent.
Output | Transfers the contents of the current window or the associated report for the current window to a file. When you select Output, your system's standard Save As dialog box appears titled as Output File. The Save As dialog boxes for other operating environments are similar. See your operating system documentation for more information.
Printer Setup | Displays your system's Print Setup dialog box, allowing you to select a printer and set printer options. The Print Setup dialog box for other operating environments are similar. See your operating system documentation for more information.
Exit | Exits SQLWizard. If any windows contain data that has not yet been saved, you are prompted to save it.
Parent topic: SQLWizard Menus Overview


Edit Menu

Although it is not available when SQLWizard first starts, the Edit menu is available when working with many of SQLWizard's features. The Edit menu typically provides functions to undo the last changes, cut/copy/paste using the clipboard, and perform other edit functions. This menu changes depending on the window that is active.

Undo | If there are changes to the current field that can be restored to their previous state, click this command to undo them.
Redo | If there are changes to the current field that can be entered again, click this command. (This command only appears on the menu when appropriate to the task at hand.)
Cut | Removes the currently selected text or object and saves it to the clipboard.
Copy | Copies the currently selected text or object to the clipboard.
Paste | Pastes the current clipboard contents at the cursor position. If the data on the clipboard is not compatible, it is not pasted.
Delete | Deletes the selected item or the text at the cursor position.
Other menu items | Depending on what kind of SQLWizard window is active, other commands may appear on this menu, such as the Insert Row and Delete Row commands that are used when using a Result table to do data entry. The 72-column Format command is available when a SQL Edit window is the current window.
Parent topic: SQLWizard Menus Overview


View Menu

The View menu provides access to the Catalog Browser. You also use it to switch between different views of the current window depending on the editing mode you are using. For example, if a Query Design window is active, the View menu provides commands to switch to SQL view.

The three Catalog Browser commands are described here. Specialty View menu commands are described in their respective chapters.

Locations | Brings the Catalog Browser to the front with the Location tab selected so that you can work with locations.
Tables | Brings the Catalog Browser to the front with the Table tab selected so that you can work with tables.
Queries | Brings the Catalog Browser to the front with the Query tab selected so that you can work with queries.
Parent topic: SQLWizard Menus Overview


Location Menu

You use the Location menu to set and manage locations.

Set Location | Displays the Set Location/SQLID dialog box, which allows you to change your current location and SQLID.
Create | Displays the Create Location dialog box, which allows you to define specifications for a new location and create it.
Alter | Displays the Alter Location dialog box, which allows you to change a location's parameters.
Drop | Displays the Drop Location dialog box, which allows you to drop (delete) the specified location and all its tables.
Parent topic: SQLWizard Menus Overview


Table Menu

Use the Table menu to open and manage tables.

Open | Opens a table by selecting all columns and rows from it and displaying it in a Result Table window.
Create | Displays the Create Table dialog box so that you can define and create a new table along with its associated indexes, keys, synonyms, and aliases.
Alter | Allows you to select a table for modification. Once you have selected a table, the Alter Table dialog box is displayed so that you can alter the table's specifications, as well as create, alter, or drop its associated indexes, keys, synonyms, and aliases.
Drop | Allows you to select a table that you want to delete from your database. Once you have selected a table, SQLWizard asks for confirmation before actually performing the drop.
Parent topic: SQLWizard Menus Overview


Admin Menu

Use the Admin menu to create and manage AuthIDs, passwords, groups, and XDB Server priorities.

Change Password | Allows users to change their own passwords and allows a super user to change the passwords of others. You must have the appropriate privileges to change any password other than your own.
Users | Allows you to define, modify, or delete AuthIDs, and assign users to groups. You must be a super user to access this command.
Groups | Allows you to define, modify, or delete user groups. You must be a super user to access this command.
Priorities | Allows you to define, modify, or delete priority definitions to control access to the database and limit XDB Server usage. You must be a super user to access this command.
Parent topic: SQLWizard Menus Overview


Window Menu

The Window menu is a standard system menu used to arrange and size windows and icons, as well as to switch between the currently open document windows.

Tile | Divides the SQLWizard parent window evenly among the currently open child windows, and resizes the child windows to fit in the space allocated.
Cascade | Makes all of the child windows a standard size and displays them one below the other and slightly offset to the right.
Arrange Icons | Evens out the arrangement of any minimized child windows along the bottom of the parent window.
List of Open SQLWizard Windows | A numbered list of open child windows appears at the bottom of the menu. By clicking on the name of a window, you make that window the active window.
Parent topic: SQLWizard Menus Overview


Help Menu

The Help menu provides comprehensive help on the SQLWizard interface as well as an online SQL Reference. SQLWizard makes use of the native help system for your operating environment. If you are not familiar with how Help works in your environment, consult your operating environment documentation or click the How To Use Help command on the SQLWizard Help menu.

Contents | This command displays the contents of the SQLWizard help file.
Search for Help On | (Windows systems only.) Displays the Help Search dialog box to assist you in locating a help topic.
How To Use Help | Accesses a general help file that describes how to use help.
SQL Command Tutor | Opens the SQL Option Help, which contains descriptions and syntax for all SQL commands supported by XDB Server. This online reference can assist you in writing SQL statements. You can use help facilities to copy example code to the SQL Edit window or to your editor.
About SQLWizard | Describes the SQLWizard application.

In addition to the Help menu, you can access help to display information about the current context by:

  • Pressing F1.
  • Clicking the Help button on the toolbar.
  • Clicking a Help button on a dialog box.
Parent topic: SQLWizard Menus Overview


Keyboard Navigation Overview

SQLWizard uses a graphical user interface oriented to mouse usage. However, you can navigate almost all of SQLWizard's windows, dialog boxes and menus using the keyboard.

Menu items can be accessed using the standard keystrokes for your operating environment. For example, in Windows you can hold down Alt while typing the underlined character on the menu you want to use. Many menu commands have keystroke shortcuts, such as Ctrl+O to open a file or Ctrl+S to save a file. These are displayed on the menus.

Navigating within a window or dialog box uses the standard keystrokes for your operating environment. In most cases, you can move from one item to the next on a window or dialog box by pressing Tab. (Use Shift+Tab to tab within a data entry field.)

You can select an item from a drop-down list by tabbing to the list and then pressing Down Arrow. Likewise, to select an item from a group of radio buttons, you can tab to one of the items in the group and press Down Arrow to select it. Use the space bar to press a command button or to change the setting of a checkbox after tabbing to it.

Note:

There are some situations where the customary keystrokes cannot be used, and you will need to use your mouse.

Parent topic: SQL Wizard


Completing the Connect Dialog Box

The Connect dialog box contains four fields: Server, Location, AuthID, and Password.

Server Use this field to specify the name of the XDB Server you wish to access. You can select from any server in the drop-down list. If you don't see the server you want to use, exit SQLWizard and run the Options utility to add the server to your system. For more information about adding servers to SQLWizard, see the Options utility online help.
Location Use this field to specify the location to which you want to connect. You can type a name or click the Browse button to select a name from the Browse dialog box. The Browse dialog box shows all locations known to the selected XDB Server.
Note: Each time you access the Browse Dialog box, the selected XDB Server is checked for the list of all known locations available and you are logged in to the specified XDB Server with the current AuthID and password. If security is on, you must have SELECT privileges on the XDB Server's system location for this feature to operate correctly.

If you do not click the Browse button, the XDB Server is not accessed until you connect.

AuthID Use this field to specify the AuthID you wish to use when logging in. The AuthID is used for access security, object ownership, and determining database privileges.

The default AuthID that appears in this field reflects your AUTHID entry in the Options utility. You can type in a different name if desired.

Note: Your AuthID may be remapped to a SecondaryID by your XDB Server Administrator. If you have a SecondaryID, you will log in using one AuthID and appear to be doing work as another AuthID.
Password The Password field appears only if Security is turned on in the Options utility. Security must be on in the Options utility if you are accessing an XDB Server that is running with security on. If you are accessing an XDB Server that does not require security to be on, you can choose whether to turn security on or off for your own workstation.

The password you enter must be between four and eight characters and must follow the rules for a short identifier. Your password must meet the specifications for the current "password enforcement level" defined for the XDB Server you are accessing.

Parent topic: SQL Wizard


Create/Alter/Drop Location Dialog Box

Use the Create/Alter/Drop Location dialog box to define, change, or delete XDB Server locations. You access the Create/Alter/Drop Location dialog box using the Create, Alter, and Drop commands on the Location menu. Regardless of whether you are creating, altering, or dropping a location, this dialog box is essentiallythe same.

The following describes all fields on the Create/Alter/Drop Location dialog box.
Location A location is a collection of databases, tables, indexes, and related objects organized in a specific structure. An XDB Server can have multiple locations, all managed by the same database server.
Name
Specifies the name of the location. A location name may be up to 16 characters long, and must be unique among all of the locations that reside on a given XDB Server.
Creator
Specifies the AuthID of the person who created the location. The default is to use your current SQLID, but you can change this if you are authorized to use a different SQLID.
Path
Specifies the directory where your location files are stored. When creating a location, if you name a directory that does not exist, SQLWizard creates it for you.
Forward Log If using XDB Server version 4.x and earlier, you must specify the name of the file used for forward logging. In XDB Server version 5 and later, this file is automatically created by the system, however you can specify the directory to which it is stored.
Name
Specifies the name of the file that will be used as the Forward Log. SQLWizard uses up to eight characters of the location name as a default forward log file name. You can change it if desired.
Path
Specifies the directory in which the Forward Log will be stored (under XDB Server version 5 and later; the Backward Log is placed in this directory too). SQLWizard uses the location path as the default, but if possible, it is best to use a different physical drive for the Forward Log. Keeping the Forward Log on a different drive will enable you to restore your database in the event of a disk failure on the drive containing your location and database files.
Sort Sequence SQLWizard allows you to specify the sort sequence to be used for ordering and comparing data on a per location basis. Select one of these sort sequences from the drop-down list:
  • Case Insensitive ASCII
  • ASCII
  • EBCDIC Sensitive
  • User Defined
  • Classic EBCDIC
  • Language EBCDIC
Remarks | Type any comments about the location in this field. Comments can be up to 30 characters.
SQL | Click this to examine the SQL statements represented by the entries you have made.
Parent topic: SQL Wizard


Create/Alter/Drop Table Dialog Box

Through the Create/Alter/Drop Table dialog box, SQLWizard provides an interactive means of creating, altering, and dropping tables. In addition to allowing changes to a table's column definition, the Create Table and Alter Table dialog boxes let you add or change an existing table's indexes, primary keys, foreign keys, synonyms, and aliases.

The following describes all fields on the Create/Alter/Drop Table dialog box.

Table Name | Specifies a table name using a three-part, two-part, or unqualified table name, as appropriate. If you are altering or dropping a table, you can choose the table name from the Catalog Browser dialog box or the Open Table dialog box when you first access the Alter/Drop Table dialog box.
Comments | Describes the table. The comment is stored in the Remarks column in the SYSIBM.SYSTABLES table.
Indexes and Keys | Contains a list of the current or pending indexes on the table. You can choose one of the buttons to create, alter, or drop an index or key.
Relationships | Contains a list of current foreign keys on this table. You can choose one of the buttons to create, alter, or drop a foreign key.
OK button | Accepts all table definition information as shown on the Create/Alter Table dialog box and executes the SQL commands to effect them. On the Drop Table dialog box, the OK button executes the SQL command to drop the table and all its related files and database objects.
Cancel Button | Discards all entries or changes that may have been made on the Create/Alter/Drop dialog box.
Options Button | Accesses the Table Options dialog box where you can define synonyms and aliases, as well as other important options for your table specification.
SQL Button | Opens the Show SQL window to display the pending SQL command(s). Information shown on the Create/Alter/Drop Table dialog box are used by SQLWizard to generate the SQL command(s).
Field (Column) Definitions The grid at the bottom of the Create/Alter/Drop Table dialog box is used to define the columns in your table. Except for the field name, you can either use the default values provided, or change the fields as described below.
Fld. No.
Shows the number of the table row.
Primary Key
The key icon indicates whether the column is part of a primary key. A primary key is used to uniquely identify the rows in a table. Once you have defined a primary key for the table, a key icon appears next to the column.
Field (Column) Name
Identifies each column in a table, view, or result. A column name can be up to 18 characters and must satisfy the rules for a long identifier.
Data Type
Defines the kind or type of data a column may hold. The following lists all available data types:
  • Char
  • Char for bit data
  • Long Varchar
  • Graphic
  • Long Vargraphic
  • Varchar
  • Varchar for bit data
  • Long Varchar for bit data
  • Vargraphic
  • Rowid
  • Time
  • Date
  • Integer
  • Float
  • Float (4)
  • Decimal
  • Money
  • Timestamp
Length
For data types with flexible lengths, type a field length to replace the default field length. If the data type does not have a flexible length, the field length is automatically filled in for you and the field is disabled.
Note: The length shown for some data types is the physical number of bytes used to store the data, rather than a limit on the number of digits or characters in the field. For example, even though the length of a smallint field is shown as 2, a smallint field can contain values between + and - 32767.
Not Null
Allows you to specify whether or not Null values are allowed in the column. Click the down-arrow button to display a drop-down list of options. You may also choose from the list by typing the first character of the option.
False
The column can be null.
True
The column cannot be null. It must contain data.
w/ Default
If the field is null, SQLWizard inserts a default.
Unique
For NOT NULL UNIQUE, used by DB2. If a column is defined as NOT NULL UNIQUE, DB2 allows at most one record to contain a null value.
Comments
Optional. Shows text up to 254 characters for each column in the table. These comments appear in the Catalog Browser dialog box when the Details option is checked.
Parent topic: SQL Wizard


Table Options Dialog Box

When you create or alter a table, the Table Options dialog box allows you to create, alter, or drop synonyms and aliases related to the table and specify DB2-related options (including the database and table space the table resides in, edit and validation procedures, and audit, data capture, and OBID options). These DB2-related options are provided for those who transfer data between XDB Server and mainframe DB2. For more information on these items, consult your DB2 documentation.

Database/Tablespace
Provides options for organizing your tables and indexes.
Database (In Database clause) An XDB Server database is a collection of tables, indexes, and table spaces. Each database definition occupies a separate directory. A database can consist of a number of files that span several directories. If you use stogroups, it can also span several disks.
Note: The database and/or stogroup must exist before you create the table. To create a database or stogroup, open an SQL Edit window and issue a CREATE DATABASE or CREATE STOGROUP command as explained in the SQL Reference.

Database names are stored in the system catalog table SYSIBM.SYSDATABASE. Every location contains a default database (DSNDB04) for user-defined tables and two XDB Server catalog databases (DSNDB06 and DSNDB07). Also, a location may include any number of additional user-defined databases. The SYSTEM location includes two additional databases: XDBACF, which stores information on security and access, and DSNDDF, which stores information on other locations.

Tablespace (In Tablespace clause) A table space is a physical area of disk space that holds a table. The table space object provides compatibility with DB2, and is optional in XDB Server. By default, XDB Server assumes a table space name that is the same as the table name, and each table is stored in its own table space.
Note: The table space must exist before you create the table. To create a table space, open an SQL Edit window and issue a CREATE TABLESPACE command as explained in the SQL Reference.

In DB2, table spaces and stogroups provide a means of organizing tables and indexes on specific disk storage devices. Generally, you associate each table space and index with a stogroup. You create a table within a specific table space. When you create an index, you can associate it with a stogroup.

Audit
Identifies the types of table access that causes auditing. Audit options are provided for mainframe DB2 compatibility. The options are:
None | Default.
Changes | The table is audited during the first insert, update, or delete operation by each unit of work.
All | The table is audited when the table is accessed during the first operation of any kind by each unit of work. The appropriate audit-trace class must be active and audit is not done when the table is accessed by COPY, RECOVER, REPAIR, or a stand-alone utility.
Procedures
Allows you to enter two kinds of procedures. These procedures are provided for mainframe DB2 compatibility.
Edit Proc | Names an edit routine for the table that is provided by the current server's site. Default is none.
Valid Proc | Names a validation exit routine for the table. Default is none.
OBID
Names the table's internal descriptor within the XDB Server SYSTEM catalog. The OBID option is used with ROSHARE databases.
Data Capture
Specifies if the log records for SQL INSERT, UPDATE, and DELETE commands can contain additional information. This option is provided for mainframe DB2 compatibility.
None | Do not record additional information to the log.
Changes | Write additional data about SQL updates to the log.
Global Temp. Table
Allows you to create the table as a global temporary table.
Synonyms and Aliases
Allows you to create, alter, or drop synonyms and aliases for the table. Altering an alias or a synonym is used only when you wish to remove a dropped status.
Parent topic: SQL Wizard


Catalog Browser Tabs

There are three tabs arranged along the left side of the Catalog Browser dialog box. Use these tabs to switch between different hierarchical views of the system catalog. Each view provides a different set of buttons on the right side of the Catalog Browser dialog box.

Location Tab | Shows information about known locations, and provides access to location management commands.
Locaton button
Table Tab | Shows information about tables and related objects such as databases, indexes, keys, and columns. Also provides access to table management commands.
Table button
Query Tab | Shows information about queries and SQL statements stored in the system catalog tables, and accessible by the current server.
SQL Query button
  • Location Tab Buttons
  • Table Tab
  • Query Tab Buttons
  • Object Icons
  • Expanding and Collapsing the Hierarchy
  • Query Window
  • Result Window
  • Import Window
  • Export Window
  • Target File Information
  • Source Table Information (Design Mode)
  • Source Table Information (SQL Mode)
  • Export Options Dialog Box
Parent topic: SQL Wizard


Location Tab Buttons

The following are the buttons available for the Location view of the Catalog Browser.

Create | The Create button displays the Create Location dialog box.
Alter | The Alter button displays the Alter Location dialog box for the currently selected location.
Drop | The Drop button displays the Drop Location dialog box for the currently selected location.
Set | The Set button displays the Set Location dialog box, allowing you to select a new current location and/or SQLID. This button is available only if a location name is highlighted (selected) on the list of locations. Locations that can be selected in this manner apply only to the server to which you are currently connected. Note: To connect to a location managed by another XDB Server (including XDB Link), use the Set Location command on the Location menu.
Refresh | The Refresh button queries the system catalog to find out current details for all locations. Click this button after you or someone else has made changes to objects, such as inserting, altering, or dropping locations, tables, indexes, queries, etc.
Detail | The Detail checkbox indicates if comments on the locations should be shown to the right of each location name. If checked, comments are displayed. To add comments to a location, use the Alter Location dialog box, and type a remark. Click the OK button to confirm the Alter command. When you return to the Catalog Browser, click the Refresh button to view the changes.
Parent topic: Catalog Browser Tabs


Table Tab

The following buttons are available from the Table view of the Catalog Browser.

Create Create button | The Create button displays the Create Table dialog box, allowing you to specify parameters for a new table in the current location.
Alter Alter button | The Alter button displays the Alter Table dialog box to let you change the currently selected table.
Drop Drop button | The Drop button displays the Drop Table dialog box for the currently selected table.
Open Open button | The Open button displays the contents (data) of the selected table in a Result window. Clicking Open is the same as executing the SQL command: SELECT * FROM tablename FOR FETCH ONLY
Refresh Refresh button | The Refresh button queries the system catalog to find out current details for all tables and related objects. Click this button after you or someone else has made changes to objects, such as inserting, altering, or dropping locations, tables, indexes, queries, etc.
Filter Filter button | The Filter button enables you to specify filters to control the databases, AuthIDs and table items that are displayed in the Catalog Browser for any particular location.
Detail Detail button | The Detail checkbox indicates whether comments on the tables, columns, or other objects should be shown to the right of the object name. If checked, comments are displayed. At the column level, the column definition, including data type, is also displayed. You may have to increase the width of the Catalog Browser to see all of the information for each object.
Parent topic: Catalog Browser Tabs


Query Tab Buttons

The following buttons are available from the Query view of the Catalog Browser.

New New button | The New button opens a new Query Design window, and prompts you to select tables for your query.
Batch | The Batch button executes the highlighted query in batch mode. If the Quiet option is on, the query runs in the background. If the Quiet option is off, the query is displayed in an SQL Edit window as it runs; each step is highlighted to show progress as the query executes. To set the Quiet option on or off, you must run the query using the Run Batch command from the File menu.
Delete Delete button | The Delete button deletes a highlighted query from the system catalog. After deleting a query, you need to click the Refresh button to see the updated list of queries.
Open Open button | The Open button displays the highlighted query for further modification or execution. If the query was saved as a Prompted Query, it is opened in a Query Design window; otherwise, it is opened in an SQL Edit window.
Refresh Refresh button | The Refresh button runs a query on the system catalog to find out current details on all objects. Click this button after you or someone else has made changes to objects, such as inserting, altering, or dropping tables, indexes, queries, etc.
Detail Detail button | The Detail checkbox indicates whether comments on the queries or SQL statements should be shown to the right of the query name. If checked, comments are displayed. You may have to increase the width of the Catalog Browser to see all of the information for each object.
Parent topic: Catalog Browser Tabs


Object Icons

The object icons are displayed next to the name of each object in the Catalog Browser dialog box to help you visually interpret the levels of the hierarchy. Some appear when any tab (Location, Table or Query) is selected and some appear only under one tab. You can configure which levels appear in the hierarchy using the Browser tab of the Options utility.

Parent topic: Catalog Browser Tabs


Expanding and Collapsing the Hierarchy

The Expand and Collapse buttons appear to the left of the object icons to indicate if an item's subordinate objects are hidden or displayed.

Expand | The Expand button indicates that the item may have sub-items beneath it that are not currently visible. Click the button to open the item and display the sub-items. When you expand the levels, you may need to drag the border of the Catalog Browser dialog box to make it wide enough to read all of the information as shown below.
Collapse | The Collapse button indicates that the item has been expanded, and that the sub-items are currently visible in the hierarchy. Click this button to collapse the hierarchy and hide the sub-items.
Note:

If an Expand button disappears when you click it and there is no replacement Collapse button, then there are no objects in that list.

Parent topic: Catalog Browser Tabs


Query Window

  • Query Window Menus Overview
  • Query Toolbar
Parent topic: Catalog Browser Tabs


Query Window Menus Overview

When a Query Design window or the SQL Edit window is active, the Query menu and Column menu are displayed. Depending on which of these windows is active, certain items may be disabled.

In addition to the Query and Column menus, other menus (such as File menu and Edit menu) are available for use when working with queries.

Note: The Column menu that appears when working on a Query is different from the Column menu that appears when viewing a Query Result window.
  • File Menu
  • Edit Menu
  • View Menu
  • Query Menu
  • Column Menu
Parent topic: Query Window


File Menu

The File menu provides options for opening new or existing queries and other objects, as well as for printing and saving. File menu commands relating to your work with writing queries are listed below.

New |  | Creates a new query. Clicking the New command displays a cascading submenu from which you can select:
 | Query | Opens the Add Table dialog box, allowing you to select tables for your query and place them in a new Query Design window. From this window, you can specify parameters for your query and then run the query.
 | SQL | Opens a new SQL Edit window where you can type your own SQL command statement, save it as a batch SQL script file, and then run it in batch mode.
Open |  | Opens a previously saved query or batch SQL script file. Optionally, use the Catalog Browser dialog box to open an existing query.
Run Batch |  | Allows you to choose a previously saved batch SQL script file and run it in batch mode.
Parent topic: Query Window Menus Overview


Edit Menu

The Edit menu provides basic editing commands such as Undo, Cut, Copy, and Paste. The Edit menu also provides commands that are specifically for use with the Query Design window.

Insert Row | Inserts a row into the Query Conditions Grid so you can enter additional search conditions.
Delete Row | Deletes the current row from the Query Conditions Grid.

The Edit menu also provides a command that is used only with the SQL Edit window.

72-column Format When this option is selected, SQL statements are allowed to span multiple lines of 72 characters as in IBM mainframe utilities.
Parent topic: Query Window Menus Overview


View Menu

The View menu allows you to access the Catalog Browser dialog box or switch the views of the current query window between Query Design mode and SQL Edit mode.

Design | If checked, shows the current query in the Query Design window, instead of in an SQL Edit window.
SQL | If checked, shows the current query in the SQL Edit window, instead of in a Query Design window.
Arrange Tables | Rearranges the Column Selection Lists in the Table Display Area in a uniform fashion.
Parent topic: Query Window Menus Overview


Query Menu

The Query menu provides options for running and designing queries. This menu is available only if a Query Design window or an SQL Edit window is the currently active window.

Run | Executes the statement or statements in the current Query Design or SQL Edit window. If the window contains a SELECT statement, a Query Result window is displayed. If it contains non-SELECT statements, these are executed, and the execution status is shown in the status bar at the bottom of the window.
Step Mode | If checked, steps through one SQL command at a time when there are multiple commands. This command is enabled only if the Execute All Commands option is in effect. See the Query Run tab in the Options utility online help.
Add Table | Displays the Add Table dialog box so that you can add a table to the current Table Display Area of the Query Design window.
Delete Table | Deletes the currently selected table from the Query Design window, thus removing it from the query.
And... | Displays a dialog box so that you can specify an extended WHERE condition or nested query.
Sort... | Displays the Order By dialog box so that you can specify the columns on which the result is to be sorted.
Group... | Displays the Group By dialog box so that you can specify the GROUP BY clause used to create a summary result.
Having... | Displays the Having dialog box so that you can specify search conditions that summary rows must satisfy.
Show Table Names | If checked, adds a row to the Query Conditions Grid. This row displays the name of the table from which each column comes.
Parameters | Displays the Parameters dialog box, so that you can supply values for the host variables in an SQL statement. You can fill this out before running your query, or just run the query and let the system prompt you to supply values for the parameters. Note: The values entered in the Parameters dialog box are saved for use each time you run commands from this window. Use this PARAMETERS command if you want to make changes to the values.
Auto Join | Displays the Auto Join submenu. A checked option causes the system to generate an automatic join condition.
Result Table View | If checked, opens the Result window in the multi-record Result Table view when a query is run.
Result Form View | If checked, opens the Result window in the single-record Result Form view when a query is run.
Highlight Nulls | Check this to enable the highlighting of null values in the color selected in the Options utility. When checked, the highlighting differentiates null values from spaces.
Allow Editing | If checked, attempts to open the Result window directly into Edit mode when a query is run. There is some additional overhead in doing this, so the default is to not go directly to Edit mode.
AutoCommit | If checked, sets AUTOCOMMIT on when a Result window switches to Edit mode.
Show Positive SQL Code | Check this to set SQL Wizard to display a warning message when the server returns either a positive or a negative SQL return code. When unchecked, SQL Wizard displays warnings for negative return codes only.
Current Query Options | Displays the Query Options dialog box for the current query. From this dialog box, you can set query design and query run options, such as the maximum number of rows to retrieve.
Parent topic: Query Window Menus Overview


Column Menu

The options found in the Column menu are applied to the currently selected column (or columns) of the Query Conditions Grid on the Query Design window. To select a column, double click the column name displayed in the Query Conditions Grid.

Note:

The Column menu that appears when working on a Query is different from the Column menu that appears when viewing a Query Result window.

Create Computed Column | Displays the Create Computed Column dialog box, so that you can define a column based on an expression.
Hide Column | Sets the currently selected column to hidden mode, so that it will not be included in the SELECT clause of the query. If a column is hidden before you run the query, you will not be able to select it from the hidden column list in the Query Result window.
Select Hidden Column | Displays the Select Hidden Column dialog box, and lets you move columns between a list of hidden columns and a list of displayed columns.
Sort Column | Displays the Sort Column submenu. When you pick either ascending or descending order from the submenu, the currently selected columns will be added to the Order By clause with the appropriate sequence.
Function | Displays the Function submenu. When you pick a function, the current column is converted into a computed column by using it as an argument for the function. Since the functions are all aggregate functions, the computed columns defined will retrieve summary rows. For the current column you can:
Delete Column | Deletes the currently selected column(s) from the Query Conditions Grid.
Parent topic: Query Window Menus Overview


Query Toolbar

When a query window is the active window, the query toolbar is displayed, as shown below. Depending on whether you are in the Query Design window or the SQL Edit window, certain buttons may be disabled.

Figure 1. *
Query toolbar showing all icons and their names
Parent topic: Query Window


Result Window

  • Result Window Menus Overview
  • Directional Commands and Buttons
  • Goto Command
  • Scroll Bars
  • Cut
  • Copy
  • Paste
Parent topic: Catalog Browser Tabs


Result Window Menus Overview

When a Result window is active, the Result window menu bar is displayed. Depending on whether you are in Result Table view or Result Form view, certain items may be disabled.

Also, some commands (such as Data Entry) are available only if Edit mode is active.

The primary menus used for working with a Result window are:

  • File menu (for printing and saving)
  • Record menu
  • Column menu
  • View menu (for switching between Result Table and Result Form)
  • File Menu
  • Edit Menu
  • View Menu
  • Record Menu
  • Column Menu (Result Table View Only)
Parent topic: Result Window


File Menu

The File menu provides commands for opening new or existing queries and other objects, as well as for printing and saving. File menu commands relating to your use of a query result are listed below:

  • Save
  • Save As
  • Close
  • Print
  • Output
  • Printer Setup
  • Exit
Parent topic: Result Window Menus Overview


Edit Menu

The Edit menu provides functions to undo the last changes, to cut/copy/paste using the clipboard, and to perform other edit functions. Information about using these commands with a Result window are described below.

Undo | If there are changes to the current field that can be undone, click this command to undo them. This command is available only if Allow Editing is on. To reverse the last change (insert, update, or delete) to a record, use the Undo Record command from the Record menu.
Redo | If there are changes to the current field that can be redone, click this command to redo them. This command is available only if Allow Editing is on.
Cut | Moves the currently selected text or object to the clipboard. This command is available only if Allow Editing is on.
Copy | Copies the currently selected text or object to the clipboard. This command is available only if Allow Editing is on.
Paste | Pastes the current clipboard contents at the cursor location. If the clipboard contents is not compatible, it is not pasted. This command is available only if Allow Editing is on.
Delete | Deletes the currently selected text or object. This command is available only if Allow Editing is on.
Parent topic: Result Window Menus Overview


View Menu

The View menu allows you to access the Catalog Browser dialog box, switch the view of the active Result window between Result Table view and Result Form view, and view or edit text for a particular field in a zoom window.

The following View menu commands are applicable to your use of a Result window.

Result Table | If checked, the active Result window is shown in Result Table view. Multiple records are shown in a spreadsheet-like format.
Result Form | If checked, the active Result window is shown in Result Form view. One record is shown at a time, with fields arranged vertically down the screen.
Highlight Nulls | Check this to enable the highlighting of null values in the color selected in the Options utility. When checked, the highlighting differentiates null values from spaces.
Zoom | Displays a window containing the contents of the result field on which the cursor is positioned. This supplemental window is useful for reading or editing data in large character fields where data may be spread over several lines or paragraphs. You can open a Zoom window by clicking on the Zoom command from the View menu, or by double clicking on the desired field in the Result window display.
Parent topic: Result Window Menus Overview


Record Menu

The Record menu provides commands for moving among records, updating records, and performing other data entry functions. Most of these commands require that you have the Allow Editing command checked. The Record menu is available only when a Result window is the active window.

Update | Explicitly writes the current record's changes to the database. If Autocommit is on, you do not need to click Update; simply moving your cursor to another record or closing the Result window will automatically update the record your cursor was on. The Update command is enabled only if there have been changes to the field(s) of the current record since it was last read from the database. The Allow Editing command must be checked for this command to be enabled.
Delete | Deletes the current record from the database. The Allow Editing command must be checked for this command to be enabled.
Undo Removes the changes made to the record that the cursor is on by re-reading the record from the table. The Undo command is available only if you have made changes to the fields of the current record since you last read it, and you have not moved to another record.

If the last undo-able action is a delete, this command changes to Undo Delete, and choosing it will undelete (restore) the deleted record.

Append Duplicate | Appends a copy of the selected record to the end of a result table when Allow Editing is enabled. If there is a unique index on any of the fields in the record you are appending, you must change the values in these fields before moving from the appended row.
Data Entry | Switches to Data Entry view of the Result window, in which only newly inserted records are displayed. Initially, you see only a blank record into which you enter data for a new record. As you enter the data for each record and move to the next record, the new record is inserted into the database. Enabled only if the Allow Editing command is checked.
Show All Records | Switches from Data Entry view (which only shows newly inserted records) to a regular view that shows all records in the result.
Moving and Scrolling Commands | When using any of the following moving and scrolling commands, SQLWizard updates the current record before moving the cursor and redisplaying the requested records. The directional arrow buttons on the toolbar perform the same functions as these commands.
First

Moves the cursor to the first record of the entire set of results records.
Previous Page

Previous Page button

Moves the cursor and displays the results of the previous page of records. This command is only visible in Result Table view.
Previous

Moves the cursor to the previous record. In Result Table view, SQLWizard scrolls the display if the previous record is not completely visible.
Next

Moves the cursor to the next record. In Result Table view, SQLWizard scrolls the display if the next record is not completely visible.
Next Page

Next Page button

Moves the cursor and changes the results display to the next page of records. Next Page is available only in Result Table view.
Last

Moves the cursor to the last record of the entire set of results records. In Result Table view SQLWizard scrolls the table if the last record is not completely visible.
New

Moves to the end of the result set and displays a blank record where you can enter data. Only available if Allow Editing is checked.
Note:

If your result is very large (has many records), the New command will have a negative performance impact because the system must seek to the end of the result set before the data entry can occur. If you want to insert a record without seeking to the end of the result set, switch to Data Entry mode using the Data Entry command on the Record menu.

Goto Click the Goto command to display the Goto Record dialog box. Type the number of the record to which you want to move and click OK. This is particularly useful for very large tables.

If you enter a record number higher than the highest in the table, the last record in the table is displayed.

Refresh Redisplays the current Results table by re-running your original query. The cursor moves to the first record.

If you have changed any fields of the current record, SQLWizard updates that record before refreshing the display. If you made changes to the table which you have not committed (if running with Autocommit off), SQLWizard prompts you to commit changes before refreshing the table.

Commit | Makes all the changes in your current transaction, as well as the current record, permanent, as it saves them to the disk. Commit is not available if you checked Autocommit.
Rollback Rollback is like an Undo. If the Rollback command is active (and the Backward Log is turned on through the Options utility), you can click Rollback to return your data to the condition of the last commit.

Rollback is not available if you checked Autocommit on the Record menu because when Autocommit is on, XDB Server automatically commits each record as you complete it.

See Transaction Processing for more information about the Commit, Rollback, and Autocommit concepts,.

Autocommit When you check Autocommit, changes are saved to each record as soon as you move your cursor to another record. When Autocommit is off, you must explicitly commit changes to the table. You may be able to rollback changes since the last commit; see Rollback command above.

When you click Autocommit on, SQLWizard automatically commits any changes to fields that you have not already committed.

SQLWizard lets you set a default initial setting for Autocommit on the Query Run tab of the Options utility. The status of Autocommit on the Record menu always over-rides the default in the Options utility.

Count

Refreshes the data in the status bar at the bottom of the SQLWizard window, to reflect the current count of records in the result, and the record number where the cursor is currently located.

Sort Displays the Order By dialog box allowing you to sort the records in the result. You can sort the result by one or more columns.

To select a column to sort by, double click its name to move it to the Sorted Columns list. To deselect a column, double click its name to move it to the Unsorted Columns list. You can select one or more columns for your sort.

To indicate if the sort should be ascending or descending for each column, click the Arrow-Toggle button next to each name in the Sorted Columns list.

If sorting by more than one column, you can define your sort priority by re-arranging the items in the Sorted Columns list. To move a column name up or down the list, click to highlight the column name, then click the up or down arrow buttons to the right of the Sorted Columns list to reposition the column name.

Allow Editing If you select Allow Editing, the system attempts to reopen the Result window in Edit mode so that you can update, delete, and insert records. When editing is allowed, SQLWizard displays a check mark next to Allow Editing. You will not be able to check Allow Editing if the query does not support updates, as would be the case if you run a join query.

When you check the Allow Editing command, the following edit commands become available on the Record menu: Update, Delete, Undo, New, Data Entry, Commit, Rollback, and Autocommit. Other requirements may restrict the availability of these features.

If you uncheck Allow Editing, you cannot make changes to the records. SQLWizard disables editing commands on the Record menu.

Note:

When running against a non-XDB Server data source such as mainframe DB2, you will not be able to edit a result table unless the result includes a unique index (or primary key), or unless the Check Unique Key option is disabled.

Parent topic: Result Window Menus Overview


Column Menu (Result Table View Only)

The Column menu provides commands for controlling how you view data in a Result window. Most of the commands in the Column menu are applied to the currently selected column(s).

To select a column, double click the column name displayed across the top row of the Result window. The Column menu is available only when a Result window is the active window.

Fix Locks the selected column(s) against the left margin of the Result table grid. When you scroll horizontally, other columns scroll past but the fixed column(s) remain in view. This lets you keep one or more identifying columns visible as you look at the information to the right of the spreadsheet grid.
Free Unlocks fixed columns. This command is available only if you select (double click) one or more fixed columns.

Another way to free a fixed column is to drag it to the right, dropping a it one or more columns away from the left fixed boundary of the table. You can monitor this by watching the left arrow on the horizontal scroll bar, as it relocates when you free the fixed fields.
Hide Removes the selected columns from the Result table display. You can hide as many columns as you want, individually or as a group. To redisplay a column, use the Select Hidden command.
Note:

Hiding a column only affects your viewing of the result display. It does not affect the table, where all columns and data remain intact.
Select Hidden Displays the Select Hidden Columns dialog box, allowing you to select which columns should be displayed or hidden. This dialog box displays two lists Hidden Columns and Displayed Columns.

You can move columns between the lists in either of two ways:

  • Click a column name to highlight it. Then clicking on an arrow button to move it to the other list.
  • Double click a column name to move it to the other list.

When you click OK, SQLWizard rearranges the result display to reflect the new set of hidden and displayed columns
Parent topic: Result Window Menus Overview


Directional Commands and Buttons

In the Record menu you will find commands to go to the First, Previous Page, Previous Record, Next Record, Next Page, and Last rows of a result. These menu commands correspond to the directional arrow buttons you see in the toolbar when a Result window is active.

Figure 1. *
Result Window button
Parent topic: Result Window


Goto Command

There is a Goto command in the Record menu which allows you to move directly to a specific row of the result without having to scroll.

Parent topic: Result Window


Scroll Bars

You can use the scroll bars to quickly move through a Result window. The behavior of the scroll bars depends on the result view. The Result Table view shows many records at once and Result Form view shows a single record at a time.

To view additional columns in a record:

  • If you are in Result Table view, use the horizontal scroll bar to scroll through the columns in your result.
  • If you are in Result Form view, use the vertical scroll bar to move through all of the fields in a record.

To view other records:

  • If you are in Result Table view, use the vertical scroll bar to move through the rows of your result.
  • If you are in Result Form view, use the toolbar buttons or Record menu items to move from one record of the result to the next.
Parent topic: Result Window


Cut

Cut Text button
Deletes the highlighted text from Result window and holds it on the clipboard for a future paste. You can also use the appropriate keystroke for cut in your operating environment. For example, in Microsoft Windows you can use Ctrl+X to cut data to the clipboard.

Parent topic: Result Window


Copy

Copy Text button
Copies the highlighted text from Result window and holds it on the clipboard for a future paste. You can also use the appropriate keystroke for cut in your operating environment. For example, in Microsoft Windows you can use Ctrl+C to copy data to the clipboard.

Parent topic: Result Window


Paste

Paste button
Pastes the clipboard text to the field that the cursor is on in a Result window. You can also use the appropriate keystroke for cut in your operating environment. For example, in Microsoft Windows you can use Ctrl+V to paste data from the clipboard.

Note:

If the pasted data contains more characters than are allowed by the size of the column you are pasting into, the data is truncated.

Parent topic: Result Window


Import Window

  • Import Window Menus Overview
  • Import Window Toolbar
Parent topic: Catalog Browser Tabs


Import Window Menus Overview

Once you open an Import window, you can use the File, View, and Import menus to work with your import specifications and batch commands. The primary menus used for working with an Import window are:

  • File Menu
  • View Menu
  • Import Menu
  • File Menu
  • View Menu
  • Import Menu
Parent topic: Import Window


File Menu

The File menu provides commands for opening an Import window, for saving and retrieving import specifications, and for running Batch Import files. File menu commands relating to your use of an Import specification are provided below.

New | Opens a new Import window where you can enter specifications for importing data.
Open | Presents the Open dialog box, allowing you to retrieve previously saved SQLWizard import specifications into an Import window.
Run Batch | Presents the Run Batch dialog box, allowing you to run a previously saved SQLWizard Batch Import (*.imp) file.
Parent topic: Import Window Menus Overview


View Menu

In addition to the standard View menu commands, the following commands become available when an Import window is active:

Source File | Opens a window to show the contents of the source file that is specified in the Import window. If no file is specified in the Import window, a File Open dialog box is presented, allowing you to choose a file.
Batch Import Commands | Opens a window showing the Batch Import commands that would be generated from the information currently appearing on the Import window. This is the SQL that would be saved if you use the Save or Save As command.
Parent topic: Import Window Menus Overview


Import Menu

The Import menu appears in the title bar when an Import window is active. The following functions are available when importing most source file types into XDB Server table definitions:

Run | After you have entered all required information on the Import windows, starts importing your source file into the desired table definition. Optionally, you can click the Run button from the toolbar. When the process is completed, the system shows the number of records imported in the status bar at the bottom of the window. You can then process another file.
End Current | Allows you to abort an import operation while it is running. Data that was already imported up to that point remains imported. When you select this command while running an import batch file that has several transactions, the transaction currently running is ended and the next transaction is started.
End All | Aborts all batch processing when you have more than one transaction in an Batch Import file.
Clear Form | Clears all the current import specifications from the Import window. Values are set to their user-defined defaults as specified in the Defaults dialog box.
Recalculate | When you select a source file to import, automatically calculates a table definition for the data (except for the DSNTIAUL format). This command allows you to prompt the system to reanalyze the currently selected source file and get the system to suggest a table definition. This gives you the ability to revert to the original interpretation of the file's table definition. If you are creating a new table, you can then redefine any fields that are not grayed out in the table-definition display area.
Options Displays the Options dialog box, which allows you to customize your import processes. You can set the import speed to run in Normal or Engine Direct Write modes. You can also write errors to a log file and write records containing errors to a log file.

You can also set error handling options that allow you to:

  • Skip any invalid data and go on to the next record.
  • Insert NULL in fields when invalid data is encountered if the field is nullable.
  • Quit the current import process and continue with the next if an error is encountered.
  • End all Batch Import processing.
Defaults | Displays the Default Settings dialog box. The defaults consist of preset parameters. You can use this command to set format parameters of your own, or you can use the XDB Server defaults when you click the Defaults button. Default settings can be provided for Free-format ASCII, Fixed-format ASCII, and DSNTIAUL formats.
Parent topic: Import Window Menus Overview


Import Window Toolbar

When an Import window is active, the Import toolbar will be displayed as shown below.

Figure 1. *
Import Window toolbar showing all buttons and descriptions
Parent topic: Import Window


Export Window

  • Export Window Menus Overview
  • Export Window Toolbar
Parent topic: Catalog Browser Tabs


Export Window Menus Overview

Once you open an Export window, you can use the File, View, and Export menus to work with your export specifications and batch commands. The primary menus used for working with an Export window are:

  • File Menu (for opening, saving, and printing)
  • View Menu
  • Export Menu
  • File Menu
  • View Menu
  • Export Menu
Parent topic: Export Window


File Menu

The File menu provides commands for opening an Export window, for saving and retrieving export specifications, and for running Batch Export files. File menu commands relating to your use of an export specification are provided below.

New | Opens a new Export window where you can enter specifications for exporting data.
Open | Presents the Open dialog box, allowing you to retrieve previously saved SQLWizard export specifications into an Export window.
Save or Save As | Allows you to save the specifications that appear in the active Export window. You can save these specifications as a Batch Export file or as a Batch Import file.
Run Batch | Presents the Run Batch dialog box, allowing you to run a previously saved SQLWizard Batch Export file (*exp).
Parent topic: Export Window Menus Overview


View Menu

In addition to the standard View menu commands, the following commands become available when an Export window is active:

Design Export | Displays the standard Export window, allowing you to interactively select a table to export, specify a file to receive the exported data, specify various format-specific options, and specify a WHERE condition. An alternate Export window view is available if you select the SQL command from the View menu.
SQL | Provides an alternate view of your Export specifications, allowing you enter an SQL SELECT statement instead of using the standard Export window to specify the source table and WHERE condition.
Target File | Allows you to view the data as it appears in the file to which you exported data.
Batch Export Commands | Opens a window showing the Batch Export commands that would be generated from the information currently appearing on the Export window. This is the command list that would be saved if you use the Save or Save As command. It can later be run as a Batch Export file.
Batch Import Commands | Opens a window showing the Batch Import commands that would be generated from the information currently appearing on the Export window. This is the command list that would be saved if you use the Save or Save As command and saved the file as an Import (*.imp) file. Generating a batch import file at the time you are exporting data can help you when you plan to import the data onto another XDB Server. You would take the exported data file and the corresponding batch import file to the other XDB Server. Then use batch import on that machine to transfer the data onto that XDB Server.
Parent topic: Export Window Menus Overview


Export Menu

The Export menu appears in the SQLWizard title bar when you access the Export utility. The following functions are available from the Export menu when exporting an XDB Server table into a target file:

Run | Starts exporting the desired XDB Server table into a target file. Click the Run button from the toolbar, or click the Run command from the Export menu. When the process is completed, the system shows the number of records exported in the status bar at the bottom of the window.
End Current | Allows you to end an export process while it is running. Data that was already exported up to that point will appear in the destination file. If you select this command while running a Batch Export file that has multiple transactions, the transaction currently running is aborted and the next transaction is started.
End All | Aborts all batch processing when you have more than one transaction in a Batch Export file.
Clear Form | Clears all of the current export specifications from the Export window. Values are set to their user-defined defaults as specified from the Defaults dialog box.
Options | Displays the Export Options dialog box where you can specify error handling preferences.
Defaults | Displays the Export Default Settings dialog box where you can set preferences for various options. These preferences take effect whenever you open a new Export window. You can set default format parameters for each export file type (Free- and fixed-format ASCII and DSNTIAUL) and specify which view of the Export window you prefer (Design mode or SQL mode).
Parent topic: Export Window Menus Overview


Export Window Toolbar

When an Export window is active on the SQLWizard desktop, the Export toolbar will be displayed as shown below.

Figure 1. *
Export Window toolbar showing all buttons and descriptions
Parent topic: Export Window


Target File Information

This section of the Export window is where you specify the name of the file to which you want to export your XDB Server data, as well as the format to be used in that file and any other parameters required by the particular format.

File Name | Enter the drive, path, and name of the file to which you want to export data. If you enter the name of a non-existent file, SQLWizard will create it. You can use the Browse button to select an existing file that you want to over-write.
Format | Click the down-arrow button to display the drop-down list; select the format for your target file. SQLWizard can export data to free or fixed ASCII files, and mainframe-readable DSNTIAUL files. SQLWizard can also create SQL statements that you can run on another SQL database system to re-create the source table on that other system. You can include the data from the source file or just the table structure.
Other Target File Parameters | Depending on the format of the target file, additional parameters may be required.
Parent topic: Catalog Browser Tabs


Source Table Information (Design Mode)

This section of the Export window is where you specify exactly what you want to export. You can export an entire table, selected columns, or selected data.

Table Name | Enter the name of the XDB Server table that you want to extract data from. Use the Browse button to select a table from the Open dialog box.
Not Included/Included Lists | The Not Included and Included lists allow you to choose the columns of the source table that you want to export. Only the columns appearing in the Included list when you run the export will be transferred to the target file. Double click a column name to move it to the other list. You can also re-arrange the order of the columns. For example, if your source table has columns called FIRSTNAME and LASTNAME in that order, you can switch the order to LASTNAME FIRSTNAME in the exported data. After selecting the columns you want to include in the exported data, click a name to highlight it, then move it up or down the Included list until the column names are in the order you want.
WHERE Condition | You can limit the amount of data that will be exported by entering an SQL WHERE clause. For example, when exporting data from the TUTORIAL.TUTORIAL.EMPLOYEE table, you can export information about employees who live in Maryland by entering ST="MD" in the WHERE Condition box. You do not have to type the word WHERE. Note: When the SQL format is selected, the WHERE Condition field is available only when INSERT mode is selected.
Parent topic: Catalog Browser Tabs


Source Table Information (SQL Mode)

This section of the Export window is where you specify exactly what you want to export. You can export an entire table, selected columns, or selected data.

Query Enter a standard SQL SELECT query to define the data you want to export. The data will be retrieved from the database and stored in the target file and format you specify.
Parent topic: Catalog Browser Tabs


Export Options Dialog Box

Items appearing on the Export Options dialog box are described below.

On Error |  | Sets error handling options.
 | Continue | Continues processing after encountering a recoverable error.
 | Quit | Aborts the current export transaction. If running a Batch Export file containing multiple transactions, starts the next transaction.
 | End All | Aborts all export processing. If running a Batch Export file containing multiple transactions, cancels all subsequent transactions.
 | Prompt | If an error is encountered, prompts for further action.
ASCII Conversion |  | Translates the character data in the export's output file by indicating the appropriate code page translation to use. This translation happens after the data is presented by the XDB engine.
Error Logging |  | Keeps a list of all errors encountered during an export process. After the export process completes, you can view the listing of errors by editing the file with an ASCII text editor.
 | On | Indicates that you want to write errors to a log file.
 | File | Specifies the name of a file to receive the error listing.
Parent topic: Catalog Browser Tabs


Add/Modify User Dialog Box

The fields and controls in the Add/Modify User dialog box are described below.

Add | Adds a new AuthID to the system.
Delete | Permanently removes the display AuthID from the system. To temporarily deny access to a user (leaving all AuthID specifications intact), de-select the Access Authority checkbox.
Update | Changes a user's access information using the information currently displayed on the dialog box.
Close | Closes the Add/Modify User dialog box.
User ID | The AuthID (user name or UserID) is used for security purposes when you access the XDB Server, utilities, and database objects. It is also used to determine ownership of database objects. Only an XDB Server Administrator who has super-user authority can change the AuthID.
Password The password must be between four and eight characters long and must follow the rules for a short identifier. If an XDB Server is being accessed and security is on, the password specified for the user must meet the specifications for the current Password Enforcement Level as defined for that XDB Server. The user can specify a higher level access authority using the Options utility. Any super user can modify the password for an existing user, but cannot delete a user's password.

Because XDB Server passwords are stored in an encrypted format, neither a user nor an administrator can view any user's existing password. The password entered is never displayed. Instead, an asterisk (*) is displayed for each character entered.

SQLWizard has three password enforcement levels:

  • Level 1 password must be four or more characters.
  • Level 2 password must be six or more characters and include at least one digit.
  • Level 3 password must be six or more characters, include at least one digit, and must include the two randomly generated characters that appear in the prompt message when the password is created or modified.
    Note:

    Passwords are case sensitive. Be sure to always enter your password in the same combination of upper and lower case characters.

Verification | The Verification field is used to confirm entry of a password. It reassures that you have entered the correct password for a user.
Secondary ID The SecondaryID field is provided so that a variety of users can have the same AuthID for processing queries or for object ownership, but have different accounts for connecting to the XDB Server. The SecondaryID can be up to eight characters long and must follow the rules for a short identifier.

The SecondaryID value is used only when security is on. When a user with a SecondaryID creates an object, the AuthID portion of the object's name is the SecondaryID. All other users who have the same SecondaryID will have all privileges granted to that ID.

It is in this way that users can have controlled access to specific tables and information. An XDB Server Administrator can also grant location, database and table level privileges by assigning GroupIDs to AuthIDs. See Appendix A, "Security and Authority" for more information on using GroupIDs versus SecondaryIDs.

Security Options These options are applicable when accessing an XDB Server with security on. These options are ignored when accessing an XDB Server with security off. Note that these options relate only to accessing the XDB Server itself. An administrator must still grant appropriate location, database, and/or table privileges to each account.

The available security options include:

Password Required | If checked, the user must enter a password when connecting to an XDB Server.
Access Authority | If checked, the user can connect to the XDB Server. If not checked, the user is denied access to the XDB Server. This option provides a temporary way of restricting a user's access without deleting the AuthID and other information from the system.
User Type This option grants the user either User or Super User privileges. The default setting is User. Only a super user can create locations, edit system tables, and give super-user privileges to another user. If you wish to limit a user's access to certain locations or tables, you must use the GRANT and REVOKE commands.

The available User Types include:

User | Those users who are assigned USER for user type can only change their own password. They cannot modify their AuthID, SecondaryID, user comment, priority, user type, security options, or group information and cannot create locations.
Super User If you are granted super-user privileges you can add, delete, and update information for users, groups and priorities. Super users can also create locations, directly edit system catalog tables, and perform other administration functions.
Note:

If security for the XDB Server is off, all users are effectively super users.

User Comments | A descriptive comment about the user or the AuthID. The comment may be longer than the display area (use cursor keys to scroll left and right in this field). The user comment can be up to 254 characters in length.
Group Membership A group is another method available (in addition to using the SecondaryID) for an administrator to control system and location level access. All available groups are displayed in a scrollable list. If no groups exist, the list will be empty.

Groups can be added using the Groups command from the Admin menu. The advantage of using groups is that you can grant/revoke privileges to one group instead of to many individual users. A user can be added to or removed from any group by clicking to highlight the desired group name(s) on the displayed list. Users can have multiple group assignments thus gaining the privileges of all of those groups combined.

Priorities Priorities are a set of usage restrictions imposed on an AuthID. Setting priorities gives an XDB Server Administrator the ability to define XDB Server usage priorities for peak hour processing, or to restrict users who do particularly intensive queries to off-peak hours. A user who exceeds the limits that are set, is disconnected from the XDB Server. This gives an administrator the ability to regulate XDB Server usage for users.

All available priorities are displayed in a scrollable list. If no priorities exist, the list will be empty. Priorities can be added using the Priorities command from the Admin menu. Users can be assigned or removed from any priority by selecting the priority name(s) from the list displayed. If you are not running against an XDB Server version that supports priorities, or if the XDB Server has the Governor feature turned off, the Priorities command is grayed out on the Admin menu.

For more information about the Governor features of the XDB Server, see the description of the Maximum Governor Cycle Time option in the section Governor Cycle Timein the chapter Server Configuration Utility in your SQL Option Server Administration Guide

Parent topic: SQL Wizard
Related information
Governor Cycle Time


Groups Dialog Box

Items appearing on the Groups dialog box are described in this topic.

Add | Creates a new GroupID. If AuthIDs appear in the MEMBER OF list, they are assigned to the group when the group is added.
Delete | Removes a group and dissociates all assigned AuthIDs from the GroupID.
Update | Changes a GroupID's information, including comments and/or memberships.
Close | Closes the Groups dialog box.
Group Name | Identifies the group. This field is up to eight characters long and must follow the rules for a short identifier.
Comment | Allows for the storage of additional information about the group or its purpose. The comment can be up to 254 characters in length.
Group Membership | Indicates which users belong to the displayed group. AuthIDs in the USER ID list on the left are not members of the group. AuthIDs in the MEMBER OF list on the right are members of the group.
Parent topic: SQL Wizard


Define Priority Dialog Box

Items appearing on the Define Priority dialog box are shown below.

Add | Defines a new set of priorities for XDB Server usage. Priorities are assigned to AuthIDs to limit server usage.
Delete | Permanently removes an XDB Server usage priority specification.
Update | Changes the parameters that define a priority specification for XDB Server usage.
Close | Closes the Define Priority dialog box.
Priority Name | Identifies a priority. This entry can be up to eight characters long.
Number of API Calls Specifies the maximum number of Application Programming Interface (API) calls allowed during a single session on the XDB Server.

This entry must be greater than or equal to zero. The entry must be greater than or equal to zero, up to a maximum of 999,999,999. When this entry is zero, users with this priority are not limited by the number of API calls in the XDB Server SQL engine.

APIs are routines that are invoked by calls to the SQL engine from the user's application. The number of API calls that users cause the XDB Server engine to invoke is an accurate gauge of their overall use of system resources. The purpose of limiting API calls is to control user access to the system resources.

To limit users to a certain number of API calls, you need to know how many calls the users generally need during the course of their work. In many cases, determining this number is complex because it is dependent on the size of the tables the user accesses. In this case it might be best to set the number of API calls to zero (unlimited number of API calls) while limiting the user with one of the other priorities.

Max Time in Engine | Specifies the maximum cumulative time (in seconds) a user with this priority can use the XDB Server SQL engine during a single session on the XDB Server (called being "in the engine"). This number must be greater than or equal to zero, up to a maximum of 999,999,999 seconds (31 years, 259 days, 1 hour, 40 minutes, and 39 seconds). When set to zero, users with this priority will be allowed unlimited time in the engine. The purpose of this limit is to control the use of system resources.
Max Time Per API | Specifies the maximum time allowed (in seconds) per API from a user with this priority. This number must be greater than or equal to zero, up to a maximum of 9,999 seconds. When set to zero, users with this priority will not be limited by how much SQL engine time is used by an API. The purpose of this limit is to prevent the use of too much SQL engine time on a single API.
Max Idle Time | Specifies the maximum time a user with this priority can be connected to the XDB Server without running any operation on the engine (called "idle time"). This number must be greater than or equal to zero, up to a maximum of 999,999,999 seconds. When set to zero, users with this priority will be allowed unlimited idle time. The purpose of this limit is to prevent users from taking up engine threads while not using the engine.
Max Fetches | Limits a user with this priority to a specified number of records returned (fetches). This number must be greater than or equal to zero, up to a maximum of 999,999,999 fetches. When set to zero, users with this priority will be allowed an unlimited number of fetches. The purpose of this limit is to control the use of system resources.
Start Enforcement Specifies the start of a time period (which ends with END ENFORCEMENT) when engine restrictions are enforced for a user with this priority. The format of the entry is dependent on the time picture defined in Options.
Note:

If the start and end free times are equal and not null (blank entry), then all priority limits are effectively canceled. This is equivalent to saying that the full 24-hour period is free time.
End Enforcement Specifies the end of the time period (which begins with Start Enforcement) when engine restrictions are enforced for a user with this priority. The format of the entry is dependent on the time picture defined in Options.
Note:

If the start and end free times are equal and not null (blank entry), then all priority limits are effectively canceled. This is equivalent to saying that the full 24-hour period is free time.
Comments | Adds an optional description (up to 254 characters) about the general purpose or scope of this priority.
Parent topic: SQL Wizard


Mainframe Batch Database Tools (MBDT)

The MBDT toolset provides basic batch utility support for the following z/OS DB2 utilities:

DSNTIAUL
Enables you to unload your data from the target DBMS, using an SQLTUL alias.
Attention: This feature is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.
DSNTEP2
Enables you to execute SQL DDL and DML in a target DBMS using an SQLTP2 alias.

DSNTEP2 accepts native DBMS DDL and DML syntax for DB2 LUW, Oracle, and SQL Server by default. DSNTEP2 also accepts z/OS DB2 DDL and DML syntax for SQL Server. See MBDT Configuration Utility for details.

DSNUTILB
Enables you to load or unload your data to or from the target DBMS using an SQLUTB alias.

The versions of DSNTIAUL, DSNTEP2 and DSNUTILB provided by Micro Focus initialize the OpenESQL compiler directives required to set up the appropriate environment parameters, and then call OpenESQL runtime functions. They always use ODBC to communicate with target DBMSs. To enable ODBC support, you must define an XAR to Enterprise Server that uses the ODBC generic one-phase commit switch module. See Generic One-phase Commit for ODBC RM Switch Module for details.

Note: We provide MBDT for DB2 LUW, DB2 for z/OS, SQL Server, Oracle, and PostgreSQL. MBDT does not support the loading and unloading of true DBCS data (Chinese, Japanese and Korean) if the local client codepage is UTF-8.
  • Batch Migration Process
    Describes the process of migrating databases using MBDT.
  • DSNTIAUL, DSNTEP2, and DSNUTILB Aliases
    Describes the aliases MBDT uses to replace DSNTIAUL, DSNTEP2, and DSNUTILB.
  • MBDT Configuration Utility
    Describes the options you can set for Mainframe Batch Database Tools (MDBTs).
  • SQLTUL Tool - Unloading SQL Tables
    Describes the use of SQLTUL to unload SQL tables.
  • SQLTP2 Tool - Executing Dynamic SQL Statements
    Describes the use of SQLTP2 to execute dynamic SQL statements.
  • SQLUTB Tool - Loading and Unloading SQL Tables
    Describes the use of SQLUTB to load and unload SQL tables.
  • Support for Partitioned Tables in DB2 LUW
    Describes MBDT DSNUTILB support for partitioned tables in DB2 LUW.
  • How to
  • Reference
Parent topic: Database Access
Related concepts
Mainframe Batch Database Tools


Batch Migration Process

The database migration process using MBDT consists of the following steps:

  1. Create a destination database and schemas using tools provided by your DBMS vendor.
  2. Catalog an ODBC Data Source Name to the new target database using the 32- or 64-bit ODBC Data Source Administrator, depending on the COBOL working mode of your enterprise server instance.
  3. Unload data and the LOAD control statement from z/OS DB2 with DSNUTILB UNLOAD.
  4. Using Enterprise Server, create an enterprise server instance with Mainframe Subsystem Support (MSS) that also supports JCL applications.
  5. Configure your enterprise server instance by creating an ODBC XAR, and MBDT aliases.
  6. Copy the LOAD control statement to the MBDT loxL machine.
  7. Copy and catalog the unloaded DB2 data on the MBDT local machine.
  8. Using SQLTP2, execute DDL to create the tables in the new target database.
  9. Load the DB2 data into the new target database with SQLUTB, using the LOAD card generated on the mainframe.
  10. Using SQLTP2, execute DDL to create the DB2 constraints and indexes in the new target database.
Parent topic: Mainframe Batch Database Tools (MBDT)
Related reference
mbdtconfig command


DSNTIAUL, DSNTEP2, and DSNUTILB Aliases

To use the MBDT versions of DSNTIAUL, DSNTEP2, and DSNUTILB, you must configure your enterprise server instance to include an alias for each. You can do this in one of two ways:

Keep DSNTIAUL, DSNTEP2, and DSNUTILB Program Names
If you want to keep the program names DSNTIAUL, DSNTEP2, and DSNUTILB in your JCL, and have them execute the MBDT version of these utilities, add the following alias definitions:
Program | Alias
DSNTIAUL | SQLTUL
DSNTEP2 | SQLTP2
DSNUTILB | SQLUTB
Specify Alternative Program Names
If you want to specify a different program name in the JCL for each MBDT, you can do this instead. For example:
Program | Alias
HCOTIAUL | SQLTUL1
HCOTEP2 | SQLTP2
HCOUTILB | SQLUTB
Parent topic: Mainframe Batch Database Tools (MBDT)


MBDT Configuration Utility

The MDBT Configuration Utility enables you to configure options for the following tools:

SQLTP2 tool
Enables you to specify how to handle dynamic SQL statements during migration.
HCOSS
For SQL Server databases in which dynamic SQL statements are z/OS DB2 statements. This option is required when you are using HCOSS to migrate the database and your code contains z/OS DB2 DDL statements.
Agnostic
For SQL Server, DB2 LUW, Oracle, and PostgreSQL databases in which dynamic SQL statements are specific to the DBMS vendor specifications. Default.
SQLUTB tool
Enables you to specify the issuing of single or multiple commit statements during a LOAD operation. The default is a single commit issued after all records have been loaded.

You can also use this tool to specify the format of DATE columns for input data and output data, respectively, and to check the row size of the table against the LRECL of SYSREC using Fuji mainframe behavior.

We recommend that you use the single commit to provide optimal performance. However, if DBMS logging or other such issues are a concern, you might prefer the multiple commit. For the multiple commit, you also specify a batch size (number of rows). During the LOAD operation, a commit is issued each time the batch size has been reached.

SQLTUL tool
Enables you to specify that the return code (RC=04) for execution of non-SELECT * statements should match the mainframe DSNTIAUL return code. The default is to not match the return code, but to return RC=0.

The SQLTUL tool also enables you to specify how to handle dynamic SQL statements during execution by setting either the HCOSS or Agnostic options:[1]

HCOSS
For SQL Server databases in which dynamic SQL statements are z/OS DB2 statements. This option is required when you are using HCOSS to migrate the database and your code contains z/OS DB2 SQL statements.
Agnostic
For SQL Server, DB2 for z/OS, DB2 LUW, Oracle, and PostgreSQL databases in which dynamic SQL statements are specific to the DBMS vendor specifications. Default.

For complete information about running the MBDT Configuration Utility from the command line, see the mbdtconfig command topic.

Parent topic: Mainframe Batch Database Tools (MBDT)
Related concepts
SQLUTB LOAD
SQLUTB UNLOAD
SQLTP2 Tool - Executing Dynamic SQL Statements
Related tasks
To start the MBDT Configuration Utility UI
To run the MBDT Configuration Utility from a command prompt
Related reference
MBDT - JCL batch utilities tab
mbdtconfig command


SQLTUL Tool - Unloading SQL Tables

The SQLTUL tool is equivalent to DB2 DSNTIAUL. It is used unload some or all rows from up to 100 tables in one JCL step. With SQLTUL, you can unload data of all built-in data types except LOB and time-interval types. The format of unload data is compatible with SQLUTB LOAD utility and the load control statements are generated during the unload process. The unload data is encoded in ASCII character set as the default and in EBCDIC character set as optional.

You can also use SQLTUL to execute SQL non-SELECT statements dynamically.

Note: As part of the environment setup, SQLTUL initializes the ALLOWNULLCHAR SQL compiler directive option to preserve the X"00" null character in CHAR and VARCHAR fields. See ALLOWNULLCHAR in the Enterprise Developer documentation for details.

SQLTUL supports a number of popular RDBMSs via the OpenESQL runtime, including SQL Server, DB2 for z/OS, DB2 LUW, Oracle, and PostgreSQL. When running against SQL Server, the SQL dialect of the statements used in SQLTUL can be native or of DB2 for z/OS. For the latter, set the HCOSS option in the MBDT Configuration Utility. For example, when targeting SQL Server, use the T-SQL dialect.

The following is an example of JCL using SQLTUL:

//UNLOADTL  JOB
//RESETDB  EXEC PGM=IKJEFT01
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSREC00 DD  DSN=MCS.UNLOAD. UNLOADTL,
//             UNIT=SYSDA,SPACE=(CYL,(1,1)),DISP=(MOD,CATLG),
//             VOL=SER=SCR03,RECFM=FB
//SYSPUNCH DD  DSN=MCS. UNLOADTL.SYSPUNCH,
//             UNIT=SYSDA,SPACE=(CYL,(1,1)),DISP=(MOD,CATLG),
//             VOL=SER=SCR03,RECFM=FB
//SYSUDUMP DD  SYSOUT=*
//SYSOUT      DD  SYSOUT=*
//SYSTSIN      DD  *
 DSN SYSTEM(HCOD)
 RUN  PROGRAM(SQLTUL) PARMS('SQL,250')
//SYSIN       DD  *
SELECT * FROM MFIXCH.EMP;
/*

Where HCOD is the ODBC XAR ID for your database connection.

Parameters

The following parameters are supported by SQLTUL:
  • SQL
  • TOLWARN
  • EBCDIC (specifies that the dataset is encoded in EBCDIC)

SQLTUL ignores parameters that indicate the number of rows per fetch, and ignores the LOBFile parameter.

Parent topic: Mainframe Batch Database Tools (MBDT)


SQLTP2 Tool - Executing Dynamic SQL Statements

The SQLTP2 tool is equivalent to DB2 DSNTEP2. It is used to execute dynamic SQL statements embedded in JCL, given an ODBC database connection that is established by an XAR definition in Enterprise Server. In the database migration process, we use it to execute DDL against a DBMS to create and modify schema objects.

Important: Because of referential integrity implementation differences between mainframe DB2 and other DBMSs, we recommend that you include an initial DSNTEP2 step to create your tables. After loading the data, you can run additional DSNTEP2 steps to create your indexes and constraints.

Executing SQLTP2

To use SQLTP2, directly submit JCL using the JES CONTROL feature in Enterprise Server. The JCL syntax must be z/OS DB2 compatible.

When you run the MBDT Configuration utility, you have two options for processing SQL statements. These options are specified as the database type, which can be set to the default, A[gnostic], to use the native DBMS SQL dialect, or set to H[COSS] to use the DB2 dialect for SQL Server. When you set the database type to HCOSS (DB2 dialect for SQL Server), the SQLTP2 tool instructs the OpenESQL runtime to translate z/OS DB2 SQL statements to SQL Server statements before dispatching them for execution.

Note: As part of the environment setup, SQLTP2 initializes the ALLOWNULLCHAR SQL compiler directive option to preserve the X"00" null character in CHAR and VARCHAR fields. See ALLOWNULLCHAR in the Enterprise Developer documentation for details.

The following is an example of JCL for a CREATE TABLE statement using the DB2 dialect for SQL Server:

Note: The MBDT Configuration utility HCOSS option does not support SQL statements of mixed dialects. In addition, any SQL Server-specific syntax in SQL statements could cause errors.
//DDLJOB2 JOB
//RESETDB  EXEC PGM=IKJEFT01
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSPUNCH DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSTSIN  DD  *
 DSN SYSTEM(HCOD)
 RUN  PROGRAM(DSNTEP2)
 END
/*
//SYSIN DD *
CREATE TABLE HCOSQL.EMP
(
EMPNO       CHAR(6) NOT NULL,
FIRSTNME    VARCHAR(12) NOT NULL,
MIDINIT     CHAR(1) NOT NULL,
LASTNAME    VARCHAR(15) NOT NULL,
WORKDEPT    CHAR(3),
PHONENO     CHAR(4),
HIREDATE    DATE,
JOB         CHAR(8),
EDLEVEL     SMALLINT,
SEX         CHAR(1),
BIRTHDATE    DATE,
SALARY      DECIMAL(9,2),
BONUS       DECIMAL(9,2),
COMM        DECIMAL(9,2),
PRIMARY KEY (EMPNO)
) IN XDBIBMDB.XDBIBMTS;

/*
//

Where HCOD is the ODBC XAR ID for your database connection, SQLTP2 has been established as an alias for DSNTEP2, and the semi-colon (;) is the SQL terminator.

Parameters

The SQLTP2 parameters supported are:

  • ALIGN (MID), ALIGN(LHS)
  • MIXED, NOMIXED
  • TOLWARN(YES), TOLWARN(NO)
  • SQLTERM (termchar)

Control Statements

Control statements for the SYSIN data set use the following syntax:
--#SET control-option-value
Where control-option-value can be any of the following:
  • TERMINATOR
  • ROWS_FETCH
  • ROWS_OUT
  • MAXERRORS
  • TOLARTHWRN
  • TOLWARN
The following control option values and error-raising values are not supported:
  • MULTI-FETCH
  • PREPWARN
  • SQLFORMAT
Note: To ensure proper parsing of SYSIN, do not include the tab character (ASCII decimal character code 9; EBCDIC decimal character code 5) in its contents. When parsed, the tab character could cause spurious, unintended errors.
Parent topic: Mainframe Batch Database Tools (MBDT)
Related concepts
MBDT Configuration Utility


SQLUTB Tool - Loading and Unloading SQL Tables

SQLUTB supports both LOAD and UNLOAD. They are both equivalents of the DB2 for z/OS DSNUTILB utility, having the same basic features and options. Although they are primarily designated for database migration, you can also use them to perform routine LOAD and UNLOAD of data, emulating z/OS DSNUTILB LOAD and UNLOAD.

Note: As part of the environment setup, SQLUTB initializes the ALLOWNULLCHAR SQL compiler directive option to preserve the X"00" null character in CHAR and VARCHAR fields. See ALLOWNULLCHAR in the Enterprise Developer documentation for details.
  • SQLUTB LOAD
  • SQLUTB UNLOAD
Parent topic: Mainframe Batch Database Tools (MBDT)


SQLUTB LOAD

SQLUTB LOAD is designed to work with LOAD cards generated by DSNUTILB UNLOAD on the mainframe as well as LOAD cards generated by SQLUTB UNLOAD itself. For example, the following UNLOAD control statements generate valid LOAD statements:
UNLOAD DATA FROM TABLE HCOSQL.CUSTOMER
UNLOAD TABLESPACE HCOSQL.HCOTS FROM TABLE HCOSQL.EMPLOYEE
Important:
  • SQLUTB LOAD requires that you modify the LOAD control statement created on the mainframe to include either the REPLACE or the RESUME YES option. If neither is included, the JCL job terminates with an abend.
  • You can configure the SQLUTB LOAD date format to specify the format(s) of date values in the input dataset. See mbdtconfig command for details.

Executing SQLUTB LOAD

To use SQLUTB LOAD, directly submit JCL using the JES CONTROL feature in Enterprise Server. The JCL syntax must be z/OS DB2 compatible.

The following is an example of JCL using a LOAD card generated on the mainframe:

//DSNCUSTM JOB
//DSNUTILB EXEC PGM=HCOUTILB,PARM='HCOD,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=SH.HCOSQL.CUSTOMRS
//SYSIN    DD   *
LOAD DATA INDDN SYSREC LOG NO RESUME NO REPLACE
 EBCDIC  CCSID(00037,00000,00000)
 INTO TABLE
 "HCOSQL".
 "CUSTOMRS"
 WHEN(00001:00002) = X'0028'
 NUMRECS               242100
 ( "C_ID"
  POSITION(  00003:00006) INTEGER
 , "C_D_ID"
  POSITION(  00007:00008) SMALLINT
 , "C_W_ID"
  POSITION(  00009:00010) SMALLINT
 , "C_FIRST"
  POSITION(  00012:00029) VARCHAR
                          NULLIF(00011)=X'FF'
 , "C_MIDDLE"
  POSITION(  00031:00032) CHAR(00002)
                          NULLIF(00030)=X'FF'
 , "C_LAST"
  POSITION(  00034:00051) VARCHAR
                          NULLIF(00033)=X'FF'
 , "C_STREET_1"
  POSITION(  00053:00074) VARCHAR
                          NULLIF(00052)=X'FF'
 , "C_STREET_2"
  POSITION(  00076:00097) VARCHAR
                          NULLIF(00075)=X'FF'
 , "C_CITY"
  POSITION(  00099:00120) VARCHAR
                          NULLIF(00098)=X'FF'
 , "C_STATE"
  POSITION(  00122:00123) CHAR(00002)
                          NULLIF(00121)=X'FF'
 , "C_ZIP"
  POSITION(  00125:00133) CHAR(00009)
                          NULLIF(00124)=X'FF'
 , "C_PHONE"
  POSITION(  00135:00150) CHAR(00016)
                          NULLIF(00134)=X'FF'
 , "C_SINCE"
  POSITION(  00152:00177) TIMESTAMP EXTERNAL
                          NULLIF(00151)=X'FF'
 , "C_CREDIT"
  POSITION(  00179:00180) CHAR(00002)
                          NULLIF(00178)=X'FF'
 , "C_CREDIT_LIM"
  POSITION(  00182:00188) DECIMAL
                          NULLIF(00181)=X'FF'
 , "C_DISCOUNT"
  POSITION(  00190:00192) DECIMAL
                          NULLIF(00189)=X'FF'
 , "C_BALANCE"
  POSITION(  00194:00200) DECIMAL
                          NULLIF(00193)=X'FF'
 , "C_YTD_PAYMENT"
  POSITION(  00202:00208) DECIMAL
                          NULLIF(00201)=X'FF'
 , "C_PAYMENT_CNT"
  POSITION(  00210:00211) SMALLINT
                          NULLIF(00209)=X'FF'
 , "C_DELIVERY_CNT"
  POSITION(  00213:00214) SMALLINT
                          NULLIF(00212)=X'FF'
 , "C_DATA"
  POSITION(  00216:00717) VARCHAR
                          NULLIF(00215)=X'FF'
 )

/*
//

Where HCOD is the ODBC XAR ID for your database connection, SQLUTB has been established as an alias for program HCOUTILB, and SH.HCOSQL.CUSTOMRS is the cataloged data file mapped to SYSREC.

LOAD Options

Standard LOAD Options
DATA
Syntactically optional.
REPLACE
REPLACE is mutually exclusive to RESUME YES. Either REPLACE or RESUME YES is required.

If neither REPLACE nor RESUME YES are present, warnings are generated based on the target table having an empty status.

DISCARDDN
This option behaves differently from DB2 for z/OS in handling unique index. The tool does not check for duplicates in the input data set, but instead forwards all data to the database. If duplicate records exist in the data set, only the first instance is loaded into the target table, assuming that no existing record in the table has the same index.
LOG YES|NO
YES
Default value.
NO
Supported if the user has the privileges of ALTER TABLE ACTIVATE NOT LOGGED INITIALLY WITH EMPTY TABLE.
RESUME YES
RESUME YES is mutually exclusive to REPLACE. Either RESUME YES or REPLACE is required.

If neither RESUME YES nor REPLACE are present, warnings are generated based on the target table having an empty status.

Ignored, but Syntactically Recognized LOAD Options
  • CCSID
  • CONTINUE IF
  • COPYDDN
  • DISCARDS
  • ENFORCE
  • ERRDDN
  • FLOAT (S390/IEEE)
  • FORMAT-SPEC
  • FREQVAL
  • HISTORY
  • INCURSOR
  • INDEX
  • KEEPDICTIONARY
  • KEYCARD
  • MAPDDN
  • NOCOPYPEND
  • NOSUBS
  • PREFORMAT
  • RECOVERYDDN
  • REUSE
  • SHRLEVEL
  • SORTDEVT
  • SORTKEY
  • SORTNUMS
  • STATISTICS
  • WORKDDN
Unsupported LOAD Options
  • COPYDICTIONARY
  • DECFLOAT ROUNDMODE-SPEC
  • IDENTITYOVERRIDE
  • INDEXDEFER
  • PRESORTED

Specifications

INTO TABLE Specifications
The INTO TABLE specifications have a number of options.
INTO TABLE Supported Options
  • WHEN
  • NUMRECS
  • IGNOREFIELDS
  • FIELD SPECIFICATION
  • PART (for DB2 LUW only)
Ignored, but Syntactically Recognized INTO TABLE Options
  • PART (for all DBMSs except DB2 LUW)
LOAD Specification
  • INDDN SYSREC (or ddname)
  • EBCDIC/ASCII/UNICODE
Note: Unlike the mainframe, SQLUTB LOAD does not default to EBCDIC, but defaults to ASCII.
FIELD Specification
Supported SQL Data Types for FIELD Specification
  • INTEGER, BIGINT, SMALLINT
  • FLOAT, REAL
  • DECIMAL
  • CHAR, VARCHAR (UP TO VARCHAR(20000))
  • GRAPHIC, VARGRAPHIC
  • DATE, TIME, TIMESTAMP
  • BINARY, VARBINARY
Unsupported SQL Data Types for FIELD Specification
  • DECFLOAT
  • ROWID
  • BLOB
  • CLOB
  • DBCLOB
  • XML
Supported Options for FIELD Specification
  • DEFAULTIF (for character-string as the condition parameter only)
Important: SQLUTB LOAD commit behavior can be configured to issue one commit or multiple commits. See MBDT Configuration Utility for details.
Note: To ensure proper parsing of SYSIN, do not include the tab character (ASCII decimal character code 9; EBCDIC decimal character code 5) in its contents. When parsed, the tab character could cause spurious, unintended errors.
Parent topic: SQLUTB Tool - Loading and Unloading SQL Tables
Related concepts
SQLUTB UNLOAD
MBDT Configuration Utility
Related reference
mbdtconfig command


SQLUTB UNLOAD

SQLUTB UNLOAD unloads data from a table in a DBMS, and places it into an output data set file. You can use SQLUTB UNLOAD to unload all rows from a table, or unload only those rows that meet certain criteria, such as those selected from a provided field specification list. Output data sets are compatible with z/OS DB2 in both encoding and formatting, and can be used as input to SQLUTB LOAD.

Important: You can configure the SQLUTB LOAD date format to specify the format(s) of date values in the input dataset. See mbdtconfig command for details.

Executing SQLUTB UNLOAD

SQLUTB UNLOAD is similar to DSNUTILB LOAD. Include an SQLUTB UNLOAD card in your JCL, and execute it by submitting the JCL directly using the JES CONTROL feature in Enterprise Server. The JCL syntax must be z/OS DB2 compatible.

The following is an example of JCL using a UNLOAD card:

//ULEMP001  JOB CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,REGION=0M
//DELETE  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE MCS.UNLOAD.ULEMP001
  SET    MAXCC=0
//DSNUTILB EXEC PGM=HCOUTILB,PARM='HCOD,ULEMP001'
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SORTOUT  DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSPRINT DD SYSOUT=*
//UTPRINT  DD SYSOUT=*
//SYSPUNCH DD SYSOUT=*
//SYSREC   DD DSN=MCS.UNLOAD.ULEMP001,DISP=(MOD,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(1,1)),
//            DCB=(RECFM=VB,LRECL=107,BLKSIZE=6500)
//SYSIN    DD *
   UNLOAD DATA FROM TABLE [DSN8910].[EMP] EBCDIC
/*
//
//         PARM='&SYSTEM,&UID,&UTPROC'
//*STEPLIB  DD   DSN=&LIB,DISP=SHR
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*

Where HCOD is the ODBC XAR ID for your database connection, SQLUTB has been established as an alias for program HCOUTILB, and MCS.UNLOAD.ULEMP001 is the cataloged output data file.

In contrast to DB2 for z/OS DSNUTILB UNLOAD, the default code set for the output of SQLUTB UNLOAD is ASCII instead of EBCDIC. Also, the default record format, RECFM, is FB. You can override the RECFM default with DCB in the SYSREC definition.

UNLOAD Options

Supported Specifications and Options
  • ASCII – default code set
  • EBCDIC – to override the default ASCII if needed
  • MAXERR
  • NOPAD
  • NOSUBS
  • PUNCHDDN
  • PART (for DB2 LUW only)
  • TABLESPACE – does not apply to SQL Server
  • UNICODE – code set
  • UNLDDN
Unsupported Specifications and Options
  • CHARDEL
  • COLDEL
  • CCSID
  • DECFLOAT_ROUNDMODE
  • DECPT
  • DELIMITED
  • FLOAT IEEE
  • FLOAT S390
  • FORMAT INTERNAL
  • FROMCOPY
  • FROMCOPYDDN
  • LIST
  • PART (for all DBMSs except DB2 LUW)
  • SHRLEVEL
Supported FROM TABLE Options
  • FIELD SPECIFICATION
  • HEADER
  • POSITION
  • STRIP
  • TRUNCATE
  • WHEN
Unsupported FROM TABLE Options
  • LIMIT
  • SAMPLE
Supported TABLE FIELD TYPES
  • BIGINT
  • BINARY
  • CHAR
  • CINSTANT
  • DATE EXTERNAL
  • DECIMAL (PACKED)
  • DECIMAL EXTERNAL
  • DOUBLE
  • FLOAT EXTERNAL
  • FLOAT
  • GRAPHIC
  • INTEGER EXTERNAL
  • INTEGER
  • REAL
  • SMALLINT
  • TIME EXTERNAL
  • TIMESTAMP EXTERNAL
  • VARBINARY
  • VARCHAR
  • VARGRAPHIC
Unsupported TABLE FIELD TYPES
  • BLOB
  • CLOB
  • DBCLOB
  • GRAPHIC EXTERNAL
  • ROWID
Note: To ensure proper parsing of SYSIN, do not include the tab character (ASCII decimal character code 9; EBCDIC decimal character code 5) in its contents. When parsed, the tab character could cause spurious, unintended errors.
Parent topic: SQLUTB Tool - Loading and Unloading SQL Tables
Related concepts
SQLUTB LOAD
MBDT Configuration Utility
Related reference
mbdtconfig command


Support for Partitioned Tables in DB2 LUW

Starting with Enterprise Server 2.3 Update 2, Enterprise Developer MBDT DSNUTILB supports the DB2 LUW Table Partition Feature for all supported IBM versions of DB2 LUW in terms of data movement from and to partitioned tables in a single partition scope:

  • LOAD can load one partition of a partitioned table within one JCL job
  • UNLOAD can unload one partition of a partitioned table within one JCL job

Neither LOAD nor UNLOAD support parallel data movement from and to multiple partitions of a partitioned table within one JCL job.

MBDT supports a partitioning key consisting of a single column only, and does not support a partitioning key consisting of multiple columns.

To load data into a single partition of partitioned table, include the PART n option in the control statement in the JCL. For example:

//DB2LDPAR JOB
//DSNUTILB EXEC PGM=TSTUTILB,PARM='DB2C,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=MCSDB2.UNLOAD.ULDB2EMP
//SYSIN    DD   *
LOAD DATA INDDN(SYSREC) ASCII
 INTO TABLE TEST.EMPLOYEE PART 1 REPLACE
 WHEN(00001:00002) = X'0001'
 ( "EMPNO"
        POSITION(  00003:00008) CHAR(00006)
 , "FIRSTNME"
        POSITION(  00009:00022) VARCHAR
 , "MIDINIT"
        POSITION(  00024:00024) CHAR(00001)
                          NULLIF(00023)=X'FF'
 , "LASTNAME"
        POSITION(  00025:00041) VARCHAR
 , "WORKDEPT"
        POSITION(  00043:00045) CHAR(00003)
                          NULLIF(00042)=X'FF'
 , "PHONENO"
        POSITION(  00047:00050) CHAR(00004)
                          NULLIF(00046)=X'FF'
 , "HIREDATE"
        POSITION(  00052:00061) DATE EXTERNAL
                          NULLIF(00051)=X'FF'
 , "JOB"
        POSITION(  00063:00070) CHAR(00008)
                          NULLIF(00062)=X'FF'
 , "EDLEVEL"
        POSITION(  00071:00072) SMALLINT
 , "SEX"
        POSITION(  00074:00074) CHAR(00001)
                          NULLIF(00073)=X'FF'
 , "BIRTHDATE"
        POSITION(  00076:00085) DATE EXTERNAL
                          NULLIF(00075)=X'FF'
 , "SALARY"
        POSITION(  00087:00091) DECIMAL
                          NULLIF(00086)=X'FF'
 , "BONUS"
        POSITION(  00093:00097) DECIMAL
                          NULLIF(00092)=X'FF'
 , "COMM"
        POSITION(  00099:00103) DECIMAL
                          NULLIF(00098)=X'FF'
 )
/*
//

The syntax and partition numbering of the JCL follow mainframe DB2 conventions. The partition numbering is 1-based whereas the numbering in DB2 LUW is 0-based. MBDT DSNUTILB converts the two conventions internally. The executed JCL job loads the data set into Partition 0 in DB2 LUW.

To unload data from a single partition of a partitioned table, include the PART n option in the control statement in the JCL in two forms:

UNLOAD TABLESPACE tabespacename PART n FROM TABLE
tablename

And:

UNLOAD TABLESPACE tabespacename PART n

For example:

//ULDB2PAR JOB CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,REGION=0M
/*JOBPARM  SYSAFF=ANY
//DELETE  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE MCSDB2.UNLOAD.ULDB2PAR
  SET    MAXCC=0
//*------------------------------------------------------------------
//*       EXECUTE DSNUPROC
//*------------------------------------------------------------------
//DSNUTILB EXEC PGM=TSTUTILB,PARM='DB2C,ULDB2PAR’
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SORTOUT  DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSPRINT DD SYSOUT=*
//UTPRINT  DD SYSOUT=*
//SYSPUNCH DD SYSOUT=*
//SYSREC   DD DSN=MCSDB2.UNLOAD.ULDB2PAR,DISP=(MOD,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSIN    DD *
   UNLOAD TABLESPACE PARTSPACE1 PART 1
   FROM TABLE XINYUC.EMPLOYEE2
/*
//

Again, the partition numbering convention follows mainframe DB2 convention. The JCL specifies PART 1 and the actual partition number in DB2 LUW is 0. A punch card specified in the JCL is generated following execution. The unload data set, MCSDB2.UNLOAD.ULDB2PAR, is automatically cataloged by DSNUTILB. The default code set is ASCII, and can be optionally changed to EBCDIC.

Parent topic: Mainframe Batch Database Tools (MBDT)


How to

  • To start the MBDT Configuration Utility UI
  • To run the MBDT Configuration Utility from a command prompt
  • To set a default dialect for SQLTP2
  • To set a default commit behavior for SQLUTB
Parent topic: Mainframe Batch Database Tools (MBDT)


To start the MBDT Configuration Utility UI

In standalone mode:
Windows 8, 8.1, and Windows Server 2012
  • From the Windows Start screen, click the MBDT Configuration Utility tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Server > MBDT Configuration Utility.
Parent topic: How to
Related concepts
MBDT Configuration Utility
Related tasks
To set a default dialect for SQLTP2
To set a default commit behavior for SQLUTB
To run the MBDT Configuration Utility from a command prompt


To run the MBDT Configuration Utility from a command prompt

  1. Start an Enterprise Server command prompt
  2. Issue the mbdtconfig command.

See To start an Enterprise Server command prompt and mbdtconfig command for details.

Parent topic: How to
Related concepts
MBDT Configuration Utility
Related tasks
To start the MBDT Configuration Utility UI


To set a default dialect for SQLTP2

  1. Start the MBDT Configuration Utility.
  2. In the Database Selection group, select either HCOSS or Agnostic.
  3. Click Save to confirm changes.
  4. Click OK to close the MBDT Configuration Utility.
Parent topic: How to
Related tasks
To set a default commit behavior for SQLUTB
To start the MBDT Configuration Utility UI
Related reference
MBDT - JCL batch utilities tab


To set a default commit behavior for SQLUTB

  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. Click Save to confirm changes.
  5. Click OK to close the MBDT Configuration Utility.
Parent topic: How to
Related tasks
To set a default dialect for SQLTP2
To start the MBDT Configuration Utility UI
Related reference
MBDT - JCL batch utilities tab


Reference

  • mbdtconfig command
    Runs the command-line version of the MBDT Configuration Utility.
  • MBDT and DBMS Data Types
  • MBDT - JCL batch utilities tab
Parent topic: Mainframe Batch Database Tools (MBDT)


mbdtconfig command

Runs the command-line version of the MBDT Configuration Utility.
Important: You must run this command from a 32-bit or a 64-bit Enterprise Server command prompt. For instructions, see To start an Enterprise Server command prompt.

Syntax

mbdtconfig -t {H[COSS] | A[gnostic]} [-s size={0 | n}] [–c {Y[es] |
   N[o]}] [–f {I[SO] | E[UR] | U[SA]}] [–m {I[SO] | E[UR] | U[SA]]
   [-r {Y[es] | N[o]}]

Parameters

-t
Sets the database type.
H[COSS]
Indicates a SQL Server database in which SQL statements are z/OS DB2 statements.
A[gnostic]
Indicates a SQL Server, DB2 for z/OS, Oracle, or PostgreSQL database in which SQL statements are specific to the DBMS vendor specifications. This option does not support mainframe DB2 DDL. Default.
-s
Sets the commit behavior.
size=0
Default. Perform a single commit after all records have been loaded.

size=n
Enables multiple commits. Provide a number to indicate the number of rows to process before issuing each commit.
–c
Sets the LOAD behavior when the LRECL of SYSREC is found to be greater than the row size.
Y[es]
The LOAD fails when the LRECL of SYSREC is greater than the row size.
N[o]
Default. The LOAD continues regardless of the LRECL of SYSREC size as compared to the row size.
-f
Sets the format of DATE values for the input dataset.
I[SO]
Default. The LOAD only acceptS the ISO format (yyyy-mm-dd) for DATE (external) values.
E[UR]
The LOAD accepts the EUR format (dd.mm.yyyy) and ISO format for DATE (external) values.
U[SA]
The LOAD accepts the USA format (mm/dd/yyyy) and the ISO format for DATE (external) values.
-m
Sets the format of DATE values for the output dataset.
I[SO]
Default. The UNLOAD only acceptS the ISO format (yyyy-mm-dd) for DATE (external) values.
E[UR]
The UNLOAD accepts the EUR format (dd.mm.yyyy) and ISO format for DATE (external) values.
U[SA]
The UNLOAD accepts the USA format (mm/dd/yyyy) and the ISO format for DATE (external) values.
-r
Sets the return code of SQLTUL for non-SELECT * statements.
Y[es]
Match the return code of mainframe DSNTIAUL, RC=04.
N[o]
Default. Do not match the return code, instead returning mainframe DSNTIAUL RC=0.
Parent topic: Reference
Related concepts
SQLUTB LOAD
SQLUTB UNLOAD
MBDT Configuration Utility


MBDT and DBMS Data Types

The DSNTIAUL, DSNTEP2, and DSNUTILB batch utilities use ODBC, and therefore ODBC data types, to communicate with a DBMS. The following table shows the supported DBMS data types these utilities support. Footnotes provide additional information and/or restrictions.

ODBC Data Types | HCOSS (DB2 for z/OS) | SQL Server | DB2 LUW | Oracle | PostgreSQL
SQL_CHAR | CHAR | CHAR | CHAR | CHAR | CHAR
SQL_LONG_VARCHAR | VARCHAR | VARCHAR | VARCHAR | VARCHAR2 | VARCHAR
SQL_WCHAR | GRAPHIC | NCHAR | GRAPHIC | NCHAR | CHAR
SQL_WVARCHAR | VARGRAPHIC | NVARCHAR | VARGRAPHIC | NVARCHAR2 | VARCHAR
SQL_BIGINT | BIGINT | BIGINT | BIGINT | NUMBER(19,0) | BIGINT
SQL_INTEGER | INT | INT | INT | NUMBER(10,0) | INT
SQL_SMALLINT | SMALLINT | SMALLINT | SMALLINT | NUMBER(5) | SMALLINT
SQL_TINYINT | SMALLINT 1 | TINYINT 1 | SMALLINT 1 | NUMBER(3) 1 | SMALLINT 1
SQL_DOUBLE | FLOAT | FLOAT(53) | FLOAT | BINARY_DOUBLE | DOUBLE PRECISION
SQL_REAL | REAL | REAL | REAL | BINARY_FLOAT | REAL
SQL_DECIMAL(p,s) | DECIMAL(p,s) | DECIMAL(p,s) | DECIMAL(p,s) | NUMBER(p,s) | DECIMAL(p,s) 2
SQL_NUMERIC(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | NUMBER(p,s) | NUMERIC(p,s) 2
SQL_BIT | CHAR(1) 1 | BIT 1 | CHAR(1) 1 | NUMBER(3) 1 | BOOLEAN 1
SQL_GUID | CHAR(36) 1 | GUID 1 | CHAR(36) 1 | CHAR(36) 1 | CHAR(36) 1
SQL_BINARY | BINARY | BINARY | CHAR FOR BIT DATA | RAW 1 | BYTEA 1
SQL_VARBINARY | VARBINARY | VARBINARY | VARCHAR FOR BIT DATA | RAW 1 | BYTEA 1
SQL_LONGVARBINARY | BLOB 4 | BLOB 4 | BLOB 4 | LONG RAW 4 | BYTEA 4
SQL_WLONGVARCHAR | CLOB 4 | CLOB 4 | CLOB 4 | LONG 4 | TEXT 4
SQL_DATE | DATE | DATE | DATE | DATE 3 | DATE
SQL_TYPE_TIME | TIME | TIME | TIME | CHAR(15) 1 | TIME
SQL_TIMESTAMP | TIMESTAMP | DATETIME2(6) | TIMESTAMP | DATE 3 | TIMESTAMP

1 Supported in DSNTIAUL, DSNTEP2, and DSNUTILB (LOAD and UNLOAD) with cited equivalent data types

  • For PostgreSQL data type BYTEA, the default size is 255, and can be expanded (DSNTEP2 and DSNUTILB only) by resetting the ODBC connection VARCHAR(MAX) size, to a larger number
  • For Oracle data type RAW, the maximum width is 200
  • For SQL Server data type TINYINT, OpenESQL maps it to SMALLINT
  • For SQL Server data type BIT, OpenESQL maps it to TINY (one byte)
  • For SQL Server data type GUID, OpenESQL maps it to CHAR (36)
  • For PostgreSQL data type BOOLEAN, OpenESQL maps it to VARCHAR(5)

2 PostgreSQL data types DECIMAL and NUMERIC are supported in DSNTIAUL, DSNTEP2, and DSNUTILB (LOAD and UNLOAD) where the supported range is s <= p <= 38.

3 Oracle DATE data type has both date and time, and is supported in DSNTIAUL, DSNTEP2, and DSNUTILB (LOAD and UNLOAD)

4 Unsupported in DSNTIAUL, DSNTEP2, and DSNUTILB (LOAD and UNLOAD)

Parent topic: Reference


MBDT - JCL batch utilities tab

Database Selection
HCOSS
For SQL Server databases in which dynamic SQL statements are z/OS DB2 statements. This option is required when you are using HCOSS to migrate the database and your code contains z/OS DB2 SQL statements.
Agnostic
Default. For SQL Server, DB2 for z/OS, Oracle, and PostgreSQL databases in which dynamic SQL statements are specific to the DBMS vendor specifications.
Commit
Single commit...
Default. Perform a single commit after all records have been loaded.
Multiple commits...
Perform a commit each time the Batch Size value has been reached.
Batch Size
When Multiple commits... is selected, the number of rows to process before performing a commit.
Date format
Input Data
ISO | Default. LOAD accepts only Date values in ISO format.
EUR | LOAD accepts Date values in both EUR and ISO formats.
USA | LOAD accepts Date values in both USA and ISO formats.
Output Data
ISO | Default. UNLOAD accepts only Date values in ISO format.
EUR | UNLOAD accepts Date values in both EUR and ISO formats.
USA | UNLOAD accepts Date values in both USA and ISO formats.
Fail if LRECL of SYSREC is greater than row size
Default is unchecked. When checked, the LOAD fails when the LRECL of SYSREC is found to be greater than the row size.
Parent topic: Reference
Related concepts
MBDT Configuration Utility
Related tasks
To set a default dialect for SQLTP2
To set a default commit behavior for SQLUTB


Data Files

  • Data Tools
  • 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 Tools

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

Data Tools combines the functionality of the previous generations of the Data File Tools products with further enhancements that make it suitable for working with remote catalogued datasets. Data Tools is comprised of two components: the REST-based file service API and the Record Editor client. The file service handles the file requests while maintaining security and synchronization and the client provides the UI for editing records. The two components work together such that a user only needs to set up the remote data server and then they can interact with the editor to open, edit and save data files, while the service handles all of the requests.

The file service API is supported on all Enterprise products in Windows and UNIX platforms. This includes:

  • Enterprise Server for Windows and UNIX
  • Enterprise Developer
  • Enterprise Test Server
  • Enterprise Developer UNIX Components

The Record Editor is available with development products in the Enterprise suite in Windows and UNIX. The editor is an Eclipse-based RCP application. You do not need to have an Eclipse IDE installed on your machine to run the editor.

  • Data Tools Software Requirements
  • Current Restrictions
  • Supported File Types
  • File Service API
  • Troubleshooting Data Tools
Parent topic: Data Files


Data Tools Software Requirements

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

To use the Data Tools product, you must have the following installed.

For the file service:

  • An Enterprise Developer or Enterprise Server or Enterprise Test Server product, version 10.0 or later.

For the Record Editor:

  • An Enterprise Developer product, version 10.0 or later.
  • A Java Runtime Environment (JRE) or Java Development Kit (JDK), version 17 or later. You must add the path to the JRE or JDK in the file datatools.ini.
Parent topic: Data Tools


Current Restrictions

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

This version of the Data Tools product currently has the following restrictions:

  • There is no support for opening and editing non-cataloged files. Any files opened and modified by the file service or Record Editor must be accessed from a dataset on a local or remote Enterprise Server that is configured in advance.
  • You cannot create new files using the file service.
  • There is no Save As option available. Any changes you make must be saved to overwrite the existing file.
  • There is no support for ESDS or Extended ESDS files.
  • The file service is not supported within a Performance and Availability Cluster (PAC).
  • There is no support for files stored via the Micro Focus Database File Handler (MFDBFH)
  • There is no Filter functionality.
  • There is no Search/Replace functionality.
  • The Data Tools product Help, available from the Help > Help Contents menu options, is out of date. For up-to-date documentation, use the online product Help.
Parent topic: Data Tools


Supported File Types

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

The file service and editor support the following file types:

  • Indexed files
  • Variable Block (VB) files
  • Fixed Block (FB) files
  • Line Sequential files (file service support only)
  • Relative files (file service support only)
Restriction: Currently, the following types are not supported:
  • ESDS files
  • Extended ESDS files
  • Files stored via the Micro Focus Database File Handler (MFDBFH)
Parent topic: Data Tools


File Service API

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

Data Tools uses a REST-based file service API to access, move, and edit data files located on remote servers.

The file service API supports the following functions when using the command line:

  • Request file information from local and remote data servers
  • Create new files with specific parameters
  • Edit data files
Restriction: The file service is only available on Windows and AIX platforms.
  • Set up the File Service
    Before you open data files in the Record Editor, you need to configure the file service API through Enterprise Server Common Web Administration (ESCWA).
  • File Service Interactive API Library
    The file service API library documents all possible file requests.
Parent topic: Data Tools


Set up the File Service

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

Overview of the setup process

You need to manually configure the file service in ESCWA so that it connects to the Data Tools client, that is, the file editor UI. Currently, the setup supports using remote data servers, not local servers. Enterprise Server default security must be enabled, otherwise the file service will reject any connection attempts.

The process for setting up the file service is as follows:

  1. Open the ESCWA web UI.
  2. Create an RFA (remote file access) listener.
  3. Enable security for the enterprise server region.
  4. Allow user access to the cataloged datasets.

Start Enterprise Server Common Web Administration (ESCWA)

  1. In a web browser, type the URL http://localhost:10086.

    This starts the ESCWA UI in a browser.

  2. Click Native.
  3. In the navigation pane, expand Directory Servers > Default to view existing enterprise server regions.

The following sections assume that an enterprise server region has been created and is visible in ESCWA.

Add an RFA listener

To set up a new listener that communicates with the end-point client:

  1. Go to Directory Servers > Default > <RegionName>. Ensure that the region is not running.
  2. Click General > Listeners.
  3. Expand Communications Process 1 to view all listeners.
  4. Select New Listener in the Listener Properties page.
  5. In the Name field, type the name you want to assign to the listener, for example, RFA.
    Note: The listener name cannot be the same as the name of the region.
  6. In the Port field, enter the port number you intend to use.
    Note: The hostname and/or IP address can be set to localhost and 127.0.0.1 respectively to limit access to the service to the local machine, which provides additional security. If localhost is not specified, you should enable TLS, otherwise user credentials and file details will be transmitted unencrypted across the network.
  7. Select RFA in the Conversation Type section.
  8. If you want to define a TLS enabled file service listener:
    1. Click TLS Settings.
    2. Check Enable TLS.
    3. Type the location of the CA certificate into the Certificate File field.
    4. Type the location of the private key into the Keyfile field.
  9. Click Save.

    The new RFA listener is displayed under Communications Process 1.

Enable security for the enterprise server region

The enterprise server region security must be configured. In addition, you must ensure that a user has the correct permissions; you can do this by creating a new user or edit the permissions of an existing user.

First, verify that security is enabled for the region:

  1. In ESCWA, select your enterprise server region in the navigation pane.
  2. Click General > Security to open the Region Security Facility Configuration page.
  3. Ensure that the option Use Default Security Facility Configuration is checked.

Configure the user permissions

Next, configure the user to enable access.

  1. In ESCWA, click Security.
  2. In the navigation pane, go to ESCWA Configuration > VSAM ESM > Users.
  3. If editing the permissions of an existing user, click [image] (Edit) to open the Properties window. Alternatively, you can create a new user and configure their permissions. To create a new user:
    1. Click New.
    2. In the Account Id field, enter an account name. In this instance, we will use the account ID RFAUSER for demonstration purposes.
    3. In the Password field, type a suitable password.
  4. Under Groups, check #AllUsrs.
  5. Click Save.

Now, you must configure the permissions of the user of the datasets in the data repository.

  1. Go to ESCWA Configuration > VSAM ESM > Resources.
  2. Expand DATASET, and select the datasets(s) that the user should be allowed to access.

    This opens the Resource Options page which allows you to set access rules for the chosen dataset.

  3. In the ACL field, type allow:<AccountId>:alter. As an example, for the user RFAUSER, you would type allow:RFAUSER:alter.

    This allows the user to view and modify the region's catalog. Alter access is required for the editor to open datasets.

  4. Click Apply.
  5. Click DATASET in the navigation pane.
  6. Click New Resource.
  7. In the Name field, type <RegionName>.<AccountId>.
  8. In the ACL field, type allow:<AccountId>:alter, and click Save.

    The class is added to the list of resources and you can view the permissions in the Description column. The region is ready for access via the file service API.

  9. To start the region, click Directory Servers > Default > <RegionName>, and click [image] (Start).
Parent topic: File Service API


File Service Interactive API Library

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

The API library is accessible at http://<hostname>/cobolfs/docs/, where hostname is the hostname of the configured RFA listener. For example, for a localhost file service using port number 9092, the API would be accessed from http://localhost:9092/cobolfs/docs/. The API library details all possible file service requests. This is an interactive client that allows you to copy and test requests.

Parent topic: File Service API


Troubleshooting Data Tools

Attention: This topic applies to a feature that is in Early Adopter Program (EAP) release status. We intend to provide the finalized feature in a future release. Please contact OpenText Support for Micro Focus Products if you require further clarification.

If you encounter any issues while using Data Tools, try troubleshooting using the following suggestions.

  • Firstly, when you encounter an issue with the editor, try to restart the editor. To do this, click File > Exit and reopen Data Tools.
  • Enable tracing for logging purposes:
    1. Open the .options file located in the Data Tools directory.
    2. Set com.microfocus.datatools.core/debug=true within the Core section.
    3. Open the file datatools.ini.
    4. Type the following at the end of the file: -debug.
    5. Save the file and return to the editor.
Parent topic: Data Tools


Data File Tools

  • Data File Editor
    Data File Editor is a standalone record editor in which to create and edit data files for use in your COBOL testing environment.
Parent topic: Data Files


Data File Editor

Data File Editor is a standalone record 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 edit existing data sets within your Enterprise Server regions if Enterprise Server is enabled.

The Data File Editor is a multi-tabbed environment in which you can have one or more data files open at the same time. Switching between tabs enables you to edit files simultaneously. Files may be open either in 'shared mode', allowing other users to also open the file with a shared file locking permission, or 'exclusive mode' where only you have permission to edit the file. You will only be able to open the file in exclusive mode if no other user has the file open.

This editor also provides a comprehensive filtering tool, enabling you to filter on only the records you require.

Data File Editor includes the following editors:

Data File Editor
The Data File Editor is a tabbed pane within the Data File Editor 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 Editor 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 Editor is a multi-tabbed environment in which you can have one or more data files and structure files open at the same time. Switching between tabs enables you to edit files simultaneously.

  • Current Restrictions
  • Accessing Data File Editor
  • Preferences
  • Using the Data File Editor
  • Using the Structure File Editor
Parent topic: Data File Tools


Current Restrictions

This version of Data File Editor has the following restrictions:
  • This version of Data File Editor 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 Editor from the Windows menu, ensuring no such filename manipulation variables are set at a system level.
  • The only supported UNIX platforms are SUSE, Red Hat, and AIX.
  • There is no support for Unicode files.
  • There is no file conversion functionality.
  • Earlier releases of this product used structure files with a .dfs extension. These files were a different structure to the conventional structure (.str) files. In this release and beyond, we have reverted back to the conventional .str files. If you use .dfs structure files, you must recreate those structure files.
  • There is no support for the following types of data file:
    • ACUCOBOL-GT (Vision)
    • IMS
    • RM/COBOL
  • You are unable to edit data that is marked within a structure file as floating point (COMP-2) data; this is to ensure that the internal representation of the floating point item is not corrupted.
  • 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.
  • When editing records, Insert mode does not work when using a layout to edit numeric fields; you can only edit numerics in Overwrite mode.
  • A limitation of the Windows clipboard means that when cutting or copying text from the editor, if the selection contains 0x00, any text after this character is truncated when pasted from the clipboard.
  • If you are setting MFCODESET, in order to use a particular character set, you must invoke the Data File Editor from the command line (in the environment in which MFCODESET is set); you cannot invoke it from the IDE if setting MFCODESET is required.
  • You cannot copy and paste the same record(s) in an indexed file type as that will create record(s) with a duplicated primary key.
  • When using the Find/Replace functionality with DBCS characters, you must enter the hexadecimal characters directly into the Hex pane. In order to do that, you must first enter some ANSI/EBCDIC text into the Find or Replace with fields, and then edit the resulting hexadecimal values, as appropriate.
  • When using a structure file containing multiple structures, the filter does not differentiate between corresponding fields (same offset and size) in different structures: when one of these fields in queried, the values from all corresponding fields are also used to filter the records.
Parent topic: Data File Editor


Accessing Data File Editor

The following sections describe how you can access Data File Editor.
  • Launching Data File Editor from a Command Line Prompt
  • Launching Data File Editor from the Start Menu
Parent topic: Data File Editor


Launching Data File Editor from a Command Line Prompt

Data File Editor can be launched from a command line prompt to open local files or catalogued files from an enterprise server region.

Local files
For local files use the following syntax:
mfdatatools2 [file-type][path][filename][option...]
file-type
This parameter is optional. If omitted, Data File Editor 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.
path
This parameter is optional. If specified, Data File Editor attempts to open the named file located in the path specified. If omitted, Data File Editor attempts to open the named file located in the current working directory.
filename
This parameter is optional. If specified, Data File Editor uses the path (if specified) and filename to open the file in the appropriate editor. If omitted, Data File Editor 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 Editor 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.
Catalogued data set
Use the following syntax to open a catalogued data set from an enterprise server region:
mfdatatools2 /dsn [data set name] [options...]
Parameter | Usage | Description
/dsn [data set name] | Required | Specifies the catalogued data set to be opened.
/host [host name] | Optional | Host name of the machine running Enterprise Server. The default value is localhost.
/port [port] | Optional | Port of the target region's Web Services and J2EE listener. The default value is 9003.
/user [user ID] | Optional | User ID for enterprise server region authentication.
/pwd [password] Conditional Password for enterprise server region authentication. Required if the /user parameter was specified.
Can either contain the password in clear text or an identifier to obtain the password from the mfsecrets vault. To obtain the password from the vault use:
mfsecret:vault_name:/secret_path
To use the default vault, use:
mfsecret:/secret_path

The password must be stored in the vault beforehand, for example by using the mfsecretsadmin utility. For more information, see Restricting Access to the Vault Facility.

/group [user group] | Optional | User group for enterprise server region authentication.
/fs [Fileshare name] | Optional | Name of the Fileshare server to use.
/tls | Optional | Enable TLS protocols to open the data set.
Example
mfdatatools2 /dsn MFI01V.MFIDEMO.BNKACC /host rhel-es01 /port 9006 /fs FS01 /user psmith /pwd mfsecret:/mySecrets/esPassword /tls

This opens the data set MFI01V.MFIDEMO.BNKACC from the enterprise sercver region with port 9006 (TLS-enabled) on host rhel-es01 using the Fileshare server FS01 and user ID psmith. The user password is obtained from the Micro Focus Secrets Vault under the path /mySecrets/esPassword.

Parent topic: Accessing Data File Editor
Related information
Launching Data File Editor from the Start Menu


Launching Data File Editor from the Start Menu

On Windows platforms, launch Data File Editor from the Start menu:

  • Click Start > All Programs > product-name > Data Tools > Data File Tools.
Parent topic: Accessing Data File Editor
Related information
Launching Data File Editor from a Command Line Prompt


Preferences

The Preferences section contains the following tabs:

Data File Editor

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 View previous set of records icon and View next set of records icon icons to navigate the pages of records.
Note: You must restart Data File Editor before any changes to this setting take effect.
Maximum number of requested data sets
Set the number of data sets requested when expanding an enterprise server region catalog in Data Explorer. When a catalog contains more data sets than requested, a More data sets in catalog stub will appear at the end of the data set list. It is recommended that you keep the number of requested data sets small and use filters to access specific data sets in large catalogs.

Default value: 100.

Maximum value: 5000.

Quick final page access
For large variable sequential files (files > 10,000 records), select this option to immediately jump to the last page of the file when it is opened. When this option is in effect, the last n records are displayed, as per the Records per page setting; from this point, you can navigate the file as normal.
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.
Copy and Paste to External Destination
This option sets a character to replace a NULL byte when copying a record to an external destination. By default, this character is set to a period. Use the Replace NULL character field to set the replacement character.
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.
Dialog boxes when using a temporary file
When using a temporary file whilst making edits, the default behavior is to not display the confirmation dialog boxes each time you update a record (as the record is only written to the temporary file, not data file, at this point). You can turn these confirmation messages back on whilst using a temporary file by clearing the option Do not show update warning when editing using temporary file.

Search

Max Record
When using filtering or find/replace on files in Fileshare, use this option to pause the operation every x records. This limits the performance impact on Fileshare, as the pause allows Fileshare to process other requests. The default value 0 will not set a limit.

Security

If you are connecting to an enterprise server using an SSL connection, use the Certificate Authority Trust Store setting to specify the trust store that contains the trusted root certificate used by the connection.

To use this setting requires that you have already created a trust store that includes a CA root certificate or (for non-production scenarios only) a self-signed certificate on your client, and that the enterprise server that you are connecting to has a valid server certificate (which is used to establish the server/client connection) and private key (for encryption) configured.

The required trust store is Java-specific, and so we recommend that to create the trust store, you use the keytool utility from the JDK that matches your version of Java. Type the following into a Enterprise Developer command prompt to create a trust store:

keytool -importcert -alias alias -keyalg alg -file CARootECcert.pem -keystore keystore.jks

where alias is the name of the certificate, alg is the name of the security algorithm to generate the key pair, and keystore.jks is the name of the trust store to be generated. Refer to the keytool utility documentation on the Oracle web site (http://docs.oracle.com/en/java/) for more information.

If your trust store is password protected, you must specify the password via the Java property javax.net.ssl.trustStorePassword:

-Djavax.net.ssl.trustStorePassword=myKeyStorePassword

To configure an enterprise server to use an SSL connection, create a listener that specifies the server certificate and keyfile. This type of listener does not automatically start when you start the enterprise server; it must be authorized after the server has started, by entering the key's passphrase, before the listener starts.

  • Set the Editor Preferences
Parent topic: Data File Editor


Set the Editor Preferences

  1. From the Data File Tools window, click Tools > Preferences, or click The Preferences icon (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 Editor before any changes to this setting take effect.
  3. To enable quick access (that is, immediate navigation to the end page of records) to a variable sequential file that has 10,000 records, select Quick final page access.

    This option takes effect immediately.

  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. To specify the replacement character for the NULL byte, enter the character in the Replace NULL character box. Otherwise the default character will be a period.
  6. 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.
  7. To display a confirmation message each time you update a record when using a temporary file, clear Do not show update warning when editing using temporary file; this gives the same behavior as when not using a temporary file.
  8. Click OK.

    The dialog box is closed.

Parent topic: Preferences


Using the Data File Editor

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.

Files may be open either in 'shared mode', allowing other users to also open the file with a shared file locking permission, or 'exclusive mode' where only you have permission to edit the file. You will only be able to open the file in exclusive mode if no other user has the file open.

As an additional security measure, Data File Editor contains a timeout mechanism, where if the editor is left open and inactive for 30 minutes, you receive a warning to say that any open data files will be automatically closed after a further two minutes inactivity, unless you cancel the warning message. If you do not respond to the warning, any open data files are closed, and any unsaved edits are lost.

  • 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.
  • Profile Files
    Profile files are side-files that supply file infrastructure details for files that do not contain file headers. The Data File Editor can read these files and apply the information to the data file.
  • Working with Different Character Sets
    Displaying and editing data from different character sets requires certain configuration of your environment, including installation of an Input Method if you are dealing with DBCS-encoded languages.
  • Viewing, Filtering and Printing Data Files
    Often, large data files can be difficult to scan or information within it can be difficult to locate. Data File Editor provides a number of tools to help display or locate information within formatted and unformatted data files.
  • Comparing Data Files
    Compare data files to one another, analyzing the contents to highlight the differences.
  • Viewing Merged Spool Files in the Data File Editor
    Administrators of a JES-enabled Enterprise Server can now merge archived spool files to one central location by running the Merge Archived Spool File process. After which, they can view them from one data file, from within the editor.
  • 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 Editor


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 are written into the file header for certain file organizations; those 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 profile file (.pro 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.

For non-indexed files, you can create them ready to edit with a temporary file, which writes your edits to a temporary file before they are committed to the actual data file. This allows you to revert the current edits before the data file is written to. See Editing Data Files for more information.

  • 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 Micro Focus Data File Tools window, select File > New, or click The New File icon (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 Editor was started.)
    • A Fileshare path: for example, $$FS-server-name\dat-name.dat.
  4. If you are applying a record layout 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 the structure (.str) file that contains the layout.
  5. In the File Details section, click [image] beside Format, then select the organization for the file.
  6. Click [image] beside Encoding, then select either ANSI or EBCDIC.
    Note: Once the file is created and open in the editor, you can switch between the two encodings.
  7. If the records will be of variable length, check Variable length records.
  8. Specify the Min Length (only applicable for variable length records), and Max Length values.
  9. Check Save details to save file details to a profile file.

    If selected, a new filename.pro file is created in the same location as the data file. When you next open the data file, the details saved to the profile file are used.

    Note: For certain file types, Save details is not available, because the details are stored in the file header of the data file instead.
  10. To edit the file using an additional temporary file, click Use a temporary file for editing. When enabled, all modifications are written to a temporary file during editing, before being saved to filename when Save all... is selected. This option will also give you the chance to revert any current edits without writing to filename when using the Revert all... option.
  11. 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 Micro Focus Data File Tools window, select File > New, or click The New File icon (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 Editor was started.)
    • A Fileshare path: for example, $$FS-server-name\dat-name.dat.
  4. If you are applying a record layout 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 the structure (.str) file that contains the layout.
  5. In the File Details section, click [image] beside Organization, then select Indexed.
  6. Click [image] beside Format, then select an indexed file format.
    Note: Not all indexed formats are compatible with the editor; those that are not, are not displayed.

    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.

    The Key Information dialog box

  8. Add a primary key:
    1. On the Key tab, click The Insert Before icon (Insert Before).

      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 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. Select Component 0, then 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 The Insert After icon (Insert After), select the new component and specify the key values.
      Tip: To delete a component, select it, then click The Delete Component icon (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 The Insert Before icon (Insert Before).

      An Alt Key <number> key is created, with a default component.

    3. In the 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 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. Select the Alt Key, then specify the Offset and Length values.

      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 The Insert After icon (Insert After), select the new component and specify the key values.
      Tip: To delete a component, select it, then click The Delete Component icon (Delete).
    8. Click OK. The alternate key is created.
  10. Click [image] beside Encoding, then select either ANSI or EBCDIC.
    Note: Once the file is created and open in the editor, you can switch between the two encodings.
  11. If the records will be of variable length, select Variable length records.
  12. 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.
  13. 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 the contents of a data file must be performed whilst the file is in exclusive mode, which places a lock on the file, so that others cannot also edit its contents. Once in edit mode, you have a number of tools to aid text manipulation, such as cut/copy/paste functions, duplicate entire records, and editing using hexadecimal values.

If you open a non-indexed file with the Use temporary file for editing option selected, which is available on the Open Data File and New Data File dialog boxes, edits are made in a temporary file before you commit them to the actual data file. This allows you to revert current changes, if required. If using a temporary file, [TEMP] is displayed in the file lock status indicator, beside EXCLUSIVE; you must use the Save all changes to file or Revert all changes to file to complete your edits.

Notes about cut/copy/paste: Copied records will have the same raw bytes as the original records, and maintains the encoding and data types. When pasted, record(s) will be trimmed to the maximum record length of the data file if they are too long.
  • Working with Data Sets in Enterprise Server
  • Working Directly with Data Files Hosted in a Database
  • Insert a Record
  • Edit an Unformatted Record
  • Edit a Formatted Record
  • Duplicate a Record
  • Layout and Field Validation
  • Edit a Record Using Hexadecimal Values
  • Delete a Record
Parent topic: Using the Data File Editor


Working with Data Sets in Enterprise Server

Important: If you plan to open a data set on an enterprise server region that was created prior to version 3.0 and it uses a non-default resource definition file (i.e. not the dfhdrdat file that is supplied with your product), then you must run the following from the command line before you start/restart the enterprise server region : caspcupg -dp=<resource definition path>.

You can access and edit existing data sets within an enterprise server region using Data File Editor. Opening 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 are opened by establishing a connection to either the ESCWA service, or directly to the listener of an enterprise server region. The Data Explorer allows you to maintain these connections, and open the resulting catalogs and data sets that you have permission to access.

When connecting to an ESCWA service, you potentially have access to catalogs for all regions within a Micro Focus Directory Server associated with the ESCWA service. Alternatively, you can connect directly to a region (the ESMAC method), to access only the data sets in that region's catalog.

Opening and editing a data set from Data File Editor is subject to the same permissions checks as you would expect if you were connecting directly to the enterprise server region. Further security measures are also taken, such as removing the full pathname of a data set from the File Information tab and the list of recent files.

If an external security manager is in place, you must enter valid logon credentials when attempting to open the data set. When opening and closing a data set, the ENQ and DEQ locking mechanisms are applied accordingly, and if the Audit Manager is running, file operations are recorded in the audit trails.

Disk-based 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 disk-based data sets on a remote enterprise server region (that is, a region not hosted on your local machine), 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 server before you open Data File Editor.
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 region.

For database-hosted data sets, you must ensure that a database configuration file (as referenced by the MFDBFH_CONFIG environment variable) contains connection details for the region and datastore that houses the desired file. If you are opening the Data File Editor from the IDE, set MFDBFH_CONFIG as a system variable before opening the IDE. See The Database Configuration File for more details on configuring the database configuration file.

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

  • Open an Enterprise Server Data Set through ESMAC (deprecated)
  • Open an Enterprise Server Data Set through ESCWA
  • Error Messages When Using Data File Editor with Enterprise Server
Parent topic: Editing Data Files
Related information
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Duplicate a Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a Record


Open an Enterprise Server Data Set through ESMAC (deprecated)

Note: The Enterprise Server Monitor and Control (ESMAC) interface has been deprecated. Micro Focus no longer supports ESMAC and will remove the feature in a future release. It has been provided for backward compatibility only. Micro Focus strongly recommends that you adopt the Enterprise Server Common Web Administration (ESCWA). See Enterprise Server Common Web Administration (ESCWA) for more information.
Before you start, you must ensure that the enterprise server region is running; additionally, if you are connecting to a remote enterprise server region, you must set the CCITCP2 environment variable in your environment to the IP address of the machine on which the region resides, and a Fileshare server must be running within the region.

This process allows you to connect to a catalog on a single enterprise server region; it is similar to the process of opening data sets in earlier versions of Micro Focus Data File Tools in that it takes the same connection details (host/port number).

  1. In the Micro Focus Data File Tools window, select File > Data Explorer, or click Data Explorer icon (Data Explorer).

    The Data Explorer opens in the left-hand pane.

  2. Click Down arrow and select Add Connection.

    The Data Source Settings dialog box is displayed.

  3. Click the ES Region tab.
  4. In the Enterprise Server Region section, enter the connection details for the region that contains the data set:
    1. In the Host field, type the network name or IP address of the region containing the data set.
    2. In the ESMAC Port field, enter the port number.
      Note: To locate the ESMAC port number, view the Listeners page of the region. The port number is displayed after the IP address and colon for the Web Services and J2EE listener (non-SSL connections) or the SSL-enabled listener (SSL connections).
    3. If the connection is via SSL, check Use SSL.

      For more information about enabling SSL connections, see the Security section in Preferences.

  5. In the Authentication section, if the region has an external security manager enabled, type the ID, password, and group for a user that has access to the data set you intend to edit. If the region does not have an external security manager enabled, do not enter any details in these fields.
    Tip: before you connect to ESMAC, you can test your connection details: click Test.
  6. In the Filter section, to initially filter the data sets that are retrieved, in the DSN Filter field, type a data set name filter (for example: MFIJCL.*.*.DATA).
    Note: To further control filter behavior, use Disable Additional Qualifiers. Use this option to make catalog searching and filtering more consistent with the results produced on the mainframe. Check the option to disable the use of additional qualifiers when filtering the catalog results. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B (as if A.B** had been entered).
  7. Click Apply.

    If you are connecting to an unsecured server, an 'Insecure Connection' warning is displayed. See the Use SSL option above to connect securely.

    The catalog associated with the enterprise server region is displayed in the Data Explorer, showing the enterprise server regions you have permission to view.

    If you only want to display a subset of the data sets in the catalog, click Filter icon (Filter), then in the Filter dialog box, type a data set name filter (for example: MFIJCL.*.*.DATA) and click Confirm.

    Note: To further control filter behavior, use Disable Additional Qualifiers. Use this option to make catalog searching and filtering more consistent with the results produced on the mainframe. Check the option to disable the use of additional qualifiers when filtering the catalog results. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B (as if A.B** had been entered).
  8. To open a data set, double-click it from the list displayed underneath the region node.

    The Specify Fileshare Name dialog box appears.

  9. If you are opening a data set on a remote enterprise server region, in the Fileshare Server section, check Use Fileshare, type the name of a Fileshare server running on the remote region, and click OK. (If the region is on this machine, you do not need to enter any details: clear Use Fileshare and click OK.)

    The Open Data File dialog box appears.

  10. 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.
Tip: If you want to remove an existing connection from the Data Explorer, click Settings icon (Settings) to the right of the connection name, and then on the Data Source Settings dialog box, click Delete.
Parent topic: Working with Data Sets in Enterprise Server
Related concepts
Preferences
Related information
Open an Enterprise Server Data Set through ESCWA
Error Messages When Using Data File Editor with Enterprise Server
CCITCP2


Open an Enterprise Server Data Set through ESCWA

Before you start, you must ensure that the enterprise server region is running; additionally, if you are connecting to a remote region, you must set the CCITCP2 environment variable in your environment to the IP address of the machine on which the region resides, and a Fileshare server must be running within the region.

This process allows you to work with multiple catalogs at the same time: connecting to an ESCWA service potentially gives access to each Micro Focus Directory Server associated with the service, and in turn, access to each catalog for the regions within each directory server. If you are connecting using SSL, you need to add both the ESCWA endpoint and each region's endpoint that you need to work with to your Certificate Authority Trust Store, because Micro Focus Data File Tools needs to connect to a region directly, to ENQ/DEQ the data set.

  1. In the Micro Focus Data File Tools window, select File > Data Explorer, or click Data Explorer icon (Data Explorer).

    The Data Explorer opens in the left-hand pane.

  2. Click Down arrow and select Add Connection.

    The Data Source Settings dialog box is displayed.

  3. Click the ESCWA tab.
  4. In the Enterprise Server Common Web Administration section, enter the connection details for the ESCWA service:
    1. In the Host field, type the network name or IP address of the ESCWA service containing the enterprise server region that houses the required data set.
    2. In the ESCWA Port field, enter the port number.
    3. If the connection is via SSL, check Use SSL.

      For more information about enabling SSL connections, see the Security section in Preferences.

  5. In the Authentication section, if ESCWA has an external security manager enabled, type the ID and password for a user that has access to the data set you intend to edit. If ESCWA does not have an external security manager enabled, do not enter any details in these fields.
    Tip: before you connect to ESCWA, you can test your connection details: click Test.
  6. Click Apply.

    If you are connecting to an unsecured server, an 'Insecure Connection' warning is displayed. See the Use SSL option above to connect securely.

    The directory server associated with the ESCWA service are displayed in the Data Explorer.

  7. If an external security manager is also enabled at the directory server and/or region levels, at each point that requires additional credentials, click Settings icon (Settings), enter the required credentials, then click Logon. After which, you can expand a node of an enterprise server regions that you have permission to view to display the catalog associated with that region.
  8. Expand the required region node to display the catalog. If you only want to display a subset of the data sets in the catalog, click Filter icon (Filter), then in the Filter dialog box, type a data set name filter (for example: MFIJCL.*.*.DATA) and click Confirm.
    Tip: To further control filter behavior, use Disable Additional Qualifiers. Use this option to make catalog searching and filtering more consistent with the results produced on the mainframe. Check the option to disable the use of additional qualifiers when filtering the catalog results. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B (as if A.B** had been entered).
  9. To open a data set, double-click it from the list displayed underneath the region node.
    The Specify Fileshare Name dialog box appears.
    Note: If you specified a database-hosted data set, this dialog box is not shown, and you can skip the next step.
  10. If you are opening a data set on a remote enterprise server region, in the Fileshare Server section, check Use Fileshare, type the name of a Fileshare server running on the remote region, and click OK. (If the enterprise server region is on this machine, you do not need to enter any details: clear Use Fileshare and click OK.)

    The Open Data File dialog box appears.

  11. 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.
Tip: If you want to remove an existing connection from the Data Explorer, click Settings icon (Settings) to the right of the connection name, and then on the Data Source Settings dialog box, click Delete.
Parent topic: Working with Data Sets in Enterprise Server
Related information
Open an Enterprise Server Data Set through ESMAC (deprecated)
Error Messages When Using Data File Editor with Enterprise Server


Error Messages When Using Data File Editor with Enterprise Server

The follow messages relate to using the Data File Editor to view or edit data sets when connecting to an enterprise server:

Message | Description
User does not have sufficient access to perform the operation | The user does not have permission to perform a certain action, such as getting the list of data sets, or modifying them.
User does not have sufficient access to this dataset's DCB | The user does not have permission to read and write to the data set.
User and password combination not found | Invalid user or password entered in the Authentication section.
Please enter a password | This message depends on how the security manager is set up. Some default/common users may not be required to provide passwords; however, other users must specify a password.
Signon error | This is a generic error for which the cause may not be known. If you receive this error, contact OpenText Support for Micro Focus Products.
DSN cannot be found | The data set being viewed is no longer available. It may have been deleted or removed from the catalog.
Dataset has been dequeued by Enterprise Server The enterprise server has performed a dequeue on the data set and has made it available to other users. This could be for the following reasons:
  • The enterprise server is using a non-default CICS resource definition, which requires upgrading to support this feature.
  • The Data File Editor has stopped performing its regular comms checks with the server, and therefore enterprise server has assumed that Data File Editor is no longer working, and has released the lock on the data set. For such a problem, you will need to contact OpenText Support for Micro Focus Products.
  • An error has occurred on the enterprise server, causing it to not be able to maintain the lock on the data set. For such a problem, you will need to contact OpenText Support for Micro Focus Products.
Failed to connect to port <port> The connection is refused at the ESMAC port that you are attempting to connect to. You should make sure that:
  • You have entered the correct ESMAC port number.
    Note: To locate the ESMAC port number, view the Listeners page of the region. The port number is displayed after the IP address and colon for the Web Services and J2EE listener (non-SSL connections) or the SSL-enabled listener (SSL connections).
  • The correct port can be reached. A firewall may be preventing connections to that port; if this is the case, you must configure the firewall to allow the connection.
Connection refused. Please check the types of connection allowed at <host>:<port> | This error may depend on whether the Use SSL option is enabled or not: the type of connection that you are trying to perform may not be allowed at <host>:<port>. For example, the server socket at <host>:<port> may only allow SSL connections, but you do not have Use SSL checked.
Could not find host <host>The host which user is trying to connect does not exist | The specified host does not exist. Check the host name specified in the Host field.
The client level of security does not match that of the server | The server and the client cannot negotiate the desired level of security. A common problem is that, for SSL connections, the encryption algorithm used by the server is not supported by the client. In this is the case, check what version of Java is running on your client machine, and ensure that it supports the encryption algorithm running on the enterprise server. If there is a mismatch, you must update either the client or the server so that they use the same encryption.
Failed to connect because of bad SSL key | This normally indicates that the configuration of the server or client SSL certificate and private key is incorrect. Check that they have been generated and are configured correctly.
Failed to connect to <host>:<port> This is a generic error. If you receive this error, check that the correct details are specified in the Host and ESMAC Port fields, then ensure that the server is running and the port is listening. Also ensure that any firewall in effect is configured to allow the type of connection being performed.

If this error persists, contact OpenText Support for Micro Focus Products.

Parent topic: Working with Data Sets in Enterprise Server
Related information
Open an Enterprise Server Data Set through ESMAC (deprecated)
Open an Enterprise Server Data Set through ESCWA


Working Directly with Data Files Hosted in a Database

Restriction: Currently, this feature only supports KSDS formatted VSAM files.

Within the Data File Editor, you can use the Data Explorer to directly open files hosted by the Micro Focus Database File Handler (MFDBFH); that is, not accessing them via the catalog.

Use this method if you cannot access database-hosted files through those methods described in Working with Data Sets in Enterprise Server. It can be useful when there are connection problems to the Enterprise Server region in which they are cataloged.

However, care must be taken when accessing them directly, as errors can occur in the JCL engine if it attempts to use a file that you currently have open. Also, resource locking (ENQ/DEQ) is not supported when opening a database-hosted file in this way, which could cause undesired results if a file is edited by multiple users at once.

Tip: You can disable this particular method of opening by setting DT_ENABLE_MFDBFH=false before starting the Data File Editor: this disables the MFDBFH settings required for the Data Explorer.
When working with database-hosted files in the Data File Editor, you must ensure that a database configuration file (as referenced by the MFDBFH_CONFIG environment variable) contains connection details for the datastore that houses the desired file. If you are opening the Data File Editor from the IDE, set MFDBFH_CONFIG as a system variable before opening the IDE. See The Database Configuration File for more details on configuring the database configuration file.
Note: To save new data files to a datastore, you must use the upload process detailed in Datastore Management.
  • Open a File Through MFDBFH
    To directly open a file that is hosted using MFDBFH, add a connection to the Data Explorer by specifying the server and datastore in which the file is stored.
Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Duplicate a Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a Record


Open a File Through MFDBFH

To directly open a file that is hosted using MFDBFH, add a connection to the Data Explorer by specifying the server and datastore in which the file is stored.
  1. In the Micro Focus Data File Tools window, select File > Data Explorer, or click Data Explorer icon (Data Explorer).

    The Data Explorer opens in the left-hand pane.

  2. Click Down arrow to the right of the default connection, select the required connection (datastore connections are prefixed sql://), and then click Reload (Reload); if a connection does not already exist, you need to create one:
    1. Click Down arrow and select Add Connection.

      The Data Source Settings dialog box is displayed.

    2. Click the MFDBFH tab.
    3. In the Micro Focus Native Database File Handling section, enter the connection details for the MFDBFH datastore:
      Note: The following details must be the ones that correspond to the details configured in the database configuration file that is in effect. The path to this file, which is determined by the MFDBFH_CONFIG variable, is displayed in the Configuration File field. If these options are unavailable, set the DT_ENABLE_MFDBFH=true environment variable and restart Micro Focus Data File Tools.
      • Server - the server or instance name that houses the datastore.
      • Datastore - the name of the datastore.
  3. In the Filter section, to initially filter the data sets that are retrieved, in the DSN Filter field, type a data set name filter (for example: MFIJCL.*.*.DATA).
    Note: To further control filter behavior, use Disable Additional Qualifiers. Use this option to make catalog searching and filtering more consistent with the results produced on the mainframe. Check the option to disable the use of additional qualifiers when filtering the catalog results. For example, when checked, a filter of A.B would only return a data set of A.B. This option emulates the effect of disabling the 'Include Additional Qualifiers' option on the mainframe. When unchecked, a filter of A.B would return all data sets starting A.B (as if A.B** had been entered).
  4. Click Apply.

    The available files are displayed in the left-hand pane.

  5. Double-click the required file.

    The Open Data File dialog box appears.

  6. Complete the Open Data File dialog box, and then use the Data File Editor as you would for any other data file.
Parent topic: Working Directly with Data Files Hosted in a Database


Insert a Record

Note: A new record is immediately padded to its minimum length with the character you specify in the Preferences section.
  1. In the Micro Focus Data File Tools window, ensure you have a data file open. If you are in Shared mode, click The Switch to Exclusive Mode icon (Switch to Exclusive Mode).
  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 Structure dialog box appears.

    The Select Structure dialog box

  3. Select the required layout from the structure file in use, then click OK. (An additional layout (Use padding byte) is also available, which is always equal to the minimum record length of the file, and when selected initializes each field to the padding character specified in the Preferences section.)

    The record length is set according to the selected layout; the fields are initialized to default values (according to the field type); however, if you have selected a conditional layout, it is not displayed until the conditions within it are met.

    The green bar indicates where the record will be inserted.

    Data file showing record insertion indicator

    The editor switches to Insert mode, as indicated in the status bar.

    Insert Mode indicator 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.

    For files with variable record lengths that are not using a layout, the length of any new record defaults to the file's minimum record length, but you can enter text up to the record's maximum length.

  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 The Save Record icon (Save Record) to save the record.
  7. If you are not using a temporary file for your edits, you are prompted to save the new record to the file: click Yes to confirm. If you are using a temporary file for your edits (indicated by [TEMP] displayed in the file lock indicator), click Save all changes to file icon (Save all changes to file) after all your edits are made.
Parent topic: Editing Data Files
Related concepts
Create an Indexed Data File
Create a Non-indexed Data File
Related reference
Preferences
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Edit an Unformatted Record
Edit a Formatted Record
Duplicate a 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. You can load and unload structure files whilst a data file is in the editor; see Load and Unload Structure Files.
  1. In the Micro Focus Data File Tools window, ensure you have an unformatted data file open. If you are in Shared mode, click The Swich to Exclusive Mode icon (Switch to Exclusive Mode).
  2. Select the required record to edit, then click The Edit Record icon (Edit Record).

    The record text in the bottom pane becomes editable.

    The editing field in an unformatted record

  3. Edit the text in the bottom pane, then click The Save Record icon (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. Press Ins or Insert on your keyboard to toggle between the modes; the current mode (INS or OVR) is displayed in the status bar at the bottom of the screen.
  4. Click Yes to confirm.

    The record is updated.

  5. If you are using a temporary file for your edits (indicated by [TEMP] displayed in the file lock indicator), click Save all changes to file icon (Save all changes to file); otherwise, the changes are saved to the data file automatically.
Parent topic: Editing Data Files
Related concepts
Load and Unload a Structure File
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit a Formatted Record
Duplicate a 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. You can load and unload structure files whilst a data file is in the editor; see Load and Unload Structure Files.
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.
EAP feature:

In Insert mode, when you edit PIC X fields with EBCDIC data, the required SOSI characters are added at the start and end of the edited text; you can view the added characters (0E and 0F) when the Hex pane is displayed. These characters are not added if you are editing an unformatted record or editing directly from the Hex pane.

  1. In the Micro Focus Data File Tools window, ensure you have a formatted data file open. If you are in Shared mode, click The Switch to Exclusive Mode icon (Switch to Exclusive Mode).
  2. In the left-hand pane, select the required record to edit.
  3. In the right-hand pane, select the field to edit, then click The Edit Record icon (Edit Record).

    The field becomes editable.

    The editable field in a formatted record

  4. Edit the text in the field, then click The Save Record icon (Save Record).
  5. Click Yes to confirm.

    The record is updated.

  6. If you are using a temporary file for your edits (indicated by [TEMP] displayed in the file lock indicator), click Save all changes to file icon (Save all changes to file); otherwise, the changes are saved to the data file automatically.
Parent topic: Editing Data Files
Related concepts
Load and Unload a Structure File
Working with Different Character Sets
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit an Unformatted Record
Duplicate a Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values
Delete a Record


Duplicate a Record

  1. In the Micro Focus Data File Tools window, ensure you have a non-indexed data file open. If you are in Shared mode, click The Switch to Exclusive Mode icon (Switch to Exclusive Mode).
  2. Select the required record to duplicate, then use one of the following:
    • On the Edit menu, click Duplicate Record.
    • Right-click the record, then select Duplicate Record.
    • Press F5.
    • On the Edit menu, click Copy (or press Ctrl+C), and then on the Edit menu, select Paste Before (or press Ctrl+Alt+V) or select Paste After (or press Ctrl+V).
    Tip: You can select multiple consecutive records to duplicate at once using one of the following selection methods:
    • To select a range of records, click on the first record you need, then hold the SHIFT key and click on the last record you need.
    • To select all records in the current page, press CTRL + A.

    The record is duplicated.

    Note: Duplicated records are saved automatically unless you are using a temporary file during editing; in which case, you must use the Save all... or Revert all... option after the record has been duplicated.
Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit an Unformatted Record
Edit a Formatted 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 The invalid record icon displayed beside the name of the layout in use. In the case of an invalid field, asterisks are 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, The valid record icon 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).

  • Fix Validation Warnings
Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Duplicate a Record
Edit a Record Using Hexadecimal Values
Delete a Record


Fix Validation Warnings

  1. In the Micro Focus Data File Tools window, ensure you have a formatted data file open.
  2. Select the required record to edit, then click The Edit Record icon (Edit Record) to enter Edit mode.
    Tip: A record that has an invalid field displays The invalid record icon beside the name of the layout it is using in the layout pane.
  3. (optional) To re-initialize the field to a default value:
    1. Click the Value column for the required field.
    2. At the prompt, click Yes. The field is re-initialized to a default value, which depends on the picture definition.
  4. Click the current field value in the text box beneath the layout, then edit it accordingly.
  5. Edit the text in the bottom pane, then click The Save Record icon (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. Press Ins or Insert on your keyboard 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 if all fields are now valid, The valid record icon is displayed beside the name of the layout.

Parent topic: Layout and Field Validation


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 Micro Focus Data File Tools window, ensure you have Hex View enabled; see Show Contents of a Data File in Hexadecimal. If you are in Shared mode, click The Switch to Exclusive Mode icon (Switch to Exclusive Mode).
  2. Double-click the record that you want to edit.
  3. 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.

    The Hex pane

  4. Type a new two-digit/character hex pair, then click The Save Record icon (Save Record).
    Note: You cannot enter a numerical or character value if it results in an invalid hex pair.
  5. If you are not using a temporary file for your edits, you are prompted to save the updated record to the file: click Yes to confirm. If you are using a temporary file for your edits (indicated by [TEMP] displayed in the file lock indicator), click Save all changes to file icon (Save all changes to file) after all your edits are made.
Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Duplicate a Record
Layout and Field Validation
Delete a Record
Show the Contents of a Data File in Hexadecimal


Delete a Record

  1. In the Micro Focus Data File Tools window, ensure you have the required data file open. If you are in Shared mode, click The Switch to Exclusive Mode icon (Switch to Exclusive Mode).
  2. In the left-hand pane, right-click the required record, then click Delete Record.
    Tip: You can select multiple records to delete at once using one of the following selection methods:
    • To select a range of records, click on the first record you need, then hold the SHIFT key and click on the last record you need.
    • To select multiple non-consecutive records, hold the CTRL key while you click on required records.

      You can also use a combination of these two methods to select multiple records.

    • To select all records in the current page, press CTRL + A.
  3. If you are not using a temporary file for your edits, you are prompted to confirm the deletion from the file: click Yes to confirm. If you are using a temporary file for your edits (indicated by [TEMP] displayed in the file lock indicator), the record is removed, and you must click Save all changes to file icon (Save all changes to file) after all your edits are made to confirm deletion.
    Note: If you delete a record in error whilst using a temporary file, click Revert all changes icon (Revert all changes) to restore the deleted records.
    Tip: You can also delete records by cutting them using the Cut option on the Edit menu, or pressing Ctrl+X.
Parent topic: Editing Data Files
Related information
Working with Data Sets in Enterprise Server
Working Directly with Data Files Hosted in a Database
Insert a Record
Edit an Unformatted Record
Edit a Formatted Record
Duplicate a Record
Layout and Field Validation
Edit a Record Using Hexadecimal Values


Profile Files

Indexed data files contain a file header that describes the format and organization of the file. When opening an indexed data file, the Data File Editor reads the header information and uses it to format the file in the editor.

Other files, such as line sequential, fixed-length sequential and fixed-length relative files do not have file headers, and therefore the Data File Editor cannot determine the format and organization by reading the data file directly. To enable the Data File Editor to obtain the file information required to properly render a data file, you can create a profile (.pro) file containing that information.

When you create a non-indexed data file, the Open Data File dialog box enables you to create a profile file containing the header details that you specify in the File Details section. By default, the profile file is created in the same directory as the data file, using the same file prefix as the data file, plus a .pro extension.

The Save Details to profile file option

When you edit the same data file again, Data File Editor automatically loads the header information contained in the profile file. If you try to open a line sequential, fixed-length sequential or fixed-length relative file that has no profile file, the Data File Editor will prompt you for file header details each time you open it.

Parent topic: Using the Data File Editor


Working with Different Character Sets

The Data File Editor enables you to view and edit data within a variety of character sets, including for DBCS-encoded languages such as Japanese, Chinese and Korean.

To set the environment on Windows, set the system locale to the country associated with the character encoding you plan to use; alternatively, if you run the Data File Editor from the command line, you can set the MFCODESET variable to the appropriate country code - refer to Supported Country Codes, in the main product documentation, for a list of available codes. Then, set the Windows display language to the appropriate language.

To set the environment on UNIX, set the system locale to the country associated with the character encoding you plan to use (the lang variable), and then set the MFCODESET variable - refer to Supported Country Codes, in the main product documentation, for a list of available codes.

If you are dealing with DBCS-encoded languages, you also need to install and use an input method or IME in order to edit in those languages. Microsoft provides one as part of Windows: use the Region and Language settings to install the required language pack(s), and then use the keyboard input method as shown in the system tray. You can also use other input methods, but the Microsoft offering is the recommended one for the Data File Editor.

On UNIX, the available input method will vary on different UNIX/Linux platforms, so consult your system documentation to find a suitable solution.

After setting the environment, characters from that encoding scheme should display correctly in the editor (whereas, previously they would be displayed as ?). For DBCS character sets, data input is carried out using the input method currently enabled.

If you are working with EBCDIC data, the DBCS characters require shift-out and shift-in (SOSI) control characters at the start and end of the DBCS data. When editing a formatted record, the editor will automatically add these characters to any PIC X fields as long as you are editing in insert mode. You can see the added characters (0E and 0F) when the Hex pane is displayed. These characters are not automatically added if you are editing an unformatted record or editing directly from the Hex pane.

Parent topic: Using the Data File Editor
Related reference
Supported country codes
Edit a Formatted Record


Viewing, Filtering and Printing Data Files

Often, large data files can be difficult to scan or information within it can be difficult to locate. Data File Editor 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.

Structure files can be specified when a data file is opened, or you can load and unload structure files to a data file that is already open.

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 use a filter. The filter allows you to use multiple criteria in order to filter the records that are displayed, either by only including matching records, or by omitting the matching records from view. After the filter has been applied, you can switch between the entire file and the filtered results.

You can print data records by clicking File > Print or by using the shortcut Ctrl + P. In the Print dialog, you can adjust the range of records to print and select additional print options.

  • View File Information
  • Filtering a Data File
  • Load and Unload a Structure File
  • Navigate a Data File
  • Show the Contents of a Data File in Hexadecimal
  • Find and Replace Information in a Data File
  • 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 Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. In the File group, click The File Information icon (File Information).
    Basic file information for the selected file appears.
    Note: If you are opening a data set from Enterprise Server, the physical file location is not displayed.
  6. Click OK to close the dialog box.
Parent topic: Viewing, Filtering and Printing Data Files
Related information
Filtering a Data File
Load and Unload a Structure File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Find and Replace Information in a Data File
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 sets of conditions, and you can produce filtered results that include or exclude records matching all or any one of those sets.

There are two types of condition that you can use within each set:

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 positions 7 to 9 within each record, as indicated below

Example showing a reference condition selection

Field condition
This type of condition is only available if you have applied a layout to your data file. A field condition allows you to select a field name from the layout instead of having to manually specify a start and end position on which to base your filter. You can select any non-group field in the layout.

For both types of condition, you select an appropriate data type, an operator (for example, greater than, contains, or not equal to), and a value that you wish to filter on.

Data File Editor 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.

Note about remote filtering: When dealing with data files on a remote Fileshare server (see Opening a Data Set in Enterprise Server), there may be performance differences depending on the version of the server. Product versions from 5.0PU13 or 6.0PU3 onwards support server-side filtering, which performs the filtering on the remote server, and then only returns the filtered records to the client: this significantly improves performance. Filtering files using a Fileshare server older than this results in all records being downloaded locally before being filtered.

There is also a deprecated filtering function from earlier versions of the editor. It is currently available because it contains some functionality not yet available in the new version. As the new version matures, the older version may be removed.

  • Filter the Data File
  • Filter the Data File (Deprecated)
  • Filter Data Types
  • Filter Operators
Parent topic: Viewing, Filtering and Printing Data Files
Related information
View File Information
Load and Unload a Structure File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Find and Replace Information in a Data File
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Filter the Data File

The results of a filter include or exclude each record that contains data that satisfies the filter's condition sets.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. In the Filter group, click The Filter icon (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 condition sets.

  6. To add a new set, click New Set.

    The relationship indicator is displayed in the Condition Set column; this determines the relationship between the conditions within the set.

  7. Click the indicator, and select the required relationship:
    Option | Description
    AND | All conditions in the set must be satisfied.
    OR | Only one condition in the set must be satisfied.
  8. You must now add one or more conditions to the set:
    • 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:

        Example showing a reference condition selection

      3. In the Data Types field, click [image] and select the type of text to filter.
        Tip: Hover over each option for a description of the type.
      4. In the Operator field, click [image] and select the required operator.
      5. In the Value field, enter the filter value.
    • 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.
        Restriction: When using a structure file containing multiple structures, the filter does not differentiate between corresponding fields (same offset and size) in different structures: when one of these fields in queried, the values from all corresponding fields are also used to filter the records. You cannot select Group fields.

        The Data Types 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.
    Note: You can nest sets within other sets: simply click New Set and configure the set as described above. The results of the set's conditions are then compared with the other conditions and sets in its parent set, and then filtered accordingly.
  9. At the top of the dialog box, select Include (to show records that satisfy the condition sets), or Omit (to remove the records that satisfy the condition sets).
  10. Click Filter.

    The results appear.

    Tip: At this point, you can export the filtered results to a new file using the Search > Export Results option.
  11. You can toggle between the results and the original file by clicking [image] in the Filter group and select None or Filtered.
  12. In the Filter group, click The Filter icon (Filter) again and the last set of conditions that were used is displayed, where you can amend, add or delete conditions, then click Filter again to refine the results of the filter.
Parent topic: Filtering a Data File
Related reference
Preferences
Related information
Filter the Data File (Deprecated)
Filter Data Types
Filter Operators


Filter the Data File (Deprecated)

CAUTION:
These instructions are for the old filter functionality, which is now deprecated. It does not support the faster remote filtering available when used with newer Fileshare Servers. However, it does include some features not currently available in the new filtering model, such as case insensitive query, checking fields with valid structure, and DBCS query.

The results of a filter include each record that contains data that satisfied the conditions.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. On the Search menu, select Filter (Deprecated).

    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:

      Data file excerpt showing referenced positions

    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.

    The Filter dialog box showing the Match One Match All options

  9. Click Filter.

    The results appear.

    Tip: At this point, you can export the filtered results to a new file using the Search > Export Results option.
  10. You can toggle between the results and the original file by clicking [image] in the Records field and select All or Filtered.
  11. In the Filter group, click The Filter icon (Filter) again and the last set of conditions that were used is displayed, where you can amend, add or delete conditions, then click Filter again to refine the results of the filter.
Parent topic: Filtering a Data File
Related information
Filter the Data File
Filter Data Types
Filter Operators


Filter Data Types

The following list of data types are available when adding a new filter:

Data Type | Description
Alphanumeric
CH | Characters (Pic X display) * Also applicable for normal plain text search
SS | Substring search (Pic X display) * Also applicable for normal substring search
Displayed Numeric
NU | Numerics (Pic 9 display) * Also applicable for numerics in plain text
ZD | Zoned decimal, signed (Pic S9 display)
CLO/OL | Signed numeric, leading overpunch sign (Pic S9 leading included)
CTO/OT | Signed numeric, trailing overpunch sign (Pic S9 trailing included)
CSL/LS | Signed numeric, leading separate sign (Pic S9 leading separate)
CST/TS | Signed numeric, trailing separate sign (Pic S9 trailing separate)
Packed Numeric
PD | Packed decimal, signed (Pic S9 Comp-3)
PD0 | Packed decimal, with sign and first digit ignored
C6 | (Comp-6)
Binary Numeric
C5 | (Pic 9 Comp-5)
S5 | (Pic S9 Comp-5)
CX | (Comp-X)
Decimal
BI | Binary, unsigned (Comp)
FI | Fixed point, signed (Comp)
FL | Floating point, signed (Comp-1, Comp-2)
Parent topic: Filtering a Data File
Related information
Filter the Data File
Filter the Data File (Deprecated)
Filter Operators


Filter Operators

Note: Some of these operators are only applicable to the deprecated filtering version.

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
Filter the Data File (Deprecated)
Filter Data Types


Load and Unload a Structure File

You can switch between a formatted and an unformatted view of the data file by loading and unloading structure files. If a structure file was already applied when the data file was opened, you can unload it and load another structure file.
  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. If the data file is displayed unformatted, on the Structure menu, click Load Structures, and then use the Open dialog box to select a structure file. The structure file is applied to the data file.
  6. If the data file is already displayed formatted, do one of the following:
    • On the Structure menu, click Load Structures, and then use the Open dialog box to select a structure file.

      The structure file is applied to the data file.

    • On the Structure menu, click Unload Structures.

      The current structure file is removed from the data file, and the data file is displayed unformatted.

Parent topic: Viewing, Filtering and Printing Data Files
Related information
View File Information
Filtering a Data File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Find and Replace Information in a Data File
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Navigate a Data File

There are a number of techniques that enable you to navigate around the data file.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    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, use the cursor keys.
    • To move forwards or back a page, click The previous record icon and The next record icon.
      Note: Each page contains a maximum of 100 records, configurable from the Preferences dialog box.
    • Click First or Last to jump to the first or last page of records.
    • To jump directly to a particular record, click The Go to icon (Go to) then enter the record number in the Record Number field and click OK; alternatively, click the record in the Data File pane.
      Note: If you enter a record number that exceeds the number of records in the file, you are taken to the last record in the file.
Parent topic: Viewing, Filtering and Printing Data Files
Related information
View File Information
Filtering a Data File
Load and Unload a Structure File
Show the Contents of a Data File in Hexadecimal
Find and Replace Information in a Data File
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 Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. In the Appearance group, click The Toggle Hex icon (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.

    The Hexadecimal pane

    Tip: You can edit the hex values directly; see Edit a Record Using the Hexadecimal Values.
  6. To hide the Hex pane, click The Toggle Hex icon (Toggle Hex) again.
Parent topic: Viewing, Filtering and Printing Data Files
Related tasks
Edit a Record Using Hexadecimal Values
Related information
View File Information
Filtering a Data File
Load and Unload a Structure File
Navigate a Data File
Find and Replace Information in a Data File
Select the Encoding for a Data File
Order a Data File using Indexed Keys


Find and Replace Information in a Data File

Restriction: You can only replace data with data of the same length.
  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. On the Search menu, click Find/Replace. The Find/Replace dialog box is displayed.
  6. To display the equivalent hexadecimal values of your find/replace criteria, select Hex.
  7. Do one of the following:
    • Find data in the file:
      1. Ensure that your keyboard is not in Overwrite mode; if it is, press Insert to toggle to Insert mode. If the Find field is blank, Overwrite mode will only allow you to enter text for a single character in length.
      2. In the Find field, click Down arrow, select one of the following input types, and then enter the find text into the field:
        • all - search each entire record.
        • in offsets - search a range of positions within each record. When you select this option, two additional fields are displayed in which you enter the offset to start searching and the number of positions on from that in which to search.
        • in field - (only available if the file is using a layout) search a particular field in each record. When you select this option, an additional field is displayed in which you select the field in which to search.
      3. Click Find Next to immediately jump to the first occurrence after the currently selected record, or click Find All to highlight all occurrences in the file.
    • Replace data in the file:
      1. Ensure that the file is in Exclusive mode: double-click The Switch to Exclusive Mode icon (Switch to Exclusive Mode).
      2. Input the Find criteria, as detailed above, and then enter the replacement text in the Replace with field.
      3. click Replace to replace the next matching text, or click Replace All to replace all matching text at once.

        An indicator showing the number of replacements is displayed.

    Note: If you are searching and replacing DBCS characters, you must use the Hex pane: select Hex, and then enter the hexadecimal values directly into the Hex pane.
  8. Click Close.
Parent topic: Viewing, Filtering and Printing Data Files
Related information
View File Information
Filtering a Data File
Load and Unload a Structure 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


Select the Encoding for a Data File

By default, the file is displayed using ANSI encoding.

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. In the Appearance group, click The down arrow icon beside ANSI, then select another encoding.

    The data file is displayed using the selected encoding.

Parent topic: Viewing, Filtering and Printing Data Files
Related information
View File Information
Filtering a Data File
Load and Unload a Structure File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Find and Replace Information in a Data File
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 Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 record layout, click Browse to the right of the Structure File (optional) field, then use the Open dialog box to navigate to and select the structure (.str) file that contains the layout.
  4. Click Open Shared (to open the file in read-only mode) or Open Exclusive (to open the file in edit mode).

    The file is displayed on its own tab in the main window.

  5. To order from the currently selected record, click The down arrow icon beside Primary Key, then select an alternate key to order your data file by.

    The key selection menu

    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 The Go To Key icon 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 The Go Back icon, which is displayed just above the records, on the left-hand side.
Parent topic: Viewing, Filtering and Printing Data Files
Related information
View File Information
Filtering a Data File
Load and Unload a Structure File
Navigate a Data File
Show the Contents of a Data File in Hexadecimal
Find and Replace Information in a Data File
Select the Encoding for a Data File


Comparing Data Files

You can compare one data file to another, to quickly locate the differences in its content and structure.

You can analyze the entire contents of each file, or you can compare only a certain number of consecutive records, or even selected parts of a record. If you are using a structure file, you can use the layout to select the individual fields to compare.

Results are available in the same unformatted and structured views as individual files are when opened in the editor, but are strictly read-only.

  • Compare Two Data Files
Parent topic: Using the Data File Editor


Compare Two Data Files

  1. From the Micro Focus Data File Tools window, click Tools > Compare Files.

    The File Compare dialog box appears.

    The File Compare dialog box

  2. Select the two data files to compare:
    1. In the File 1 section, click The Select File icon and select the required file.
      Note: If the editor cannot determine the organization and record length of the selected file (for example, it contains no header, or no identically named .pro file found in the same directory), you are prompted to supply the file organization details.
    2. In the Encoding field, click ANSI and set the appropriate encoding for the file.
    3. In the Start at record field, select the record number at which to start the compare.
    4. Repeat these steps in the File 2 section to select the second file.
  3. Select one of the following comparison types:
    • Entire record - the entirety of each record is compared.
      1. In the Compare field, select Entire record.
    • Using structure - only selected fields associated with a structure file, in each record, are compared:
      1. In the Compare field, select Using structure.
      2. In the Structure File field, click The Select File icon (Select file), and then use the use the Open dialog box to select the required .str file.
      3. If you want to only compare some of the fields within a record, click Select fields, and then use the Select fields dialog box to select the layout(s) or field(s) within the structure file that you want to compare; unselected layouts and fields are still displayed, but they are not compared.
        Note: Regardless of the fields selected for comparison, all layouts in the selected structure file are used, where appropriate, when the Structure perspective is selected.
    • Column range - only a specific range of columns within each record is compared.
      1. In the Compare field, select Column range.
      2. In the Start column and End column fields, select the required range.
  4. In the Number of records section, select the number of records to compare:
    Option | Description
    Compare all records | All records in each file are compared.
    x records | Only the first x records, starting from the record number specified during file selection, are compared.
  5. In the Other section, select the following, if applicable:
    Option | Description
    Ignore padding characters | When selected, do not highlight the current padding character (Tools > Preferences > Padding Character) at the end of a record if a difference has been detected.
    Stop if difference found | When selected, the comparison halts after the first difference is encountered.
  6. Click OK.

    The records from the two files are display unformatted, side by side; records containing differences are highlighted.

    The Compare results

  7. If you selected a structure file in step 3, you can view the records in the structured view by selecting a record, then clicking the Structure option in the Perspective group. To return to an unformatted record view, click the Perspective group option again and select Record.
Tip: To view statistics about the current comparison, click The File Information icon (File Information) to display a dialog box of statistics:

Parent topic: Comparing Data Files


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 Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 Open Data File dialog box

    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

The Structure File Editor is a tabbed pane within the Data File Editor window that enables you to create and edit layouts within a structure file. The layouts within a 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.

Using layouts also makes it easier to filter records in a data file, as you can apply field conditions to a filter, as opposed to only being able to apply reference conditions when a layout is not used; see Filtering a Data File for more information.

Layouts are derived from the Data Division (level-01 fields and below in the File Section, the Working Storage Section, and the Linkage 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. You can apply a structure file when opening a data file, or whilst editing, you can load and unload existing structure files to and from the data file.

If a structure file is not applied, the records are displayed unformatted, as long continuous strings of text.

  • 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; the updated layouts are applied the next time you open the data file, or load the structure file on to an opened data file.
Parent topic: Data File Editor
Related reference
Filtering a Data File


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 Micro Focus Data File Tools window, click File > New > Structure File.

    The Open dialog box appears.

  2. 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, which contains the Data Division of the .idy file in the Available Layouts pane. The group structures are maintained, but the levels use consecutive numbering instead of the numbering used in the COBOL source.

    The Structure File editor

  3. To create a default layout, from the Available Layouts pane, right-click the required level entry and select Create Default Layout.

    The new default layout appears in the Selected Layouts pane, and consists of the selected level entry and any sub-level entries.

    The Available Layouts pane

    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.

  4. (Optional) Create a conditional layout:

    The ANSI/EBCDIC indicator (displayed to the right of the Browse button) defaults to the character set specified when the COBOL compilation generated the debug file (.idy file). It indicates the character set representation to be shown when adding condition values to the next conditional layout.

    1. If the indicator is showing a character set other than the one required, click the indicator and select the required character set.
    2. Right-click another level entry in the Available Layouts pane, then select Create Conditional Layout.

      The new conditional layout appears in the Selected Layouts pane.

      Note: You can differentiate the layouts by the icons The Default Layout icon (Default) and The Conditional Layout icon (Conditional).
    3. In the Selected Layouts pane, expand the layout to display the field on which to base the condition, then right-click it and select Properties.
      Note: Conditions cannot be applied to group fields within a layout.

      The Field Properties dialog box appears.

    4. Check Convert if you plan to use this layout with the Data File Converter and want this field to be converted between EBCDIC and ANSI. Clear this option if the field contain non-text data items (for example, binary values), which you do not want to be converted (as they will corrupt the converted file).

      The presence of [image] in the Selected layouts pane indicates which fields within the record would be converted:

      The Converted Fields indicator
    5. From the Condition section, select Set Condition to enable the condition properties.
    6. Click the current operator and select an appropriate operator from the list.
    7. Complete the value(s) for the condition.
    8. Click OK.
      Note: You can add more conditions to other entries; any record must match all conditions for all entries in order to use the layout.
  5. On the File menu, select Save As....

    The Save As dialog box appears.

  6. 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; the updated layouts are applied the next time you open the data file, or load the structure file on to an opened data file.

You can also add layouts to existing structure files; the layouts do not necessarily need to be from the same debug file.

  • Edit a Structure File
Parent topic: Using the Structure File Editor
Related information
Creating Structure Files and Layouts


Edit a Structure File

  1. From the Micro Focus Data File Tools window, click File > Open > File, or click The Open File icon (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 (.str) to filter on structure files only.

    The structure file appears in the Structure File Editor.

  3. To add a new layout:
    1. Within the Debug File section, click Browse, then navigate to and select the required .idy file. The Data Division of the file appears in the Available Layouts pane.
    2. Create the layout as explained in Create a Structure File. The layout is added to the structure file.
  4. To delete a layout:
    1. Select any node within the layout, right-click and select Delete Layout.

      The layout is deleted.

  5. To add a condition to a layout:
    1. Right-click the node on which to add the condition, then select Properties.
      Note: Conditions can only be added to elementary items, not group items.

      The Field Properties dialog box appears.

    2. Add the condition criteria, then click OK.

      The condition is added to the layout.

  6. To edit a condition within a layout:
    1. Right-click the node on which the condition is set, then select Properties.

      The Field Properties dialog box appears.

    2. Edit the condition criteria, then click OK.
  7. To delete a condition within a layout:
    1. Right-click the node on which the condition is set, then select Properties.

      The Field Properties dialog box appears.

    2. Clear the Set Condition check box, then click OK. The condition is deleted from the layout.
  8. On the File menu, select Save.

    The Save dialog box appears.

  9. 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 reference
Rebuild Command Line Options
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.

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 forward slash (//) must be placed before options beginning with a single forward slash (/). 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.

See the Rebuild Command Line Options section for a full description of each option.

Parent topic: Rebuild
Related reference
Rebuild Command Line Options
Related information
Overview
Command Line
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Reorganizing Indexed Files

The format of the command line for reorganizing a file is:

rebuild in-file,out-file
[-c] [-d] [-i] [-k] [-n] [-p] [-s] [-v] [-x]

As indexed files are updated by adding, deleting and altering records, the index and data structures become disjointed, making processing less efficient. In addition, space left by deleted records is not always reused, making the file bigger than it needs to be.

After a large number of changes have been made, it is worth reorganizing an indexed file to rebuild the data and indices in an ordered sequential fashion and to reclaim any free space. This will ensure optimum performance and data integrity.

There are other reasons why you may want to reorganize a file. For example, if a file is processed sequentially, the access time to process the file increases over time, as the records start to become out of sequence due to updates. In this situation, you can reduce access time by reorganizing the file.

A third reason is to rebuild a duplicate key chain. A duplicate key has a duplicate occurrence value appended to it to make it unique. When a new duplicate key is added, the occurrence value of the last added key is incremented by one and used for the newly added key. If keys are deleted, no change is made to the occurrence values of the remaining keys. Therefore, you can reach the maximum number of duplicate values, even if some of those keys have already been deleted. In these circumstances it is a good idea to reorganize the file. For more information on duplicate keys, see the topic Duplicate Keysin the section File Organizations.

For example:

rebuild infile.dat,outfile.dat

causes Rebuild to read the data file (infile.dat) using the index file (infile.idx) and then create the output file (outfile.dat). The deleted records in infile.dat are not written to the output file.

Note: You cannot use the same filename for the input file and the output file.
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Rebuilding a Corrupt Indexed File

The format of the command line for rebuilding an index is:

rebuild in-file[,out-file]
[-c] [-d] [-e] [-i] [-k] [-n] [-p] [-s] [-v]

The out-file parameter is optional, but recommended, because if you do not specify it, and the Rebuild operation fails, you will lose your original file.

There are a number of reasons why an indexed file becomes corrupt, for example:

  • A close operation on an indexed file fails.
  • A power surge occurs while the indexed file is open.
  • The machine is rebooted or powered off while an indexed file is open.

When a COBOL program attempts to open a corrupt indexed file, the run-time system detects that the file is corrupt and returns an extended file status code.

Rebuild can recover corrupt indexed files for you:

  • If the data portion of the file is intact and only the index portion is corrupt, then Rebuild can generate a new index (.idx) file from the data file with no loss of data.
  • If the data portion of the file is corrupt then Rebuild can rebuild a complete new indexed file, both data and index portions, but there will be loss of data as Rebuild discards any corrupt data records that it encounters.
    Note: For indexed files that have a separate .idx file (IDXFORMAT4 and IDXFORMAT12), the rebuild process does not remove any incomplete transactional data from the data file. This data is safe to leave in the data file, as it will not be accessible, but if you want to remove it then run a rollback recovery on the file.

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}

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.

The following example 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 /i

The following example reorganizes the file. The data is written in the order of the third alternate key.

rebuild infile.dat,outfile.dat /x:3

The following example rebuilds the indexed file (assuming that the index (.idx) file is still present, and the key information held therein is not corrupt).

rebuild infile.dat

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. The following example 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 /s:c-isam /c:d1 /t:mf

The following example generates an index, with key compression, for a fixed-length relative file.

rebuild infile.dat,outfile.dat --o:rel,ind /k:1+2:3+10d
/c:i7 /r:f10

The following example 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.

rebuild infile.dat,outfile.dat /s:lii /t:lii

The following example reorganizes and displays information about the file /tmp.dat.

set data=/tmp.dat rebuild data /i
Parent topic: Rebuild
Related reference
Rebuild Command Line Options
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.
  • FSView
    View the available API calls and command line options that you can make with the FSView utility.
  • 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.
  • Rebuild Command Line Options
    Use a number of options available to configure and run Rebuild from the command line.
  • Rebuild Error, Information and Warning Messages
    Rebuild may output error, information or warning messages when rebuilding, converting or reorganizing an indexed file.
  • 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.

The File Handler searches for the configuration file in the following order:

  1. The file specified by the EXTFH variable.
  2. The file extfh.cfg in the current directory.
  3. The file %COBDIR%\etc\extfh.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]

Further tags are available to use within [XFH-DEFAULT] or instead of it. Settings that apply to all indexed files, all sequential files, and all relative files are listed under these tags:

[IDX-DEFAULT], [SEQ-DEFAULT], and [REL-DEFAULT]
Note: If you are using the [REL-DEFAULT] tag, use the RELFORMAT=<opt> configuration option (with <opt> being either MF or RM) to redirect the handling of relative files to either the Micro Focus file handler, or the RM/COBOL file handler - the default is RELFORMAT=MF. The IDXFORMAT option to redirect files is not supported under this tag.
Parent topic: Format of the Configuration File


FOLDER tag

Settings that apply to all files in a specific local 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.

This section does not support the use of networked shared folders; the folder must be local to your machine.

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


Extension tag

Settings that apply to files of the same file extension are listed under the specific extension tag, for example:

[*.DAT]
IDXFORMAT=2

sets all files with a .DAT extension to an IDXFORMAT of 2.

Parent topic: Format of the Configuration File


INTERNAL tag

The settings for an individual file override the global settings. If you just specify the filename, it must be the resolved filename, that is, the filename that the File Handler uses after it has completed its filename mapping process. Alternatively, you can prefix the filename with the keyword INTERNAL, to signify that the filename is the name that is used in the SELECT clause; the settings will then be applied to the file that is identified at the conclusion of the filename mapping process. For example, if the ASSIGN mode is dynamic, and you code:

[INTERNAL:$myfile\outfile.dat]
IDXFORMAT=8

where myfile is an environment variable holding the name of the directory where the folder is located, the settings will be applied to outfile.dat in that directory.

If the ASSIGN mode is external, and you had:

SELECT MYDATA ASSIGN TO EXTERNAL REALDATA

you could code:

[INTERNAL:REALDATA]

where any options which follow apply to the file to which the logical name "REALDATA" is mapped.

If, however, you have:

SELECT MYDATA ASSIGN TO '\directory\subdirectory\datadirectory\myfile'

you cannot use the INTERNAL option in the configuration file. The literal value in the SELECT statement must be replicated [inside square brackets] in the configuration file.

Filenames can use paths and DD_mappings but not wildcards or logic names. If you set the File Handler configuration option BASENAME=ON, you can specify filenames without paths. Note that the name of a file must match the mapped name in your program.

Parent topic: Format of the Configuration File


Filename tag

Settings that apply to a specific file are listed under the specific filename tag; for example:

[file1.dat]
IDXFORMAT=17
[file2.dat]
IDXFORMAT=21

sets file1.dat to IDXFORMAT 17 and file2.dat to IDXFORMAT 21.

Comments:

To enable the use of filenames (without a pathname), set BASENAME=ON in the [XFH-DEFAULT] section.

When you use the filename tag, the path to the current directory is assumed, and if a FOLDER tag exists for any folder along the path, settings for that tag are applied. For example, if you have the following file assignment:

SELECT myFile ASSIGN TO 'file1.dat'

and your application is run in the directory 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


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


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.
  • ASCIISOSI
    The ASCIISOSI option enables correct representation of EBCDIC DBCS characters.
  • 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.
  • EXTENDEDESDSXRBA
    The EXTENDEDESDSXRBA 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.
  • FLUSHSYSOUT
    The FLUSHSYSOUT option controls the ability to view the progress of an active spool job.
  • 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 or opening 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 if you open a file for input.
  • INDEXCOUNT
    The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.
  • INDEXFILE
    The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.
  • INSERTNULL
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.
  • INSERTTAB
    When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.
  • INTEROP
    The INTEROP option determines which file handler is used for all file organizations in a given folder.
  • KEYCHECK
    The KEYCHECK option specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening.
  • KEYCOMPRESS
    The KEYCOMPRESS option specifies the type of key compression in use.
  • LOADONTOHEAP
    The LOADONTOHEAP option specifies whether the File Handler loads the file into memory before executing any I/O operations.
  • LOCKTYPE
    The LOCKTYPE option specifies the type of record locking in use.
  • LOG
    When LOG is set to ON, any unusual file-related situations, such as corrupted files, or automatic file recovery, are noted in a log file for later examination.
  • LOGFILENAME
    When the LOG option is active, the LOGFILENAME option specifies the name of the log file to produce.
  • LSEQNAMETYPE
    The LSEQNAMETYPE option determines if the FILESUFFIX option is used for line sequential files that do not explicitly specify a file extension.
  • LSFILETERM
    The option controls the behavior of the File Handler upon encountering the EOF character x"1a" when reading line sequential files.
  • LSRECDELIM
    The LSRECDELIM option specifies the characters to be used as the record delimiter in line sequential files.
  • MAINFRAMEPRINT
    For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT option determines whether to use mainframe printer file format (filetype 11).
  • NAMEOPTIONS
    The NAMEOPTIONS option specifies whether the name you pass to the OPEN statement can contain File Handler options.
  • NFSFILELOCK
    The NFSFILELOCK option enables applications to detect record locks and file locks on UNIX NFS file systems.
  • NODESIZE
    The NODESIZE option specifies the size of the index nodes to use for an indexed file.
  • NOSEQCHECK
    The NOSEQCHECK option disables sequence-checking of keys in indexed files.
  • OPENINPUTSHARED
    The OPENINPUTSHARED option specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.
  • OSVSREWRITE
    The OSVSREWRITE option specifies whether to permit the WRITE statement for sequential files that are open for output. If so, these WRITE statements behave exactly like REWRITE statements.
  • READSEMA
    The READSEMA option specifies whether the system attempts to gain a semaphore for shared files when I/O operations are performed that do not modify the file.
  • READTODELIM
    The READTODELIM option specifies whether the file pointer is advanced to the next logical record in the file when reading in a record that is longer than the user data area. In these circumstances, the data record would effectively be truncated.
  • RELDATBUF
    The RELDATBUF option determines the size of buffer used when accessing a file with organization RELATIVE.
  • RELFORMAT
    Determines how relative files are handled.
  • 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
Related concepts
Features Added in Enterprise Test Server 2.3
File Handling


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


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


ASCIISOSI

The ASCIISOSI option enables correct representation of EBCDIC DBCS characters.

This option adds the required SOSI characters to the relevant character strings in order for them to be displayed or written out correctly; otherwise you may receive garbage characters as a result of the internal character translations that occur between ASCII and EBCDIC when process your data.

Syntax:

ASCIISOSI = { ON } { OFF }

Parameters:

ON
SOSI characters are appropriately added to EBCDIC DBCS characters strings in order for them to be displayed correctly.
OFF
No SOSI characters are added to EBCDIC DBCS characters strings.

Properties:

Default: OFF

Comments:

Only set this option if you are dealing with DBCS data items, and the shift-in and shift-out characters are not explicitly set preceding/following the relevant string in your source code.

This parameter can only be set globally; 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


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:

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


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 (see the EXTENDEDESDSXRBA option).
OFF
When set, new ESDS files are created as standard ESDS files.

Properties:

Default: OFF

Comments:

Ensure IDXFORMAT"15" is also set in order to create the extended version of an ESDS file.

Parent topic: Configuration File Options


EXTENDEDESDSXRBA

The EXTENDEDESDSXRBA option enables you to use extended relative byte addressing with extended ESDS files.

Syntax:

EXTENDEDESDSXRBA = { 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, before the EXTENDEDESDSXRBA setting takes effect. (EXTENDEDESDS files also require that IDXFORMAT"15" is set.)

Parent topic: Configuration File Options


FASTREAD

The FASTREAD option specifies whether or not the File Handler performs extra checking to ensure data integrity when reading an indexed file.

Syntax:

FASTREAD = { ON } { OFF }

Parameters:

ON
Do not perform extra checking.
OFF
Perform extra checking to ensure data integrity.

Properties:

Default: ON

Comments:

To increase the efficiency of reads on fixed length, non-compressed indexed files, set FASTREAD to ON.

Parent topic: Configuration File Options


FHREDIR

The FHREDIR option specifies whether a remote server using Fileshare can handle files.

Syntax:

FHREDIR = { ON } { OFF }

Parameters:

ON
Use Fileshare to access files on a remote server.
OFF
Do not use Fileshare.

Properties:

Default: OFF

Comments:

If FHREDIR is set to OFF, the File Handler examines the name at open time to determine whether the file is to be handled locally.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Take care with this option. If it is in effect when Fileshare is running, Fileshare will attempt to redirect file I/O requests to itself, and this will cause a timeout failure.

Parent topic: Configuration File Options


FILECASE

The FILECASE option enables you to adjust the case of data file names.

Syntax:

FILECASE = { 0 } { 1 } { 2 } { 3 } { 4 }

Parameters:

0
Data file names are not changed
1
Data file names are changed to lower case, including directory (path) elements
2
Data file names are changed to upper case, including directory (path) elements
3
Data file names are changed to lower case, excluding directory (path) elements
4
Data file names are changed to upper case, excluding directory (path) elements

Properties:

Default: 0

Examples:

FILECASE=2  *> e.g. cust_acc\fy11.dat becomes CUST_ACC\FY11.DAT
FILECASE=3  *> e.g. CUST_ACC\FY11.dat becomes CUST_ACC\fy11.dat

Comments:

Translation occurs before the filename is mapped with the values in COBDATA or before the FILESUFFIX option is applied. You should make sure that those variables specify the correct case.

Parent topic: Configuration File Options


FILESUFFIX

The FILESUFFIX option specifies the file extension to be used for files that do not explicitly specify one. This option is switched on/off according to file organization, by using the IDXNAMETYPE, SEQNAMETYPE, LSEQNAMETYPE, and RELNAMETYPE configuration options.

Syntax:

FILESUFFIX = suffix

Parameters:

suffix
The file extension to append to a filename that does not explicitly specify one.

Properties:

Default: Not set
Parent topic: Configuration File Options


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 COBOL 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
Related reference
remote_64bit_access


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


FLUSHSYSOUT

The FLUSHSYSOUT option controls the ability to view the progress of an active spool job.

Syntax:

FLUSHSYSOUT = { ON } { OFF }

Parameters:

ON
For active spool jobs, the buffer is flushed after each record is written, allowing you to view the contents of the spool file as the job is in progress.
OFF
The buffer is flushed only when it is full, before which the contents of the spool file cannot be viewed. This option is more performant.
Note: The buffer size is determined by SEQDATBUF, and if that is not specify, a buffer size of 4096 bytes is used.

Properties:

Default: ON
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 or opening indexed files.

Syntax:

IDXFORMAT = integer

Parameters:

Value | Meaning
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:

IDXFORMAT 16 is documentary only. Set IDXFORMAT 15, and then use the EXTENDEDESDS (and EXTENDEDXRBA) options in EXTFH.CFG to handle EXTENDEDESDS file types.

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


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 information
File Handler (Known Issues)


IGNORELOCK

The IGNORELOCK option specifies whether to ignore locks if you open a file for input.

Syntax:

IGNORELOCK = { ON } { INPUT } { OFF }

Parameters:

ON
If another user has the file open in any mode and locked a record, the lock is ignored.
INPUT
If another user has the file open for input and locked a record, the lock is ignored.
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


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
The name of the log file. name can also include a full or relative (to the current directory) path in which to generate the log file. If no path is specified, the file is generated in the current working directory.

Properties:

Default: XFHLOG

Comments:

LOGFILENAME can be set globally only; that is, under the tag [XFH-DEFAULT] in your configuration file. You cannot set the parameter for an individual file.

This option overrides the XFHLOG environment variable if both are set.

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


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:

NFSFILELOCK = { 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


RELFORMAT

Determines how relative files are handled.

Syntax:

RELFORMAT = { MF } { RM }

Parameters:

MF
Redirects the handling of relative files to the Micro Focus file handler.
RM
Redirects the handling of relative files to the RM/COBOL file handler.

Properties:

Default: RELFORMAT=MF.

Comments:

This option is supported under all appropriate tags except directly within the [XFH-DEFAULT] tag.

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


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


RETRYOPEN

The RETRYOPEN option indicates whether you wish to retry an I/O operation that fails because the file is locked.

Syntax:

RETRYOPEN = { ON } { OFF } { 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


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


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
Related concepts
FLUSHSYSOUT


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


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:

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


FSView

  • FSVIEW Command Line
Parent topic: File Handling Reference


FSVIEW Command Line

All of the features of FSVIEW are available to you as a command line utility.

The commands you specify on the command line define the operation to be carried out by FSVIEW. Information is returned as a scrolling screen output.

  • Redirection of Information
  • Command Files
  • FSVIEW Command Line Syntax
Parent topic: FSView


Redirection of Information

All information displayed by the FSVIEW command line utility can be redirected to a text file using standard operating system redirection:

> | Creates a new file
>> | Extends an existing file

For example:

@fred.ctl >> fsview.txt

redirects the output from fred.ctl to the existing file fsview.txt.

Parent topic: FSVIEW Command Line
Related information
Command Files
FSVIEW Command Line Syntax


Command Files

On the FSVIEW command line, an at character (@) followed by a filename indicates that the named file contains FSVIEW commands.

If you use a file to supply FSVIEW commands, the file must be an ASCII text file.

Within the FSVIEW command file:

  • Commands should be separated by spaces.
  • Line ends are treated as spaces but a new command must start on a new line.
  • Any text between an exclamation mark (!) and the line end is treated as a comment.

The following example shows an FSVIEW command file that identifies a file and lists the users currently accessing it:

    ! Demo of fsview command file
    ! Identify file and list its users

    option upcase
    option no-echo
    admin logon FSVIEW MFTEST
    server set NWB-GLEN
    server get
    users get
    files get
    file get-users F:\testing\fsvtests\fresh\testfile1.dat
    user-file close 7 F:\testing\fsvtests\fresh\testfile1.dat
    users get
    files get

    exit

    ! All done

Note that if your command file does not use the FSVIEW exit command, you will remain in FSVIEW after the file has been executed.

Parent topic: FSVIEW Command Line
Related information
Redirection of Information
FSVIEW Command Line Syntax


FSVIEW Command Line Syntax

The following commands can be entered on an FSVIEW command prompt:

  • Admin logon
    Logs on a user to administer Fileshare.
  • Admin password
    Sets the password for secure commands.
  • Exit
    Exits FSVIEW.
  • File close
    Closes a specific file for all users.
  • File get-locks
    Gets the list of record locks held by Fileshare for a specific file.
  • File get-users
    Gets the list of users accessing a specific file.
  • Files get
    Gets the list of open files.
  • Help
    Displays the list of FSVIEW Command Line commands.
  • Logfile autorename
    Invokes the automatic log file rename on the server.
  • Logfile rename
    Renames the log file.
  • Opentrace toggle
    Toggles the XFH open trace.
  • Option echo
    Sets the echo command option on.
  • Option no-echo
    Sets the echo command option off.
  • Option no-upcase
    Sets the case of filenames to lower case.
  • Option upcase
    Sets the case of filenames to upper case.
  • Server get
    Gets the server information from the connected server.
  • Server set
    Connects to the named server.
  • Server shutdown
    Shuts down the server.
  • Trace toggle
    Toggles the Fileshare trace.
  • User-file close
    Terminates file access for a specific file and user.
  • User get-files
    Gets the list of open files for a specific user.
  • User logoff
    Logs off a user.
  • Users get
    Gets the list of logged-on users.
  • XFH trace toggle
    Toggles the XFH trace.
Parent topic: FSVIEW Command Line
Related information
Redirection of Information
Command Files


Admin logon

Logs on a user to administer Fileshare.

Syntax:

admin logon user-ID
            user-passwd

Parameters:

user-ID
A valid user ID
user-passwd
The password associated with user-ID

Comments:

This command is required if Fileshare security is enabled but the FSVIEW user ID is not going to be used.

Note: Long usernames and passwords that contain spaces must be surrounded with double quotes. In addition, if the username or password contains a double quote then you must escape it by adding an extra double quote immediately after.
Parent topic: FSVIEW Command Line Syntax
Related reference
Exit
Help
Admin password


Admin password

Sets the password for secure commands.

Syntax:

admin password supervisor-passwd

Parameters:

supervisor-passwd
The supervisor password to be set

Comments:

This command is required if you want to access secure commands and Admin logon has not been used (Fileshare security is not enabled).

Note: Long passwords that contain spaces must be surrounded with double quotes. In addition, if the password contains a double quote then you must escape it by adding an extra double quote immediately after.
Parent topic: FSVIEW Command Line Syntax
Related reference
Admin logon
Exit
Help
Server get
Server set
Server shutdown


Exit

Exits FSVIEW.

Syntax:

exit

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Admin logon
Help
Admin password


File close

Closes a specific file for all users.

Syntax:

file close filename

Parameters:

filename
The name of the file. The name must contain the full path.

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
Files get
File get-users


File get-locks

Gets the list of record locks held by Fileshare for a specific file.

Syntax:

file get-locks filename

Parameters:

filename
The name of a file. The name must contain the full path.
Parent topic: FSVIEW Command Line Syntax


File get-users

Gets the list of users accessing a specific file.

Syntax:

file get-users filename

Parameters:

filename
The name of a file. The name must contain the full path.
Parent topic: FSVIEW Command Line Syntax
Related reference
File close
Files get


Files get

Gets the list of open files.

Syntax:

files get

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
File close
File get-users
User-file close
Users get
User get-files
User logoff


Help

Displays the list of FSVIEW Command Line commands.

Syntax:

help

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Admin logon
Exit
Admin password


Logfile autorename

Invokes the automatic log file rename on the server.

Syntax:

logfile autorename

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Logfile rename


Logfile rename

Renames the log file.

Syntax:

logfile rename log-file

Parameters:

log-file
The log file to be renamed
Parent topic: FSVIEW Command Line Syntax
Related reference
Logfile autorename


Opentrace toggle

Toggles the XFH open trace.

Syntax:

opentrace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Trace toggle
XFH trace toggle


Option echo

Sets the echo command option on.

Syntax:

option echo

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-echo.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option no-echo


Option no-echo

Sets the echo command option off.

Syntax:

option no-echo

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-echo.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option echo


Option no-upcase

Sets the case of filenames to lower case.

Syntax:

option no-upcase

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-upcase.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option upcase


Option upcase

Sets the case of filenames to upper case.

Syntax:

option upcase

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-upcase.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option no-upcase


Server get

Gets the server information from the connected server.

Syntax:

server get

Parameters:

None.

Comments:

The information returned by this command includes activity statistics, log file information and database information.

Parent topic: FSVIEW Command Line Syntax
Related reference
Server set
Server shutdown
Admin password


Server set

Connects to the named server.

Syntax:

server set fileshare-name

Parameters:

fileshare-name
The name of the Fileshare server to connect to
Parent topic: FSVIEW Command Line Syntax
Related reference
Server get
Server shutdown
Admin password


Server shutdown

Shuts down the server.

Syntax:

server shutdown

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
Server get
Server set
Admin password


Trace toggle

Toggles the Fileshare trace.

Syntax:

trace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Opentrace toggle
XFH trace toggle


User-file close

Terminates file access for a specific file and user.

Syntax:

user-file close user-ID
                filename

Parameters:

user-ID
A valid user ID associated with filename
filename
The name of a file. The name must contain the full path.

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
Users get
User get-files
Files get
User logoff


User get-files

Gets the list of open files for a specific user.

Syntax:

user get-file user-ID

Parameters:

user-ID
A valid user ID
Parent topic: FSVIEW Command Line Syntax
Related reference
User-file close
Users get
Files get
User logoff


User logoff

Logs off a user.

Syntax:

user logoff user-ID

Parameters:

user-ID
A valid user ID

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
User-file close
Users get
User get-files
Files get


Users get

Gets the list of logged-on users.

Syntax:

users get

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
User-file close
User get-files
Files get
User logoff


XFH trace toggle

Toggles the XFH trace.

Syntax:

xfhtrace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Trace toggle
Opentrace toggle


File Status

  • File Status Codes
  • Extended File Status Codes
  • Microsoft COBOL V2 File Status Codes
Parent topic: File Handling Reference


File Status Codes

The following are the possible two-byte codes returned as the file status after each I/O operation.

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.
51
Couldn't find the index in the specified C-ISAM indexed file.
52
Attempted to add an index that already exists in the specified C-ISAM indexed file.
53
Attempted to delete the prime index in the specified C-ISAM indexed file.
54
The specified C-ISAM indexed file is open for sharing in a distributed environment.
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 COBOL Sort module | The default module that executes a SORT (or MERGE) operation in your COBOL programs.
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 OpenText Support for Micro Focus Products 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
MFJSENGINE


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 OpenText Support for Micro Focus Products 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
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-+   |
           |                 |
           +-SIGN-EBCDIC-----+
           |                 |
           +-SORT-EBCDIC-----+
Note:
  • VLSHRT is ON by default.
  • SIGN-EBCDIC and SORT-EBCDIC are MFJSORT extensions; see Sort/Merge Operations (MFJSORT) for more information.

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-+  |
                   +---ALL------------------------------+
                   |                                    |
                   +---NONE-----------------------------+

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-.)-.---<<
           | +-BUILD-+                       |
           |          +--------,----------+  |
           |          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---+  +-length-+           |
                               |                                           |
                               +-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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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), DIV, LITERALS, MUL, SEPERATOR CHARS, SEQNUM, SUB.

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.

The following options of SEQNUM processing are supported:

>--SEQNUM,n,fs--.----------.--.---------.--.----------------.-------<<
                +-,START=j-+  +-,INCR=i-+  +-,RESTART=(p,m)-+
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-+
                             +-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-+  |
               +---ALL-------------------------------+
               |                                     |
               +---NONE------------------------------+

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-.---------------------------------------.-.----------<<
  +-OUTFILE-+   |                                                           |
                |         +---,-----+                                       |
                |         V         |                                       |
                +--FILES=-.-.-d---.-.---------------------------------------+
                |           +-dd--+                                         |
                |           +-OUT-+                                         |
                |                                                           |
                +--STARTREC=-n----------------------------------------------+
                |                                                           |
                +-ENDREC=-n-------------------------------------------------+
                |                                                           |
                |             +------,-------+                              |
                |             V              |                              |
                +-.OUTREC.-=-(.item-statement.)-.----------.-.------------.-+
                | +-BUILD+                      +-,VTOF----+ +-VFILL=byte-+ |
                |                               +-,CONVERT-+                |
                |            +-------,--------+                             |
                |            V                |                             |
                +--OVERLAY=-(.-item-statement-.)----------------------------+
                |                                                           |
                |                                                           |
                |                                                           |
                +-.-INCLUDE=-.-(-logical-expression-)-.---.-----------------+
                | |          +-ALL--------------------+   |                 |
                | |          +-NONE-------------------+   |                 |
                | |                                       |                 |
                | |                                       |                 |
                + +-OMIT=-.-(logical-expression-)-.-------+                 |
                |         +-ALL-------------------+                         |
                |         +-NONE------------------+                         |
                |                                                           |
                +--SAVE-----------------------------------------------------+
                |                                                           |
                +--FTOV-----------------------------------------------------+
                |                                                           |
                +--VLTRIM=byte----------------------------------------------+
                |                                                           |
                +--SPLIT----------------------------------------------------+
                |                                                           |
                +--NULLOFL=-.-RC0--.----------------------------------------+
                |           +-RC4--+                                        |
                |           +-RC16-+                                        |
                |                                                           |
                +--LINES=n--------------------------------------------------+
                |                                                           |
                |           +--------,--------+                             |
                |           V                 |                             |
                +--HEADERn=-.-(-header-item-)-.-----------------------------+
                |                                                           |
                |            +-------,----------+                           |
                |            V                  |                           |
                +--TRAILERn=-.-(-trailer-item-)-.---------------------------+
                |                                                           |
                |            +-------,----------+                           |
                |            V                  |                           |
                +--SECTIONS=-.-(-section-item-)-.---------------------------|
                |                                                           |
                +--NODETAIL-------------------------------------------------|
                |                                                           |
                +--REMOVECC-------------------------------------------------|
                |                                                           |
                +--CONVERT--------------------------------------------------|
                |                                                           |
                +--BLKCCH1--------------------------------------------------|
                |                                                           |
                +--BLKCCH2--------------------------------------------------+
Note: The maximum number of OUTFILs is 2048.

In order for BLKCCH1 and BLKCCH2 to take effect in MFSORT, they need to be used with MAINFRAMEPRINT in the extfh.cfg file and with SORTTYPE=2 in the environment.

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.--.--------.-----------+
                               |           +-,to---+  +-length-+           |
                               |                                           |
                               +-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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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), DIV, LITERALS, MUL, SEPERATOR CHARS, SEQNUM, SUB.

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 a 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-.-+           |
                         | |           +--to--+ |           |
                         | |                    |           |
                         | +-COUNT+n=--.-edit-.-+           |
                         | |           +--to--+ |           |
                         | |                    |           |
                         | +-COUNT-n=--.-edit-.-+           |
                         |             +--to--+             |
                         |                                  |
                         +-.-SUBCOUNT-----------.-----------|
                         | +-SUBCOUNT15---------+           |
                         | +-SUBCOUNT=(.-edit-.)+           |
                         |             +-to---+             |
                         |                                  |
                         +-.-TOTAL-.=-(p,m,f.------.)-------+
                         | +-TOT---+        +-,to--+        |
                         |                                  |
                         +-MIN=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-MAX=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-AVG=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +--.-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, MIN, MAX, and AVG 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=(.-trailer-item-.)----------------+

The following options of SEQNUM processing are supported:

>--SEQNUM,n,fs--.----------.--.---------.--.----------------.-------<<
                +-,START=j-+  +-,INCR=i-+  +-,RESTART=(p,m)-+

Limitations:

  • The following parameters are only supported when this control statement is run via MFJSORT:
    • FNAMES
    • CONVERT
    • VTOF
    • FTOV
    • VFILL
    • VLTRIM
    • NULLOFL
  • The maximum length of COUNT and SUBCOUNT values is 9 digits.
  • For COUNT+n and COUNT-n, n must be in the range 0-999.
  • The maximum length of the TOTAL fields:
    TOTAL field formats | MFJSORT | DFSORT
    Length (m) | *Maximum 18 Digits (d) | Length (m) | Digits (d)
    ZD | 1-15 | 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
    SFF | 1-44 | 1-44 | 31
    UFF | 1-44 | 1-44 | 31

    * MFJSORT will display the total to the same amount of digits as specified in the length.

  • The TO parameter for TOTAL, MIN, MAX, and AVG is only applicable for TRAILER3.

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-.)----.---<<
           | +-BUILD--+                          |
           |              +--------,----------+  |
           |              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---+  +-length-+           |
                               |                                           |
                               +-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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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), DIV, LITERALS, MUL, SEPERATOR CHARS, SEQNUM, SUB.

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.

The following options of SEQNUM processing are supported:

>--SEQNUM,n,fs--.----------.--.---------.--.----------------.-------<<
                +-,START=j-+  +-,INCR=i-+  +-,RESTART=(p,m)-+
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-+
Notes:
  • The maximum size of a sort field is 256 characters.
  • EQUALS and NOEQUALS always give the results as EQUALS.

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. The maximum SUM field length for formats FI, BI, and FL is 8; for ZD format, it's 31; for all other formats, 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; for example, SYMNAME substitution is only supported for the ON and WITH clauses used within the SELECT and SPLICE operators. There is no support for parameters that are not listed.
  • COPY
  • COUNT
  • DISPLAY
  • OCCUR
  • RANGE
  • RESIZE
  • 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--+           |
                    | +-RC8--+           |
                    | +-RC12-+           |
                    |                    |
                    +-.----------------.-|
                    | +-WRITE(countdd)-+ |
                    | +-DIGITS(d)------+ |
                    | +-WIDTH(n)-------+ |
                    |                    |
                    +-.-------------.----+
                      +-EMPTY-------+
                      +-NOTEMPTY----+
                      +-HIGHER(x)---+
                      +-LOWER(y)----+
                      +-EQUAL(v)----+
                      +-NOTEQUAL(w)-+

Limits and Restrictions:

These parameters are parsed but ignored: LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE)

Parent topic: ICETOOL Emulation


DISPLAY

The following parameters of this ICETOOL operator are supported in MFJSORT:

                        +----------------------------------------------+
                        |   +--------------------------+               |
                        V   V                          |               |
>--DISPLAY--FROM(indd)--.-.-.-.--ON(p,m,f)-------------.-LIST(listdd).-.----<<
                          |   +--ON(p,m,f,formatting-+               |
                          |   +--ON(p,m,HEX)---------+               |
                          |   +--ON(VLEN)------------+               |
                          |   +--ON(NUM)-------------+               |
                          |                                          |
                          | +---------------------+                  |
                          | V                     |                  |
                          +-.-.-----------------.-.------------------+
                          |   +-TITLE('string')-+                    |
                          |                                          |
                          +-.------.---------------------------------+
                          | +-PAGE-+                                 |
                          |                                          |
                          +-.------------.---------------------------+
                          | +-DATE-------+                           |
                          | +-DATE(abcd)-+                           |
                          |                                          |
                          +-.-----------.----------------------------+
                          | +-TIME------+                            |
                          | +-TIME(abc)-+                            |
                          |                                          |
                          +-.-------.--------------------------------+
                          | +-BLANK-+                                |
                          | +-PLUS--+                                |
                          |                                          |
                          +-.-------.--------------------------------+
                          | +-NOCC-+                                 |
                          |                                          |
                          | +----------------------+                 |
                          | 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)-----------+   |
                           |   +-ON(VALCNT,formatting)+   |
                           |                              |
                           +---LIST(listdd)---------------+
                           |                              |
                           | +-------,-------------+      |
                           | V                     |      |
                           +-.-.-----------------.-.------+
                           |   +-TITLE('string')-+        |
                           |                              |
                           +-.------.---------------------+
                           | +-PAGE-+                     |
                           |                              |
                           +-.------------.---------------+
                           | +-DATE-------+               |
                           | +-DATE(abcd)-+               |
                           |                              |
                           +-.-----------.----------------+
                           | +-TIME------+                |
                           | +-TIME(abc)-+                |
                           |                              |
                           +-.-------.--------------------+
                           | +-BLANK-+                    |
                           | +-PLUS--+                    |
                           |                              |
                           +-.-------.--------------------+
                           | +-NOCC--+                    |
                           |                              |
                           | +----------,-----------+     |
                           | 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


RESIZE

The following parameters of this ICETOOL operator are supported in MFJSORT:

>>-RESIZE--FROM(indd)--TO(outdd)--TOLEN(n)--+-------------+----><
                                            '-USING(xxxx)-'

Limits and Restrictions:

Parameter | Restriction
indd | indd count - must have a RECFM type of Fixed (for example, FB)
outdd | outdd count - must have a RECFM type of Fixed unless FTOV is provided in an OUTFIL statement in the USING clause
n | A number that is not the same size as the LRECL of indd
xxxx | Number of MODS or OUTREC statements can be present in the USING clause
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--+                    |
                       |                                |
                       +-.-------------.----------------+
                         +-USING(xxxx)-+

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 OpenText Support for Micro Focus Products 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
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages
MFJSENGINE


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-+   |
           |                 |
           +-SIGN-EBCDIC-----+
           |                 |
           +-SORT-EBCDIC-----+
Note:
  • VLSHRT is ON by default.
  • SIGN-EBCDIC and SORT-EBCDIC are MFJSORT extensions; see Sort/Merge Operations (MFJSORT) for more information.

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


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


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


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-+  |
                   +---ALL------------------------------+
                   |                                    |
                   +---NONE-----------------------------+

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


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-.)----.---<<
           | +-BUILD--+                          |
           |              +--------,----------+  |
           |              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---+  +-length-+           |
                               |                                           |
                               +-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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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), DIV, LITERALS, MUL, SEPERATOR CHARS, SEQNUM, SUB.

The following options of SEQNUM processing are supported:

>--SEQNUM,n,fs--.----------.--.---------.--.----------------.-------<<
                +-,START=j-+  +-,INCR=i-+  +-,RESTART=(p,m)-+
Parent topic: SYNCSORT Program Control Emulation


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


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


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-+  |
                +---ALL------------------------------+
                |                                    |
                +---NONE-----------------------------+

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


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


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-.---------------------------------------.-.----------<<
  +-OUTFILE-+   |                                                           |
                |         +---,-----+                                       |
                |         V         |                                       |
                +--FILES=-.-.-d---.-.---------------------------------------+
                |           +-dd--+                                         |
                |           +-OUT-+                                         |
                |                                                           |
                +--STARTREC=-n----------------------------------------------+
                |                                                           |
                +-ENDREC=-n-------------------------------------------------+
                |                                                           |
                |             +------,-------+                              |
                |             V              |                              |
                +-.OUTREC.-=-(.item-statement.)-.----------.-.------------.-+
                | +-BUILD+                      +-,VTOF----+ +-VFILL=byte-+ |
                |                               +-,CONVERT-+                |
                |            +-------,--------+                             |
                |            V                |                             |
                +--OVERLAY=-(.-item-statement-.)----------------------------+
                |                                                           |
                |                                                           |
                |                                                           |
                +-.-INCLUDE=-.-(-logical-expression-)-.---.-----------------+
                | |          +-ALL--------------------+   |                 |
                | |          +-NONE-------------------+   |                 |
                | |                                       |                 |
                | |                                       |                 |
                + +-OMIT=-.-(logical-expression-)-.-------+                 |
                |         +-ALL-------------------+                         |
                |         +-NONE------------------+                         |
                |                                                           |
                +--SAVE-----------------------------------------------------+
                |                                                           |
                +--FTOV-----------------------------------------------------+
                |                                                           |
                +--VLTRIM=byte----------------------------------------------+
                |                                                           |
                +--SPLIT----------------------------------------------------+
                |                                                           |
                +--NULLOFL=-.-RC0--.----------------------------------------+
                |           +-RC4--+                                        |
                |           +-RC16-+                                        |
                |                                                           |
                +--LINES=n--------------------------------------------------+
                |                                                           |
                |           +--------,--------+                             |
                |           V                 |                             |
                +--HEADERn=-.-(-header-item-)-.-----------------------------+
                |                                                           |
                |            +-------,----------+                           |
                |            V                  |                           |
                +--TRAILERn=-.-(-trailer-item-)-.---------------------------+
                |                                                           |
                |            +-------,----------+                           |
                |            V                  |                           |
                +--SECTIONS=-.-(-section-item-)-.---------------------------|
                |                                                           |
                +--NODETAIL-------------------------------------------------|
                |                                                           |
                +--REMOVECC-------------------------------------------------|
                |                                                           |
                +--CONVERT--------------------------------------------------|
                |                                                           |
                +--BLKCCH1--------------------------------------------------|
                |                                                           |
                +--BLKCCH2--------------------------------------------------+
Note: The maximum number of OUTFILs is 2048.

In order for BLKCCH1 and BLKCCH2 to take effect in MFSORT, they need to be used with MAINFRAMEPRINT in the extfh.cfg file and with SORTTYPE=2 in the environment.

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---+  +-length-+           |
                               |                                           |
                               +-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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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), DIV, LITERALS, MUL, SEPERATOR CHARS, SEQNUM, SUB.

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 a 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-.-+           |
                         | |           +--to--+ |           |
                         | |                    |           |
                         | +-COUNT+n=--.-edit-.-+           |
                         | |           +--to--+ |           |
                         | |                    |           |
                         | +-COUNT-n=--.-edit-.-+           |
                         |             +--to--+             |
                         |                                  |
                         +-.-SUBCOUNT-----------.-----------|
                         | +-SUBCOUNT15---------+           |
                         | +-SUBCOUNT=(.-edit-.)+           |
                         |             +-to---+             |
                         |                                  |
                         +-.-TOTAL-.=-(p,m,f.------.)-------+
                         | +-TOT---+        +-,to--+        |
                         |                                  |
                         +-MIN=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-MAX=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-AVG=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +--.-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, MIN, MAX, and AVG 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=(.-trailer-item-.)----------------+

The following options of SEQNUM processing are supported:

>--SEQNUM,n,fs--.----------.--.---------.--.----------------.-------<<
                +-,START=j-+  +-,INCR=i-+  +-,RESTART=(p,m)-+

Limitations:

  • The following parameters are only supported when this control statement is run via MFJSORT:
    • FNAMES
    • CONVERT
    • VTOF
    • FTOV
    • VFILL
    • VLTRIM
    • NULLOFL
  • The maximum length of COUNT and SUBCOUNT values is 9 digits.
  • For COUNT+n and COUNT-n, n must be in the range 0-999.
  • 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
    SFF | 1-44 | 1-44 | 31
    UFF | 1-44 | 1-44 | 31

    * MFJSORT will display the total to the same amount of digits as specified in the length.

  • The TO parameter for TOTAL, MIN, MAX, and AVG is only applicable for TRAILER3.
Parent topic: SYNCSORT Program Control Emulation


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-.)----.---<<
           | +-BUILD--+                          |
           |              +--------,----------+  |
           |              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---+  +-length-+           |
                               |                                           |
                               +-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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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------------------------------------+
Notes:
  • For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system.
  • For seqnum processing support, see the diagram below.

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), DIV, LITERALS, MUL, SEPERATOR CHARS, SEQNUM, SUB.

The following options of SEQNUM processing are supported:

>--SEQNUM,n,fs--.----------.--.---------.--.----------------.-------<<
                +-,START=j-+  +-,INCR=i-+  +-,RESTART=(p,m)-+
Parent topic: SYNCSORT Program Control Emulation


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


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-+
Notes:
  • The maximum size of a sort field is 256 characters.
  • EQUALS and NOEQUALS always give the results as EQUALS.

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


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. The maximum SUM field length for formats FI, BI, and FL is 8; for ZD format, it's 31; for all other formats, 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


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

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. Note: For the conversion to EBCDIC to be successful, the region and data set CHARSET settings must be set to ASCII.
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 INCLUDE and OMIT for diagrams of supported parameters. 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. Refer to OUTFIL for a diagram of supported parameters.
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
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
SFF | Signed free form numeric
SS | Substring. Used in conditions only.
TS/CST | PIC S9 TRAILING SEPARATE
TI/ZD/OT/CTO | PIC S9 TRAILING INCLUDED
UFF | Unsigned free form numeric
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]
Note:
  • For input files that are either variable length or indexed files, you do not need to specify RECORD, ORG or KEY commands 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.
  • If you specify more than one input file, you cannot specify the same file as the output file unless it is the first input file specified.
  • 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


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.

Comments:

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.

When performing an MFJSORT on fixed block files, the FCD content supplied for the USING and GIVING files should contain the required fields as stated in the standard operation code OPEN.

Parent topic: Callable Sort Module
Related reference
OPEN operation code


SORT Environment Variables

The following environment variables can be used for configuring SORT:

  • MFJSABCODE
    Used to override the default abend code when MFJSERET=ABEND is specified.
  • MFJSENGINE
    Determines which sort engine the utility MFJSORT is to emulate.
  • MFJSDCBOUTFIL
    Determines whether the DCB's LRECL value is honored during an OUTFIL statement.
  • MFJSERET
    Determines the response to an unsuccessful sort, copy or merge operation.
  • MFJSLSEQFB
    During a JCL sort, line-sequential files are treated as variable-block. If you would like them to be treated as fixed-block files, set MFJSLSEQFB=ON.
  • 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.
  • SORTEXITREENTRY
    Determines whether E15 user exits will be called after the SORTIN data set has been exhausted.
  • 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.
  • TMPDIR/ TMP/ TEMP
    Determines where the run-time system of the directory stores paging files.
Parent topic: Sorting Files


MFJSABCODE

Determines the abend code issued when MFJSERET=ABEND is in effect.

If this environment variable is not set, and MFJSERET=ABEND is in effect, an abend S00D (decimal code 16) is issued when a Sort or Merge operation fails with an unrecoverable error.

Parameters

Abend code (decimal) between 1 and 99

If a Sort or Merge the operation fails with an unrecoverable error, it will abend with a code between S001 and S063

The default is that the variable is not set. Any specified value outside of the range 1 to 99 will result in an abend code of S00D being issued.

Example

MFJSABCODE=77

(results in abend code S04D)

Parent topic: SORT Environment Variables


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

MFJSENGINE=DFSORT
Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSDCBOUTFIL

Determines whether the DCB's LRECL value is honored during an OUTFIL statement.
MFJSDCBOUTFIL={ON|OFF}

Parameters

ON
The LRECL specified in the DCB properties is used during an OUTFIL statement.
OFF
Emulates the ICE222A/ICE217A mainframe restriction.

The default is MFJSDCBOUTFIL=OFF.

Example

MFJSDCBOUTFIL=OFF
Parent topic: SORT Environment Variables


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). See also MFJSABCODE.

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
TMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related information
MFJSABCODE


MFJSLSEQFB

During a JCL sort, line-sequential files are treated as variable-block. If you would like them to be treated as fixed-block files, set MFJSLSEQFB=ON.

If the concatenation combines LSEQ and FB files, and the first concatenated file is FB, you must also set SETSORTTYPE=2.

Parameters

ON|OFF
When set to ON, line-sequential files are treated as fixed-block files during a JCL SORT; when set to OFF, line-sequential files are treated as variable-block.
The default is OFF.

Example

SET MFJSLSEQFB=ON
Parent topic: SORT Environment Variables


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
TMPDIR/ 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
TMPDIR/ 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
TMPDIR/ 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
TMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME


SORTEXITREENTRY

Determines whether E15 user exits will be called after the SORTIN data set has been exhausted.
SORTEXITREENTRY={ON|OFF}

Parameters

ON
Within Enterprise Server, MFJSORT will continue to call E15 user exit programs until a return code of 8 has been returned, even after the SORTIN data set has been fully read.
OFF
E15 user exit programs are not called once the SORTIN data set has been read.

The default is SORTEXITREENTRY=OFF.

Example

SORTEXITREENTRY=ON
Parent topic: SORT Environment Variables


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
TMPDIR/ 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
TMPDIR/ 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
33554432 | 33,554,432 bytes
The minimum value is 33,554,432 bytes (32MB).
Note: The minimum value is made up of the settings for SORTSPACE and SORTTEMPSPACE combined.

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
TMPDIR/ 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
TMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


TMPDIR/ 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.
  • SORT021U SORT failed - sort engine 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.
  • SORT046U OUTFIL RECFM <value> invalid
  • SORT050U ICETOOL input file not found
    The file that is to be sorted has not been found.
  • SORT051U ICETOOL output file not found
  • SORT052U SORTIN DSORG VSAM invalid
  • 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.
  • SORT097U SORTXSUM RECFM <value> invalid
  • SORT098U SORT terminated - missing SORTXSUM
  • SORT099I Header or trailer larger than record
Parent topic: Mfsort Error Messages


SORT011U SYSIN dataset value missing

Message

No SYSIN has been found for the SORT step.

Resolution

Recode the SORT step to include a SYSIN.

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


SORT021U SORT failed - sort engine status = <value>

Message

A failure in the SORT engine detailed caused the sort to fail.

Parent topic: Messages 0001 to 0099


SORT032I Number records sorted

Message

Details the number of 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


SORT046U OUTFIL RECFM <value> invalid

Message

The RECFM specified for OUTFIL is invalid.

Resolution

Verify that the RECFM for OUTFIL matches SORTIN or use either FTOV or VTOF as appropriate.

Parent topic: Messages 0001 to 0099


SORT050U ICETOOL input file not found

The file that is to be sorted has not been found.

Message

The input file for ICETOOL that is to be sorted was not found.

Resolution

Check your SORTCARD to ensure that the input file is correct and can be accessed.

Parent topic: Messages 0001 to 0099


SORT051U ICETOOL output file not found

Message

The definition for the output file for ICETOOL was not found.

Resolution

Check your SORTCARD to ensure that the output file is correct.

Parent topic: Messages 0001 to 0099


SORT052U SORTIN DSORG VSAM invalid

Message

A concatenated SORTIN cannot have a DSORG of VSAM.

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

Message

SORT has terminated as SYSIN cannot be found.

Resolution

Recode your SORTCARD to include a 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


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


SORT097U SORTXSUM RECFM <value> invalid

Message

The RECFM of SORTXSUM is invalid.

Resolution

Ensure that the RECFM of SORTXSUM is the same as the RECFM of SORTIN.

Parent topic: Messages 0001 to 0099


SORT098U SORT terminated - missing SORTXSUM

Message

SORT has been terminated because there is no SORTXSUM defined for a SORT using XSUM.

Resolution

Recode the SORTCARD to define SORTXSUM.

Parent topic: Messages 0001 to 0099


SORT099I Header or trailer larger than record

Message

The header or trailer record is larger than the data record length.

Parent topic: Messages 0001 to 0099


Messages 0100 to 0199

Select the number of the message you require details about:

  • SORT100E Missing operator
  • 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=
  • SORT143E Expected 'C', 'X', or 'B' not found
  • 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
  • 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

Message

An end of line or end bracket was found before an expected operator. 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


SORT143E Expected 'C', 'X', or 'B' not found

Message

A condition expected a value specified above and was not found.

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


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
  • SORT215E Reformatting field error
  • SORT216I Record type is V - Data starts at position 5
  • SORT218I RECORD size not specified - Defaulting to 256
  • SORT219E No SORTIN specified
  • SORT220E More than one SORTIN required for a MERGE operation
  • SORT222I MFJSORT is using <value>.
  • SORT223I SORT not processed by <value>. Continuing using 'EXTSM'
  • SORT224I INPUT file 'Input procedure'
  • SORT225I OUTPUT file 'Output procedure'
  • SORT226E E61 Exit not found
  • SORT227E Control field sequence indicator E required
  • SORT228E Exit E61 required
  • SORT230I OVERFLOW DURING SUMMATION - RC0
  • SORT231E OVERFLOW DURING SUMMATION - RC16
  • SORT233E Maximum number of output files exceeded
  • SORT234E SUM FIELD overlaps control field
  • SORT235E Incorrect operation for Sort NUM
  • SORT236I SORTSPACE setting rejected - defaulting to minimum
  • SORT237I SORTSPACE setting rejected - defaulting to maximum
  • SORT238I SORTTEMPSPACE setting rejected
  • SORT239E Invalid data set attributes
  • SORT240I No data records for an outfil data set - RC4
  • SORT241E No data records for an outfil data set - RC16
  • SORT302I SUBSYS <value> not found - continuing
  • SORT303U SORT terminated - Too many <value> conditions
  • SORT399I End of Micro Focus MFJSORT Utility
Parent topic: Mfsort Error Messages


SORT200E Bad or unknown symbol

Message

The symbol found was bad or unknown.

Parent topic: Messages 0200 to 0399


SORT201E No previous offset defined for symbols

Message

No previous offset defined for symbols

Parent topic: Messages 0200 to 0399


SORT202E No previous length defined for symbols

Message

No previous length defined for symbols.

Parent topic: Messages 0200 to 0399


SORT203E No previous format defined for symbols

Message

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


SORT215E Reformatting field error

Message

Reformatting field error.

Parent topic: Messages 0200 to 0399


SORT216I Record type is V - Data starts at position 5

Message

You specified variable organisation for a file and also a start position in the FIELDS instruction before position 5.

Variable files data starts at position 5 to allow for the RDW.

Parent topic: Messages 0200 to 0399


SORT218I RECORD size not specified - Defaulting to 256

Message

The LRECL for a LSEQ SORTIN was not specified and therefore defaults to 256.

Parent topic: Messages 0200 to 0399


SORT219E No SORTIN specified

Message

No SORTIN is specified.

Resolution

Recode your SORTCARD to include a SORTIN.

Parent topic: Messages 0200 to 0399


SORT220E More than one SORTIN required for a MERGE operation

Message

Only one SORTIN has been specified for a MERGE.

Resolution

Recode your SORTCARD to include at least two SORTIN statements for a MERGE.

Parent topic: Messages 0200 to 0399


SORT222I MFJSORT is using <value>.

Message

An external SORT module with the specified name is being used.

Parent topic: Messages 0200 to 0399


SORT223I SORT not processed by <value>. Continuing using 'EXTSM'

Message

SORT could not complete using the specified external sort module and has continued using "EXTSM".

Parent topic: Messages 0200 to 0399


SORT224I INPUT file 'Input procedure'

Message

SORT is processing data from an input procedure rather than from SORTIN.

Parent topic: Messages 0200 to 0399


SORT225I OUTPUT file 'Output procedure'

Message

SORT is processing data to an output procedure rather than to SORTOUT.

Parent topic: Messages 0200 to 0399


SORT226E E61 Exit not found

Message

An error occurred when trying to load the E61 exit.

Parent topic: Messages 0200 to 0399


SORT227E Control field sequence indicator E required

Message

An E61 exit is defined but no E61 control flag was found.

Parent topic: Messages 0200 to 0399


SORT228E Exit E61 required

Message

An E61 control flag has been found but no E61 exit defined.

Resolution

Add an E61 exit to the SORTCARD.

Parent topic: Messages 0200 to 0399


SORT230I OVERFLOW DURING SUMMATION - RC0

Message

A sum overflow has occurred during summation and has been ignored.

Parent topic: Messages 0200 to 0399


SORT231E OVERFLOW DURING SUMMATION - RC16

Message

A sum overflow has occurred during summation and has caused a RC16.

Parent topic: Messages 0200 to 0399


SORT233E Maximum number of output files exceeded

Message

The maximum number of output files has exceeded the limit of 2048.

Parent topic: Messages 0200 to 0399


SORT234E SUM FIELD overlaps control field

Message

The SUM FIELD overlaps the control field.

Parent topic: Messages 0200 to 0399


SORT235E Incorrect operation for Sort NUM

Message

Incorrect operation for SORT NUM.

Parent topic: Messages 0200 to 0399


SORT236I SORTSPACE setting rejected - defaulting to minimum

Message

SORTSPACE has been defined to less than the minimum and, as a result, defaulting to minimum.

Parent topic: Messages 0200 to 0399


SORT237I SORTSPACE setting rejected - defaulting to maximum

Message

SORTSPACE has been defined to greater than the maximum - defaulting to the maximum.

Parent topic: Messages 0200 to 0399


SORT238I SORTTEMPSPACE setting rejected

Message

SORTTEMPSPACE is less than the minimum required 32M and has been rejected.

Parent topic: Messages 0200 to 0399


SORT239E Invalid data set attributes

Message

VLTRIM has been specified for a fixed length file.

Parent topic: Messages 0200 to 0399


SORT240I No data records for an outfil data set - RC4

Message

No data records were written to outfil.

Parent topic: Messages 0200 to 0399


SORT241E No data records for an outfil data set - RC16

Message

No data records written to outfil.

Parent topic: Messages 0200 to 0399


SORT302I SUBSYS <value> not found - continuing

Message

A call to the referenced SUBSYS has been made and resulted in an exception.

Parent topic: Messages 0200 to 0399


SORT303U SORT terminated - Too many <value> conditions

Message

SORT terminated due to the number of conditions exceeding the limit. The limit is 1024.

Parent topic: Messages 0200 to 0399


SORT399I End of Micro Focus MFJSORT Utility

Parent topic: Messages 0200 to 0399


Rebuild Command Line Options

The general format of the Rebuild command line is:

rebuild in-file [,out-file] [options]
CAUTION:
If you use Rebuild through Fileshare you can only use the options that are supported for such use. Otherwise you will obtain undefined results. See the topic Rebuild through Fileshare for more information.
  • Rebuild Options - Overview
  • Rebuild Options - /c
    Specifies file compression.
  • Rebuild Options - /d
    Specifies that Rebuild should perform a data scrape, which reconstructs the index of an indexed file from the data area.
  • Rebuild Options - /e
    Specifies Rebuild's behavior when it encounters an illegal duplicate key while rebuilding a corrupt file or a file with a new key structure (using /k).
  • Rebuild Options - /f
    Validates an indexed file.
  • Rebuild Options - /i
    Displays information about the input and output files, including record lengths, file type and key structure.
  • Rebuild Options - /k
    Defines the key structure of an indexed file.
  • Rebuild Options - /l
    Specifies the loading and unloading of files.
  • Rebuild Options - /n
    Displays information about a file.
  • Rebuild Options - /o
    Specifies the organization of the input and output files.
  • Rebuild Options - /p
    Instructs Rebuild to rebuild an IDXFORMAT"8" file in place.
  • Rebuild Options - /q
    Instructs Rebuild to rebuild an IDXFORMAT"12" index file.
  • Rebuild Options - /r
    Defines the record structure of the input and output files.
  • Rebuild Options - /s
    Specifies the format of the input file.
  • Rebuild Options - /t
    Specifies the indexed format of the output file.
  • Rebuild Options - /u
    Instructs Rebuild to attempt to recover a file for which the last update operation was not completed.
  • Rebuild Options - /v
    Causes Rebuild to display progress information as it processes the file.
  • Rebuild Options - /x
    Defines the key-of-reference.
  • Rebuild Options - /y
    Instructs Rebuild to ignore any mismatch between the physical file size and the file size indicated in the file header.
  • Rebuild Options - /z
    Instructs Rebuild to use a Fileshare server for file access.
  • Rebuild Options - //q
    Suppresses the display of the Rebuild banner.
  • Rebuild Options - //v
    Displays the version number of Rebuild.
Parent topic: File Handling Reference


Rebuild Options - Overview

The general 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. To implement filename mapping, you can use environment variables in place of in-file or out-file.

Use the following rules on your Rebuild command line:

  • The /m and //q options are not currently available.
  • If the /f or /v option is followed by parameters, use a colon (:) before the parameter(s). For other options, the colon is not required.
  • You can place options anywhere within the command, except that options beginning with two slashes must be placed before options beginning with one slash.
  • Options are free-format; spaces are required between options.
  • Do not insert spaces between the parameters of options.
CAUTION:
If you use Rebuild through Fileshare you can only use the options that are supported for such use. Otherwise you will obtain undefined results. See the topic Rebuild through Fileshare for more information.

For more information about Rebuild, see Rebuild in the Data Files section.

Parent topic: Rebuild Command Line Options


Rebuild Options - /c

Specifies file compression.

Data compression can only be specified for an output file. Key compression can be specified for an output file or the rebuild of an existing file.

The /c option operates in a similar manner to the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Parameters

d n
Data compression. n must be in the range 0 through 255:
Value | Description
0 | No data compression.
1 through 127 | Reserved.
128 through 255 | User-defined compression routines.
i n
Key compression. n must be in the range 0 through 15:
Value | Description
0 | No key compression.
1 | Duplicates are compressed.
2 | Leading characters are compressed.
4 | Leading spaces are compressed.
8 | Trailing nulls are compressed.
You can specify any combination of these key compressions by adding together the appropriate values.
Note: You cannot compress the data in C-ISAM and Level 2 files.

Examples

rebuild infile.dat,outfile.dat /c:d1i6

specifies data compression routine 1, and index compression of leading characters and trailing spaces.

rebuild infile.dat,outfile.dat /c:i1

specifies key compression of duplicates only.

Parent topic: Rebuild Command Line Options
Related information
Overview of Rebuild command line options


Rebuild Options - /d

Specifies that Rebuild should perform a data scrape, which reconstructs the index of an indexed file from the data area.

Any corrupt data records are skipped and logged to a file.

Parameters

c n Attempt to recover all valid records from the data file to the physical end of file, rather than the logical end of file. This option is valid for C-ISAM files only.

Default

If the /d option is not set, Rebuild returns file status error 9/041 when it encounters a corrupted record.

Parent topic: Rebuild Command Line Options


Rebuild Options - /e

Specifies Rebuild's behavior when it encounters an illegal duplicate key while rebuilding a corrupt file or a file with a new key structure (using /k).

When /e is set in such circumstances, Rebuild reports the duplicate, writes it to a duplicates file and continues to process the remaining records. The record with the duplicate key is not written to the file being rebuilt.

The duplicates file has the same file organization as the input file unless it is indexed, in which case the duplicates file is sequential. The duplicates file contains the same type of records, fixed-length or variable-length, as the input file. The name of the file is the input filename with .err appended, and it is written to the same directory as the input file.

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.

Default

When /e is not set, Rebuild ends with an "Error on output file - status 22" error.

Parent topic: Rebuild Command Line Options


Rebuild Options - /f

Validates an indexed file.

If the file is corrupt, Rebuild returns a non-zero value.

Parameters

c
Specifies the validation to be performed. The default is 10.
Value | Description
2 | Checks the structure of the free space list (FSL).
8 | Checks the index file structure.
256 | Checks the data file structure with file open for sharing in another process. You cannot specify this check in combination with any other check.
0 | Nothing.
1 | Error messages only.
2 | Messages showing the options you have specified.
3 | Information about the file. This includes key definition, records lengths, data compression, and the version of the file handler that created and updated the file.
4 The different types of record present in the file:
  1. IDXFORMAT"4" information record.
  2. Deleted record.
  3. System record.
  4. Data record that has been reduced in size by a rewrite.
  5. Data record that has been increased in size by a rewrite, and therefore cannot fit into the original record area. Instead, this record points to another record area that contains the record.
  6. The record pointed to by a type 6 record.
  7. The record pointed to by a type 6 record.
  8. The record pointed to by a type 6 record.
5 | Statistics about each key structure. This includes information about how much space is being saved by key compression.
You can select a combination of checks 2 and 8 by adding the numbers together. The more checks you perform, the longer the validation takes.
d
Specifies the message level.
These values are cumulative, so if you specify level 4, you will also receive messages at levels 1, 2 and 3. The default is 5.
Value | Description
0 | Nothing.
1 | Error messages only.
2 | Messages showing the options you have specified.
3 | Information about the file. This includes key definition, records lengths, data compression, and the version of the file handler that created and updated the file.
4 The different types of record present in the file:
  1. IDXFORMAT"4" information record.
  2. Deleted record.
  3. System record.
  4. Data record that has been reduced in size by a rewrite.
  5. Data record that has been increased in size by a rewrite, and therefore cannot fit into the original record area. Instead, this record points to another record area that contains the record.
  6. The record pointed to by a type 6 record.
  7. The record pointed to by a type 6 record.
  8. The record pointed to by a type 6 record.
5 | Statistics about each key structure. This includes information about how much space is being saved by key compression.

Examples

rebuild test.dat /f:c8

checks the structure of the index file.

rebuild test.dat /f:d1

specifies error messages only.

rebuild test.dat /f:c2d1

checks the structure of the FSL and specifies error messages only.

rebuild test.dat /f

Performs a full integrity check on a file, displaying all possible information. This is the same as specifying /f:c10.

Note:

The display might end with one of the following messages:

File is corrupt

This means that the control information in the file is not consistent with the data. For example, a record may have been deleted but the list of deleted records does not include it. Such a file is reported as corrupt, even though the data itself is not corrupt.

File contains transaction data

This means that the control information may not be consistent with the data because the file contains records which were part of a Fileshare transaction which was not subject to a successful COMMIT or ROLLBACK.

For example, a record may have been written as part of a transaction, but a system failure caused Fileshare to stop processing before the transaction was COMMITed. If you are not using Fileshare Roll-Forward recovery, you can use rebuild to remove this transaction data by using the /d option and rebuilding to a new file. Note to quickly recover the file to a usable state that you can rebuild to the same file, this will recreate the index correctly (treating transaction data as deleted records) but the transaction record data will remain in the file, the space will not be reused and rebuild /f will continue to report that the “File contains transaction data”.

Parent topic: Rebuild Command Line Options
Related information
Overview of Rebuild command line options


Rebuild Options - /i

Displays information about the input and output files, including record lengths, file type and key structure.

If you want to display this information but do not want to perform any other processing, use the /n option instead.

Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /n


Rebuild Options - /k

Defines the key structure of an indexed file.

The key structure is used to rebuild the index of an indexed file when the original index is missing or corrupt.

When converting non-indexed files to indexed files, this option is required to specify the key information for the new output file.

You can also use this option to

  • Replace the key structure of an existing indexed file with an alternative structure
  • Convert one indexed file to another with a different key structure.
  • Add a new key to an indexed file or remove an existing key without having to rebuild to a new file

Each key is defined by its starting character position within the record (the first character position in a record is 1) and its length in characters. The starting position and length must be separated by a plus sign (+) or the letter L.

The definition of one key is separated from the definition of the next key by a colon (:).

Each key can be defined as a number of parts (split key), each part being separated by a comma (,).

Alternate keys (those other than the first defined) can be terminated by the parameter d, indicating WITH DUPLICATES.

You can use the s parameter to specify a sparse key. The s parameter must be followed by the sparse character itself. If the sparse character is non-printable, or a lower or upper case 'd', the s parameter must be followed by d value, where value is the decimal value of the sparse character.

Different key compression values can be specified for each key by using the c parameter, indicating compression. The c parameter must be followed by a key compression value between 0 and 7.

You can add or remove a key without having to rebuild to a new file or specify all the keys again. To add a key you use the a parameter; to remove a key you use the r parameter. You can only add or remove one key at a time, and you can only rebuild in place. You cannot use any other functions when you are adding or removing a key

Examples

  • This example defines a single key, starting at character position 1 and 20 characters in length.
    /k:1+20
  • This example defines three keys. The first key, the primary key, starts at character position 5 and is 5 characters in length; the second key, an alternate key allowing duplicates, starts at character position 20 and is 1 character in length; the third key, a split alternate key, has two parts, the first starting at character position 40 and 2 characters in length and the second starting at character position 43 and 10 characters in length.
    /k:5+5:20+1d:40+2,43+10
  • This example defines two keys. The first key, the primary key, starts at character position 1 and is 5 characters in length; the second key, an alternate, sparse key allowing duplicates, starts at character position 20 and is 10 characters in length, the sparse character is Z.
    /k:1+5:20+10dsZ
  • This example defines two keys. The first key, the primary key, starts at character position 1 and is 5 characters in length. The second key, an alternate, sparse key allowing duplicates, starts at character position 20 and is 10 characters in length; the sparse character is the null character.
    /k:1+5:20+10dsh0
  • This example defines two keys. The first key, the primary, starts at character position 1 and is 10 characters in length. The second key, an alternate compressed key allowing duplicates, starts at character position 11 and is 20 characters in length. The types of key compression being used are compression of duplicates (1) and compression of leading characters (2).
    /k:1+10:11+20dc3
  • This example adds a new key which allows duplicates. The key starts at character position 1 and is 3 characters in length.
    /k:a:1+3d
  • This example removes the key that starts at character position 10 and is 5 characters in length.
    /k:r:10+5
  • This example shows how to correctly rebuild the index of an index file when the original index is missing. Use the s parameter to select an idxformat 4 index.
    Note: When the index is missing you should specify the key information exactly as the original key specification for idxformat 4 files, as the data file contains control information related to keys which allow duplicates. If the new key information does not exactly match, it can result in file corruptions or loss of data. We recommend you use the f parameter to validate the rebuild once the new key has been created.
    rebuild infile.dat, outfile.dat /k:1+5:6:10d /s:MF4
Parent topic: Rebuild Command Line Options


Rebuild Options - /l

Specifies the loading and unloading of files.

Use the /l option when you are loading to and unloading from IDXFORMAT 9 files.

For loading, you need to define the record size and key definition (one key only).

All records must be the key order of the target file and there must be no records which result in duplicate keys.

You do not need to define the record size and key definition for unloading.

Parameters

r9 | Load a record sequential file to an IDXFORMAT 9 file
9r | Unload an IDXFORMAT 9 file to a record sequential file

Examples

rebuild /l:r9 file1, file2 /k:1+10 /r:v20-30

This example loads a record sequential file to an IDXFORMAT 9 file, with the key structure specified by the /k option and the recording mode and record lengths specified with the /r option.

rebuild /l:9r file1, file2

This example unloads an IDXFORMAT 9 file to a record sequential file.

Parent topic: Rebuild Command Line Options


Rebuild Options - /n

Displays information about a file.

The /n option displays the same information as the /i option, plus the number of data records in the file, but without performing any other processing.

Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /i


Rebuild Options - /o

Specifies the organization of the input and output files.

If the input file is line sequential and the record contains COMP or COMP-3 items, the file must have been created with the INSERTNULL configuration option set to ON. If the file has been created with INSERTNULL set to OFF, or has come from a third party and does not precede non-printable characters with null bytes, the file will not be correctly processed if the COMP/COMP-3 items contain bytes with the values x"00", x"09" (tab), x"0A" (newline) or x"0D" (carriage return).

Parameters

/o:infile-org[,outfile-org]

infile-org and outfile-org can be any of the following:

Value | Description
lseq | line sequential
seq | sequential
rel | relative
ind | indexed

This format enables you to convert from any one file organization to another.

If outfile-org is omitted, the output file will have the same organization as the input file.

Using this syntax, you can convert a line sequential file to an indexed file, or an indexed file to a variable sequential file, and so on.

Examples

rebuild in-file, out-file /o:lseq,ind /t:mf /k:1+10 /r:v20-30

converts a line sequential file to an indexed file with the key structure specified by the /k option, the file format specified by the /t option, and the recording mode and recording lengths specified by the /r option. The key information must be wholly contained within the minimum record length.

rebuild in-file, out-file /o:ind,seq /r:v20-30

converts an indexed file to a variable length sequential file with the recording mode and record lengths specified by the /r option.

Parent topic: Rebuild Command Line Options


Rebuild Options - /p

Instructs Rebuild to rebuild an IDXFORMAT"8" file in place.

The rebuild uses less disk space, but if it fails the file is lost. You must back up the file before you attempt a rebuild with this option.

Parent topic: Rebuild Command Line Options


Rebuild Options - /q

Instructs Rebuild to rebuild an IDXFORMAT"12" index file.

The rebuild process is performed using the .idx file that is used with IDXFORMAT"12" files. This rebuild process is considerably quicker than other rebuild processes such as a data scrape or Rebuild option /p, which could be a consideration for using this particular format of index file. The consequence of using it is that any corrupted information found in the file is not deleted; however, when the index is rebuilt, this information cannot be reached.

Parent topic: Rebuild Command Line Options


Rebuild Options - /r

Defines the record structure of the input and output files.

You can specify a different record structure for the output file, and if the record length of the output file is greater than the record length of the input file, you can specify a padding character. You need to specify the record structure of the input file only where the file does not have a header. If you do not specify the record structure of the output file it will have the same structure as the input file. If you only specify one record structure, it is taken to be the record structure of the output file, unless the input file has no header, in which case it is taken to be the record structure of the input file.

If you convert to and from Btrieve format indexed files using the /s and /t options, you might need to supply the /r option, even where you are not changing the record structure. This is because some indexed file features are implemented differently by Btrieve. An example is that Btrieve does not store the maximum record length. Therefore, on conversion from a COBOL format file to a Btrieve file and back again, certain record length and recording mode information can be lost. This makes the file unreadable to a COBOL program using the original file description. Using the /r option, you can specify the record length and recording mode information on the command line to retain the correct record definitions during conversion. You can determine the correct options from the COBOL format file using the /n option.

Parameters

frecord-length | specifies a fixed-length record format with records of record-length
vmin-record-length-max-record-length | specifies a variable-length format where min-record-length is the minimum record length and max-record-length is the maximum record length. Separate the lengths with a hyphen
ppad-character|[ddecimal-value] | specifies the padding character where the output record length is greater than the input record length. The default is spaces for line sequential files and NULLs for all other file organizations. d indicates that the padding character is supplied as a decimal value in the range 0 through 255, indicating the ANSI character to be used

Examples

/r:f100

(where the input file has no header) specifies that the input file has a fixed record length of 100 bytes and that the output file will have the same fixed record length.

/r:v100-200

(where the input file has a header) specifies that the output file will have a variable record length with a minimum record length of 100 bytes and a maximum record length of 200 bytes.

/r:f20,f30pZ

specifies that the input file has a fixed record length of 20 bytes, and that the output file will have a fixed record length of 30 bytes with Z used as a padding character.

/r:f40pd49

specifies that the output file will have a fixed record length of 40 bytes with the character "I" used as a padding character.

Parent topic: Rebuild Command Line Options
Related information
Overview of Rebuild command line options


Rebuild Options - /s

Specifies the format of the input file.

Parameters

/s:btrv | Btrieve format
/s:c-isam | C-ISAM format
/s:cisam | C-ISAM format
/s:lii | Level II V2.5 COBOL format
/s:l2 | Level II V2.5 COBOL format
/s:mf | IDXFORMAT"3" format
/s:mf4 | IDXFORMAT"4" format
/s:mf8 | IDXFORMAT"8" format
/s:mf12 | IDXFORMAT"12" format
Note: Since Rebuild automatically recognizes the file format, you do not need to specify this option.
Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /t


Rebuild Options - /t

Specifies the indexed format of the output file.

If /t is not specified, the output file will have the same format as the input file, or the default format if the input file is not indexed.

Parameters

/t:btrv | Btrieve format
/t:c-isam | C-ISAM format
/t:cisam | C-ISAM format
/t:lii | Level II V2.5 COBOL format
/t:l2 | Level II V2.5 COBOL format
/t:mf | IDXFORMAT"3" format
/t:mf4 | IDXFORMAT"4" format
/t:mf8 | IDXFORMAT"8" format
/t:mf12 | IDXFORMAT"12" format
/t:esds | ESDS format
/t:xesds | Extended ESDS format
Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /s


Rebuild Options - /u

Instructs Rebuild to attempt to recover a file for which the last update operation was not completed.

Use this option if a program failed or was terminated while updating a file. Rebuild may be able to recognise the specific problem with the file and fix it. This is quicker than doing a standard rebuild, so try this option first.

Parent topic: Rebuild Command Line Options


Rebuild Options - /v

Causes Rebuild to display progress information as it processes the file.

This is useful if you want to keep track of how Rebuild is progressing. We recommend that you don't use the -v option if you are redirecting the output to a file.

Parameters

n If you specify the /f option, Rebuild displays a '"." character every n records. If you do not specify the /f option, Rebuild displays a a record count every n records. If you do not specify the n parameter, Rebuild displays information about its processing phases.

Parent topic: Rebuild Command Line Options


Rebuild Options - /x

Defines the key-of-reference.

The key-of-reference defines the order in which data is read when an indexed file is specified as an input file.

Parameters

n The number of the key to be used where the primary key is 0 and the alternate keys are numbered, starting at 1, in the order they are specified in the SELECT statement in the creating program.

Default

If no /x option is specified, the primary key (key 0) is assumed.

Example

/x:2

Data is written in the order specified by the second alternate key for the file.

Parent topic: Rebuild Command Line Options


Rebuild Options - /y

Instructs Rebuild to ignore any mismatch between the physical file size and the file size indicated in the file header.

If no /y option is specified and Rebuild detects that the physical file size is less than that indicated in the file header, it stops. This is because a possible cause of the problem is that striping information has not been supplied to Rebuild. Under these circumstances continuing with the rebuild could cause loss of records.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.
Parent topic: Rebuild Command Line Options


Rebuild Options - /z

Instructs Rebuild to use a Fileshare server for file access.

Use this option for using Rebuild through Fileshare.

Parameters

/z:server-name
server-name The name of a Fileshare server.
Parent topic: Rebuild Command Line Options


Rebuild Options - //q

Suppresses the display of the Rebuild banner.
Parent topic: Rebuild Command Line Options


Rebuild Options - //v

Displays the version number of Rebuild.
Parent topic: Rebuild Command Line Options


Rebuild Error, Information and Warning Messages

Rebuild may output error, information or warning messages when rebuilding, converting or reorganizing an indexed file.

Also, when Rebuild encounters a problem, it searches for the next good record and writes it to a file called rebuild.1af.

  • Syntax Errors
    These occur when an error is encountered, the command line is displayed with a caret (^) symbol under the point at which the error was detected and error message is displayed.
  • Execution Errors
    These occur when the program sets the return code to a value other than zero to indicate the type of error that has occurred.
  • Information Messages
    These messages are displayed for information purposes only.
  • Warning Messages
    Depending on the operation selected, some command line options are unnecessary. In these cases, the incorrect usage will be indicated, but the option will be ignored and processing will continue. Note that the option may be correct, but omission of other information may have caused Rebuild to select the wrong process. If this is the case, correct the command line and rerun.
Parent topic: File Handling Reference


Syntax Errors

These occur when an error is encountered, the command line is displayed with a caret (^) symbol under the point at which the error was detected and error message is displayed.

If an error in the syntax of the command line occurs, the return code will be set to 9.

  • Key positions must be specified using /k option
    You did not supply a key definition for the index of the file being generated from a sequential or relative file, or from an indexed file with a missing .idx component
  • Data compression out of range
    The integer you specified for data compression is not within the allowable range.
  • Data compression specified more than once
    You have specified the option for data compression more than once; that is, /c:[dn][dn]
  • Input file same as output file
    You have given the output file the same name as the input file.
  • Index compression out of range
    The integer you specified for index compression is not within the allowed range.
  • Index compression specified more than once
    You have specified the option for index compression more than once; that is, /c[in][in].
  • Invalid command line
    The command line contains an error other than those described in more specific syntax error messages.
  • Invalid compression choice - must be 'd' or 'i'
    The specification of data or index compression was not correct.
  • Invalid format
    The value you specified for index file format is invalid.
  • Invalid key length - cannot be zero
    One of the keys you defined has a zero length, which is illegal. This may be due to incorrect use of separator characters.
  • Invalid key specification - key not contained in record
    One of the keys, as defined, is not wholly contained in the record. This is illegal.
  • Invalid key start - cannot be zero
    One of the keys defined has a start character position of zero, which is illegal. This may be due to incorrect use of separator characters.
  • Invalid key structure - '+' expected
    A key part parameter of the /k option is incorrect.
  • Invalid option
  • Invalid organization
    The syntax of the /o option is incorrect.
  • Invalid organization - must be indexed for index rebuild
    You have specified a non-indexed input file with no output file. If there is no output file Rebuild assumes that you want to rebuild an indexed file.
  • Invalid record length - cannot be zero
    You have specified that the length of a record is zero. This is invalid.
  • Invalid record lengths - maximum must not be less than minimum
    The integers you have used to specify the maximum and minimum lengths of a record indicate that the maximum length is less than the minimum length. This is invalid.
  • Invalid record parameter - '-' expected
    When specifying the record structure of a variable length file, you have not separated the minimum record length and the maximum record length with a hyphen (-).
  • Invalid record type - 'F' or 'V' expected
    You have entered record type other than fixed or variable. This is invalid.
  • Invalid format
    The format of the /s or /t option is incorrect.
  • No output file specified for /t option to refer to
    You did not specify a name for the output file which was referred to with the /t option.
  • No output file specified for data compression
    You did not specify an output filename for data compression.
  • Number expected
    You have specified another character where a number was expected.
  • Output organization was specified but not output file name
    You did not supply a filename although you specified an output organization.
  • Options file not found
    The options file specified on the command line cannot be found.
Parent topic: Rebuild Error, Information and Warning Messages


Key positions must be specified using /k option

You did not supply a key definition for the index of the file being generated from a sequential or relative file, or from an indexed file with a missing .idx component

Resolution:

Specify a key definition.

Parent topic: Syntax Errors


Data compression out of range

The integer you specified for data compression is not within the allowable range.

Resolution:

Data compression requires an integer in the range 0 through 255.

Parent topic: Syntax Errors


Data compression specified more than once

You have specified the option for data compression more than once; that is, /c:[dn][dn]

Resolution:

Use the correct format: /c:[dn][in]

Parent topic: Syntax Errors


Input file same as output file

You have given the output file the same name as the input file.

Resolution:

Use a different output filename.

Parent topic: Syntax Errors


Index compression out of range

The integer you specified for index compression is not within the allowed range.

Resolution:

Specify an integer in the range 0 through 15.

Parent topic: Syntax Errors


Index compression specified more than once

You have specified the option for index compression more than once; that is, /c[in][in].

Resolution:

Use the correct format: /c:[dn][in].

Parent topic: Syntax Errors


Invalid command line

The command line contains an error other than those described in more specific syntax error messages.

Resolution:

Check the syntax, spelling, and spacing in the command line you are trying to enter.

Parent topic: Syntax Errors


Invalid compression choice - must be 'd' or 'i'

The specification of data or index compression was not correct.

Resolution:

Specify the d or i parameter.

Parent topic: Syntax Errors


Invalid format

The value you specified for index file format is invalid.

Resolution

Specify a valid value: C-ISAM, CISAM, MF, MF4, MF8, BTRV, LII, L2.

Parent topic: Syntax Errors


Invalid key length - cannot be zero

One of the keys you defined has a zero length, which is illegal. This may be due to incorrect use of separator characters.

Resolution:

Make sure that any keys you define have a valid length.

Parent topic: Syntax Errors


Invalid key specification - key not contained in record

One of the keys, as defined, is not wholly contained in the record. This is illegal.

Resolution:

Ensure that the key is wholly contained in the record. For variable length records, the key must be wholly contained in the minimum length record.

Parent topic: Syntax Errors


Invalid key start - cannot be zero

One of the keys defined has a start character position of zero, which is illegal. This may be due to incorrect use of separator characters.

Resolution:

Make sure that any keys you define have a valid start character.

Parent topic: Syntax Errors


Invalid key structure - '+' expected

A key part parameter of the /k option is incorrect.

Resolution:

Make sure that you specify each key part as start character position and length separated by a plus (+) or L.

Parent topic: Syntax Errors


Invalid option

Parent topic: Syntax Errors


Invalid organization

The syntax of the /o option is incorrect.

Resolution:

Specify a valid organization, one of: lseq, seq, rel and ind. The forms s, r, i, si and ri are also permitted for compatibility with previous products.

Parent topic: Syntax Errors


Invalid organization - must be indexed for index rebuild

You have specified a non-indexed input file with no output file. If there is no output file Rebuild assumes that you want to rebuild an indexed file.

Resolution:

Make sure that you specify an output file if your input file is not an indexed file.

Parent topic: Syntax Errors


Invalid record length - cannot be zero

You have specified that the length of a record is zero. This is invalid.

Resolution

Specify a length greater than zero which falls within the limits for record lengths for this COBOL system.

Parent topic: Syntax Errors


Invalid record lengths - maximum must not be less than minimum

The integers you have used to specify the maximum and minimum lengths of a record indicate that the maximum length is less than the minimum length. This is invalid.

Resolution

Reenter the maximum or minimum record length, ensuring that the maximum length is greater than the minimum length.

Parent topic: Syntax Errors


Invalid record parameter - '-' expected

When specifying the record structure of a variable length file, you have not separated the minimum record length and the maximum record length with a hyphen (-).

Resolution:

Use the correct format: /r:vminreclen-maxreclen

Parent topic: Syntax Errors


Invalid record type - 'F' or 'V' expected

You have entered record type other than fixed or variable. This is invalid.

Resolution

Reenter the record type using either f (fixed) or v (variable).

Parent topic: Syntax Errors


Invalid format

The format of the /s or /t option is incorrect.

Resolution:

For details of the correct format see the help topic Rebuild Options - /s or the help topic Rebuild Options - /t.

Parent topic: Syntax Errors
Related information
Rebuild Options - /s
Rebuild Options - /t


No output file specified for /t option to refer to

You did not specify a name for the output file which was referred to with the /t option.

Resolution:

Specify the name of an output file for this option.

Parent topic: Syntax Errors


No output file specified for data compression

You did not specify an output filename for data compression.

Resolution:

Specify a valid output filename.

Parent topic: Syntax Errors


Number expected

You have specified another character where a number was expected.

Resolution:

Specify a numeric value for this parameter.

Parent topic: Syntax Errors


Output organization was specified but not output file name

You did not supply a filename although you specified an output organization.

Resolution:

Specify an output filename.

Parent topic: Syntax Errors


Options file not found

The options file specified on the command line cannot be found.

Resolution:

Check that the file exists, and the specification used on the command line is correct.

Parent topic: Syntax Errors


Execution Errors

These occur when the program sets the return code to a value other than zero to indicate the type of error that has occurred.
  • ***Error on input file - disk space exhausted
    File processing cannot continue because there is insufficient disk space to do so.
  • ***Error on input file - duplicate key - record not written:
    The record was not written to the output file as this would have created an invalid duplicate key.
  • ***Rebuild aborted - file is not as specified in s option (s option not required)
    The file specified by the /s option was not recognized.
  • ***Error on input file - File locked
    The file you specified as your input file is locked by another process.
  • ***Error on input file - file not found
    The input file cannot be found. The return code is set to 1.
  • ***Error on input file - illegal filename specified
    A filename does not conform to the standards imposed by the operating system or COBOL system.
  • ***Error on input file - invalid key of reference specified in x option
    The number specified in the key-of-reference option (/x) is greater than or equal to the number of keys for the given file. The return code is set to 1.
  • ***Error on input file - status xx, and ***Error on input file - status 9/yyy
    An error other than one of the above input file errors has occurred while processing the input file.
  • ***Error on output file - record length << min or >> max
    Rebuild attempted to write a record to the output file with a record length less than the minimum or greater than the maximum length for the file.
  • ***Error on output file - status xx, and ***Error on output file - status 9/yyy
    An error has occurred processing the output file.
Parent topic: Rebuild Error, Information and Warning Messages


***Error on input file - disk space exhausted

File processing cannot continue because there is insufficient disk space to do so.

Resolution:

Ensure that the input file is not corrupt. The output file is closed and should be usable, even if the rebuild is not complete.

Parent topic: Execution Errors


***Error on input file - duplicate key - record not written:

The record was not written to the output file as this would have created an invalid duplicate key.
Parent topic: Execution Errors


***Rebuild aborted - file is not as specified in s option (s option not required)

The file specified by the /s option was not recognized.

Resolution:

Either remove the /s option or correct it.

Parent topic: Execution Errors


***Error on input file - File locked

The file you specified as your input file is locked by another process.

Resolution:

Try again when the file is free to be accessed.

Parent topic: Execution Errors


***Error on input file - file not found

The input file cannot be found. The return code is set to 1.

Resolution:

Check that the filename you entered is correct, and the file does actually exist.

Parent topic: Execution Errors


***Error on input file - illegal filename specified

A filename does not conform to the standards imposed by the operating system or COBOL system.

Resolution:

Try the file operation again using a correct filename.

Parent topic: Execution Errors


***Error on input file - invalid key of reference specified in x option

The number specified in the key-of-reference option (/x) is greater than or equal to the number of keys for the given file. The return code is set to 1.

Resolution:

Check the key required, and try again.

Parent topic: Execution Errors


***Error on input file - status xx, and ***Error on input file - status 9/yyy

An error other than one of the above input file errors has occurred while processing the input file.

Possible causes are:

  • The file does not exist
  • A hardware error has occurred opening or reading the file
  • The file is corrupt

The status xx is a COBOL file status. If the first byte is a 9, then the status yyy is a COBOL run-time error number. The output file is closed, and should be usable, even if the rebuild is not complete. The return code is set to 1.

Resolution:

Investigate the error. For run-time system error messages see the help topic Run-time System Error Messages.

Parent topic: Execution Errors
Related reference
***Error on output file - status xx, and ***Error on output file - status 9/yyy
File Status Codes
Run-time System Error Messages


***Error on output file - record length << min or >> max

Rebuild attempted to write a record to the output file with a record length less than the minimum or greater than the maximum length for the file.

Resolution:

Change the record lengths specified in the /r option.

Parent topic: Execution Errors


***Error on output file - status xx, and ***Error on output file - status 9/yyy

An error has occurred processing the output file.
Possible causes are:
  • The file cannot be created
  • A hardware error has been encountered on opening or writing the file
  • The parameters specified are incorrect.

The status xx is a COBOL file status. If the first byte is a 9, then the status yyy is a COBOL run-time error number. The return code is set to 2.

Resolution:

Investigate the error. For run-time system error messages see the help topic Run-time System Error Messages.

Parent topic: Execution Errors
Related reference
***Error on input file - status xx, and ***Error on input file - status 9/yyy
File Status Codes
Run-time System Error Messages


Information Messages

These messages are displayed for information purposes only.
  • Rebuild successful
    The file you specified has been successfully rebuilt.
  • Records processed
    The indicated number of records were processed when the file was rebuilt or reorganized.
Parent topic: Rebuild Error, Information and Warning Messages


Rebuild successful

The file you specified has been successfully rebuilt.
Parent topic: Information Messages


Records processed

The indicated number of records were processed when the file was rebuilt or reorganized.
Parent topic: Information Messages


Warning Messages

Depending on the operation selected, some command line options are unnecessary. In these cases, the incorrect usage will be indicated, but the option will be ignored and processing will continue. Note that the option may be correct, but omission of other information may have caused Rebuild to select the wrong process. If this is the case, correct the command line and rerun.
  • Option ignored - k option not needed with n option
    A key definition option has been together with a request for file information. The k option is ignored.
  • Option ignored - x option not needed for index rebuild
    A key-of-reference option has been used when an action other than indexed file reorganization has been selected. The option is ignored.
Parent topic: Rebuild Error, Information and Warning Messages


Option ignored - k option not needed with n option

A key definition option has been together with a request for file information. The k option is ignored.
Parent topic: Warning Messages


Option ignored - x option not needed for index rebuild

A key-of-reference option has been used when an action other than indexed file reorganization has been selected. The option is ignored.
Parent topic: Warning Messages


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=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
    This section describe how to configure the communications between Fileshare clients and Fileshare servers. Fileshare clients and servers communicate using the Common Communications Interface (CCI).
  • 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
Related concepts
Fileshare


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.

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.

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:

/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

The default protocol for Fileshare over CCI is TCP/IP (CCITCP). For Fileshare clients and servers on Windows platforms, you can also use the Named Shared Memory protocol (CCISM). Use the CCI.INI configuration file on the Fileshare client to specify which protocol to use for which Fileshare server.

  • To specify the Named Shared Memory protocol (CCISM) as the default protocol:
    /cm ccism
  • To specify that the Named Shared Memory protocol is used when communicating with a specific Fileshare Server, use the /cm and /s options together:
    /cm ccism /s server1
    The Fileshare Client uses CCISM for communicating with the Fileshare Server named server1, whilst using the default protocol (CCITCP) for other servers.

If you are using the TCP/IP protocol, you do not need to specify it in a CCI.INI configuration file.

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 concepts
Fileshare Client Configuration Options
About CCISMEM
Configuring Your Fileshare Client
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:

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

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 concepts
Fileshare Client Configuration Options
Using CCISMEM
Specifying the Communications Protocol
About CCISMEM
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Using the File Handling Redirector Module
FHREDIR Return Codes
Using CCITCP


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.
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
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 concepts
Configuring Your Fileshare Client
Using CCISMEM
Specifying the Communications Protocol
About CCISMEM
The mfsecretsadmin Utility
Related information
Example Client Configuration File
Using CCITCP


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 | Description
-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:

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. For Windows platforms, if you want to use the CCISMEM protocol, you need to specify the /cm option in the CCI.INI configuration file; for example:

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

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: 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 16KB. If you specify a value greater than 64, the Fileshare Server uses a buffer size of 64KB.
/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:

ccitcp, or ccism

/pf password-file
 The name of the password file that the Fileshare Server uses.
/cf file-name

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.

/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
/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. After which, it runs a disk stats check, to calculate the disk usage and the amount of space remaining, generating a warning if disk space is low. Use /fds to control the frequency of this check.

If the file is unable to be flushed to disk due to low disk space, the operation will be suspended for 30 seconds, and then retried.

Also, 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.
Warning: Setting this option will degrade the performance of Fileshare.
/fds <value>
 Controls the frequency of the disk stats check performed after a flush, and so this option only has an effect when /fc is also specified.

By default, this check is performed after every flush, but you can use /fds to change the frequency.

Set this option to a value between 1-65536 to represent the nth flush on which to run the checks. (A value less than 1 equates to 1, and a value greater than 65536 equates to 65536.)

/lw
 Enables write through for the transaction log file, 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.
/sm

Starts Fileshare in sharing mode. It enables files to be shared using the 'Sharing with all other' sharing mode model.

This option is only applicable to stand-alone Fileshare, and only for those files not marked as transactional files (that is, not flagged with advanced logging). Transactional files will still be opened exclusively.

/uv

Instructs Fileshare to use the specified password file that is stored in the Vault Facility.

The password file must have been uploaded to a vault, with a prepended path of microfocus/fh, before you start Fileshare using this option. Upload the file using the mfsecretsadmin command; for example:

mfsecretsadmin write microfocus/fh/pass.dat  -file pass.dat  -vault aesvault
Note: If you update your password file, you must upload the updated version to the vault; see The mfsecretsadmin Utility for more information.
/clp
 Upgrades the password file to enable support for long usernames and passwords, up to 100 characters in length. It must be combined with the /pf option to upgrade a specific password file.
Note: Password files that are upgraded to enable long username and password support are no longer compatible with versions of Enterprise Developer prior to version 3.0. Once the /clp option has been run, all future password files created on the server now support long usernames and passwords.
  • Example Server Configuration File
Parent topic: Configuring the Fileshare Server
Related concepts
BKFHFHSHAFS010
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 clients and Fileshare servers. 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 Windows 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 platforms:

  • TCP/IP

    Setting: ccitcp

  • CCISMEM

    Setting: ccism

UNIX platforms:

  • TCP/IP

    Setting: 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 concepts
Fileshare Client Configuration Options
Configuring Your Fileshare Client
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 concepts
Specifying the Communications Protocol
Fileshare Client Configuration Options
Configuring Your Fileshare Client
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 concepts
Fileshare Client Configuration Options
Configuring Your Fileshare Client
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 reference
To Enable CTF Tracing
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 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
Fileshare 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
Related information
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Database Sequence Numbering


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
Related information
Advanced Rollback Recovery
Advanced Rollforward Recovery


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
Recovery Logging


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
Fileshare Exit Procedure - fsexitproc.cbl
Best Practices for Backup and Recovery
Enabling Advanced Recovery Logging


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
Fileshare Exit Procedure - fsexitproc.cbl
Best Practices for Backup and Recovery
Enabling Advanced Recovery Logging


Database Sequence Numbering

Database sequence numbering provides a method of linking groups of data files so that they and their corresponding log file can be kept in step.
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
Basic Recovery Logging


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

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
Related information
Basic Recovery Logging
Fileshare Manager
Best Practices Basic Logging


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
Related information
Fileshare Exit Procedure - fsexitproc.cbl
Best Practices for Backup and Recovery
Fileshare Client Configuration Options
Configuring the CCI Timeout


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.

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
Basic Recovery Logging


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.

Tip: You can specify multiple files at once by using a wildcard. The wildcard symbol must be the last character in the filename string. For example, the following syntax enables logging for all files in the TRANS-DATS folder:
fs /d dbase.ref /f TRANS-DATS\*

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
Advanced Rollback Recovery
Advanced Rollforward Recovery
Hot Backups


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
Related information
Automatic Database Backup and Rollforward 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
Related information
Fileshare Exit Procedure - fsexitproc.cbl
Advanced Rollforward Recovery
Advanced Rollback Recovery
Hot Backups
Running a Hot Backup


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 (FHRdrLngPwd or 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 (FHRdrLngPwd or 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 FHRdrLngPwd 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 either the FHRdrLngPwd or FHRdrPwd module. You can only use the FHRdrPwd module with Fileshare configured for short usernames and passwords, while FHRdrLngPwd module can be used with Fileshare that is configured for either short or long usernames and passwords.

Note: Micro Focus recommends that you only use the single module that is appropriate to the username and password length your Fileshare is configured for.

FHRdrLngPwd Module

To call the FHRdrLngPwd module for Fileshare systems that support short or long usernames and passwords, that is a user-ID and user-password defined as pic x(100):

call "fhrdrlngpwd" 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(100).
01 user-password       pic x(100).

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(100).
01 user-password    pic x(100).
...
procedure division.
...
    move 1 to          function-code
    move "UserID" to   user-name
    move "Password" to user-password
    call "fhrdrlngpwd" using function-code,
                             user-name,
                             user-password
    end-call
    ...
    open output testfile
    ...

You can substitute the FHRdrLngPwd 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 FHRdrLngPwd Module for further details.

FHRdrPwd Module

To call the FHRdrPwd module for Fileshare systems configured for short usernames and passwords, that is a user-ID and user-password defined as pic x(20).

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
    ...
Parent topic: Password System
Related information
Fileshare Server
Writing Your Own FHRdrLngPwd 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 FHRdrLngPwd Module
Password File Maintenance


Writing Your Own FHRdrLngPwd 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.
Note: Ensure that the user-ID and password parameters are defined as pic x(100) if you want your module to support long usernames and passwords.

Once you have written your own File Handling Redirector password module:

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

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 (FHRdrLngPwd or 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 (FHRdrLngPwd or 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(100).
password
pic x(100).
return-status
pic x comp-x.
Note: The FHRdrLngPwd module also requires the user-ID and password parameters to be defined as pic x(100) to support long usernames and passwords.

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. Most of the information in the password file is encrypted for security reasons, and so you can only add records to and remove records from the password file using the Password File Maintenance Utility. (User-IDs are not encrypted, allowing an administrator to view a list of valid users by browsing the file.

However, you can add extra security by storing this file in a Secrets vault (see Vault Facility for more information). To use this extra layer of security, use the /uv parameter when starting Fileshare, as detailed in Fileshare Server Configuration Options.

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 100 characters in length.
    Note: The username and password does not support the following characters "/\-". In addition, you should only use characters that are invariant when converted to EBCDIC.
  • [/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.

  • [/clp]

    The /clp option is used to upgrade password files created using Enterprise Developer prior to version 3.0. Upgraded password files can support long usernames and passwords up to 100 characters in length.

    Note: Micro Focus recommend that you take a backup of your password file before you upgrade.

Examples

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.

fs /pf pass.dat /clp

This example upgrades a password file that was created using Enterprise Developer prior to version 3.0. The upgraded password file now supports long usernames and passwords.

Parent topic: Security
Related concepts
The mfsecretsadmin Utility
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:

set FSCOMMS=$local /s servername

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.

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

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 | Description
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:\Windows. 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.

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


Large File Support with Fileshare

File size limits when using Fileshare are the same as those permitted with other, conventional, file handling operations (for example, see Indexed File Size Limits).

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.

Note: Striping is deprecated, and provided for backward compatibility only. We recommend you use IDXFORMAT"8" instead.

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.

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

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


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

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


Database File Handling and Enterprise Server Region Database Management

The Micro Focus Database File Handler (or MFDBFH for short) is a file handler that enables your native CICS and batch enterprise server applications to interact with data files and certain infrastructure files stored within a database.

Applications that use this file handler require no changes to their file handling source code, but you are required to make a number of changes to the environment in which those applications run.

Broadly speaking, you are required to:

  • Configure a number of ODBC data sources or connection strings.
  • Maintain a configuration file that references the sources and connections.
  • Configure enterprise server regions and/or applications to use the data sources\connections, to connect to data files within a datastore database, or to utilize region and cross-region databases in the running of certain Enterprise Server features.
  • If you are using database-hosted data files, you must also create and configure the datastores, using the command line utility dbfhdeploy to upload existing or create new data files in a datastore database.

MFDBFH currently supports Microsoft SQL Server, Microsoft Azure, PostgreSQL, Db2, and Oracle as the database solution.

  • System Requirements
    The minimum required versions for the supported databases and drivers.
  • Types of Database
    There are different types of database that you can create, designed to store different types of resources.
  • Database Permissions
    Certain permissions are required for users to create and/or use the different types of database stored in any of the database providers.
  • Configuration Requirements
    The amount of configuration required depends on the features that you employ from the Micro Focus Database File Handler and Enterprise Server Region Database Management.
  • Datastore Management
    Use the dbfhdeploy command line utility to administer your datastore databases.
  • Database Management and Recovery
    Use the dbfhadmin command-line tool to recover resources from region, cross-region, and datastore databases in the event of a system failure.
  • File View Generation
    Use the dbfhview command line utility to generate database views intended for viewing datastore data from within your proprietary database software.
  • Resource Locking
    Set up resource locking for a cluster of enterprise server regions that need to access resources from a database.
  • Record Locking Strategies
    MFDBFH supports the following types of record locking strategy: table record locking (default), in-memory record locking, and database record locking.
  • MFDBFH Error Messages
  • MFDBFH (Known Issues)
    There are a number of limitations to the Micro Focus Database File Handler currently. Some of the limitations may be permanent due to the database technologies in use, and some may just be temporary as the database file handling capabilities are developed.
Parent topic: Data Access
Related concepts
Planning and Designing XARs
Related information
ES_DB_FH
MFDBFH_CONFIG


System Requirements

The Micro Focus Database File Handler requires the following minimum support for databases and ODBC drivers.

Windows:

Database | ODBC driver
Microsoft SQL Server 2014 (including Express and Azure SQL Database editions) | ODBC 13.1 for SQL Server
PostgreSQL 10.x (incl. Amazon Aurora Postgres) | psqlodbc 12.02.0000
Db2 LUW 10.5 | n/a
Oracle 19c | n/a

UNIX:

Note: The MFDBFH is only supported on x86-64 running Red Hat Linux 7.3 or 7.4 or x86-64 running on SUSE v12 SP2 as these are also the minimum requirements for Microsoft SQL Server 2017.
Database | ODBC driver
Microsoft SQL Server 2017 (including Express and Azure SQL Database editions) | ODBC 13.1 for SQL Server Note: SQL Server 2017 installs versions 13 and 17 (x64 only)
PostgreSQL 10.x | psqlodbc 12.02.0000
Db2 LUW 10.5 | n/a
Oracle 19c | n/a

Additionally, there are minimum requirements for the following components:

Component | Version
Driver manager (MSSQL, Azure, and PostgreSQL installations only) | unixODBC 2.3.2
Parent topic: Database File Handling and Enterprise Server Region Database Management


Types of Database

The types of information that you plan to store within a database when utilizing the Micro Focus Database File Handler (MFDBFH) or enterprise server region management determines the types of database that you must configure.

It is possible that you would have more than one instance of these resources, and these can each be configured as separate databases, or preferably, you can house them all in one single database. Using one single database has performance benefits; for example, you can use the same database connection to access all resources (datastores, region and cost-region databases) stored in the same database; see Database Connections for more information.

The table below shows the types of database available, and when you are likely to use them:

Datastore database
A datastore database is designed to store any of the following data file types: KSDS, RRDS, ESDS, line-sequential, and fixed- and variable-length sequential files.
Using the dbfhadmin -script command line utility, you can create script files to run against your database that create the new datastores. Once created, you can upload existing files to the datastore.
Note: For all database types except Oracle, datastores can also be created implicitly if your application opens a data file specifying a datastore that doesn't currently exist; however, it is good practice to create the required datastores explicitly beforehand, using the script files or the dbfhadmin -createdb command. For Oracle datastores, the underlying database for the datastore must already exist beforehand.
Refer to the Configuring Datastores section for details on how to place new and existing data files in a database, and then depending on the type application that is to use the files, refer to Configuring CICS Applications for Native Database File Handling and Configuring the JCL Environment for Native Database File Handling. If your application was working correctly with the data files before they were moved to a database, your source code will not need to be altered/recompiled to be able to use datastore files.
However, if your applications are transactional, an additional XA resource is required to interact with the datastore. If you have COBOL applications that also use the same database (that contains the datastore), you'll need to configure multiple XA resources and then ensure the correct XAR is used in the correct scenario - refer to Working with Multiple XARs for details on how to handle such situations.
Region database
A region database contains tables and stored procedures that support certain features of a particular enterprise server region. The feature attribute, specified in the <dsn> element of the configuration file, determines the features currently being supported by the region database. (Resource locking - that is, ENQ/DEQ processing - is currently the only feature available.)
The following table shows the features that you can enable/disable within the configuration:
Value Description Example
all All available region features
<dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" feature="all"/>
none No region features
<dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" feature="none"/>
[+|-]reslocking Enable/disable database resource locking
<dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" feature="none +reslocking"/>
<dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" feature="all -reslocking"/>
If you omit the feature attribute from the <dsn> element, feature=all is assumed.
Features are stored as tables and stored procedures within the region database. There is no visible change to the data processing or operation of a region that is configured to use such a database.
Once configured, you are required to cold-start the region, where the region database will be created on startup. If the database already exists, its MFDBFH objects are dropped and recreated afresh.
See Configuring Region and Cross-Region Databases for each database type, for more information.
Cross-region database
A cross-region database facilitates functionality that is used across more than one enterprise server region. This can include such things as support for systems-scoped ENQ requests and recovery processing.
A cross-region database is required if you have also configured a region database, and must be configured on the same database server. If it does not already exist, it is created when the enterprise server region specified in your region database configuration is cold started; although, it is preferable that you create the database ahead of time, using database script files created with dbfhadmin -script.
See Configuring Region and Cross-Region Databases for more information.
Parent topic: Database File Handling and Enterprise Server Region Database Management
Related reference
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling
Working with Multiple XARs
Database Permissions


Database Permissions

If your data files are stored within a database, or your COBOL environment uses a database to perform any operations, you will require certain database permissions to interact with the database. These permissions will vary depending on the actions being performed and the database provider used.

The following lists show the permissions required for administrative users (users who typically create datastores and databases) and everyday users (users accessing data files within a database or operating within an environment where a database is performing some function). These lists should enable an administrator to create distinct database roles suited for the user type.

Administrative roles

For users who are required to create datastores and region\cross-region databases, ensure that they have permissions to the following operations:

SQL Server and Azure SQL Databases

  • ALTER TABLE ADD PRIMARY KEY
  • ALTER TABLE ALTER|DROP COLUMN
  • CREATE DATABASE
  • CREATE/ALTER/DROP TABLE
  • CREATE FUNCTION
  • CREATE PROCEDURE
  • CREATE SCHEMA
  • ALTER TABLE DROP CONSTRAINT
  • INSERT permissions for tables
  • EXECUTE permissions for stored procedures and functions

PostgreSQL

  • ALTER COLUMN
  • CREATE DATABASE
  • CREATE/ALTER/DROP TABLE
  • CREATE/DROP TYPE
  • CREATE INDEX
  • CREATE FUNCTION
  • CREATE SCHEMA
  • EXECUTE permissions for functions
  • INSERT permissions for tables
  • ALTER TABLE ALTER COLUMN SET DATA
  • ALTER TABLE DROP COLUMN

Db2

  • ALTER COLUMN
  • CALL SYSPROC.ADMIN_CMD('REORG TABLE <table-name>')
  • CREATE DATABASE
  • CREATE BUFFERPOOL
  • CREATE TABLESPACE
  • CREATE SCHEMA
  • CREATE/ALTER TABLE
  • CREATE INDEX
  • CREATE PROCEDURE
  • CREATE FUNCTION
  • EXECUTE permissions for stored procedures and functions
  • INSERT permissions for tables
  • ALTER TABLE ALTER COLUMN SET DATA
Note: The database creation scripts generated by dbfhadmin -script will grant the appropriate permissions required by MFDBFH to PUBLIC for each of the objects created.

Oracle

  • ALTER TABLE DROP|ADD CONSTRAINT
  • CREATE USER
  • CREATE/ALTER TABLE
  • CREATE INDEX
  • CREATE PROCEDURE
  • CREATE FUNCTION
  • ALTER TABLE MODIFY <column>
  • Table INSERT permission
  • Stored procedure and function EXECUTE permissions
Note: The database creation scripts generated by dbfhadmin -script will grant the appropriate permissions required by MFDBFH to PUBLIC for each of the objects created unless the MFDBFH_GRANT_USER_PERMISSIONS variable is set; in which case, permission is granted to those users/roles specified.

All other users

For users who handle data files that are stored in a database, or are running in an environment where some of the operations are handled using a region or cross-region, ensure that they have permissions to the following operations:

SQL Server and Azure SQL Databases

  • ALTER TABLE ADD PRIMARY KEY
  • ALTER TABLE ALTER|DROP COLUMN
  • CREATE/ALTER/DROP TABLE
  • CREATE FUNCTION
  • CREATE PROCEDURE
  • CREATE SEQUENCE
  • ALTER TABLE DROP CONSTRAINT
  • INSERT permissions for tables
  • EXECUTE permissions for stored procedures and functions

PostgreSQL

  • ALTER COLUMN
  • CREATE/ALTER/DROP TABLE
  • CREATE INDEX
  • CREATE FUNCTION
  • CREATE SEQUENCE
  • EXECUTE permissions for functions
  • SELECT/INSERT/UPDATE/DELETE permissions for tables
  • ALTER TABLE ALTER COLUMN SET DATA
  • ALTER TABLE DROP COLUMN

Db2

  • ALTER COLUMN
  • CALL SYSPROC.ADMIN_CMD('REORG TABLE <table-name>')
  • CREATE/ALTER/DROP TABLE
  • CREATE INDEX
  • CREATE/DROP PROCEDURE
  • CREATE SEQUENCE
  • EXECUTE permissions for stored procedures and functions
  • SELECT/INSERT/UPDATE/DELETE permissions for tables
  • ALTER TABLE ALTER COLUMN SET DATA
Note: When MFDBFH dynamically creates database objects, it grants the appropriate permissions it requires to PUBLIC for each one.

Oracle

  • ALTER TABLE DROP|ADD CONSTRAINT
  • CREATE/ALTER/DROP TABLE
  • CREATE INDEX
  • CREATE/DROP PROCEDURE
  • CREATE SEQUENCE
  • ALTER TABLE MODIFY <column>
  • Table SELECT/INSERT/UPDATE/DELETE permission
  • Stored procedure and function EXECUTE permissions
Note: When MFDBFH dynamically creates database objects, it grants the appropriate permissions it requires to PUBLIC for each one unless the MFDBFH_GRANT_USER_PERMISSIONS variable is set; in which case, permission is granted to those users/roles specified.
  • Further Recommended Privilege and Role Permissions for Oracle Users
Parent topic: Database File Handling and Enterprise Server Region Database Management
Related concepts
Types of Database


Further Recommended Privilege and Role Permissions for Oracle Users

This section outlines the minimum permissions required to interact with Oracle when using MFDBFH. It covers how to create the necessary tables/procedures/types used by Enterprise Server. There are two recommended processes in which to grant the minimum required privileges to users that require MFDBFH to function with Oracle:

  • Method 1 creates three roles that cover the various uses of MFDBFH; assign users to one or more of these roles, as appropriate. Each role is configured to contain the permissions that MFDBFH will require. This method still requires the GRANT ANY privileges, which can be deemed as insecure.
  • Method 2 utilizes proxy users. This may result in additional database connections per process, and you cannot perform an upgrade of MFDBFH without manual intervention; however, this method does removes the requirement for GRANT ANY.
Note about setting MFDBFH_GRANT_USER_PERMISSIONS:

The environment variable MFDBFH_GRANT_USER_PERMISSIONS specifies which users/roles to grant execute privileges to for the various procedures/types created by MFDBFH. If you intend to start an enterprise server region under a different user to the one that will use these procedures/types, then you must also specify them with this variable.

Use a space-delimited string to specify the roles or users that require grant execute privileges. For example; if you have 2 roles, named role_dbfh_admin and role_dbfh_standard, which are used for running the region, and a 3rd role named role_dbfh_install used only for creating the datastores and region/cross-region databases, you would set the following:

MFDBFH_GRANT_USER_PERMISSIONS=role_dbfh_admin role_dbfh_standard

The roles of any other users that may start the region would also need to be specified within the variable. This variable also needs to be set in the region itself if you intend to run the region with multiple different users, because Enterprise Server will also create tables/procedures on-the-fly as new data files are created.

After the variable is set, you can use the dbfhadmin commands to create your datastores.

  • Method 1 - Using MFDBFH-specific roles
  • Method 2 - Proxy users
Parent topic: Database Permissions


Method 1 - Using MFDBFH-specific roles

This method recommends that you create a number of roles that cover the distinct MFDBFH-related interactions with an Oracle database, and then assign users to the appropriate roles. Each role should contain the permissions to the functions/operations likely to be required for that role.
Note: When MFDBFH dynamically creates database tables, it grants the appropriate permissions it requires to the PUBLIC role for each table. For procedures, types, and functions, only the schema owner receives permission, unless the MFDBFH_GRANT_USER_PERMISSIONS environment variable is set; in which case, those users/roles are granted the appropriate permissions.

Install role

This role is appropriate for administrative users who are required to create and install datastores and region/cross-region databases. This role needs permissions to the following operations:

Function | Purpose
CREATE ANY TABLE/INDEX/SEQUENCE/TYPE/PROCEDURE/VIEW | to create all listed objects required for datastores and region/cross-region databases
CREATE SESSION | to connect to an Oracle database
CREATE USER | to create schemas for datastores and region\cross-region databases
DROP ANY TABLE | to drop schema.tables if there were any errors during the creation process
GRANT ANY OBJECT PRIVILEGE | to grant appropriate privileges on tables, data types, procedures and functions, to other users
SELECT on sys.v_$active_instances | to record and make decisions based on an Oracle RAC configuration
SELECT on sys.v_$instance | to record and make decisions based on a non-RAC Oracle configuration
SELECT on sys.v_$parameter | to record and make decisions based on the Oracle max_string_size configuration
SELECT ANY SEQUENCE | to create tables with identity columns for datastores and region/cross-region databases

Upgrade role

This role is appropriate for users required to perform datastore upgrades (using the dbfhadmin -upgrade command). This role needs permissions to the following operations:

Function | Purpose
ALTER ANY TABLE/INDEX/SEQUENCE/TYPE/PROCEDURE/VIEW | to modify listed objects required across datastores and region/cross-region databases
CREATE ANY TABLE/INDEX/SEQUENCE/TYPE/PROCEDURE/VIEW | to create listed new objects required across datastores and region/cross-region databases)
CREATE SESSION | to connect to an Oracle database
DROP ANY TABLE/INDEX/SEQUENCE/TYPE/PROCEDURE/VIEW | to drop listed old objects across datastores and region/cross-region databases
GRANT ANY OBJECT PRIVILEGE | (to grant appropriate privileges on new tables, data types, procedures and functions to other users
SELECT on sys.v_$active_instances | to record and make decisions based on an Oracle RAC configuration
SELECT on sys.v$instance | to record and make decisions based on a non-RAC Oracle configuration
SELECT on sys.v_$parameter | to record and make decisions based on the Oracle max_string_size configuration
SELECT ANY SEQUENCE | to create tables with identity columns for datastores and region/cross-region databases

Standard role

This role is appropriate for any user that handles data files that are stored in a database, and who are running in an environment where some of the operations are handled using a region or cross-region database. This role needs permissions to the following operations:

Tip: This role is also sufficient for those who are starting/restarting MFDBFH-enabled enterprise server regions. However, they will not be able to perform an upgrade, and so manual intervention is required if MFDBFH detects an upgrade is necessary; therefore, we recommend starting regions with a user who has both an install and upgrade role.
Function | Purpose
Table SELECT/INSERT/UPDATE/DELETE/ALTER | to maintain tables (These permissions should have been granted by the 'create' scripts for datastores and region/cross-region databases, or by the upgrade process.)
Type, stored procedure and function EXECUTE | to execute required procedures/functions (These permissions should have been granted by the 'create' scripts for datastores and region/cross-region databases, or by the upgrade process.)
GRANT ANY OBJECT PRIVILEGE | to grant appropriate privileges on new tables, data types, procedures and functions, to other users
CREATE ANY TABLE/INDEX/SEQUENCE/TYPE/PROCEDURE | to create all listed objects required for datastores and region/cross-region databases
DROP ANY TABLE/INDEX/SEQUENCE/TYPE/PROCEDURE | to drop listed old objects across datastores and region/cross-region databases
CREATE USER | to create schemas for datastores and region\cross-region databases
CREATE SESSION | to connect to an Oracle database
SELECT on sys.v_$active_instances | to record and make decisions based on an Oracle RAC configuration
SELECT on sys.v_$instance | to record and make decisions based on a non-RAC Oracle configuration
SELECT on sys.v_$parameter | to record and make decisions based on the Oracle max_string_size configuration
SELECT ANY SEQUENCE | to create tables with identity columns, for datastores and region/cross-region databases
Parent topic: Further Recommended Privilege and Role Permissions for Oracle Users
Related information
Method 2 - Proxy users


Method 2 - Proxy users

This method makes use of proxy connections, which results in more restrictive permissions for the users, but provides a more secure environment. It does mean that there may be more connections to the database, per process, as a separate connection is required for each unique set of credentials.

It is recommended to create the relevant schemas before starting the MFDBFH-enabled enterprise server region, rather than allowing the region to automatically generate the schemas, as you need to create and grant the appropriate privileges to the schema users to be able to use them as proxies.

Micro Focus suggest performing the following steps:

  1. Create the schema users for the region, cross-region and any datastores you intend to use.
    Tip: You can locate the names of the schema users in the creation scripts that are produced using the dbfhadmin -script command (for an example, see Create Oracle Datastores Using Script Files). Within the script, search for the ‘CREATE USER’ statement. In general, they are:
    Datastores | Name of the datastore prefixed with DBFH_; for example, DBFH_VSAM for a datastore named ‘VSAM’
    Region databases | Name of the PAC prefixed with DBRG_; for example, DBRG_TESTDB for a PAC named ‘TESTDB’
    Cross-region databases | Always named DBRG__XREGN_
  2. Grant the appropriate permissions for each schema user to allow proxy connections and the creation of tables/procedures within their own schemas. For example, grant the following (replacing <schema-user> with the schema users located above, and <user> with the user you intend to make the proxy connection through):
    ALTER USER <schema-user> GRANT CONNECT THROUGH <user>
GRANT CREATE SESSION, CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE, CREATE TYPE TO <schema-user>
GRANT SELECT ON SYS.V_$ACTIVE_INSTANCES
GRANT SELECT ON SYS.V_$INSTANCE
GRANT SELECT ON SYS.V_$PARAMETER
GRANT UNLIMITED TABLESPACE TO <schema-user>

    See the lists in Method 1 - Using MFDBFH-specific roles for the minimum required permissions for each user, depending on the role they perform.

  3. Populate the relevant region and cross-region schemas. This should be done via the scripts generated with dbfhadmin. You can execute these using sqlplus or dbfhadmin, ensuring you provide the credentials as the proxy user. For example:
    sqlplus dbfhinstall[DBRG__XREGN_]/dbfhinstall@DBFHTEST @datastorescript.sql
dbfhadmin -createdb -file:createregn.sql -type:region -provider:ora -existdb:DBFHTEST -user:dbfhinstall[DBRG_TESTDB] -password:dbfhinstall
  4. In your MFDBFH configuration file, ensure the proxy user is specified in the connection string. The proxy user for each connection should be the name of the schemas identified above. For example:
    <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" optio="none" dbname="DBFHTEST" connect="dbfhdefault[DBFH_VSAM]/dbfhdefault@DBFHTEST"/>
<dsn name="ORA.CAS.CROSSREGION" type="crossregion.cas" dbname="DBFHTEST" connect="dbfhdefault[DBRG__XREGN_]/dbfhdefault@DBFHTEST"/>
<dsn name="ORA.CAS.TESTDB" type="region.cas" region="TESTDB" dbname="DBFHTEST" connect="dbfhdefault[DBRG_TESTDB]/dbfhdefault@DBFHTEST"/>

To reduce the number of connections per process, you could specify the proxy user for the region and cross-region databases to be the same user as used for one of your datastores; each other datastore will still needs its own unique proxy user. This can only be done if you populate the region/cross-region databases before you start the enterprise server region, as otherwise the necessary tables are not created. In the above example, this would mean replacing DBRG__XREGN_ and DBRG_TESTDB with DBFH_VSAM, which reduces the number of connections used for proxy users from 3 to 1.

Note: If you configure your proxy users this way and are prompted that an upgrade is required, you will need to perform the upgrade manually for your region and cross-region databases, using the dbfhadmin -upgrade command. Datastores will still be upgraded automatically, because the correct user is defined in the database configuration file, but as the configuration file now specifies that user for the connection to the region and cross-region databases also, you will need to manually run dbfhadmin specifying the region/cross-region database users (located in step 1) for the upgrade to be successful.
Parent topic: Further Recommended Privilege and Role Permissions for Oracle Users
Related concepts
The dbfhadmin Command Line Utility
Related information
Method 1 - Using MFDBFH-specific roles


Configuration Requirements

The amount of configuration required depends on the features that you employ from the Micro Focus Database File Handler and Enterprise Server Region Database Management.
Following the instructions in the sections indicated that match your requirements:
  • If you plan to store data files within one of the supported databases, refer to the Configuring Datastores... topic in the relevant section for your database provider.
  • If you plan to use a CICS application that uses data files stored within a database, refer to Configuring CICS Applications for Native Database File Handling.
  • If you plan to use a JCL application that uses data files stored within a database, refer to Configuring the JCL Environment for Native Database File Handling.
  • If you plan to use the database to handle your application's resource locking, refer to Configuring Region and Cross-Region Databases... topic in the relevant section for your database provider.
    Note: If an enterprise server region is running as part of a Performance and Availability Cluster (PAC), resource locking must be managed in a database.
  • Using Microsoft SQL Server
    Configuration details for using Microsoft SQL Server to store and interact with data files, and to perform certain enterprise server region management/housekeeping tasks.
  • Using PostgreSQL
    Configuration details for using PostgreSQL to store and interact with data files, and to perform certain enterprise server region management/housekeeping tasks.
  • Using Db2
    Configuration details for using Db2 to store and interact with data files, and to perform certain enterprise server region management/housekeeping tasks.
  • Using Oracle
    Configuration details for using Oracle to store and interact with data files, and to perform certain enterprise server region management/housekeeping tasks.
  • Configuring CICS Applications for Native Database File Handling
    Details on the necessary adjustments required to your CICS environment to use the native database file handler.
  • Configuring the JCL Environment for Native Database File Handling
    Details on the necessary adjustments required to your JCL environment to use the native database file handler.
  • The Database Configuration File
    A configuration file is used to specify the data sources and types of database utilized by the Micro Focus Database File Handler (MFDBFH) and enterprise server region management.
  • Database Connections
    Connecting the Micro Focus Database File Handler to a database uses either an ODBC data source name, or syntax that makes a direct connection to the database.
Parent topic: Database File Handling and Enterprise Server Region Database Management


Using Microsoft SQL Server

Use this section to configure datastores and/or enterprise server region and cross-region databases in Microsoft SQL Server.

Tip: It is recommended that you create any required datastores or databases ahead of time (using dbfhadmin -script|-createdb), so as to not impact on processing time - the following steps will take you through this process. If a datastore/database does not exist at the point that your application attempts to access it, the application must wait for it to be created on-the-fly.
  • Configure Datastores for Microsoft SQL Server
    Use these steps to configure datastore databases in Microsoft SQL Server.
  • Configure Region and Cross-Region Databases in Microsoft SQL Server
    Use these steps to configure region and cross-region databases in Microsoft SQL Server.
Parent topic: Configuration Requirements
Related reference
The dbfhadmin Command Line Utility


Configure Datastores for Microsoft SQL Server

Use these steps to configure datastore databases in Microsoft SQL Server.

  1. Create Microsoft SQL Server Datastores Using Script Files
  2. Update the Configuration File for Microsoft SQL Server Datastores
  3. Windows: Create Datastore Data Sources for Microsoft SQL Server
  4. UNIX: Create Datastore Data Sources for Microsoft SQL Server
  5. Upload Files to a Microsoft SQL Server Datastore
  6. Create an XA Resource
Parent topic: Using Microsoft SQL Server
Related information
Configure Region and Cross-Region Databases in Microsoft SQL Server


Create Microsoft SQL Server Datastores Using Script Files

If a database does not exist at the point that it is required (for example, you attempt to upload a data file to a datastore that has not yet been created in the database instance), it is created on-the-fly; this can be slow for certain RDBMS types, and so we recommended that you create any required databases ahead of time, using SQL scripts.

  1. To create the database script file, on the command line, enter the following command:
    dbfhadmin -script -type:datastore -provider:ss -name:<datastore-name> [-db|existdb:<database-name>] [-file:<script-name.sql>]

    where <datastore-name> is the name of the datastore to create; <database-name> is the name of a new database (-db) or existing database (-existdb) that can house multiple datastores\regions, and a cross-region database - if you omit either option, a new database called <datastore-name> will be created for the datastore; <script-name.sql> is the name of the script file to be created .

    Note: If you omit the -file option, the default name is create_datastore_<datastore-name>_ss.sql.
  2. Create further script files for any more required datastores.

    Once you have created the script files, use the dbfhadmin utility to run them, and create the required databases. Before you run the -createdb command, ensure that the sqlcmd command is on the PATH.

  3. To create the datastore(s) on the command line, enter the following command:
    dbfhadmin -createdb -usedb:<instance> -provider:ss -type:datastore -file:<script-name.sql> -user:<user> -password:<pass>

    where <instance> is the SQL server instance name, and <user> and <pass> are valid logon credentials for the database. If -user and -password are not specified, SQL Server SSPI authentication is used - see your SQL Server documentation for more details.

Note: If you do not use script files for datastore creation, you can also create them using the dbfhdeploy data create URL/<datastore-name> command.

Now that the datastores have been created, you can configure the database configuration file to use them.

Parent topic: Configure Datastores for Microsoft SQL Server
Next topic: Update the Configuration File for Microsoft SQL Server Datastores


Update the Configuration File for Microsoft SQL Server Datastores

You should only create or update a configuration file using the dbfhconfig command line utility.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:ss

    where <server-name> is the name of the database server instance. An entry of (local) or localhost is also valid, which defaults to your machine name.

    Next you need to specify the databases within the instance.

  4. Firstly, you need to create a reference to the master database - this is the primary configuration database supplied with MSSQL:
    Note: If the <server> element for your database server instance already exists, this reference should already exist.
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:database -name:master [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the master database (in which case, make a note of it for later), or a unique name within the server configuration in which to reference the database if you are using a connection string; and <connection-string> is the database connection string if you are establishing a database connection without the use of an ODBC data source - see Database Connection Strings for the database-specific syntax.

  5. Repeat the following step for each required datastore:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:datastore [-db:<existing-db>] [odbcdsn:<dsn-name>] -optio:<opts> -name:<dsname> [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the datastore (in which case, make a note of it for later), or a unique name within the server configuration in which to reference the datastore if you are using a connection string; <existing-db> is the name of an existing database in which the datastore is stored - if this option is omitted, it is implied that the datastore is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <opts> are the optimizations to be applied to I/O operations; and <dsname> is the actual name of the datastore (as configured in the data source properties).

    <opts> can be one of:
    option | description
    all | All optimizations applied, as if +<opt> had been specified for each available option. You can then selectively disable certain options using -<opt>.
    none | No optimizations applied.
    {+|-}oiseq | Enables (+) or disables (-) optimizations for line-sequential files opened for input.
    {+|-}ooseq | Enables (+) or disables (-) optimizations for line-sequential files opened for output.
    {+|-}oi | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for input.
    {+|-}oo | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for output.

Example configuration file

The configuration file is written to after each command. The following is an example of a configuration file that contains two datastores, a region database and a cross-region database; each of these is stored in their own database within the instance (and named according to the dbname attribute). The MSSQL server instance is also configured for Windows authentication, hence the omission of the userid and password attributes.

<datastores usevault="false">
   <server name="(local)" type="sqlserver" access="odbc">
      <dsn name="SS.MYMASTER" type="database" dbname="master"/>
      <dsn name="SS.VSAM" type="datastore" dsname="VSAM" dbname="VSAM"/>
      <dsn name="SS.SEQ" type="datastore" dsname="SEQ" dbname="SEQ" optio="all -ooseq"/>
      <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" dbname="ESDEMO" feature="all"/>
      <dsn name="SS.CROSSREGION" type="crossregion.cas" dbname="_$XREGN$"/>
   </server>
</datastores>

Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have used connection strings, you can skip the data source creation and use the dbfhdeploy command line utility to upload files to your datastores.

Parent topic: Configure Datastores for Microsoft SQL Server
Previous topic: Create Microsoft SQL Server Datastores Using Script Files
Next topic: Windows: Create Datastore Data Sources for Microsoft SQL Server
Related reference
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling
Configure a Secrets Vault for the Micro Focus Database File Handler
Database Connection Strings
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Windows: Create Datastore Data Sources for Microsoft SQL Server

Note: We recommend that you use a connection string to connect to Microsoft SQL Server databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for Microsoft SQL Server Datastores.

If you did not use connection strings when configuring the database configuration file, use the following steps to create ODBC data sources to access the datastore databases.

  1. Open the ODBC Data Source Administrator.
    Tip: On most newer Windows versions, click the Start Menu button, type ODBC, and then select the appropriate desktop app.
  2. On the ODBC Data Source Administrator dialog box, select the System DSN tab.
  3. Add the mandatory data sources:
    Note: In order to create or query databases, you must have an active data source connection to the master database (the primary configuration database supplied with MSSQL). If this data source already exists, you can skip this step.
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, ODBC 17 for SQL Server is a common one for MSSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The Create New Data Source... wizard appears.

    3. Enter a name and description for the data source, and the name of the server on which the database will reside.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this database.

    4. Click Next twice.
    5. Select the Change the default database to: option, and enter master.
    6. Click Next, and then click Finish.

      An overview of the data source details is displayed.

    7. Click Test Data Source.

      The connection should be successful; if not, it indicates that you have a problem with your Microsoft SQL Server installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    8. Click OK twice.
  4. Add a new data source for each required datastore:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, ODBC 17 for SQL Server is a common one for MSSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The Create New Data Source... wizard appears.

    3. Enter a name and description for the data source, and the name of the server on which the database will reside.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this datastore.

    4. Click Next twice.
    5. Select the Change the default database to: option, and if your datastore is to be housed in a single physical database containing other datastores/region databases, enter the name of that database as specified by -db|existdb:<db-name> when updating the database configuration file, or if the datastore is to be housed in its own database, enter the name of the database as specified by -name:<dsname> when updating the database configuration file.
    6. Click Next, and then click Finish.

      An overview of the data source details is displayed.

    7. Click Test Data Source.

      The connection should be successful; if not, it indicates that you have a problem with your Microsoft SQL Server installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    8. Click OK.

      The ODBC Data Source Administrator appears again.

    9. Repeat these sub-steps for each additional datastore you require.
  5. Click OK.

    The data sources for the datastores are configured.

The data sources for the datastore databases are configured. You can now start to upload data files to them using the dbfhdeploy command line utility.

Parent topic: Configure Datastores for Microsoft SQL Server
Previous topic: Update the Configuration File for Microsoft SQL Server Datastores
Next topic: UNIX: Create Datastore Data Sources for Microsoft SQL Server


UNIX: Create Datastore Data Sources for Microsoft SQL Server

If you did not use connection strings when configuring the database configuration file, use the following steps to create ODBC data sources to access the datastore databases.

There are a number of different driver managers that you can use to configure an ODBC data source. These instructions are carried out using unixODBC. If you are using a different driver manager, consult the vendor instructions for creating data sources.

  1. Run the command odbcinst -j command, and note down the location of the drivers configuration file (odbcinst.ini) and the user data sources configuration file (.odbc.ini).
  2. Open the odbcinst.ini configuration file and ensure that you have something similar to the following:

    (This may differ depending on the version of MSSQL you are running.)

    [ODBC Driver 17 for SQL Server]
Description=Microsoft ODBC Driver 17 for SQL Server
Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.2.so.0.1
UsageCount=1
  3. Open the .odbc.ini configuration file and add an entry for the mandatory data source:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Database = master
    where:
    • <datasource-name> - a name for the data source.
    • <driver-name> - the name of the driver as configured in the .odbcinst.ini file; in the example above, that would be ODBC Driver 17 for SQL Server.
    • <server-name> - the name of the server on which the database instance resides.
    • master - the name of the primary configuration database supplied with MSSQL.
  4. Add a new data source entry for each required datastore:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Database = <datastore-name>
    where:
    • <datastore-name> - the name of the datastore that you want to create.
  5. Save the .odbc.ini configuration file.

Example .odbc.ini file

The following is an example of an .odbc.ini configuration file contains data sources for a local MSSQL database instance with two datastores. It also includes the mandatory data source for the master database.

[SS.MASTER]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = master

[SS.VSAM]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = VSAM

[SS.SEQFILES]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = SEQ
The data sources for the datastore databases are configured. You can now start to upload data files to them using the dbfhdeploy command line utility.
Parent topic: Configure Datastores for Microsoft SQL Server
Previous topic: Windows: Create Datastore Data Sources for Microsoft SQL Server
Next topic: Upload Files to a Microsoft SQL Server Datastore


Upload Files to a Microsoft SQL Server Datastore

Use these steps to upload existing data files to the datastore databases created in the previous steps.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, if you have used ODBCS data sources, the command prompt must be the same bitism as the data sources that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the database configuration file that contains a reference to the data source:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, the file is assumed to be located in the current directory, or you may use the -configfile:<name> option appended to the following dbfhdeploy commands (see The dbfhdeploy Command Line Utility for more details).

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a data file to the datastore:
    dbfhdeploy data add <filename> URL/<file-ref>[?folder=<folder-name>]

    If <folder-name> does not already exist, it is created.

  4. To test that the data file is now in the datastore, you can produce a listing of files and folders in the database using dbfhdeploy:
    dbfhdeploy list URL[?folder=<folder-name>]

    A list of files is displayed.

    Note: If you do not specify a folder name, only files and folders at the base level of the datastore are displayed.

If any of the files in your datastore are transactional, you must also configure an XA resource within the enterprise server region that points to the datastore; see Create an XA Resource. If none of your files are transactional, you can skip that step and proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore, and if resource locking is to be managed by an enterprise server region, configuring region and cross-region databases.

Parent topic: Configure Datastores for Microsoft SQL Server
Previous topic: UNIX: Create Datastore Data Sources for Microsoft SQL Server
Next topic: Create an XA Resource
Related reference
The dbfhdeploy Command Line Utility
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling


Create an XA Resource

Your enterprise server region requires an XA resource for each datastore that contains one or more transactional files. If the database containing the datastore is also used by other COBOL applications, additional XA resources are required. Refer to Working with Multiple XARs for details on how to handle such situations.

  1. Open the ESCWA Administration page, and then select the enterprise server that references the transactional data file from the left pane.
  2. In the right pane, click General > XA Resources.
  3. Click NEW.
  4. Specify the following XAR details:
    Option | Description
    ID | Unique ID for the XAR
    Name | Unique name for the XAR
    Module | Specify the location of the RM switch module executable file (.dll on Windows or .so on UNIX platforms). This is database specific: esmssql.dll/.so for MSSQL and Azure SQL, ESPGSQLXA.dll/.so for PostgreSQL, and ESDB2XA.dll/.so for Db2. Refer to Building RM Switch Modules for more information.
    Enabled | Enable the resource for immediate use.
    Open string DSN=<datastore-dsn>

    where <datastore-dsn> is the ODBC data source name of the datastore you are configuring.

    Note: These are only the mandatory options required, with the addition of USRPASS=userid.password if you are using a PostgreSQL database. You can also specify further options as required, as detailed in To define an XA resource (XAR) for an enterprise server region.
  5. Click SAVE.

    The XA resource should be effective immediately.

You can now proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore.

Parent topic: Configure Datastores for Microsoft SQL Server
Previous topic: Upload Files to a Microsoft SQL Server Datastore
Related concepts
Building RM Switch Modules
Related reference
To define an XA resource (XAR) for an enterprise server region
Working with Multiple XARs
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling


Configure Region and Cross-Region Databases in Microsoft SQL Server

Use these steps to configure region and cross-region databases in Microsoft SQL Server.

You can connect to a Microsoft SQL Server database using two methods. The recommended method is to use connection strings, which are configured using the connect attribute within the database configuration file. You can also connect using an ODBC data source.

  1. Create Microsoft SQL Server Region and a Cross-Region Database Using Script Files
  2. Update the Configuration File for Microsoft SQL Server Region and Cross-Region Databases
  3. Windows: Create Region and Cross-Region Data Sources for Microsoft SQL
  4. UNIX: Create Region and Cross-Region Data Sources for Microsoft SQL
  5. Configure a Region or Cross-Region Database in Enterprise Server
Parent topic: Using Microsoft SQL Server
Related information
Configure Datastores for Microsoft SQL Server


Create Microsoft SQL Server Region and a Cross-Region Database Using Script Files

If a database does not exist at the point that it is required, it is created on-the-fly; this can be slow for certain RDBMS types, and so we recommended that you create any required databases ahead of time, using SQL scripts.

  1. To create a script file for a region database, on the command line, enter the following command:
    dbfhadmin -script -type:region -provider:ss -name:<ES-name> [-db|existdb:<database-name>] [-file:<script-name.sql>]

    where <ES-name> is the name of the enterprise server region that will use the region database; <database-name> is the name of a new database (-db) or existing database (-existdb) that can house multiple datastores\regions, and a cross-region database - if you omit either option, a new database called <ES-name> will be created for the region database; <script-name.sql> is the name of the script file to be created.

    Note: If you omit the -file option, the default name is create_region_<ES-name>_ss.sql.
  2. To create a script file for a cross-region database, on the command line, enter the following command:
    dbfhadmin -script -type:crossregion -provider:ss [-db|existdb:<database-name>] [-file:<script-name.sql>]

    where <database-name> is the name of a new database (-db) or existing database (-existdb) that can house multiple datastores\regions, and a cross-region database - if you omit either option, a new database called _$XREGN$ will be created for the cross-region database

    Note: If you omit the -file option, the default name is create_crossregion_ss.sql.

    Before you run the -createdb command, ensure that the sqlcmd command is on the PATH.

  3. To create the region database, on the command line, enter the following command:
    dbfhadmin -createdb -usedb:<instance> -provider:ss -type:region -name:<ES-name> -file:<script-name.sql> -user:<user> -password:<pass>

    where <instance> is the SQL server instance name, and <user> and <pass> are valid logon credentials for the database. If -user and -password are not specified, SQL Server SSPI authentication is used - see your SQL Server documentation for more details.

  4. To create the cross-region database, on the command line, enter the following command:
    dbfhadmin -createdb -usedb:<instance> -provider:ss -type:crossregion -file:<script-name.sql> -user:<user> password:<pass>

    where <instance> is the SQL server instance name, and <user> and <pass> are valid logon credentials for the database. If -user and -password are not specified, SQL Server SSPI authentication is used - see your SQL Server documentation for more details.

Now that the region and cross-region databases have been created, you can configure the database configuration file to use them.

Parent topic: Configure Region and Cross-Region Databases in Microsoft SQL Server
Next topic: Update the Configuration File for Microsoft SQL Server Region and Cross-Region Databases
Related reference
Types of Database


Update the Configuration File for Microsoft SQL Server Region and Cross-Region Databases

Use these steps to create or update a configuration file to include entries to one or more region databases, and a cross-region databases.

You should only create or update a configuration file using the dbfhconfig command line utility.

If you are configuring a file that has previously been configured for the database instance that you are working with, you can jump to step 5, ensuring that you use the same <server-name> as previously used.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:ss

    where <server-name> is the name of the database server instance. An entry of (local) or localhost is also valid, which defaults to your machine name. If you have already updated the configuration file with the MSSQL datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

    Now specify the required databases within the instance.

  4. Firstly, you need to create a reference to the master database - this is the primary configuration database supplied with MSSQL:
    Note: If the <server> element for your database server instance already exists, this reference should already exist as well, and so again, skip this step.
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:database -name:master [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the master database (in which case, make a note of it for later), or a unique name within the server configuration in which to reference the database if you are using a connection string; and <connection-string> is the database connection string if you are establishing a database connection without the use of an ODBC data source - see Database Connection Strings for the database-specific syntax.

    Note: On Windows, you may omit the userid and password attributes for local MSSQL installations that allow Windows (SSPI) authentication.
  5. Repeat the following step for each required region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> [-db:<existing-db>] [odbcdsn:<dsn-name>] -type:region -name:<region-name> -feature:<options> [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the region database if you are using a connection string; <existing-db> is the name of an existing database in which the region database is stored - if this option is omitted, it is implied that the region database is housed in its own database; <dsn-name2> is the name of the data source for the shared connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <region-name> is the name of the enterprise server region that this database will serve; and <options> is a list of features for which the region will use the database.

    <options> can be one or more of:
    • all - all available region features enabled (default).
    • none - no region features enabled.
    • [+|-]reslocking - enables\disables database resource locking.
  6. Now add a reference to a single cross-region database:
    dbfhconfig -add -server:<server-name> -dsn:<dsn-name> -type:crossregion [-db:<existing-db>] [odbcdsn:<dsn-name2>][-connect:<connection-string>]
    where <name> is either the name you will give an ODBC data source for the cross-region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the cross-region database if you are using a connection string; <existing-db> is the name of an existing database in which the cross-region database is stored - if this option is omitted, it is implied that the cross-region database is housed in its own database; <dsn-name2> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information.

Example configuration file

The configuration file is written to after each command. The following is an example of a configuration file that contains two datastores, a region database and a cross-region database; each of these is stored in their own database within the instance (and named according to the dbname attribute). The MSSQL server instance is also configured for Windows authentication, hence the omission of the userid and password attributes.

<datastores usevault="false">
   <server name="(local)" type="sqlserver" access="odbc">
      <dsn name="SS.MYMASTER" type="database" dbname="master"/>
      <dsn name="SS.VSAM" type="datastore" dsname="VSAM" dbname="VSAM"/>
      <dsn name="SS.SEQ" type="datastore" dsname="SEQ" dbname="SEQ" optio="all -ooseq"/>
      <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" dbname="ESDEMO" feature="all"/>
      <dsn name="SS.CROSSREGION" type="crossregion.cas" dbname="_$XREGN$"/>
   </server>
</datastores>
Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have configured connection strings, you can skip the data source creation and configure your enterprise server regions to use the region and cross-region databases.
Parent topic: Configure Region and Cross-Region Databases in Microsoft SQL Server
Previous topic: Create Microsoft SQL Server Region and a Cross-Region Database Using Script Files
Next topic: Windows: Create Region and Cross-Region Data Sources for Microsoft SQL
Related reference
Configure a Secrets Vault for the Micro Focus Database File Handler
Database Connection Strings
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Windows: Create Region and Cross-Region Data Sources for Microsoft SQL

Note: We recommend that you use a connection string to connect to Microsoft SQL Server databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for Microsoft SQL Server Region and Cross-Region Databases.

Use the following steps if you do not intend to use connection strings, but instead create ODBC data sources to access region and cross-region databases.

  1. Open the ODBC Data Source Administrator.
    Tip: On most newer Windows versions, click the Start Menu button, type ODBC, and then select the appropriate desktop app.
  2. On the ODBC Data Source Administrator dialog box, select the System DSN tab.
  3. Add the mandatory data sources:
    Note: In order to create or query databases, you must have an active data source connection to the master database (the primary configuration database supplied with MSSQL). If this data source already exists, you can skip this step.
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, ODBC 17 for SQL Server is a common one for MSSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The Create New Data Source... wizard appears.

    3. Enter a name and description for the data source, and the name of the server on which the database will reside.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this database.

    4. Click Next twice.
    5. Select the Change the default database to: option, and enter master.
    6. Click Next, and then click Finish.

      An overview of the data source details is displayed.

    7. Click Test Data Source.

      The connection should be successful; if not, it indicates that you have a problem with your Microsoft SQL Server installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    8. Click OK twice.
  4. Add a new data source for a region database:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, ODBC 17 for SQL Server is a common one for MSSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The Create New Data Source... wizard appears.

    3. Enter a name and description for the data source, and the name of the server on which the database will reside.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this region database.

    4. Click Next twice.
    5. Select the Change the default database to: option, and if your region database is to be housed in a single physical database containing other datastores/region databases, enter the name of that database as specified by -db|existdb:<db-name> when updating the database configuration file, or if the region database is to be housed in its own database, enter the name of the database as specified by -name:<dsname> when updating the database configuration file.
    6. Click Next, and then click Finish.

      An overview of the data source details is displayed.

    7. Click Test Data Source.

      The connection should be successful; if not, it indicates that you have a problem with your Microsoft SQL Server installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    8. Click OK.

      The ODBC Data Source Administrator dialog box appears again.

  5. Add a new data source for a cross-region database:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, ODBC 17 for SQL Server is a common one for MSSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The Create New Data Source... wizard appears.

    3. Enter a name and description for the data source, and the name of the server on which the database will reside.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this cross-region database.

    4. Click Next twice.
    5. Select the Change the default database to: option, and if your cross-region database is to be housed in one physical database, with other datastores/region databases, enter the name of that database as specified by -db|existdb:<db-name> when updating the database configuration file, or if the cross-region database is to be housed in its own database, type _$XREGN$.
    6. Click Next, and then click Finish.

      An overview of the data source details is displayed.

    7. Click Test Data Source.

      The connection should be successful; if not, it indicates that you have a problem with your Microsoft SQL Server installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    8. Click OK.

      The ODBC Data Source Administrator dialog box appears again.

  6. Click OK.

The data sources for the region and cross-region databases are configured. You can configure your enterprise server regions to use the region and cross-region databases.

Parent topic: Configure Region and Cross-Region Databases in Microsoft SQL Server
Previous topic: Update the Configuration File for Microsoft SQL Server Region and Cross-Region Databases
Next topic: UNIX: Create Region and Cross-Region Data Sources for Microsoft SQL


UNIX: Create Region and Cross-Region Data Sources for Microsoft SQL

Note: We recommend that you use a connection string to connect to Microsoft SQL Server databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for Microsoft SQL Server Region and Cross-Region Databases.

If you did not configure direct connection strings, use the following steps to create ODBC data sources to access the region and cross-region databases.

There are a number of different driver managers that you can use to configure an ODBC data source. These instructions are carried out using unixODBC. If you are using a different driver manager, consult the vendor instructions for creating data sources.

  1. Run the command odbcinst -j command, and note down the location of the drivers configuration file (odbcinst.ini) and the user data sources configuration file (.odbc.ini).
  2. Open the odbcinst.ini configuration file and ensure that you have something similar to the following:

    (This may differ depending on the version of MSSQL you are running.)

    [ODBC Driver 17 for SQL Server]
Description=Microsoft ODBC Driver 17 for SQL Server
Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.2.so.0.1
UsageCount=1
  3. Open the .odbc.ini configuration file and add an entry for the mandatory data source:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Database = master
    where:
    • <datasource-name> - a name for the data source.
    • <driver-name> - the name of the driver as configured in the .odbcinst.ini file; in the example above, that would be ODBC Driver 17 for SQL Server.
    • <server-name> - the name of the server on which the database instance resides.
    • master - the name of the primary configuration database supplied with MSSQL.
  4. Add a new data source for a region database:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Database = <region-name>
    where:
    • <region-name> - the name of the enterprise server region that this database will serve.
  5. Add a new data source for a cross-region database:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Database = _$XREGN$
  6. Save the .odbc.ini configuration file.

Example .odbc.ini file

The following is an example of an .odbc.ini configuration file that contains data sources for a local MSSQL database instance that stores files from the ESDEMO enterprise server region in a region and cross-region database.

[SS.MASTER]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = master

[SS.CAS.ESDEMO]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = ESDEMO

[SS.CAS.CROSSREGION]
Driver = ODBC Driver 17 for SQL Server
Server = localhost
Database = _$XREGN$

The data sources for the region and cross-region databases are configured. Now, you can configure your enterprise server regions to use the databases.

Parent topic: Configure Region and Cross-Region Databases in Microsoft SQL Server
Previous topic: Windows: Create Region and Cross-Region Data Sources for Microsoft SQL
Next topic: Configure a Region or Cross-Region Database in Enterprise Server


Configure a Region or Cross-Region Database in Enterprise Server

This process also assumes that your enterprise server region is already correctly configured to run your application.

These steps configure an enterprise server region to use a region database, and if one does not already exist, a cross-region database.

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left in the row for the required enterprise server region.
  2. Add the following environment variables to your enterprise server region:
    Variable setting | Purpose
    ES_DB_FH=Y | Enables the Micro Focus Database File Handler
    ES_DB_SERVER=<DB-instance-name> Specifies the database instance in which the resources are stored
    Note: The types of resources stored are determined by the feature attribute specified for the region database in the configuration file.
    MFDBFH_CONFIG=<path-filename-config-file> | Locates the configuration file containing the list of data sources and their database types
    MFDBFH_SCRIPT_DIR=<path-to-scripts> | Locates the stored procedures required for Enterprise Server to interact with a database
    ES_LOCKDB=<region-database> | Optional. Required for resource locking in an enterprise server cluster utilizing database-hosted files. See Resource Locking for more information.
    ES_SERVER=<server-name> | Optional. See ES_LOCKDB.
  3. Cold-(re)start the enterprise server region.
    Tip: You can cold-start a region using the /s:c option with the casstart command on the command line.

    Once the region is back up and running, you can view the console log to confirm that the region and cross-region databases were created successfully - the relevant entries are prefixed DBFH.

Parent topic: Configure Region and Cross-Region Databases in Microsoft SQL Server
Previous topic: UNIX: Create Region and Cross-Region Data Sources for Microsoft SQL
Related concepts
Resource Locking


Using PostgreSQL

Use this section to configure datastores and/or enterprise server region and cross-region databases in PostgreSQL.

Tip: It is recommended that you create any required datastores or databases ahead of time (using dbfhadmin -script|-createdb), so as to not impact on processing time - the following steps will take you through this process. If a datastore/database does not exist at the point that your application attempts to access it, the application must wait for it to be created on-the-fly.
  • Configure Datastores for PostgreSQL
    Use these steps to configure datastore databases in PostgreSQL.
  • Configure Region and Cross-Region Databases in PostgreSQL
    Use these steps to configure region and cross-region databases in PostgreSQL.
Parent topic: Configuration Requirements
Related reference
The dbfhadmin Command Line Utility


Configure Datastores for PostgreSQL

Use these steps to configure datastore databases in PostgreSQL.

  1. Create PostgreSQL Datastores Using Script Files
  2. Update the Configuration File for PostgreSQL Datastores
  3. Windows: Create Datastore Data Sources for PostgreSQL
  4. UNIX: Create Datastore Data Sources for PostgreSQL
  5. Upload Files to a PostgreSQL Datastore
  6. Create an XA Resource
Parent topic: Using PostgreSQL
Related information
Configure Region and Cross-Region Databases in PostgreSQL


Create PostgreSQL Datastores Using Script Files

If a database does not exist at the point that it is required (for example, you attempt to upload a data file to a datastore that has not yet been created in the database instance), it is created on-the-fly; this can be slow for certain RDBMS types, and so we recommended that you create any required databases ahead of time, using SQL scripts.

  1. To create the database script file, on the command line, enter the following command:
    dbfhadmin -script -type:datastore -provider:pg -name:<datastore-name> [-db|existdb:<database-name>] [-file:<script-name.sql>]

    where <database-name> is the name of a new database (-db) or existing database (-existdb) that can house multiple datastores\regions, and a cross-region database - if you omit either option, a new database called <datastore-name> will be created for the datastore; <script-name.sql> is the name of the script file to be created.

    Note: If you omit the -file option, the default name is create_datastore_<datastore-name>_pg.sql.
  2. Create further script files for any more required datastores.

    Once you have created the script files, use the dbfhadmin utility to run them, and create the required databases. Before you run the -createdb command, ensure that the psql command is on the PATH.

  3. To create the database, on the command line, enter the following command:
    dbfhadmin -createdb -provider:pg -type:datastore -file:<script-name.sql> -user:<user>
    where <script-name.sql> is the name of the script file that was created in an earlier step, and <user> is a valid user name for the database. It is also assumed that an entry for that user name has been created in the password file %APPDATA%\postgresql\pgpass.conf on Windows, or .pgpass in the user's home directory on Linux, in order to obtain the password; alternatively, you could set the pgpassword environment variable prior to running the -createdb command. On Linux, PostgreSQL also supports the use of the PGPASSFILE environment variable to specify the location of the password file. Refer to your PostgreSQL documentation for more details.
Note: If you do not use script files for datastore creation, you can also create them using the dbfhdeploy data create URL/<datastore-name> command.

Now that the datastores have been created, you can configure the database configuration file to use them.

Parent topic: Configure Datastores for PostgreSQL
Next topic: Update the Configuration File for PostgreSQL Datastores


Update the Configuration File for PostgreSQL Datastores

You should only create or update a configuration file using the dbfhconfig command line utility.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:pg

    where <server-name> is a name in which to group your related servers within the configuration file. This could be the name of the database server instance if you are creating separate databases for each datastore, or if you intend to house multiple datastores/regions under one database, it could be the name of that. An entry of localhost:<port> is also valid, which defaults to your machine name.

    Next you need to specify the databases within <server-name>.

  4. Firstly, you need to create a reference to the postgres database - this is the primary configuration database supplied with PostgreSQL:
    Note: If the <server> element for your database server instance already exists, this reference should already exist.
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:database -name:postgres [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the PostgreSQL postgres database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the database if you are using a connection string; and <connection-string> is the database connection string (if you are not using an ODBC data source) - see Database Connection Strings for the database-specific syntax.

  5. Repeat the following step for each required datastore:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:datastore [-db:<existing-db>] [odbcdsn:<dsn-name>] -optio:<opts> -name:<dsname>  [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the datastore (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the datastore if you are using a connection string; <existing-db> is the name of an existing database in which the datastore is stored - if this option is omitted, it is implied that the datastore is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <opts> are the optimizations to be applied to I/O operations; and <dsname> is the actual name of the datastore (as configured in the data source properties).

    <opts> can be one of:
    option | description
    all | All optimizations applied, as if +<opt> had been specified for each available option. You can then selectively disable certain options using -<opt>.
    none | No optimizations applied.
    {+|-}oiseq | Enables (+) or disables (-) optimizations for line-sequential files opened for input.
    {+|-}ooseq | Enables (+) or disables (-) optimizations for line-sequential files opened for output.
    {+|-}oi | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for input.
    {+|-}oo | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for output.

Example configuration file

The following is an example of a configuration file that contains a datastore, a region database, and a cross-region database. As the login credentials are required to establish a connection to this database, the secrets vault has also been enabled: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
   <server name="MyMainDB" type="postgresql" access="odbc">
      <dsn name="PG.POSTGRES" type="database" dbname="postgres" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.VSAM" type="datastore" dsname="VSAM" dbname="MyMainDB" optio="none +ooseq" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.ESDEMO" type="region.cas" region="PGDEMO" dbname="MyMainDB" feature="all" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.CROSSREGION" type="crossregion.cas" dbname="MyMainDB" userid="clerk" password="$$vault$$"/>
   </server>
</datastores>

Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have used connection strings, you can skip the data source creation and use the dbfhdeploy command line utility to upload files to your datastores.

Parent topic: Configure Datastores for PostgreSQL
Previous topic: Create PostgreSQL Datastores Using Script Files
Next topic: Windows: Create Datastore Data Sources for PostgreSQL
Related reference
Configure a Secrets Vault for the Micro Focus Database File Handler
Database Connection Strings
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Windows: Create Datastore Data Sources for PostgreSQL

Note: We recommend that you use a connection string to connect to PostgreSQL databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for PostgreSQL Datastores.

If you did not use connection strings when configuring the database configuration file, use the following steps to create ODBC data sources to access the datastore databases.

  1. Open the ODBC Data Source Administrator.
    Tip: On most newer Windows versions, click the Start Menu button, type ODBC, and then select the appropriate desktop app.
  2. On the ODBC Data Source Administrator dialog box, select the System DSN tab.
  3. Add the mandatory data sources:
    Note: In order to create or query databases, you must have an active data source connection to the postgres database - one of the default databases created with any PostgreSQL server. If this connection already exists, you can skip this step:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, PostgreSQL ODBC Driver (ANSI) is a common one for PostgreSQL), and click Finish.
      Note: If you are planning to run both 32-bit and 64-bit applications, you are required to install an ODBC driver for each bitism.

      The PostgreSQL setup dialog box appears.

    3. In the Data Source and Description fields, enter the name as used for dsn:<name> when updating the database configuration file for this database, and a description for the data source.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this database.

    4. In the Database field, type postgres.
    5. In the Server and Port fields, enter the server name and port.
    6. In the User Name and Password fields, enter a set of valid user credentials.
    7. Click Datasource, and configure the Advanced Options:
      1. Click Page 2.
      2. In the idle time and interval fields, enter a value (in seconds) in which to maintain the connection when it is idle - you may need to experiment with this value, depending on the database workload.
      3. Click OK.
    8. Click Test.

      The connection should be successful; if not, it indicates that you have a problem with your PostgreSQL installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    9. Click Save.
  4. Add a new data source for each required datastore:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, PostgreSQL ODBC Driver (ANSI) is a common one for PostgreSQL), and click Finish.
      Note: If you are planning to run both 32-bit and 64-bit applications, you are required to install an ODBC driver for each bitism.

      The PostgreSQL setup dialog box appears.

    3. In the Data Source and Description fields, enter the name as used for dsn:<name> when updating the database configuration file for this datastore, and a description for the data source.
    4. In the Database field, if your datastore is to be housed in a single physical database containing other datastores/region databases, enter the name of that database as specified by -db|existdb:<db-name> when updating the database configuration file, or if the datastore is to be housed in its own database, enter the name of the database as specified by -name:<dsname> when updating the database configuration file.
    5. In the Server and Port fields, enter the server name and port.
    6. In the User Name and Password fields, enter a set of valid user credentials.
    7. Click Datasource, and configure the Advanced Options:
      1. Click Page 2.
      2. In the idle time and interval fields, enter a value (in seconds) in which to maintain the connection when it is idle - you may need to experiment with this value, depending on the database workload.
      3. Click OK.

      The database has yet to be created, and so do not click Test.

    8. Click Save. The ODBC Data Source Administrator appears again.
    9. Repeat these sub-steps for each additional datastore you require.
  5. Click OK.

    The data sources for the datastores are configured.

The data sources for the datastore databases are configured. You can now start to upload data files to them using the dbfhdeploy command line utility.

Parent topic: Configure Datastores for PostgreSQL
Previous topic: Update the Configuration File for PostgreSQL Datastores
Next topic: UNIX: Create Datastore Data Sources for PostgreSQL


UNIX: Create Datastore Data Sources for PostgreSQL

Note: We recommend that you use a connection string to connect to PostgreSQL databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for PostgreSQL Datastores.

If you did not use connection strings when configuring the database configuration file, use the following steps to create ODBC data sources to access the datastore databases.

There are a number of different driver managers that you can use to configure an ODBC data source. These instructions are carried out using unixODBC. If you are using a different driver manager, consult the vendor instructions for creating data sources.

  1. Run the command odbcinst -j command, and note down the location of the drivers configuration file (odbcinst.ini) and the user data sources configuration file (.odbc.ini).
  2. Open the odbcinst.ini configuration file and ensure that you have something similar to the following:

    (This may differ depending on the version of PostgreSQL you are running.)

    [PostgreSQL]
Description=ODBC for PostgreSQL
Driver64=/usr/pgsql-10/lib/psqlodbcw.so
Setup64=/usr/lib64/libodbcpsqlS.so
FileUsage=1
Threading=2
    Note: Ensuring that the Threading setting is specified avoids potential problems when performing database operations on multiple threads.
  3. Open the .odbc.ini configuration file and add an entry for the mandatory data source:
    [<datasource-name>]
Driver = <driver-name>
Servername = <server-name>
Port = <port-no>
Database = postgres
KeepaliveTime=<int>
KeepaliveInterval=<int>
BatchSize=100
    where:
    • <datasource-name> - a name for the data source.
    • <driver-name> - the name of the driver as configured in the .odbcinst.ini file; in the example above, that would be PostgreSQL.
    • <server-name> - the name of the server on which the database instance resides.
    • <port-no> - the port on which the database is listening.
    • postgres - one of the default databases supplied with a PostgreSQL server.
    • <int> - the number of seconds in which the connection will remain active whilst being idle - you may need to experiment with this value, depending on the database's workload.
    Note: The BatchSize parameter is a setting to aid I/O performance.
  4. Add a new data source entry for each required datastore:
    [<datasource-name>]
Driver = <driver-name>
Servername = <server-name>
Port = <port-no>
Database = <datastore-name>
KeepaliveTime=<int>
KeepaliveInterval=<int>
BatchSize=100
    where:
    • <datastore-name> - the name of the datastore that you want to create.
  5. Save the .odbc.ini configuration file.

Example .odbc.ini file

The following is an example of an .odbc.ini configuration file contains data sources for a local PostgreSQL database instance with two datastores. It also includes the mandatory data source for the PostgreSQL database.

[PG.POSTGRES]
Driver = PostgreSQL
Servername = localhost
Port = 5432
Database = postgres
KeepaliveTime=120
KeepaliveInterval=120
BatchSize=100

[PG.VSAM]
Driver = PostgreSQL
Servername = localhost
Port = 5432
Database = VSAM
KeepaliveTime=120
KeepaliveInterval=120
BatchSize=100

[PG.SEQFILES]
Driver = PostgreSQL
Servername = localhost
Port = 5432
Database = SEQ
KeepaliveTime=120
KeepaliveInterval=120
BatchSize=100

The data sources for the datastore databases are configured. You can now start to upload data files to them using the dbfhdeploy command line utility.

Parent topic: Configure Datastores for PostgreSQL
Previous topic: Windows: Create Datastore Data Sources for PostgreSQL
Next topic: Upload Files to a PostgreSQL Datastore


Upload Files to a PostgreSQL Datastore

Use these steps to upload existing data files to the datastore databases created in the previous steps.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, if you have used ODBCS data sources, the command prompt must be the same bitism as the data sources that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the database configuration file that contains a reference to the data source:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, the file is assumed to be located in the current directory, or you may use the -configfile:<name> option appended to the following dbfhdeploy commands (see The dbfhdeploy Command Line Utility for more details).

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a data file to the datastore:
    dbfhdeploy data add <filename> URL/<file-ref>[?folder=<folder-name>]

    If <folder-name> does not already exist, it is created.

  4. To test that the data file is now in the datastore, you can produce a listing of files and folders in the database using dbfhdeploy:
    dbfhdeploy list URL[?folder=<folder-name>]

    A list of files is displayed.

    Note: If you do not specify a folder name, only files and folders at the base level of the datastore are displayed.

If any of the files in your datastore are transactional, you must also configure an XA resource within the enterprise server region that points to the datastore; see Create an XA Resource. If none of your files are transactional, you can skip that step and proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore, and if resource locking is to be managed by an enterprise server region, configuring region and cross-region databases.

Parent topic: Configure Datastores for PostgreSQL
Previous topic: UNIX: Create Datastore Data Sources for PostgreSQL
Next topic: Create an XA Resource
Related reference
The dbfhdeploy Command Line Utility
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling


Create an XA Resource

Your enterprise server region requires an XA resource for each datastore that contains one or more transactional files. If the database containing the datastore is also used by other COBOL applications, additional XA resources are required. Refer to Working with Multiple XARs for details on how to handle such situations.

  1. Open the ESCWA Administration page, and then select the enterprise server that references the transactional data file from the left pane.
  2. In the right pane, click General > XA Resources.
  3. Click NEW.
  4. Specify the following XAR details:
    Option | Description
    ID | Unique ID for the XAR
    Name | Unique name for the XAR
    Module | Specify the location of the RM switch module executable file (.dll on Windows or .so on UNIX platforms). This is database specific: esmssql.dll/.so for MSSQL and Azure SQL, ESPGSQLXA.dll/.so for PostgreSQL, and ESDB2XA.dll/.so for Db2. Refer to Building RM Switch Modules for more information.
    Enabled | Enable the resource for immediate use.
    Open string DSN=<datastore-dsn>

    where <datastore-dsn> is the ODBC data source name of the datastore you are configuring.

    Note: These are only the mandatory options required, with the addition of USRPASS=userid.password if you are using a PostgreSQL database. You can also specify further options as required, as detailed in To define an XA resource (XAR) for an enterprise server region.
  5. Click SAVE.

    The XA resource should be effective immediately.

You can now proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore.

Parent topic: Configure Datastores for PostgreSQL
Previous topic: Upload Files to a PostgreSQL Datastore
Related concepts
Building RM Switch Modules
Related reference
To define an XA resource (XAR) for an enterprise server region
Working with Multiple XARs
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling


Configure Region and Cross-Region Databases in PostgreSQL

Use these steps to configure region and cross-region databases in PostgreSQL.

  1. Create PostgreSQL Region and a Cross-Region Database Using Script Files
  2. Update the Configuration File for PostgreSQL Region and Cross-Region Databases
  3. Windows: Create Region and Cross-Region Data Sources for PostgreSQL
  4. UNIX: Create Region and Cross-Region Data Sources for PostgreSQL
  5. Configure PostgreSQL Region or Cross-Region Database in Enterprise Server
Parent topic: Using PostgreSQL
Related information
Configure Datastores for PostgreSQL


Create PostgreSQL Region and a Cross-Region Database Using Script Files

If a database does not exist at the point that it is required, it is created on-the-fly; this can be slow for certain RDBMS types, and so we recommended that you create any required databases ahead of time, using SQL scripts.

  1. To create a script file for a region database, on the command line, enter the following command:
    dbfhadmin -script -type:region -provider:pg -name:<ES-name> [-db|existdb:<database-name>] [-file:<script-name.sql>]

    where <ES-name> is the name of the enterprise server region that will use the region database, and <script-name.sql> is the name of the script file to be created; <database-name> is the name of a new database (-db) or existing database (-existdb) that can house multiple datastores\regions, and a cross-region database - if you omit either option, a new database called <ES-name> will be created for the region database; <script-name.sql> is the name of the script file to be created.

    Note: If you omit the -file option, the default name is create_region_<ES-name>_pg.sql.
  2. To create a script file for a cross-region database, on the command line, enter the following command:
    dbfhadmin -script -type:crossregion -provider:pg [-db|existdb:<database-name>] [-file:<script-name.sql>]

    where <database-name> is the name of a new database (-db) or existing database (-existdb) that can house multiple datastores\regions, and a cross-region database - if you omit either option, a new database called $XREGN$ will be created for the cross-region database.

    Note: If you omit the -file option, the default name is create_crossregion_pg.sql.

    Before you run the -createdb command, ensure that the psql command is on the PATH.

  3. To create the region database, on the command line, enter the following command:
    dbfhadmin -createdb -provider:pg -type:region -file:<script-name.sql> -user:<user>
    where <user> is a valid user name for the database. It is also assumed that an entry for that user name has been created in the password file %APPDATA%\postgresql\pgpass.conf on Windows, or .pgpass in the user's home directory on Linux, in order to obtain the password. On Linux, PostgreSQL also supports the use of the PGPASSFILE environment variable to specify the location of the password file. Refer to your PostgreSQL documentation for more details.
  4. To create the cross-region database, on the command line, enter the following command:
    dbfhadmin -createdb -provider:pg -type:crossregion -file:<script-name.sql> -user:<user>
    where <user> is a valid user name for the database. It is also assumed that an entry for that user name has been created in the password file %APPDATA%\postgresql\pgpass.conf on Windows, or .pgpass in the user's home directory on Linux, in order to obtain the password. On Linux, PostgreSQL also supports the use of the PGPASSFILE environment variable to specify the location of the password file. Refer to your PostgreSQL documentation for more details.

Now that the region and cross-region databases have been created, you can configure the database configuration file to use them.

Parent topic: Configure Region and Cross-Region Databases in PostgreSQL
Next topic: Update the Configuration File for PostgreSQL Region and Cross-Region Databases
Related reference
Types of Database


Update the Configuration File for PostgreSQL Region and Cross-Region Databases

Use these steps to create or update a configuration file to include entries to one or more region databases, and a cross-region databases.

You should only create or update a configuration file using the dbfhconfig command line utility.

If you are configuring a file that has previously been configured for the database instance that you are working with, you can jump to step 5, ensuring that you use the same <server-name> as previously used.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:pg

    where <server-name> is the name of the database server instance. An entry of localhost:<port> is also valid, which defaults to your machine name. If you have already updated the configuration file with the PostgreSQL datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

    Now specify the required databases within the instance.

  4. Firstly, you need to create a reference to the postgres database - this is the primary configuration database supplied with PostgreSQL:
    Note: If the <server> element for your database server instance already exists, this reference should already exist as well, and so again, skip this step.
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:database -name:postgres [-user:<user-name>] [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the PostgreSQL postgres database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the database if you are using a connection string; <user-name> is a valid user for the instance; and <connection-string> is the database connection string if you are establishing a database connection without the use of an ODBC data source - see Database Connection Strings for the database-specific syntax.

  5. Repeat the following step for each required region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> [-db:<existing-db>] [odbcdsn:<dsn-name>] -type:region -name:<region-name> -feature:<options> [-user:<user-name>] [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the region database if you are using a connection string; <existing-db> is the name of an existing database in which the region database is stored - if this option is omitted, it is implied that the region database is housed in its own database; <dsn-name> is the name of the data source for the shared connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <region-name> is the name of the enterprise server region that this database will serve; and <options> is a list of features for which the region will use the database.

    <options> can be one or more of:
    • all - all available region features enabled (default).
    • none - no region features enabled.
    • [+|-]reslocking - enables\disables database resource locking.
  6. Now add a reference to a single cross-region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:crossregion [-db:<existing-db>] [odbcdsn:<dsn-name>] [-user:<user-name>] [-connect:<connection-string>]
    where <name> is either the name you will give an ODBC data source for the cross-region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the cross-region database if you are using a connection string; <existing-db> is the name of an existing database in which the cross-region database is stored - if this option is omitted, it is implied that the cross-region database is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information.

Example configuration file

The following is an example of a configuration file that contains a datastore, a region database, and a cross-region database. As the login credentials are required to establish a connection to this database, the secrets vault has also been enabled: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
   <server name="MyMainDB" type="postgresql" access="odbc">
      <dsn name="PG.POSTGRES" type="database" dbname="postgres" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.VSAM" type="datastore" dsname="VSAM" dbname="MyMainDB" optio="none +ooseq" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.ESDEMO" type="region.cas" region="PGDEMO" dbname="MyMainDB" feature="all" userid="clerk" password="$$vault$$"/>
      <dsn name="PG.CROSSREGION" type="crossregion.cas" dbname="MyMainDB" userid="clerk" password="$$vault$$"/>
   </server>
</datastores>
Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have configured connection strings, you can skip the data source creation and configure your enterprise server regions to use the region and cross-region databases.
Parent topic: Configure Region and Cross-Region Databases in PostgreSQL
Previous topic: Create PostgreSQL Region and a Cross-Region Database Using Script Files
Next topic: Windows: Create Region and Cross-Region Data Sources for PostgreSQL
Related reference
Configure a Secrets Vault for the Micro Focus Database File Handler
Database Connection Strings
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Windows: Create Region and Cross-Region Data Sources for PostgreSQL

Note: We recommend that you use a connection string to connect to PostgreSQL databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for PostgreSQL Region and Cross-Region Databases.

Use the following steps if you do not intend to use connection strings, but instead create ODBC data sources to access region and cross-region databases.

  1. Open the ODBC Data Source Administrator.
    Tip: On most newer Windows versions, click the Start Menu button, type ODBC, and then select the appropriate desktop app.
  2. On the ODBC Data Source Administrator dialog box, select the System DSN tab.
  3. Add the mandatory data sources:
    Note: In order to create or query databases, you must have an active data source connection to the postgres database - one of the default databases created with any PostgreSQL server. If this connection already exists, you can skip this step:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, PostgreSQL ODBC Driver (ANSI) is a common one for PostgreSQL), and click Finish.
      Note: If you are planning to run both 32-bit and 64-bit applications, you are required to install an ODBC driver for each bitism.

      The PostgreSQL setup dialog box appears.

    3. In the Data Source and Description fields, enter the name as used for dsn:<name> when updating the database configuration file for this database, and a description for the data source.

      The data source name should be the name as specified by dsn:<name> when updating the database configuration file for this database.

    4. In the Database field, type postgres.
    5. In the Server and Port fields, enter the server name and port.
    6. In the User Name and Password fields, enter a set of valid user credentials.
    7. Click Datasource, and configure the Advanced Options:
      1. Click Page 2.
      2. In the idle time and interval fields, enter a value (in seconds) in which to maintain the connection when it is idle - you may need to experiment with this value, depending on the database workload.
      3. Click OK.
    8. Click Test.

      The connection should be successful; if not, it indicates that you have a problem with your PostgreSQL installation, and should consult the vendor instructions to troubleshoot before proceeding any further.

    9. Click Save.
  4. Add a new data source for a region database:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, PostgreSQL ODBC Driver (ANSI) is a common one for PostgreSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The PostgreSQL setup dialog box appears.

    3. In the Data Source and Description fields, enter the name as used for dsn:<name> when updating the database configuration file for this region database, and a description for the data source.
    4. In the Database field, if your region database is to be housed in a single physical database containing other datastores/region databases, enter the name of that database as specified by -db|existdb:<db-name> when updating the database configuration file, or if the region database is to be housed in its own database, enter the name of the database as specified by -name:<dsname> when updating the database configuration file.
    5. In the Server and Port fields, enter the server name and port.
    6. In the User Name and Password fields, enter a set of valid user credentials.
    7. Click Datasource, and configure the Advanced Options:
      1. Click Page 2.
      2. In the idle time and interval fields, enter a value (in seconds) in which to maintain the connection when it is idle - you may need to experiment with this value, depending on the database workload.
      3. Click OK.

      The database has yet to be created, and so do not click Test.

    8. Click Save. The ODBC Data Source Administrator appears again.
    9. Enter a name and description for the data source, and the name of the server on which the database will reside.
    10. Click OK.

      The ODBC Data Source Administrator dialog box appears again.

  5. Add a new data source for a cross-region database:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, PostgreSQL ODBC Driver (ANSI) is a common one for PostgreSQL), and click Finish.
      Note: The bitism of your driver must match the bitism of the application that will use it.

      The PostgreSQL setup dialog box appears.

    3. In the Data Source and Description fields, enter the name as used for dsn:<name> when updating the database configuration file for this region database, and a description for the data source.
    4. In the Database field, if your cross-region database is to be housed in one physical database, with other datastores/region databases, enter the name of that database as specified by -db|existdb:<db-name> when updating the database configuration file, or if the cross-region database is to be housed in its own database, type $XREGN$.
    5. In the Server and Port fields, enter the server name and port.
    6. In the User Name and Password fields, enter a set of valid user credentials.
    7. Click Datasource, and configure the Advanced Options:
      1. Click Page 2.
      2. In the idle time and interval fields, enter a value (in seconds) in which to maintain the connection when it is idle - you may need to experiment with this value, depending on the database workload.
      3. Click OK.

      The database has yet to be created, and so do not click Test.

    8. Click Save. The ODBC Data Source Administrator appears again.
  6. Click OK.

The data sources for the region and cross-region databases are configured. You can now configure your enterprise server regions to use them.

Parent topic: Configure Region and Cross-Region Databases in PostgreSQL
Previous topic: Update the Configuration File for PostgreSQL Region and Cross-Region Databases
Next topic: UNIX: Create Region and Cross-Region Data Sources for PostgreSQL


UNIX: Create Region and Cross-Region Data Sources for PostgreSQL

Note: We recommend that you use a connection string to connect to PostgreSQL databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for PostgreSQL Region and Cross-Region Databases.

If you did not configure direct connection strings, use the following steps to create ODBC data sources to access the region and cross-region databases.

There are a number of different driver managers that you can use to configure an ODBC data source. These instructions are carried out using unixODBC. If you are using a different driver manager, consult the vendor instructions for creating data sources.

  1. Run the command odbcinst -j command, and note down the location of the drivers configuration file (odbcinst.ini) and the user data sources configuration file (.odbc.ini).
  2. Open the odbcinst.ini configuration file and ensure that you have something similar to the following:

    (This may differ depending on the version of PostgreSQL you are running.)

    [PostgreSQL]
Description=ODBC for PostgreSQL
Driver64=/usr/pgsql-10/lib/psqlodbcw.so
Setup64=/usr/lib64/libodbcpsqlS.so
FileUsage=1
Threading=2
    Note: Ensuring that the Threading setting is specified avoids potential problems when performing database operations on multiple threads.
  3. Open the .odbc.ini configuration file and add an entry for the mandatory data source:
    [<datasource-name>]
Driver = <driver-name>
Servername = <server-name>
Port = <port-no>
Database = postgres
KeepaliveTime=<int>
KeepaliveInterval=<int>
BatchSize=100
    where:
    • <datasource-name> - a name for the data source.
    • <driver-name> - the name of the driver as configured in the .odbcinst.ini file; in the example above, that would be PostgreSQL.
    • <server-name> - the name of the server on which the database instance resides.
    • <port-no> - the port on which the database is listening.
    • postgres - one of the default databases supplied with a PostgreSQL server.
    • <int> - the number of seconds in which the connection will remain active whilst being idle - you may need to experiment with this value, depending on the database's workload.
    Note: The BatchSize parameter is a setting to aid I/O performance.
  4. Add a new data source for a region database:
    [<datasource-name>]
Driver = <driver-name>
Servername = <server-name>
Port = <port-no>
Database = <region-name>
KeepaliveTime=<int>
KeepaliveInterval=<int>
BatchSize=100
    where:
    • <region-name> - the name of the enterprise server region that this database will serve.
  5. Add a new data source for a cross-region database:
    [<datasource-name>]
Driver = <driver-name>
Servername = <server-name>
Port = <port-no>
Database = $XREGN$
KeepaliveTime=<int>
KeepaliveInterval=<int>
BatchSize=100
  6. Save the .odbc.ini configuration file.

Example .odbc.ini file

The following is an example of an .odbc.ini configuration file that contains data sources for a local PostgreSQL database instance that stores files from the ESDEMO enterprise server region in a region and cross-region database.

[PG.POSTGRES]
Driver = PostgreSQL
Servername = localhost
Port = 5432
Database = postgres
KeepaliveTime=120
KeepaliveInterval=120
BatchSize=100

[PG.CAS.ESDEMO]
Driver = PostgreSQL
Servername = localhost
Port = 5432
Database = ESDEMO
KeepaliveTime=120
KeepaliveInterval=120
BatchSize=100

[PG.CAS.CROSSREGION]
Driver = PostgreSQL
Servername = localhost
Port = 5432
Database = $XREGN$
KeepaliveTime=120
KeepaliveInterval=120
BatchSize=100

The data sources for the region and cross-region databases are configured. Now, you can configure your enterprise server regions to use the databases.

Parent topic: Configure Region and Cross-Region Databases in PostgreSQL
Previous topic: Windows: Create Region and Cross-Region Data Sources for PostgreSQL
Next topic: Configure PostgreSQL Region or Cross-Region Database in Enterprise Server


Configure PostgreSQL Region or Cross-Region Database in Enterprise Server

This process also assumes that your enterprise server region is already correctly configured to run your application.

These steps configure an enterprise server region to use a region database, and if one does not already exist, a cross-region database.

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left in the row for the required enterprise server region.
  2. Add the following environment variables to your enterprise server region:
    Variable setting | Purpose
    ES_DB_FH=Y | Enables the Micro Focus Database File Handler
    ES_DB_SERVER=<DB-instance-name> Specifies the database instance in which the resources are stored
    Note: The types of resources stored are determined by the feature attribute specified for the region database in the configuration file.
    MFDBFH_CONFIG=<path-filename-config-file> | Locates the configuration file containing the list of data sources and their database types
    MFDBFH_SCRIPT_DIR=<path-to-scripts> | Locates the stored procedures required for Enterprise Server to interact with a database
    ES_LOCKDB=<region-database> | Optional. Required for resource locking in an enterprise server cluster utilizing database-hosted files. See Resource Locking for more information.
    ES_SERVER=<server-name> | Optional. See ES_LOCKDB.
  3. Cold-(re)start the enterprise server region.
    Tip: You can cold-start a region using the /s:c option with the casstart command on the command line.

    Once the region is back up and running, you can view the console log to confirm that the region and cross-region databases were created successfully - the relevant entries are prefixed DBFH.

Parent topic: Configure Region and Cross-Region Databases in PostgreSQL
Previous topic: UNIX: Create Region and Cross-Region Data Sources for PostgreSQL
Related concepts
Resource Locking


Using Db2

Use this section to configure datastores and/or enterprise server region and cross-region databases in Db2.

Tip: It is recommended that you create any required datastores or databases ahead of time (using dbfhadmin -script|-createdb), so as to not impact on processing time - the following steps will take you through this process. If a datastore/database does not exist at the point that your application attempts to access it, the application must wait for it to be created on-the-fly.
  • Configure Datastores for Db2
    Use these steps to configure datastore databases in Db2.
  • Configure Region and Cross-Region Databases in Db2
    Use these steps to configure region and cross-region databases in Db2.
Parent topic: Configuration Requirements
Related reference
The dbfhadmin Command Line Utility


Configure Datastores for Db2

You can connect to a Db2 database using two methods. The recommended method is to use connection strings, as these can be used for both 32-bit and 64-bit client connections. Connection strings are configured using the connect attribute within the configuration file. If you do not use connection strings, you must connect using ODBC DSNs.

Db2 datastores can be created in their own database, or you can store multiple datastores in a single database - this database may also contain one or more region databases, and a single cross-region database.

Unlike some other database types, Db2 does not support the mixing of ANSI and EBCDIC collating sequences for table columns in the same database. This means that if you require EBCDIC files to be used, they need to be deployed to a separate datastore database to non-EBCDIC files. However, IBM does not provide commands to allow the creation of databases with an EBCDIC collating sequence; instead, you need to use a Db2 API call to achieve this, which is called when using the dbfhadmin -createdb -ebcdic syntax. The actual collating sequence used is that specified by the MFCODESET environment variable. If MFCODESET is not set, the default collating sequence for the platform is used.

Use these steps to configure datastore databases in Db2.

  1. Create Db2 Datastores Using Script Files
    Due to Db2 database creation being very slow, it is advisable (although not mandatory) to create the databases in advance, using scripts.
  2. Update the Configuration File for Db2 Datastores
    Add the database entries and connection details for your datastore databases in the database configuration file.
  3. Windows: Create Datastore Data Sources for Db2
    If you are not using connection strings in your configuration file, you must create ODBC data sources. (Connection strings are the recommended connection method for Db2 databases.)
  4. UNIX: Create Datastore Data Sources for Db2
    If you are not using connection strings in your configuration file, you must create ODBC data sources. (Connection strings are the recommended connection method for Db2 databases.)
  5. Upload Files to a Db2 Datastore
    Use the dbfhdeploy command line utility to upload data files to the datastores.
  6. Create an XA Resource
    If you are handling transactional data, you are required to create an XA resource for the datastore that houses the transactional data files.
Parent topic: Using Db2
Related concepts
Prerequisites
Related information
Configure Region and Cross-Region Databases in Db2


Create Db2 Datastores Using Script Files

You can choose to have databases created dynamically like SQL Server and PostgreSQL, but because Db2 database creation can be very slow, we recommended that you create them ahead of time using SQL scripts.

  1. To create the database script file, on the command line, enter the following command:
    dbfhadmin -script -type:datastore -provider:db2 -name:<datastore-name> -file:<script-name.sql> [-existdb:<db-name>|-db:<db-name>]

    where <datastore-name> must be 8 characters or less, which is a Db2 restriction (note, this should be a database name that you have already specified when updating the configuration file), and where <script-name.sql> is the name of the script file to be created.

    Additionally, there are two (mutually exclusive) optional parameters that you can specify: if you are creating the datastore to be within an existing Db2 database (for example, you may have one database that holds multiple datastores, region databases, and a cross-region database), use the -existdb option; if you are creating a new Db2 database for the datastore, use the -db option to specify the name of the database; if you omit both options, a new database with a default name will be created - the default name is the value given for the -name option.

    Note: If you omit the -file option, the default name is create_datastore_<datastore-name>_db2.sql
    Tip: By default, Db2 databases are created with the SYSTEM_1252_US collating sequence on Windows, and SYSTEM_923_US on Linux/UNIX. Use the -collation attribute to specify an alternative collating sequence: see The dbfhadmin Command Line Utility for more details.
  2. Create further script files for any more required datastores.

    Once you have created the script files, use the dbfhadmin utility to run them, and create the required databases.

  3. To create the database, on the command line, enter the following command:
    dbfhadmin -createdb -file:<script-name.sql> -type:datastore -provider:db2

    where <script-name.sql> is the name of the script file that was created in an earlier step.

Now that the datastores have been created, you can configure the database configuration file to use them.

Parent topic: Configure Datastores for Db2
Next topic: Update the Configuration File for Db2 Datastores
Related concepts
The dbfhadmin Command Line Utility
Related tasks
Windows: Create Datastore Data Sources for Db2


Update the Configuration File for Db2 Datastores

You should only create or update a configuration file using the dbfhconfig command line utility.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:db2

    where <server-name> is the name of the database server instance. An entry of localhost:<port> is also valid, which defaults to your machine name. If you have already updated the configuration file with the Db2 datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

    Now specify the required databases within the instance.

  4. Repeat the following step for each required datastore:
    dbfhconfig -add -server:<server-name> -dsn:<name> [-db:<existing-db>] [odbcdsn:<dsn-name>] -type:datastore -optio:<opts> -name:<dsname> [-user:<user-name>] [-password:<password>] [-bitism:<bit>] [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the datastore (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the datastore if you are using a connection string; <existing-db> is the name of an existing database in which the datastore is stored - if this option is omitted, it is implied that the datastore is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <opts> are the optimizations to be applied to I/O operations, <dsname> is the actual name of the datastore (as configured in the data source properties); <user-name> and <password> are valid credentials for the instance - you do not need to specify theses if you are using a connection string; <bit> is the bitism of the associated ODBC data source - you do not need to specify this if you are using a connection string; and <connection-string> is the database connection string if you are establishing a database connection without the use of an ODBC data source - see Database Connection Strings for the database-specific syntax.

    <opts> can be one of:
    option | description
    all | All optimizations applied, as if +<opt> had been specified for each available option. You can then selectively disable certain options using -<opt>.
    none | No optimizations applied.
    {+|-}oiseq | Enables (+) or disables (-) optimizations for line-sequential files opened for input.
    {+|-}ooseq | Enables (+) or disables (-) optimizations for line-sequential files opened for output.
    {+|-}oi | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for input.
    {+|-}oo | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for output.

Example configuration file

The following is an example of a configuration file that contains a datastore, a region database, and a cross-region database, using direct connection syntax. As the login credentials are required to establish a connection to this database, the secrets vault has also been enabled: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
   <server name="localhost:50000" type="db2" access="odbc">
      <dsn name="DB2.VSAM" type="datastore" dsname="VSAM" optio="none +ooseq" dbname="MYMFFILS" connect="$$vault$$"/>
      <dsn name="DB2.ESDEMO" type="region.cas" region="ESDEMO" feature="all" dbname="MYMFFILS" connect="$$vault$$"/>
      <dsn name="DB2.CROSSREGION" type="crossregion.cas" dsname="$XREGN$" dbname="MYMFFILS" connect="$$vault$$"/></server>
</datastores>

Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have used connection strings, you can skip the data source creation and use the dbfhdeploy command line utility to upload files to your datastores.

Parent topic: Configure Datastores for Db2
Previous topic: Create Db2 Datastores Using Script Files
Next topic: Windows: Create Datastore Data Sources for Db2
Related reference
Database Connection Strings
Configure a Secrets Vault for the Micro Focus Database File Handler
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Windows: Create Datastore Data Sources for Db2

Note: We recommend that you use a connection string to connect to Db2 databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for Db2 Datastores.

If you did not use connection strings when configuring the database configuration file, use the following steps to create ODBC data sources to access the datastore databases.

  1. Open the ODBC Data Source Administrator.
    Tip: On most newer Windows versions, click the Start Menu button, type ODBC, and then select the appropriate desktop app.
  2. On the ODBC Data Source Administrator dialog box, select the System DSN tab.
  3. Add a new data source for each required datastore:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, IBM DB2 ODBC Driver is a common one for Db2), and click Finish.

      The ODBC IBM DB2 Driver - Add wizard appears.

    3. Enter a name and description for the data source.
      Note: The data source name must be 8 characters or less.
    4. Click OK.

      The ODBC Data Source Administrator appears again.

    5. Repeat these sub-steps for each additional datastore you require.
  4. Click OK.

The data sources for the datastore databases are configured. You can now start to upload data files to them using the dbfhdeploy command line utility.

Parent topic: Configure Datastores for Db2
Previous topic: Update the Configuration File for Db2 Datastores
Next topic: UNIX: Create Datastore Data Sources for Db2
Related tasks
Create Db2 Datastores Using Script Files


UNIX: Create Datastore Data Sources for Db2

Note: We recommend that you use a connection string to connect to Db2 databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for Db2 Datastores.

If you did not use connection strings when configuring the database configuration file, use the following steps to create ODBC data sources to access the datastore databases.

There are a number of different driver managers that you can use to configure an ODBC data source. These instructions are carried out using unixODBC. If you are using a different driver manager, consult the vendor instructions for creating data sources.

  1. Run the command odbcinst -j command, and note down the location of the drivers configuration file (odbcinst.ini) and the user data sources configuration file (.odbc.ini).
  2. Open the odbcinst.ini configuration file and ensure that you have something similar to the following:

    (This may differ depending on the version of Db2 you are running.)

    [Db2]
Description=Sample Db2 ODBC Database
Driver=/opt/ibm/db2/dsdriver/lib/libdb20.so
  3. Open the .odbc.ini configuration file and add an entry for a datastore data source:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Port = <port-no>
Database = <datastore-name>
    where:
    • <datasource-name> - a name for the data source.
    • <driver-name> - the name of the driver as configured in the .odbcinst.ini file; in the example above, that would be Db2.
    • <server-name> - the name of the server on which the database instance resides.
    • <port-no> - the port on which the database is listening.
    • <datastore-name> - the name of the datastore that you want to create.
  4. Repeat the last step for each additional datastore.
  5. Save the .odbc.ini configuration file.

Example .odbc.ini file

The following is an example of an .odbc.ini configuration file contains data sources for a local Db2 database instance with two datastores.

[Db2.VSAM]
Driver = Db2
Server = localhost
Port = 50000
Database = VSAM

[Db2.SEQFILES]
Driver = Db2
Server = localhost
Port = 50000
Database = SEQ

The data sources for the datastore databases are configured. You can now start to upload data files to them using the dbfhdeploy command line utility.

Parent topic: Configure Datastores for Db2
Previous topic: Windows: Create Datastore Data Sources for Db2
Next topic: Upload Files to a Db2 Datastore


Upload Files to a Db2 Datastore

Use these steps to create Db2 datastores if you have not already created them using the scripts mentioned in Create Datastore Scripts for Db2.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the database configuration file that contains a reference to the data source:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, the file is assumed to be located in the current directory, or you may use the -configfile:<name> option appended to the following dbfhdeploy commands (see The dbfhdeploy Command Line Utility for more details).

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a data file to the datastore:
    dbfhdeploy data add <filename> URL/<file-ref>[?folder=<folder-name>]

    If <folder-name> does not already exist, it is created.

  4. To test that the data file is now in the datastore, you can produce a listing of files and folders in the database using dbfhdeploy:
    dbfhdeploy list URL[?folder=<folder-name>]

    A list of files is displayed.

    Note: If you do not specify a folder name, only files and folders at the base level of the datastore are displayed.

    If any of the files in your datastore are transactional, you must also configure an XA resource within the enterprise server region that points to the datastore; see Create an XA Resource. If none of your files are transactional, you can skip that step and proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore, and if resource locking is to be managed by an enterprise server region, configuring region and cross-region databases.

Parent topic: Configure Datastores for Db2
Previous topic: UNIX: Create Datastore Data Sources for Db2
Next topic: Create an XA Resource


Create an XA Resource

Your enterprise server region requires an XA resource for each datastore that contains one or more transactional files. If the database containing the datastore is also used by other COBOL applications, additional XA resources are required. Refer to Working with Multiple XARs for details on how to handle such situations.

  1. Open the ESCWA Administration page, and then select the enterprise server that references the transactional data file from the left pane.
  2. In the right pane, click General > XA Resources.
  3. Click NEW.
  4. Specify the following XAR details:
    Option | Description
    ID | Unique ID for the XAR
    Name | Unique name for the XAR
    Module | Specify the location of the RM switch module executable file (.dll on Windows or .so on UNIX platforms). This is ESDB2XA.dll/.so for Db2. Refer to Building RM Switch Modules for more information.
    Enabled | Enable the resource for immediate use.
    Open string Db=<database-name>, uid=<user-id>, pwd=<password>
    You can also specify further options as required, as detailed in To define an XA resource (XAR) for an enterprise server region.
    Note: This connection is applicable to all datastores in the database, unless ID is the name of a particular datastore; in which case, the connection is only applicable to that datastore.
  5. Click SAVE.

    The XA resource should be effective immediately.

You can now proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore.

Parent topic: Configure Datastores for Db2
Previous topic: Upload Files to a Db2 Datastore
Related concepts
Building RM Switch Modules
Related reference
To define an XA resource (XAR) for an enterprise server region
Working with Multiple XARs


Configure Region and Cross-Region Databases in Db2

You can connect to a Db2 database using two methods. The recommended method is to use connection strings, as these can be used for both 32-bit and 64-bit client connections. Connection strings are configured using the connect attribute within the database configuration file. You can also connect using the ODBC data source method that is used for other database types.

Db2 region and cross-region databases can be created in their own database, or you can store them in a single database. This database may also contain one or more datastore databases.

Use these steps to configure region and cross-region databases in Db2.

  1. Create Db2 Region and Cross-Region Databases Using Script Files
  2. Update the Configuration File for Db2 Region and Cross-Region Databases
  3. Windows: Create Region and Cross-Region Data Sources for Db2
  4. UNIX: Create Region and Cross-Region Data Sources for Db2
  5. Configure a Region or Cross-Region Database in Enterprise Server
Parent topic: Using Db2
Related information
Configure Datastores for Db2


Create Db2 Region and Cross-Region Databases Using Script Files

For Db2 databases, you can use the conventional method of database creation, using ODBC DSNs, as detailed for the other supported database types; but due to the Db2 architecture, it is preferable to create the databases ahead of time, using an SQL script file.

  1. To create a region database script file, on the command line, enter the following command:
    dbfhadmin -script -type:region -provider:db2 -name:<es-name> -file:<script-name.sql> [-existdb:<db-name>|-db:<db-name>]

    where <es-name> is the name of the intended enterprise server region, which must be 8 characters or less (a Db2 restriction).

    The two mutually exclusive optional parameters that you can specify determine where the database is to be created: if the region database is to be within an existing Db2 database (for example, you may have one database that holds all datastores, region databases, and a cross-region database), use the -existdb option; to create a new Db2 database, use the -db option to specify the name of the database. If you omit both options, a new database with a default name will be created - the default name for a region database is the value given for the -name option.

    Note: If you omit the -file option, the default name is create_region_db2.sql.
  2. To create a cross-region database script file, on the command line, enter the following command:
    dbfhadmin -script -type:crossregion -provider:db2 -file:<script-name.sql> [-existdb:<db-name>|-db:<db-name>]

    The two mutually exclusive optional parameters that you can specify determine where the database is to be created: if the cross-region database is to be within an existing Db2 database that does not already contain a cross-region database, use the -existdb option; to create a new Db2 database, use the -db option to specify the name of the database. If you omit both options, a new database with a default name will be created - the default name for a cross-region database is $XREGN$.

    Note: If you omit the -file option, the default name is create_crossregion_db2.sql.
    Once you have created the script files, use the dbfhadmin utility to run them, and create the required databases.
  3. To create a region database, on the command line, enter the following command:
    dbfhadmin -createdb -file:<script-name.sql> -type:region -provider:db2

    where <script-name.sql> is the name of the script file that was created in an earlier step.

  4. To create a cross-region database, on the command line, enter the following command:
    dbfhadmin -createdb -file:<script-name.sql> -type:crossregion -provider:db2
    Note: If you specify an existing database, it cannot already contain a cross-region database.

Now that the region and cross-region databases have been created, you can configure the database configuration file to use them.

Parent topic: Configure Region and Cross-Region Databases in Db2
Next topic: Update the Configuration File for Db2 Region and Cross-Region Databases


Update the Configuration File for Db2 Region and Cross-Region Databases

Use these steps to create or update a configuration file to include entries to one or more region databases, and a cross-region databases.

You should only create or update a configuration file using the dbfhconfig command line utility.

If you are configuring a file that has previously been configured for the database instance that you are working with, you can jump to step 4, ensuring that you use the same <server-name> as previously used.

  1. Open an Enterprise Developer command prompt.
    Note: On Windows, the command prompt must be the same bitism as the ODBC data source that you intend to use.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:db2

    where <server-name> is the name of the database server instance. An entry of localhost:<port> is also valid, which defaults to your machine name. If you have already updated the configuration file with the Db2 datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

    Now specify the required databases within the instance.

  4. Repeat the following step for each required region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> [-db:<existing-db>] [odbcdsn:<dsn-name>] -type:region -name:<region-name> -feature:<options> [-user:<user-name>] [-password:<password>] [-connect:<connection-string>]

    where <name> is either the name you will give an ODBC data source for the region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the region database if you are using a connection string; <existing-db> is the name of an existing database in which the datastore is stored - if this option is omitted, it is implied that the datastore is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information; <region-name> is the name of the enterprise server region that this database will serve; <options> is a list of features for which the region will use the database; <user-name> and <password> are valid credentials for the instance - you do not need to specify theses if you are using a connection string; and <connection-string> is the database connection string if you are establishing a database connection without the use of an ODBC data source - see Database Connection Strings for the database-specific syntax.

    <options> can be one or more of:
    • all - all available region features enabled (default).
    • none - no region features enabled.
    • [+|-]reslocking - enables\disables database resource locking.
  5. Now add a reference to a single cross-region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:crossregion [-db:<existing-db>] [odbcdsn:<dsn-name>] [-user:<user-name>] [-password:<password>] [-connect:<connection-string>]
    where <name> is either the name you will give an ODBC data source for the cross-region database (in which case, make a note of it for a later step), or a unique name within the server configuration in which to reference the cross-region database if you are using a connection string; <existing-db> is the name of an existing database in which the datastore is stored - if this option is omitted, it is implied that the datastore is housed in its own database; <dsn-name> is the name of the data source used as a shared database connection (if you are using ODBC data sources and using a single physical database) - see Database Connections for more information.

Example configuration file

The following is an example of a configuration file that contains a datastore, a region database, and a cross-region database, using direct connection syntax. As the login credentials are required to establish a connection to this database, the secrets vault has also been enabled: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
   <server name="localhost:50000" type="db2" access="odbc">
      <dsn name="DB2.VSAM" type="datastore" dsname="VSAM" optio="none +ooseq" dbname="MYMFFILS" connect="$$vault$$"/>
      <dsn name="DB2.ESDEMO" type="region.cas" region="ESDEMO" feature="all" dbname="MYMFFILS" connect="$$vault$$"/>
      <dsn name="DB2.CROSSREGION" type="crossregion.cas" dsname="$XREGN$" dbname="MYMFFILS" connect="$$vault$$"/></server>
</datastores>
Next, if you have not used connection strings in your database configuration file, you must create the data sources for each of the databases you have configured. If you have configured connection strings, you can skip the data source creation and configure your enterprise server regions to use the region and cross-region databases.
Parent topic: Configure Region and Cross-Region Databases in Db2
Previous topic: Create Db2 Region and Cross-Region Databases Using Script Files
Next topic: Windows: Create Region and Cross-Region Data Sources for Db2
Related reference
Database Connection Strings
Configure a Secrets Vault for the Micro Focus Database File Handler
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Windows: Create Region and Cross-Region Data Sources for Db2

Note: We recommend that you use a connection string to connect to Db2 databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for DB2 Region and Cross-Region Databases.

Use the following steps if you do not intend to use connection strings, but instead create ODBC data sources to access region and cross-region databases.

  1. Open the ODBC Data Source Administrator.
    Tip: On most newer Windows versions, click the Start Menu button, type ODBC, and then select the appropriate desktop app.
  2. On the ODBC Data Source Administrator dialog box, select the System DSN tab.
  3. Add a new data source for a region database:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, IBM DB2 ODBC Driver is a common one for Db2), and click Finish.

      The ODBC IBM DB2 Driver - Add wizard appears.

    3. Enter a name and description for the data source.
      Note: This is the name of the enterprise server region, and must be 8 characters or less.
    4. Click OK.

      The ODBC Data Source Administrator appears again.

  4. Add a new data source for a cross-region database:
    1. Click Add.
    2. Select the appropriate ODBC driver for your database (for example, IBM DB2 ODBC Driver is a common one for Db2), and click Finish.

      The Create New Data Source... wizard appears.

    3. Enter $XREGN$ as the name of the cross-region database and enter a description.
    4. Click OK.

      The ODBC Data Source Administrator appears again.

  5. Click OK.

The data sources for the region and cross-region databases are configured. You can configure your enterprise server regions to use the region and cross-region databases.

Parent topic: Configure Region and Cross-Region Databases in Db2
Previous topic: Update the Configuration File for Db2 Region and Cross-Region Databases
Next topic: UNIX: Create Region and Cross-Region Data Sources for Db2


UNIX: Create Region and Cross-Region Data Sources for Db2

Note: We recommend that you use a connection string to connect to Db2 databases; that is, using the connect attribute within the database configuration file, which is covered in Update the Configuration File for DB2 Region and Cross-Region Databases.

Use the following steps if you do not intend to use connection strings, but instead create ODBC data sources to access region and cross-region databases.

There are a number of different driver managers that you can use to configure an ODBC data source. These instructions are carried out using unixODBC. If you are using a different driver manager, consult the vendor instructions for creating data sources.

  1. Run the command odbcinst -j command, and note down the location of the drivers configuration file (odbcinst.ini) and the user data sources configuration file (.odbc.ini).
  2. Open the odbcinst.ini configuration file and ensure that you have something similar to the following:

    (This may differ depending on the version of Db2 you are running.)

    [Db2]
Description=Sample Db2 ODBC Database
Driver=/opt/ibm/db2/dsdriver/lib/libdb20.so
  3. Open the .odbc.ini configuration file and add an entry for a region database data source:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Port = <port-no>
Database = <region-name>
    where:
    • <datasource-name> - a name for the data source.
    • <driver-name> - the name of the driver as configured in the .odbcinst.ini file; in the example above, that would be Db2.
    • <server-name> - the name of the server on which the database instance resides.
    • <port-no> - the port on which the database is listening.
    • <region-name> - the name of a region database (which matches the name of an enterprise server region).
  4. Repeat the last step for each additional region database that you have.
  5. Add a new data source entry for a cross-region database:
    [<datasource-name>]
Driver = <driver-name>
Server = <server-name>
Port = <port-no>
Database = $XREGN$
  6. Save the .odbc.ini configuration file.

Example .odbc.ini file

The following is an example of an .odbc.ini configuration file contains data sources for a local Db2 database instance with two datastores.

[Db2.ESDEMO]
Driver = Db2
Server = localhost
Port = 50000
Database = ESDEMO

[Db2.XREG]
Driver = Db2
Server = localhost
Port = 50000
Database = $XREGN$

The data sources for the region and cross-region databases are configured. You can configure your enterprise server regions to use the region and cross-region databases.

Parent topic: Configure Region and Cross-Region Databases in Db2
Previous topic: Windows: Create Region and Cross-Region Data Sources for Db2
Next topic: Configure a Region or Cross-Region Database in Enterprise Server


Configure a Region or Cross-Region Database in Enterprise Server

This process also assumes that your enterprise server region is already correctly configured to run your application.

These steps configure an enterprise server region to use a region database, and if one does not already exist, a cross-region database.

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left in the row for the required enterprise server region.
  2. Add the following environment variables to your enterprise server region:
    Variable setting | Purpose
    ES_DB_FH=Y | Enables the Micro Focus Database File Handler
    ES_DB_SERVER=<DB-instance-name> Specifies the database instance in which the resources are stored
    Note: The types of resources stored are determined by the feature attribute specified for the region database in the configuration file.
    MFDBFH_CONFIG=<path-filename-config-file> | Locates the configuration file containing the list of data sources and their database types
    MFDBFH_SCRIPT_DIR=<path-to-scripts> | Locates the stored procedures required for Enterprise Server to interact with a database
    ES_LOCKDB=<region-database> | Optional. Required for resource locking in an enterprise server cluster utilizing database-hosted files. See Resource Locking for more information.
    ES_SERVER=<server-name> | Optional. See ES_LOCKDB.
  3. Cold-(re)start the enterprise server region.
    Tip: You can cold-start a region using the /s:c option with the casstart command on the command line.

    Once the region is back up and running, you can view the console log to confirm that the region and cross-region databases were created successfully - the relevant entries are prefixed DBFH.

Parent topic: Configure Region and Cross-Region Databases in Db2
Previous topic: UNIX: Create Region and Cross-Region Data Sources for Db2
Related concepts
Resource Locking


Using Oracle

Use this section to configure datastores and/or enterprise server region and cross-region databases in Oracle.

Unlike other database provider, the use of Oracle with the Micro Focus Database File Handler does not support ODBC connection types.

Connection to an Oracle database relies upon their native connection API, called OCI. Use this within a database connection string, using Oracle's Easy Connect format.

When creating datastores and region/cross-region databases, the underlying physical database must already exist within Oracle before those MFDBFH-related databases can be created. You can use one physical database that you intend to use for multiple datastores and/or region and cross-region databases, or you can use multiple physical databases for your MFDBFH datastores and databases.

  • Configuring Datastores for Oracle
    Use these steps to configure datastore databases in Oracle.
  • Configuring Region and Cross-Region Databases Oracle
    Use these steps to configure region and cross-region databases in Oracle.
Parent topic: Configuration Requirements
Related reference
The dbfhadmin Command Line Utility


Configuring Datastores for Oracle

Use these steps to configure datastore databases in Oracle.
EBCDIC data: By default, Oracle does not support individual table columns to be defined with a specific collation sequence. This means that any alphanumeric key fields defined for EBCDIC files cannot be explicitly collated using an EBCDIC collating sequence. Instead, MFDBFH defines these fields as binary data, resulting in binary collation be used. For the most part, binary collation produces the expected sequence order for EBCDIC keys.

However, if true EBCDIC collation is required, the Oracle database hosting the MFDBFH datastore must have been created with, or upgraded specifying, the MAX_STRING_SIZE configuration parameter set to a value of EXTENDED. By default, Oracle databases are created with MAX_STRING_SIZE=STANDARD. When MAX_STRING_SIZE=EXTENDED is set for the database, MFDBFH will define each alphanumeric key column of an EBCDIC file to use EBCDIC collation. For MFDBFH to recognise a key as being alphanumeric, the COBOL program creating the file must either have been compiled using the IXNUMKEY directive, or key types for the file must have been pre-defined using the dbfhadmin -keytypes -add command.

  1. Create Oracle Datastores Using Script Files
    Create database script files that can be run ahead-of-time to create Oracle datastores.
  2. Update the Configuration File for Oracle Datastores
    Add the database entries and connection details for your datastore databases in the MFDBFH configuration file.
  3. Upload Files to an Oracle Datastore
    Use the dbfhdeploy command line utility to upload data files to the datastores.
  4. Create an XA Resource
    If you are handling transactional data, you are required to create an XA resource for the datastore that houses the transactional data files.
Parent topic: Using Oracle


Create Oracle Datastores Using Script Files

Important: Unlike other database types that will create the physical database in which the datastore is to be stored if that database doesn't already exist, when using Oracle, the physical database must already have been created before these scripts are run.
  1. To create the database script file, on the command line, enter the following command:
    dbfhadmin -script -type:datastore -provider:ora -name:<datastore-name> -file:<script-name.sql>

    where <datastore-name> is the name of the datastore to be created within the database, and <script-name.sql> is the name of the script file to be created.

    Note: If you omit the -file option, the default name is create_datastore_<datastore-name>_ora.sql
  2. Create further script files for any more required datastores.

    Once you have created the script files, use the dbfhadmin utility to run them, and create the required databases.

    Before you run the -createdb command, ensure that the sqlplus command is on the PATH. (SQL *Plus is Oracle's command line database utility.)

  3. To create the database, on the command line, enter the following command:
    dbfhadmin -createdb -file:<script-name.sql> -type:datastore -provider:ora -existdb:<db-name> -user:<user-name> -password:<password>

    where <script-name.sql> is the name of the script file that was created in an earlier step; <db-name> is the name of a database reference in your tnsnames.ora file; and <user-name> and <password> are valid credentials for the instance.

Now that the datastores have been created, you can configure the database configuration file to use them.

Parent topic: Configuring Datastores for Oracle
Next topic: Update the Configuration File for Oracle Datastores


Update the Configuration File for Oracle Datastores

You should only create or update a configuration file using the dbfhconfig command line utility.

  1. Open an Enterprise Developer command prompt.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:ora

    where <server-name> is the name of the database server instance. An entry of localhost:<port> is also valid, which defaults to your machine name. If you have already updated the configuration file with the Oracle datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

    Now specify the required datastores within the instance.

  4. Repeat the following step for each required datastore:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:datastore -optio:<opts> [-bitism:<bit>]
-name:<dsname> -db:<existing-db> {-user:<user-name> -password:<password> | -connect:<connection-string>}

    where <name> is the unique name within the MFDBFH configuration file in which to reference the datastore; <opts> are the optimizations to be applied to I/O operations; <bit> is the bitism of the database connection; <dsname> is the actual name of the datastore. For the connection details, you must specify -db (where <existing-db> is the name of an existing database instance in which to store the datastore - for simplicity, we recommend specifying the identifying entry in the tnsnames.ora configuration file), and then either -user and -password (where <user-name> and <password> are valid credentials for the instance), or -connect (where <connection-string> is the database connection string - see Database Connection Strings for the database-specific syntax); .

    <opts> can be one of:
    option | description
    all | All optimizations applied, as if +<opt> had been specified for each available option. You can then selectively disable certain options using -<opt>.
    none | No optimizations applied.
    {+|-}oiseq | Enables (+) or disables (-) optimizations for line-sequential files opened for input.
    {+|-}ooseq | Enables (+) or disables (-) optimizations for line-sequential files opened for output.
    {+|-}oi | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for input.
    {+|-}oo | Enables (+) or disables (-) optimizations for ESDS, KSDS, and RRDS files opened for output.

Example configuration file

The following is an example of a configuration file that contains two datastores, a region database, and a cross-region database, using direct connection syntax. As the database login credentials are required in the connection, the secrets vault has been enabled to mask the password: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
 <server name="${TESTMFDBFH_DBINST_ORA}" type="oracle" access="oci">
    <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" optio="none" dbname="DBFHTEST" connect="$$vault$$"/>
    <dsn name="ORA.JES" type="datastore" dsname="JES" optio="none" dbname="DBFHTEST" connect="$$vault$$"/>
    <dsn name="ORA.CAS.CROSSREGION" type="crossregion.cas" dbname="DBFHTEST" connect="$$vault$$"/>
    <dsn name="ORA.CAS.TESTDB" type="region.cas" region="TESTDB" dbname="DBFHTEST" connect="$$vault$$"/>
  </server>
</datastores>

Next, you can use the dbfhdeploy command line utility to add files to the datastores.

Parent topic: Configuring Datastores for Oracle
Previous topic: Create Oracle Datastores Using Script Files
Next topic: Upload Files to an Oracle Datastore
Related reference
Configure a Secrets Vault for the Micro Focus Database File Handler
Database Connection Strings
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Upload Files to an Oracle Datastore

You should only create or update a configuration file using the dbfhconfig command line utility.

  1. Open an Enterprise Developer command prompt.
  2. Set the MFDBFH_CONFIG environment variable to locate the database configuration file that contains a reference to the data source:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, the file is assumed to be located in the current directory, or you may use the -configfile:<name> option appended to the following dbfhdeploy commands (see The dbfhdeploy Command Line Utility for more details).

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a data file to the datastore:
    dbfhdeploy data add <filename> URL/<file-ref>[?folder=<folder-name>]

    If <folder-name> does not already exist, it is created.

  4. To test that the data file is now in the datastore, you can produce a listing of files and folders in the database using dbfhdeploy:
    dbfhdeploy list URL[?folder=<folder-name>]

    A list of files is displayed.

    Note: If you do not specify a folder name, only files and folders at the base level of the datastore are displayed.

    If any of the files in your datastore are transactional, you must also configure an XA resource within the enterprise server region that points to the datastore; see Create an XA Resource. If none of your files are transactional, you can skip that step and proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore, and if resource locking is to be managed by an enterprise server region, configuring region and cross-region databases.

Parent topic: Configuring Datastores for Oracle
Previous topic: Update the Configuration File for Oracle Datastores
Next topic: Create an XA Resource


Create an XA Resource

Your enterprise server region requires an XA resource for each datastore that contains one or more transactional files. If the database containing the datastore is also used by other COBOL applications, additional XA resources are required. Refer to Working with Multiple XARs for details on how to handle such situations.

  1. Open the ESCWA Administration page, and then select the enterprise server that references the transactional data file from the left-hand pane.
  2. In the right-hand pane, click General > XA Resources.
  3. Click NEW.
  4. Specify the following XAR details:
    Option | Description
    ID | Unique ID for the XAR
    Name | Unique name for the XAR
    Module | Specify the location of the RM switch module executable file (.dll on Windows or .so on UNIX platforms). This is ESORAXA.dll/.so for Oracle. Refer to Building RM Switch Modules for more information.
    Enabled | Enable the resource for immediate use.
    Open string ORACLE_XA+SQLNET=<tnsnames-name>+DB=<db-name>+ACC=P/<user-name>/<password>+SESTM=10
    You can also specify further options as required, as detailed in To define an XA resource (XAR) for an enterprise server region.
    Note: This connection is applicable to all datastores in the database, unless ID is the name of a particular datastore; in which case, the connection is only applicable to that datastore.
  5. Click SAVE.

    The XA resource should be effective immediately.

You can now proceed to configuring your CICS or batch (JCL) applications to use the file(s) in the datastore.

Parent topic: Configuring Datastores for Oracle
Previous topic: Upload Files to an Oracle Datastore
Related concepts
Building RM Switch Modules
Related reference
To define an XA resource (XAR) for an enterprise server region
Working with Multiple XARs


Configuring Region and Cross-Region Databases Oracle

Use these steps to configure region and cross-region databases in Oracle.
  1. Create Oracle Region and Cross-Region Databases Using Script Files
    Create database script files that can be run ahead-of-time to create Oracle region and cross-region databases.
  2. Update the Configuration File for Oracle Region and Cross-Region Databases
    Add the database entries and connection details for your region and cross-region databases in the MFDBFH configuration file.
  3. Configure a Region or Cross-Region Database in Enterprise Server
    Configure an enterprise server region to use a region database and cross-region database.
Parent topic: Using Oracle


Create Oracle Region and Cross-Region Databases Using Script Files

Important: Unlike other database types that will create the physical database in which the region and cross-region databases are to be stored if that database doesn't already exist, when using Oracle, the physical database must already have been created before these scripts are run.
  1. To create a region database script file, on the command line, enter the following command:
    dbfhadmin -script -type:region -provider:ora -name:<es-name> -file:<script-name.sql>

    where <es-name> is the name of the enterprise server region that will use the region database .

    Note: If you omit the -file option, the default name is create_region_ora.sql.
  2. To create a cross-region database script file, on the command line, enter the following command:
    dbfhadmin -script -type:crossregion -provider:ora -file:<script-name.sql>
    Note: If you omit the -file option, the default name is create_crossregion_ora.sql.
    Once you have created the script files, use the dbfhadmin utility to run them, and create the required databases.

    Before you run the -createdb command, ensure that the sqlplus command is on the PATH. (SQL *Plus is Oracle's command line database utility.)

  3. To create a region database, on the command line, enter the following command:
    dbfhadmin -createdb -file:<script-name.sql> -type:region -provider:ora -existdb:<db-name> -user:<user-name> -password:<password>

    where <script-name.sql> is the name of the script file that was created in an earlier step; <db-name> is the name of an existing database instance; and <user-name> and <password> are valid credentials for the instance.

  4. To create a cross-region database, on the command line, enter the following command:
    dbfhadmin -createdb -file:<script-name.sql> -type:crossregion -provider:ora -existdb:<db-name> -user:<user-name> -password:<password>

    where <script-name.sql> is the name of the script file that was created in an earlier step; <db-name> is the name of a database reference in your tnsnames.ora file; and <user-name> and <password> are valid credentials for the instance.

    Note: The database specified by -existdb cannot already contain a cross-region database.

Now that the region and cross-region databases have been created, you can configure the database configuration file to use them.

Parent topic: Configuring Region and Cross-Region Databases Oracle
Next topic: Update the Configuration File for Oracle Region and Cross-Region Databases


Update the Configuration File for Oracle Region and Cross-Region Databases

You should only create or update a configuration file using the dbfhconfig command line utility.

If you are configuring a file that has previously been configured for the database instance that you are working with, you can jump to step 4, ensuring that you use the same <server-name> as previously used.

  1. Open an Enterprise Developer command prompt.
  2. Set the MFDBFH_CONFIG environment variable to locate the configuration file to be created or updated:
    set MFDBFH_CONFIG=<location-and-name-of-file>

    If you do not set this variable, a file named MFDBFH.cfg is assumed to be located in the current directory.

    Note: The MFDBFH_SCRIPT_DIR environment variable is also required to point to the stored procedures used to interact with a datastore; however, this variable is implicitly set already when using an Enterprise Developer command prompt.
  3. Add a database server instance that you intend to connect to:
    dbfhconfig -add -server:<server-name> -provider:ora

    where <server-name> is the name of the database server instance. An entry of localhost:<port> is also valid, which defaults to your machine name. If you have already updated the configuration file with the Oracle datastores, this entry will already exist, and you will receive a message informing you of this; you can skip to the next step.

    Now specify the required databases within the instance.

  4. Repeat the following step for each required region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:region -name:<region-name> [-bitism:<bit>]
-feature:<options> -db:<existing-db> {-user:<user-name> -password:<password> | -connect:<connection-string>}

    where <name> is the unique name within the MFDBFH configuration file in which to reference the datastore; <region-name> is the name of the enterprise server region; <bit> is the bitism of the database connection; <options> is a list of features for which the region will use the database; <dsname> is the actual name of the datastore. For the connection details, you must specify -db (where <existing-db> is the name of an existing database instance in which to store the datastore - for simplicity, we recommend specifying the identifying entry in the tnsnames.ora configuration file), and then either -user and -password (where <user-name> and <password> are valid credentials for the instance), or -connect (where <connection-string> is the database connection string - see Database Connection Strings for the database-specific syntax).

    <options> can be one of:
    • all - all available region features enabled (default).
    • none - no region features enabled.
    • [+|-]reslocking - enables\disables database resource locking.
  5. Now add a reference to a single cross-region database:
    dbfhconfig -add -server:<server-name> -dsn:<name> -type:crossregion -db:<existing-db> {-user:<user-name> -password:<password> | -connect:<connection-string>}
    where the values are the same as when specifying a region database (above).

Example configuration file

The following is an example of a configuration file that contains two datastores, a region database, and a cross-region database, using direct connection syntax. As the database login credentials are required in the connection, the secrets vault has been enabled to mask the password: see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

<datastores usevault="true">
 <server name="${TESTMFDBFH_DBINST_ORA}" type="oracle" access="oci">
    <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" optio="none" dbname="DBFHTEST" connect="$$vault$$"/>
    <dsn name="ORA.JES" type="datastore" dsname="JES" optio="none" dbname="DBFHTEST" connect="$$vault$$"/>
    <dsn name="ORA.CAS.CROSSREGION" type="crossregion.cas" dbname="DBFHTEST" connect="$$vault$$"/>
    <dsn name="ORA.CAS.TESTDB" type="region.cas" region="TESTDB" dbname="DBFHTEST" connect="$$vault$$"/>
  </server>
</datastores>
Next, you can configure your enterprise server regions to use the region and cross-region databases.
Parent topic: Configuring Region and Cross-Region Databases Oracle
Previous topic: Create Oracle Region and Cross-Region Databases Using Script Files
Next topic: Configure a Region or Cross-Region Database in Enterprise Server
Related reference
Configure a Secrets Vault for the Micro Focus Database File Handler
Database Connection Strings
The dbfhconfig Command Line Utility
Database Connections
Sharing Database Connections


Configure a Region or Cross-Region Database in Enterprise Server

This process also assumes that your enterprise server region is already correctly configured to run your application.

These steps configure an enterprise server region to use a region database, and if one does not already exist, a cross-region database.

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left in the row for the required enterprise server region.
  2. Add the following environment variables to your enterprise server region:
    Variable setting | Purpose
    ES_DB_FH=Y | Enables the Micro Focus Database File Handler
    ES_DB_SERVER=<DB-instance-name> Specifies the database instance in which the resources are stored
    Note: The types of resources stored are determined by the feature attribute specified for the region database in the configuration file.
    MFDBFH_CONFIG=<path-filename-config-file> | Locates the configuration file containing the list of data sources and their database types
    MFDBFH_SCRIPT_DIR=<path-to-scripts> | Locates the stored procedures required for Enterprise Server to interact with a database
    ES_LOCKDB=<region-database> | Optional. Required for resource locking in an enterprise server cluster utilizing database-hosted files. See Resource Locking for more information.
    ES_SERVER=<server-name> | Optional. See ES_LOCKDB.
  3. Cold-(re)start the enterprise server region.
    Tip: You can cold-start a region using the /s:c option with the casstart command on the command line.

    Once the region is back up and running, you can view the console log to confirm that the region and cross-region databases were created successfully - the relevant entries are prefixed DBFH.

Parent topic: Configuring Region and Cross-Region Databases Oracle
Previous topic: Update the Configuration File for Oracle Region and Cross-Region Databases
Related concepts
Resource Locking


Configuring CICS Applications for Native Database File Handling

To move your existing data files from disk to a database, you need to use the dbfhdeploy command line utility to deploy them to a datastore. Once deployed, you need to configure your CICS environment to locate them within the datastore.

Whether you are creating a new resource or updating an existing one, the database file handling-specific changes are the same: you need to update the file path within the FCT that details the file, to point at the new datastore location. The following example is using the ACCTFIL file, which is stored in the VSAM folder within the CICS datastore:

For more details on the notation used, see the data category in The dbfhdeploy Command Line Utility.

Additionally, if your file is transactional (as indicated above by the selected Backward Recovery option), you must also configure an XA resource within the enterprise server region that points to the datastore in which the file is stored; see the Create an XA Resource topic within the Configuring Datastores section for your database type.

You do not need to make any code changes to your CICS application's source code to use files within a datastore.

If the enterprise server region running your CICS environment terminates abnormally whilst any data files are open, Enterprise Server attempts to recover the files automatically. If you continue to receive errors accessing files (for example, file locked statuses), run the dbfhadmin command line utility to recover the files.

Parent topic: Configuration Requirements
Related concepts
The dbfhadmin Command Line Utility
Related reference
The dbfhdeploy Command Line Utility
Create an XA Resource


Configuring the JCL Environment for Native Database File Handling

You can configure your JCL environment to use the native database file handler, where catalog.dat and catalog files can be stored in a database.

This requires setting a number of environment variables within the JES region, and then configuring JES Mainframe System Support to use the datastore(s) you configured. Use the dbfhdeploy to move the catalog files from disk to the database.

You need to set the following environment variables in the enterprise server region:

Variable setting | Purpose
ES_DB_FH=Y | Enables the Micro Focus Database File Handler
MFDBFH_CONFIG=<path-filename-config-file> | Locates the configuration file containing the list of data sources and their database types
MFDBFH_SCRIPT_DIR=<path-to-scripts> | Locates the stored procedures required for Enterprise Server to interact with a database

If you are configuring a JCL environment from scratch (that is, the catalog is currently empty), then the required catalog file and specified folder structure is created on completion of the first job that is run.

Using the System Catalog and Default Allocated Dataset Location fields to specify a catalog file

The example shown above creates a catalog.dat file, if one does not already exist, within the CAT folder in the PGJCLCAT datastore. The Default Allocated Dataset Location setting creates a sub-folder from the location of the catalog file for any cataloged data sets. These two options form the values of the MFSYSCAT and MFALLOC_LOC environment variables respectively.

If you are moving an existing catalog, the method of data set storage will determine which files you move to the database. If the data sets are stored relative to the catalog, you should move catalog.dat and all its data sets from disk to the same datastore. You can use the dbfhdeploy command line utility to upload the files and create the required folder structure to ensure that the relative file locations are maintained; that way, no changes to the catalog are necessary.

If an existing catalog contains absolute paths to its data sets, or the default data set allocation method (for example, when using ES_ALLOC_OVERRIDE) is different to or not relative to the catalog folder, you can either keep the data sets stored on disk, or you can move data sets to the database. If you do move a data set cataloged with an absolute path, you are required to re-catalog the entry, updating it with its new physical file location within the database.

For help on moving an existing disk-based catalog to a database, especially one that has a mixture of the storage methods mentioned above, refer to Moving a Catalog to a Database: the mfdbcatc utility can automate some of workload involved in relocating files that are already cataloged.

Recommended: If the catalog is used within a Performance and Availability Cluster (PAC), we recommend that both the catalog.dat and all its data sets reside in the same datastore.

You do not need to make any code changes to your batch application's source code to use files within a datastore.

If the enterprise server region running your JES environment terminates abnormally whilst any data files are open, Enterprise Server attempts to recover the files automatically. If you continue to receive errors accessing files (for example, file locked statuses), run the dbfhadmin command line utility to recover the files.

  • Moving a Catalog to a Database
    You can use the mfdbcatc utility to help move a disk-based catalog to a database.
Parent topic: Configuration Requirements
Related concepts
The dbfhadmin Command Line Utility
Related reference
The dbfhdeploy Command Line Utility


Moving a Catalog to a Database

If you are deploying an existing JCL catalog and its associated data files to a database that has been configured for the Micro Focus Database File Handler (Micro Focus Database File Handler), you may need to update the catalog entries in order to locate the referenced files when they are housed in the database.

You could update each catalog entry manually in order to locate the files once they have been deployed to the database, but that would be a long, labor-intensive process, and could be prone to error. An easier method is to use the mfdbcatc utility, which is designed to assist in deploying an existing catalog and files to a database.

The utility is a two-stage process, where it scans the existing catalog and files on disk, creating some intermediate files for the next process, and then it will create a new catalog and a script file intended to deploy the files to the required database location. The actual deploying of the catalog to the database is performed by another MFDBFH utility - dbfhdeploy.

A disk-based catalog references data files in a number of different way: it locates files relative to its location, based on the value of an environment variable or Fileshare location, or uses hard-coded entries to a specific location. mfdbcatc attempts to maintain the existing structure of your catalog where possible; for example, if you have data files in <CATALOGFOLDER>/DATA/ on disk, the new catalog deploys those files to the DATA folder in the database, updating the catalog to reflect that. For other cases, where file location is not as straight-forward, you can edit the configuration files produced in stage one of the mfdbcatc process, so that files are relocated within the bounds of your database structure when stage two is run.

  • Scanning an Existing Catalog
  • Deploying a Catalog to a Database
  • The mfdbcatc Utility
Parent topic: Configuring the JCL Environment for Native Database File Handling
Related reference
The dbfhdeploy Command Line Utility


Scanning an Existing Catalog

The first step you must perform is to scan the existing disk-based catalog, which creates a series of intermediate files, locating the existing data files in the catalog. These files will be used in the second stage, when the deployable files are produced.

To scan the catalog:

mfdbcatc -s -c <catalog file>

Where: <catalog file> is the existing catalog file. This results in a series of intermediate files: a number of files prefixed R_n.dat, and some configuration files.

The configuration files are relative.cfg, static.cfg, environment.cfg and fileshare.cfg, and are used to deal with the different location types that may exist in the catalog. Before you run the second stage of the process, you can edit these files to affect the final deployable files.

relative.cfg

This configuration file deals with catalog entries that are relative to the location of the configured catalog folder. The contents will look something like this:

0001:<CATALOGFOLDER>/DATA/
0009:<CATALOGFOLDER>/DATALIB/

Such entries indicate that the catalog has two sub-folders within the catalog folder location that contain data files: DATA and DATALIB.

At this point, you could edit these entries if you wanted to change the structure of your catalog once it is deployed to a database; for example, to move files from the DATA folder to the DB_DATA folder within <CATALOGFOLDER> once they are deployed, edit the file as follows:

0001:<CATALOGFOLDER>/DB_DATA/
0009:<CATALOGFOLDER>/DATALIB/

Alternatively, to store the files currently in the <CATALOGFOLDER>-relative DATA path, to a static location called DB_DATA on the server myhost, in the datastore mydatatable, edit the file as follows:

0001:sql://myhost/mydatatable/?type=folder;folder=DB_DATA/
0009:<CATALOGFOLDER>/DATALIB/

You could even move the <CATALOGFOLDER>-relative 'DATALIB' path to a local disk-based directory location; although this is not really what the utility is intended for:

0001:<CATALOGFOLDER>/DATA/
0009:C:\DATAFILES\DATALIB\

static.cfg

The static configuration file deals with those files that are referenced using a static (hard-coded) location. This type of file is slightly different in that it won't show where the files are currently stored, but will show a suggestion of where theses types of file would be stored once they are deployed.

The suggested location is a simple extrapolation from the current path, with placeholders for database identifiers. The contents could look something like:

0001:sql://{host}/{instance}/{datastore}/?type=folder;folder=TEST_DATA_/

This result indicates that the scan identified data files in /TEST/DATA/. The identifiers {host}, {instance}, and {datastore} will be replaced with values specified during the update (second) stage, unless they are changed in this configuration file. If you edit the placeholders in this file, it ensures that the files currently in /TEST/DATA/ go to a specific location in a specified database:

0001:sql://MYHOST/MYSTORE/?type=folder;folder=MY_DATA_/

You can also move them to a different, relative location:

0001:<CATALOGFOLDER>/MY_DATA_/

Or to a static disk location (again, not really what this utility is intended for):

0001:D:\ANOTHER\DISK\MY_DATA\

environment.cfg

Sometimes the file location is relative to the value of an environment variable. The value of the variable is required to resolve the location of the source. This value can also serve as the destination location too.

This configuration file is more complex than the previous file types. When using an environment variable for part of a file location, it looks something like this:

$MYLOCATION/DATA/

At run time, the environment variable $MYLOCATION is expanded, and the full path is built from it value. For example, if MYLOCATION=C:\TMP\, the source location resolves to C:\TMP\DATA\.

The deploy stage also needs to be able to resolve the value, both to locate the source and also to deploy to the database. By default, using the above example, the configuration file contains an entry similar to:

0001:$MYLOCATION=[<ENV-VALUE>]DATA\,<CATALOGFOLDER>/DATA_/

The comma separates the source and destination parts. If <ENV-VALUE> is left as it is, the mfdbcatc utility checks for the value of the MYLOCATION environment setting when the update/deploy stage is run. You can also edit the configuration file to use a specific value:

001:$MYLOCATION=[C:\TMP\]DATA\,<CATALOGFOLDER>/DATA_/

Alternatively, you could edit the file to use a fixed location:

0001:C:\TMP\DATA\,<CATALOGFOLDER>/DATA_/

Either of these edits will affect where the files to deploy are located.

The destination part (the entry after the comma) suggests deploying the files into a catalog-relative location (in /DATA_/). You can change this to any of the entry types discussed earlier, which will modify the new catalog entry to reflect where the file has been deployed. For example, to deploy to another environment variable entry:

0001:MYLOCATION=[C:\TMP\]DATA\,NEWLOCATION=[sql://myhost/mydata/?type=folder;folder=DATA/]MOREDATA/

This deploys files found in C:\TMP\DATA\ to sql://myhost/mydata/?type=folder;folder=DATA/MOREDATA/, but the entry in the new catalog will refer to $NEWLOCATION/MOREDATA/.

Alternatively, you can just deploy to a static location:

0001:MYLOCATION=[C:\TMP\]DATA\,sql://myhost/mydata/?type=folder;folder=DATA/MOREDATA/

The difference being that here the catalog directly references sql://myhost/mydata/<filename>?folder=DATA/MOREDATA/ for the file.

You can also deploy to a new static disk location:

0001:MYLOCATION=[C:\TMP\]DATA\,C:\TMP\NEWDATA\
Note: This type of entry generates a COPY statement, and not a deploy statement in the generated deploy script.

fileshare.cfg

The content of this file will look something like this:

0001:$$FSSERVER/DATA/,<CATALOGFOLDER>/FSSERVER_DATA_/

By default, it suggests a catalog-relative destination. Again, you can change this to a specific location, as discussed for the previous file types. This file type follows the same editing rules as those for environment.cfg.

Parent topic: Moving a Catalog to a Database
Related information
Deploying a Catalog to a Database
The mfdbcatc Utility


Deploying a Catalog to a Database

After you have scanned the existing catalog and have edited the configuration files as appropriate (see Scanning an Existing Catalog), you are in a position to create the deployable files for the new database-hosted catalog. This part of the process will create a new catalog file and a response file that can be used to deploy the data files from disk to database.

You can run the mfdbcatc utility to process all configuration file types (generated in the previous stage - see Scanning an Existing Catalog) at once, or process each configuration file individually.

To perform the process for all configuration files, specify the following command:

mfdbcatc -u -c <catalog file> -fs <CATALOGFOLDER source> -fd <CATALOGFOLDER destination> -h <host> -d <datastore> -n <instance> -v

When the update process is performed, <CATALOGFOLDER source> replaces the <CATALOGFOLDER> placeholders specified in the configuration files. The <CATALOGFOLDER source> is expected to be a disk-based location. The <CATALOGFOLDER destination> location is slightly more complex in the way it's defined - if you specify the -h, -d, and -n options, the destination is built from those entries.

Using the following example, those options resolve to a destination of sql://MYHOST/MYINST/MYSTORE/?type=folder;folder=DATA:

mfdbcatc -u -c CATALOG.DAT -fs C:\DATA\ -fd DATA -h MYHOST -n MYINST -d MYSTORE -v

Alternatively, you could specify the new destination as a complete string (omitting the -h, -n, and -d options):

mfdbcatc -u -c CATALOG.DAT -fs C:\DATA\ -fd sql://MYHOST/MYINST/MYSTORE/?type=folder;folder=DATA/ -v

The result of running either of these commands is a new file called NEWCATALOG.DAT, which takes files located in C:\DATA\ that belonged to CATALOG.DAT, and attributes them to the new destination of sql://MYHOST/MYSTORE/?type=folder;folder=DATA. The original CATALOG.DAT is left untouched. The process also produces a response file called deployfile - see Deploying the files for details.

To run the process individually, once per configuration file, you need to specify the -i[cfg-type] parameter. The following example runs the process for just the files identified by relative.cfg:

mfdbcatc -u -c CATALOG.DAT -fs C:\DATA\ -fd DATA -h MYHOST -n MYINST -d MYSTORE -v -ir relative.cfg

Deploying the files

When you have finished recreating the new catalog file (NEWCATALOG.DAT, rename it to CATALOG.DAT) and the deployfile, you must now use the dbfhdeploy utility to deploy the files to the database.

The deployfile file can simply be run using:

dbfhdeploy @deployfile

which will deploy the cataloged data files to the destination configured above.

The deployfile does not deploy the new CATALOG.DAT and its associated SPL* files, and so you must deploy these files manually - you need to be specific about the location in which they are deployed as the catalog likely contains relative references. The deploy command for the catalog file, using the above settings as an example, would look something like:

dbfhdeploy data add NEWCATALOG.dat sql://MYHOST/MYINST/MYSTORE/CATALOG.DAT
Parent topic: Moving a Catalog to a Database
Related reference
The dbfhdeploy Command Line Utility
Related information
Scanning an Existing Catalog
The mfdbcatc Utility


The mfdbcatc Utility

The mfdbcatc utility is used to partially automate the process of moving a disk-based catalog to a database-hosted one. It can scan an existing catalog on disk, and generate the necessary files to deploy the CATALOG.DAT and its cataloged data files to an MFDBFH-aware database. See Scanning an Existing Catalog and Deploy a Catalog to a Database for details on the two-step process.

Syntax:

mfdbcatc <action> <options>
<action> can be one of:
-s
Specify -s if you are scanning the existing catalog; see Scanning an Existing Catalog for more information.
-u
Specify -u if you are producing the deployable files; see Deploy a Catalog to a Database.
The following <options> can be specified, depending on the <action>:
-c
Specify the path and the catalog file you are scanning, or deploying to the database.
-fs
Specify the catalog folder (that is, the folder in which catalog.dat is stored, and where all catalog-relative locations are based).
-fd
Specify the destination folder for catalog.dat in the database. If you omit this option, the file is stored at the root location of the intended datastore. Only use this option with the -u action.
-h
Specify the host name of database. Only use this option with the -u action.
-d
Specify the name of the datastore. Only use this option with the -u action.
-n
Specify the name of the database instance. Only use this option with the -u action.
-v
Verbose output is displayed if you specify this option. (Optional.)
-i[cfg-type]
cfg-type can be one of:
  • r - relative configuration file
  • s - static configuration file
  • e -environment configuration file
  • f - Fileshare configuration file
  • q - SQL configuration file
Only use this option with the -u action.
Parent topic: Moving a Catalog to a Database
Related information
Scanning an Existing Catalog
Deploying a Catalog to a Database


The Database Configuration File

The database configuration file (by default, named MFDBFH.cfg) is used by the Micro Focus Database File Handler (MFDBFH), and for enterprise server region management.

It contains a list of database server instances, the databases available within them, and connection details. The types of database server currently supported are Microsoft SQL Server and Azure database, PostgreSQL, Db2, and Oracle. You may have one or more instances of each type configured within the same configuration file.

Within each server instance element, you configure a <dsn> element for each database available. Databases are either of type database, datastore, region.cas, or crossregion.cas; see Types of Database for more information.

To create or edit the configuration file, Micro Focus recommends that you use the dbfhconfig command line utility, and also that you enable the configuration file to use a secrets vault, so that the database connection credentials can be stored securely, behind an encryption process; see Configure a Secrets Vault for the Micro Focus Database File Handler.

MFDBFH or Enterprise Server establishes connection with a database using either a corresponding ODBC data source configured on your machine, or through a direct connection string (see Database Connection Strings).

See the Update the Configuration File for <db-type> topic in the relevant Configuring Datastores or Configuring Region and Cross-Region Databases sections for full details.

The following example shows server entries for each of the supported database providers: one of type sqlserver (called svr-mysqldb), one of type azuresqldb (whose location is determined by an environment variable), one of type postgresql (which stores its datastores, region database, and cross-region database in a single physical database - MFDevDB), one of type Db2 (which again, uses a variable), and the final server entry is type oracle. The first three use the ODBC data source names configured, but the last two (Db2 and Oracle) specify direct connection details via the connect option.

<datastores usevault="true">
  <server name="svr-mysqldb" type="sqlserver" access="odbc">
    <dsn name="SS.MYMASTER" type="database" dbname="master"/>
    <dsn name="SS.VSAM" type="datastore" dsname="VSAM" dbname="VSAM"/>
    <dsn name="SS.CAS.ESDEMO" type="region.cas" region="ESDEMO" dbname="ESDEMO" feature="all"/>
    <dsn name="SS.CROSSREGION" type="crossregion.cas" dbname="_$XREGN$"/></server>
  <server name="${VAR2AZDB}" type="azuresqldb" access="odbc">
    <dsn name="AZ.MYMASTER" type="database" dbname="master" userid="azusr" password="$$vault$$"/>
    <dsn name="AZ.VSAM" type="datastore" dsname="VSAM" dbname="VSAM" userid="azusr" password="$$vault$$"/>
    <dsn name="AZ.SEQ" type="datastore" dsname="SEQ" dbname="SEQ" optio="+ooseq" userid="azusr" password="$$vault$$"/>
    <dsn name="AZ.CAS.ESDEMO" type="region.cas" region="ESDEMO" dbname="ESDEMO" feature="all" userid="azusr" password="$$vault$$"/>
    <dsn name="AZ.CROSSREGION" type="crossregion.cas" dbname="_$XREGN$" userid="azusr" password="$$vault$$"/></server>
  <server name="MFDevDB" type="postgresql" access="odbc">
    <dsn name="PG.POSTGRES" type="database" dbname="postgres"/>
    <dsn name="PG.VSAM1" type="datastore" dsname="PGVSAM1" dbname="MFDevDB" userid="clerk" password="$$vault$$"/>
    <dsn name="PG.VSAM2" type="datastore" dsname="PGVSAM2" dbname="MFDevDB" userid="clerk" password="$$vault$$"/>
    <dsn name="PG.CAS.PGDEMO" type="region.cas" region="PGDEMO" dbname="MFDevDB" feature="all" userid="clerk" password="$$vault$$"/>
    <dsn name="PG.CROSSREGION" type="crossregion.cas" dbname=""MFDevDB" userid="clerk" password="$$vault$$"/></server>
  <server name="${TESTMFDBFH_DBINST_DB2}" type="db2" access="odbc">
    <dsn name="DB2.COPYTEST" type="datastore" dsname="COPYTEST" optio="all -ooseq" connect="$$vault$$"/>
    <dsn name="DB2.VSAM" type="datastore" dsname="VSAM" optio="all -ooseq" connect="$$vault$$"/>
    <dsn name="DB2.CAS.CROSSREGION" type="crossregion.cas" optio="none" connect="$$vault$$"/>
    <dsn name="DB2.CAS.TESTDB" type="region.cas" region="TESTDB" connect="$$vault$$"/></server>
  <server name="MY_ORA_DB" type="oracle" access="oci">
    <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" optio="none" dbname="DBFHTEST" userid="mfdbfh" password="temppwd"/>
    <dsn name="ORA.JES" type="datastore" dsname="JES" optio="none" dbname="DBFHTEST" userid="mfdbfh" password="temppwd"/>
    <dsn name="ORA.CAS.CROSSREGION" type="crossregion.cas" dbname="DBFHTEST" connect="mfdbfh/temppwd@DBFHTEST"/>
    <dsn name="ORA.CAS.TESTDB" type="region.cas" region="TESTDB" dbname="DBFHTEST" connect="mfdbfh/temppwd@DBFHTEST"/></server>
</datastores>

Each instance has a number of datastore, region, and cross-region databases. The sqlserver, azuresqldb, and postgresql server instances include an entry for type=database; this is mandatory in order for MFDBFH or Enterprise Server to be able to interact with those instances.

Use the MFDBFH_CONFIG environment variable to locate this configuration file, both when running applications through Enterprise Server and when using the dbfh* command line utilities. If the variable is not set, the configuration file is assumed to be located in the current directory, or in the enterprise server region's system directory; alternatively, these utilities can specify a configuration file (-configfile option), which will override the variable setting.

  • The dbfhconfig Command Line Utility
    Use the dbfhconfig command line utility to create and edit the database configuration file.
  • Configure a Secrets Vault for the Micro Focus Database File Handler
    To encrypt sensitive material stored in the database configuration file, enable it to use a secrets vault.
Parent topic: Configuration Requirements


The dbfhconfig Command Line Utility

Use the dbfhconfig command line utility to create and edit the database configuration file.

Syntax:

dbfhconfig [action][options]

Or:

dbfhconfig @<response-file-name> [-verbose]
action
Can be one of the following:
  • -add - adds a new <server> or <dsn> entry.
  • -delete - deletes a <server> or <dsn> entry.
  • -list - lists details of the configuration file.
  • -novault - the connection credentials are stored as plain text (default).
  • -update - updates a <server> or <dsn> entry.
  • -vault - the connection credentials are stored in the secrets vault (that is, they are encrypted); see Configure a Secrets Vault for the Micro Focus Database File Handler for more information.
options
Specify one or more of the following:
-bitism:32|64|both
Used to indicate the bitism of the associated ODBC data source. Some ODBC drivers, such as IBM Db2, require that data source names are unique, and so 32-bit and 64-bit connections to the same database must have different DSN entries. When set to both,the same DSN name is used for both 32-bit and 64-bit connections (default).
-comment:<comment>
Adds a comment line for the associated <server> or <dsn> entry. Use with the -add -dsn:<dsn-name> or -update -dsn:<dsn-name> actions/options.
-connect:<connection-string>
Adds a connection string to establish connection to the associated <server>. Connection strings are an alternative method to connecting to a database via an ODBC connection. Use with the -add -dsn:<dsn-name> or -update -dsn:<dsn-name> actions/options.
-connopts:<options>
The connection life-time options; see Database Connection Lifetime for a more detailed explanation. Use with the -add -dsn:<dsn-name> or -update -dsn:<dsn-name> actions/options
<options> can be one or more of the following, separated by a comma or a space:
  • close.heartbeat=y|n - close/leave after heartbeat (default = n).
  • close.syncpoint=y|n - close/leave after syncpoint (default = n).
  • close.task=y|n - close/leave after end of task (default = n).
  • max.cached=<n> - max number of connections to keep cached (default = 10).
  • max.dbopts=<n> - number of database operations before closing connections (default is 2147483647, that is INT_MAX).
-db:<db-name>
The name of the database to be used. This is used when a single physical database is used to host multiple datastores/regions. Use with the -add -dsn:<dsn-name> and -update -dsn:<dsn-name> actions/optons.
-dbopts:<options>
The database provider-specific options supported by MFDBFH; see Database Provider-specific Options for details of supported <options>. Use with the -add -dsn:<dsn-name> or -update -dsn:<dsn-name> actions/options
-dsn:<dsn-name>
The data source name. Use with the -add, -delete, and -update actions.
-feature:<options>
The features in use for the specified region database. Use with the -add -dsn:<dsn-name> -type:region and -update -dsn:<dsn-name> -type:region actions/options.
<options> can be one or more of the following, separated by a comma or a space:
  • all - all available region features enabled (default).
  • none - no region features enabled.
  • [+|-]reslocking - enables\disables database resource locking.
-file:<file-name>
Specifies the name of the configuration file to update. Use with the -add, -delete, and -update actions.
If not specified, the file defaults to the value of the MFDBFH_CONFIG environment variable.
-heartbeat:<secs>
The cross-region heartbeat interval, in seconds (default = 5). Use with the -add -dsn:<dsn-name> and -update -dsn:<dsn-name> actions/options. See Specifying the Cross-region Heartbeat Interval for more information.
-name:<name>
The name of the datastore, region, or database. Use with the -add -dsn:<dsn-name> and -update -dsn:<dsn-name> -type:datastore actions/options.
-nobanner
Suppresses output to a minimum.
-odbcdsn:<dsn-name>
The ODBC data source name with which to connect to a database. This option is used when you have multiple datastores, region databases, and/or a cross-region database stored in a single database, and you want those resources to share an ODBC database connection see Database Connections for more information. Use with the -add -dsn:<dsn-name> and -update -dsn:<dsn-name> actions/options.
-optio:<options>
Optimized I/O operations. Use with the -add -dsn:<dsn-name> -type:datastore and -update -dsn:<dsn-name> -type:datastore actions/options.
<options> can be one or more of the following, separated by a comma or a space:
  • all - all available I/O optimizations are enabled.
  • none - no I/O optimizations are enabled (default).
  • [+|-]oi - enables\disables I/O optimizations for ESDS, KSDS and RRDS files opened for input.
  • [+|-]oiseq - enables\disables I/O optimizations for (line-)sequential files opened for input.
  • [+|-]oo - enables\disables I/O optimizations for ESDS, KSDS and RRDS files opened for output.
  • [+|-]ooseq - enables\disables I/O optimizations for (line-)sequential files opened for output.
-optiokeyreads:<n>
The number of records to read ahead for KSDS, ESDS, and RRDS files when optimised I/O is enabled (see -optio). Specify 0 if the MFDBFH default value (of 50 records) is to be used.
-optioseqreads:<n>
The number of records to read ahead for LSEQ, and SEQ files when optimised I/O is enabled (see -optio). Specify 0 if the MFDBFH default value (of 50 records) is to be used.
-password:<password>
The password used to connect to the database. Use with the -add -dsn:<dsn-name> and -update -dsn:<dsn-name> actions/options.
-program:<prog-name>
The program/process name with which to apply the specified connection options (instead of it inheriting the connection-wide options). Use with the -add -server:<name> -dsn:<dsn-name> -connopts:<options> action/options.
-provider:<db-type>
The type of database. Use with the -add -server action/option.
<db-type> can be one of the following:
  • db2 - Db2.
  • ora or oracle - Oracle.
  • postgresql or pg - PostgreSQL.
  • sqlserver or ss - Microsoft SQL Server or Azure SQL Database.
-server:<name>
The name of the server. Use with the -add, -delete, and -update actions.
-type:<dsn-type>
The type of dsn. Use with the -add -dsn:<dsn-name> action/option.
<dsn-type> can be one of the following:
  • datastore
  • database
  • region
  • crossregion
-user:<user-name>
The user name used to connect to the database. Use with the -add -dsn:<dsn-name> and -update -dsn:<dsn-name> actions/options.
@<response-file-name>
Multiple actions, as listed above, can be added to a text file, one command per line. When that response file is run, each line is executed in turn.
For example, the following contents of a response file creates a configuration file (my.cfg) containing the required configuration for a MSSQL database (MYSRV) with one datastore (FILES) and one region database (ESDEMO):
-add -file:my.cfg -server:MYSRV -provider:ss -comment:"SQL Server server"
-add -file:my.cfg -server:MYSRV -dsn:SS.MASTER -type:database -name:master
-add -file:my.cfg -server:MYSRV -dsn:SS.FILES -type:datastore -name:FILES
-add -file:my.cfg -server:MYSRV -dsn:SS.CAS.ESDEMO -type:region -name:ESDEMO

If the file was saved with a name of commands.txt, you would run it using:

dbfhconfig @commands.txt
  • Examples of the dbfhconfig Command Line Utility
  • Database Provider-specific Options
Parent topic: The Database Configuration File
Related concepts
Database Connection Lifetime
Specifying the Cross-region Heartbeat Interval
Related tasks
Configure a Secrets Vault for the Micro Focus Database File Handler


Examples of the dbfhconfig Command Line Utility

Note: For all the following examples, if the name of the configuration file is not specified, the action is performed upon the file specified by the MFDBFH_CONFIG environment variable. If that variable is not set, a file name of MFDBFH.cfg, in the current directory is assumed.

The following command creates a database server instance element for an MSSQL server instance named MYSRV. It creates in the configuration file named MFDBFH.cfg, in the current directory; if the file is not found, a new one is created. It also inserts a comment just prior to the inserted element.

dbfhconfig -add -server:MYSRV -provider:ss -comment:"Local MSSQL Server"

The following command inserts a <dsn> element named SS.VSAM, for the MYSRV instance; the datastore is named VSAM.

dbfhconfig -add -server:MYSRV -dsn:SS.VSAM -type:datastore -name:VSAM

The following command deletes the database server element (and all its child elements) for server MYSRV.

dbfhconfig -delete -server:MYSRV

The following command deletes the <dsn> element named SS.VSAM that is specified for the MYSRV database instance.

dbfhconfig -delete -server:MYSRV -dsn:SS.VSAM

The following command lists an overview the server instances, and the number of <dsn> elements configured for each.

dbfhconfig -list

The following command lists details of the <dsn> elements configured for the server instance MYSRV.

dbfhconfig -list -server:MYSRV

The following command updates the MYSRV database server element with a comment.

dbfhconfig -update -server:MYSRV -comment:"Dev only server"

The following command updates the existing SS.VSAM <dsn> element with I/O optimizations and a comment.

dbfhconfig -update -server:MYSRV -dsn:SS.VSAM -optio:all -comment:"User files"

The following command enables vault facility use for the database credentials within the configuration file. See Configure a Secrets Vault for the Micro Focus Database File Handler for more information.

dbfhconfig -vault

The following command disables vault facility use for the database credentials within the configuration file.

dbfhconfig -novault
Parent topic: The dbfhconfig Command Line Utility
Related tasks
Configure a Secrets Vault for the Micro Focus Database File Handler


Database Provider-specific Options

The following sections detail the database-specific options that can be utilized when using the Micro Focus Database File Handler. These options are set in the database configuration file, by using the dbfhconfig command line utility.

Oracle-specific options

Option | Description | Example config file entry
connpool.max=<n> | Specify the maximum number of connection pool connections that can be opened be when OCI connection pooling is enabled. Default 5. Refer to Session Pooling and Connection Pooling in OCI in your Oracle documentation for more details. | <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" dbname="MYDB" connect="myuser/mypassword@MYDB"userid="myuser" dboptions="connpool.use=true, connpool.max=5, connpool.timeout=30"/>
connpool.timeout=<n> | Specify the time in seconds after which an idle OCI pooled connection is timed out. If this attribute is not set, or set to 0, the connections are never timed out. Default 0. Refer to Session Pooling and Connection Pooling in OCI in your Oracle documentation for more details. | <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" dbname="MYDB" connect="myuser/mypassword@MYDB"userid="myuser" dboptions="connpool.use=true, connpool.max=5, connpool.timeout=30"/>
connpool.use="true|false" | Specify whether OCI connection pooling is to be enabled. If neither OCI connection pooling, nor OCI session pooling is enabled, the default MFDBFH connection caching will be used. Default false. Refer to Session Pooling and Connection Pooling in OCI in your Oracle documentation for more details. | <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" dbname="MYDB" connect="myuser/mypassword@MYDB"userid="myuser" dboptions="connpool.use=true, connpool.max=5, connpool.timeout=30"/>
sesspool.max=<n> | Specifies the maximum number of sessions that can be opened in a session pool when OCI session pooling is enabled. Default 5. Refer to Session Pooling and Connection Pooling in OCI in your Oracle documentation for more details. | <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" dbname="MYDB" connect="myuser/mypassword@MYDB"userid="myuser" dboptions="sesspool.use=true, sesspool.max=15"/>
sesspool.use="true|false" | Specify whether OCI session pooling is to be enabled. If neither OCI connection pooling, nor OCI session pooling is enabled, the default MFDBFH connection caching will be used. Default false. Refer to Session Pooling and Connection Pooling in OCI in your Oracle documentation for more details. | <dsn name="ORA.VSAM" type="datastore" dsname="VSAM" dbname="MYDB" connect="myuser/mypassword@MYDB"userid="myuser" dboptions="sesspool.use=true, sesspool.max=15"/>

Examples

The following examples show how to set some of these options using the dbfhconfig command:

dbfhconfig -add -server:MYSRV -dsn:ORA.DATS -type:datastore -name:VSAM -dbopts:"connpool.timeout=120"
Parent topic: The dbfhconfig Command Line Utility


Configure a Secrets Vault for the Micro Focus Database File Handler

To encrypt sensitive material stored in the database configuration file, enable it to use a secrets vault.

When enabled, the connection strings and passwords usually visible as plain text in the configuration file are encrypted. The excerpt below shows how the information is replaced with a $$vault$$ placeholder; this information is encrypted/decrypted implicitly, when required at run time.

  1. Set the following environment variable to the value of the intended secrets vault:
    MFDBFH_VAULT=<vault-name>
    Note: If you do not set this variable, the vault used defaults to the default vault specified in secrets.cfg - see Vault Facility for more information.
  2. Set the database configuration file to be vault-enabled:
    dbfhconfig -vault -file:<file-name>
When a configuration file is vault-enabled, passwords and connection strings are not visible as plain text.
<datastores usevault="true">
   <server name="localhost:50000" type="db2" access="odbc">
      <dsn name="DB2.VSAM" type="datastore" dsname="VSAM" optio="none +ooseq" dbname="MYMFFILS" connect="$$vault$$"/>
      <dsn name="DB2.ESDEMO" type="region.cas" region="ESDEMO" feature="all" dbname="MYMFFILS" connect="$$vault$$"/>
      <dsn name="DB2.CROSSREGION" type="crossregion.cas" dsname="$XREGN$" dbname="MYMFFILS" connect="$$vault$$"/></server>
</datastores>
Parent topic: The Database Configuration File
Related reference
Vault Facility


Database Connections

Within your database instance, separate databases can be created for each datastore, region database and cross-region database. Alternatively, you can create one single database to house multiple datastores, region databases, and a cross-region database. Using a single database is the preferred method, as this gives additional performance benefits, allowing you to use a single database connection to access the multiple MFDBFH resources.

Regardless of how you configure your databases, you need to choose how to connect to them: either using ODBC data sources (except for Oracle databases), or using a direct connection string. Both of these methods are configured within the database configuration file; see the respective Configure Datastores\Region Cross-regions Databases... sections for each database provider for more details.

The following example is an entry from a configuration file that uses an ODBC data source connection to an MSSQL datastore, where the name value references a data source on your machine:

 <dsn name="SS.SEQ" type="datastore" dsname="SEQ" dbname="SEQ" optio="all -ooseq"/>

The following example is an entry from a configuration file that uses direct connection syntax in order to establish a connection to a Db2 datastore. See Database Connection Strings for the syntax required for each database provider.

<dsn name="DB2.VSAM" type="datastore" dsname="VSAM" optio="none +ooseq" dbname="MYMFFILS" connect="db=MFDATS;uid=db2admin;pwd=adminpw"/>

The name value in this method does not map to a data source - it is simply a unique name within the Db2 configuration that is used by MFDBFH to reference the datastore.

Tip: As the connection strings display sensitive information in plain text format, it is advisable that you encrypt it using a secrets vault; see Configure a Secrets Vault for the Micro Focus Database File Handler for details.
  • Database Connection Strings
    Use direct connection strings in your configuration files, instead of using ODBC DSNs.
  • Using a Single Database
    Use a single physical database in which to store multiple datastores, region databases, and a single cross-region database. This method is optional, but in using it, allows you to use only one database connection for each resource in the database.
  • Sharing Database Connections
    If you are using a single database to house multiple datastores, region databases and a cross-region database, connection sharing is recommended to reduce the load on database server side resources.
  • Database Connection Lifetime
    By default, when MFDBFH establishes a database connection it will keep the connection open for the remainder of the process's execution; however, there are times when this is not desirable. You can configure the database configuration file to override this default behavior, if required.
Parent topic: Configuration Requirements


Database Connection Strings

Use the following syntax when making a direct connection with the different types of supported databases (as opposed to using an ODBC DSN). These strings are used in the database configuration file and in Enterprise Server.

Note: If the connection string contains spaces, you may need to enclose the connection string in quotation marks; for example, -connect:"<connection-string>".

Microsoft SQL Server (including Azure SQL Database)

Syntax:

Driver={ODBC Driver 13 for SQL Server};<connection-options>

or

Driver={Odbc Driver 17 for SQL Server};<connection-options>

Example:

Driver={ODBC Driver 13 for SQL Server};Server=localhost;Database=VSAM;Trusted_Connection=yes

PostgreSQL

Syntax:

Driver={<PostgreSQL-driver-name>};<connection-options>

Example:

Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=VSAM;Uid=mfdbfh;Pwd=MfdbfhAdm!n5;

Db2 (preferred)

Syntax:

db=<database/alias name;>;uid=<user name>;pwd=<password>

Note: This is the preferred format to be used. The Hostname, Port, and Protocol will typically have been cataloged for the node associated with the specified database/alias name.

Example:

db=VSAM;uid=mfdbfh;pwd=MfdbfhAdm!n5

Db2

Syntax:

Driver={IBM DB2 ODBC DRIVER};<connection-options>

Example:

Driver={IBM DB2 ODBC DRIVER};Database=VSAM;Hostname=localhost;Port=50000;Protocol=TCPIP;uid=mfdbfh;pwd=MfdbfhAdm!n5

Oracle

Syntax:

<user name>/<password>@<db-name>

Note: This is Oracle's 'Easy Connect' format. <db-name> refers to the database connection name as defined in the tnsnames.ora configuration file.

Example:

mfdbfh/MfdbfhAdm!n5@DBFHTEST
Parent topic: Database Connections
Related information
Using a Single Database
Sharing Database Connections
Database Connection Lifetime


Using a Single Database

Instead of creating multiple databases for each of your datastores, region databases and cross-region databases, MFDBFH allows you to store multiple datastores, region-databases, and a single cross-region database, in a single physical database. This is facilitated by using unique database schema names to differentiate between the resources. If you view the contents of your databases in your vendor's database management tool, you can see the resources grouped under their own unique schemas:

Resource type | Schema Name Format | Notes
Cross-region | DBRG__XREGN_ | This is a fixed schema name used for cross-regions, meaning that only one cross-region may exist in any given physical database.
Datastore | DBFH_<datastore-name> | For example, if the datastore name is VSAM, its associated schema name will be DBFH_VSAM
Region | DBRG_<region-name> | For example, if the region name is ESDEMO, its associated schema name will be DBRG_ESDEMO

Using a single database is optional, but from a performance point of view, it is advantageous to store related resources all in one place. It also allows connection sharing, which significantly reduces the number of connections required for each process; see Sharing Database Connections.

The alternative to using a single database is that you use individual databases for each resource (datastores, region databases, and cross-region database). For a single operation/transaction, each resource will require separate connections, which is obviously less efficient.
Note: Regardless of the storage method you use, additional connections may also be required for other MFDBFH-related processes.

The database creation instructions within the configuration sections explain how to create the resources using both a single and separate databases.

Parent topic: Database Connections
Related information
Database Connection Strings
Sharing Database Connections
Database Connection Lifetime


Sharing Database Connections

If you have elected to store multiple datastores, region databases, and a cross-region database in a single physical database, you can configure these resources to share one database connection, which can significantly reduce the load on database server side resources, such as session management and memory usage. You can take advantage of this with both the ODBC data source and the connection string methods.

For ODBC connections:

  • Create an ODBC data source for the single physical database.
  • Reference the data source using the dbfhconfig -add/-update -odbcdsn actions/option; for example, you can update existing configurations as such:
    dbfhconfig -update -server:ONEDB_SS -dsn:SS.ONEDS -odbcdsn:ONEDB_SS
Note: Each entry you specify must belong to the same -server group within the configuration file, and each -dsn must be configured to use the same credentials to access the database.

The following example shows an excerpt from an MSSQL database configuration file where two datastores (SS.DATASTORE1 and SS.DATASTORE2), a region database (SS.REGION), and a cross-region (SS.CROSSREGION) all use one database connection (the ONEDB_SS data source).

...
<server name="SERVER_SS" type="sqlserver" access="odbc">
    <dsn name="SS.MASTER" type="database" dbname="master"/>
    <dsn name="SS.CROSSREGION" type="crossregion.cas" dbname="onedb_ss" odbcdsn="ONEDB_SS" />
    <dsn name="SS.REGION" type="region.cas" region="MYREGION" dbname="onedb_ss" odbcdsn="ONEDB_SS" /><dsn name="SS.DATASTORE1" type="datastore" dsname="MYFILES1" dbname="onedb_ss" odbcdsn="ONEDB_SS" />
    <dsn name="SS.DATASTORE2" type="datastore" dsname="MYFILES2" dbname="onedb_ss" odbcdsn="ONEDB_SS" />
  </server>
...

For connection string connections:

Ensure that the connection string specifies the single physical database:
dbfhconfig -update -server:ONEDB_SS -dsn:SS.ONEDS -connect:"Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=onedb_pg;Uid=myuser;Pwd=mypass;"
Note: Each entry you specify must belong to the same -server group within the configuration file, and each connection string must be configured to use the same credentials to access the database, effectively reusing the same connection string for each required entry within the -server group.

The following example shows an excerpt from a PostgreSQL database configuration file where the datastores (PG.DATASTORE1 and PG.DATASTORE2), a region database (PG.REGION), and a cross-region (PG.CROSSREGION) all use one database connection, as evidenced by the same connection string for each entry.

...
<server name="SERVER_PG" type="postgresql" access="odbc">
    <dsn name="PG.POSTGRES" type="database" dbname="postgres" connect="Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=postgres;Uid=myuser;Pwd=mypass;" />
<dsn name="PG.CROSSREGION" type="crossregion.cas" dbname="onedb_pg" connect="Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=onedb_pg;Uid=myuser;Pwd=mypass;" />
    <dsn name="PG.REGION" type="region.cas" region="MYREGION" dbname="onedb_pg" connect="Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=onedb_pg;Uid=myuser;Pwd=mypass;" /><dsn name="PG.DATASTORE1" type="datastore" dsname="MYFILES1" dbname="onedb_pg" connect="Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=onedb_pg;Uid=myuser;Pwd=mypass;" />
    <dsn name="PG.DATASTORE2" type="datastore" dsname="MYFILES2" dbname="onedb_pg" connect="Driver={PostgreSQL ANSI};Server=localhost;Port=5432;Database=onedb_pg;Uid=myuser;Pwd=mypass;" />
  </server>
...
Parent topic: Database Connections
Related information
Database Connection Strings
Using a Single Database
Database Connection Lifetime


Database Connection Lifetime

By default, when MFDBFH establishes a database connection it will keep the connection open for the remainder of the process's execution. This is done to avoid the unnecessary performance overhead of establishing and disconnecting database connections. However, there may be times when the lifetime of database connections needs to be restricted. For example:

  • The SQL Server master, and PostgreSQL postgres database connections are only required when determining whether a database exists, or when creating a new database. These operations are generally performed the very first time that a cross-region, region, or datastore needs to be accessed by a process, but after that are not required.
  • A database server, such as PostgreSQL, may not efficiently handle more than a few hundred active connections at any one time. In such circumstances, it would be preferable to only establish database connections when they are actually needed, and then disconnect them once the associated database operations are complete (for example, the lifetime of a batch job).
  • When optimised I/O is enabled, MFDBFH will perform I/O operations for a file on a background thread. A separate database connection to the one used for database operations on the main execution thread will be used. Once the file is closed, the background thread is stopped, and the database connection is returned to an internal cache for later re-use. By default, MFDBFH will cache up to 10 connections. Instead of caching the connection, it may be preferable to close the connection instead to avoid unnecessary database server resources being tied up for a connection that may never get re-used.

Use the dbfhconfig -connopts command line utility to update the database configuration file to override the default behavior. The following table shows the entries that each option creates and an explanation of the altered behavior:

Attribute | Description | Example
connection.close.heartbeat="true|false" | Specify whether or not a CAS process's heartbeat thread should return the cross-region database connection to the connection cache, or disconnect it after each heartbeat (every 5 seconds). Whether it is cached or disconnected is determined by the size of the connection cache that has been configured. When the connection has been disconnected, it will be re-connected the next time an operation on the database is required. Default 'false'. | <dsn name="SS.MYFILES" type="datastore" dsname="MYFILES" connection.close.heartbeat="false"/>
connection.close.syncpoint="true|false" | Specify whether or not the database connection should be returned to the connection cache, or disconnected after each CAS syncpoint. Whether it is cached or disconnected is determined by the size of the connection cache that has been configured. When the connection has been disconnected, it will be re-connected the next time an operation on the database is required. Default 'false'. | <dsn name="SS.MYFILES" type="datastore" dsname="MYFILES" connection.close.syncpoint="false"/>
connection.close.task="true|false" | Specify whether or not the database connection should be returned to the connection cache, or disconnected at the end of each CAS task (e.g. CICS transaction, or batch job). Whether it is cached or disconnected is determined by the size of the connection cache that has been configured. When the connection has been disconnected, it will be re-connected the next time an operation on the database is required. Default 'false'. | <dsn name="SS.MYFILES" type="datastore" dsname="MYFILES" connection.close.task="false"/>
connection.max.cached=<n/> | Specify the maximum number of connections that MFDBFH will keep in its connection cache for later reuse. Setting the value to 0 will ensure that no connections are cached and get immediately disconnected once they are no longer required. Default 10. | <dsn name="SS.MYFILES" type="datastore" dsname="MYFILES" connection.max.cached=0/>
connection.max.dbopts=<n/> | Specify the maximum number of database operations that MFDBFH is allowed to perform on the connection before the connection is returned to the connection cache or disconnected. Default INT_MAX (2147483647). | <dsn name="SS.MYFILES" type="datastore" dsname="MYFILES" connection.max.dbopts=5000/>
Note: You can also apply these connection options at a program/process level, meaning different programs/processes for a single connection can have different connection behavior. Use the dbfhconfig -program:<prog-name> option to configure this; see The dbfhconfig Command Line Utility for more details.[1]

Example

Multiple attributes can be configured for a single <dsn> entry; for example, to ensure that the connection to a SQL Server master database is disconnected after checking for the existence of a database, or when creating a new database, the following connection lifetime attributes should be specified:

<dsn name="SS.MASTER" type="database" dbname="master" connection.max.cached=0 connection.max.dbopts=0/>
  • Specifying the Cross-region Heartbeat Interval
Parent topic: Database Connections
Related reference
The dbfhconfig Command Line Utility
Related information
Database Connection Strings
Using a Single Database
Sharing Database Connections


Specifying the Cross-region Heartbeat Interval

When running under Enterprise Server, MFDBFH creates a process record in the cross-region database for each Enterprise Server process that accesses the region and/or cross-region database. This process record has a heartbeat field which, by default, is updated every 5 seconds while the associated Enterprise Server process is active. The heartbeat is used by MFDBFH to determine whether recovery processing is required if the Enterprise Server process is killed or abnormally terminated. MFDBFH deems that recovery processing is required if the process's heartbeat has not been updated within the heartbeat interval plus 5 seconds (that is, with a default heartbeat interval of 5 seconds, recovery processing is deemed to be required if the heartbeat has not been updated after 10 seconds).

The heartbeat interval of a cross-region database can be configured using the heartbeat option of the dbfhconfig command line utility. Changing the default heartbeat interval of 5 seconds should be done with caution, as specifying too large an interval may cause unwanted delays to region recovery. For example, if a heartbeat interval of 60 seconds is configured, a process will only be deemed to require recovery processing after at least 65 seconds has elapsed since the last heartbeat.
Note: A warning message is output to the Enterprise Server console if a heartbeat interval of greater than 15 seconds is configured.
Parent topic: Database Connection Lifetime
Related reference
The dbfhconfig Command Line Utility


Datastore Management

Use dbfhdeploy to create new datastores, and then deploy any of the following file types to it: KSDS, RRDS, ESDS, line-sequential, and fixed- and variable-length sequential files.

For existing datastores, you can also use the command line utility to list, delete, and extract files within it.

The command must be run from an Enterprise Developer command prompt that matches the bitism of the data source that you are interacting with. The MFDBFH_CONFIG environment variable must also point to a valid configuration file that contains an entry for the data source; alternatively, the dbfhdeploy command must include a valid -configfile option.

  • The dbfhdeploy Command Line Utility
    Use the dbfhdeploy command line utility to deploy files to your datastore databases.
  • The Datastore URL
    To access data files held in a datastore, you must use a specific URL syntax.
Parent topic: Database File Handling and Enterprise Server Region Database Management


The dbfhdeploy Command Line Utility

Use the dbfhdeploy command line utility to deploy files to your datastore databases.

Syntax:

dbfhdeploy [Options][Category] ActionParameters

Or:

dbfhdeploy @<response-file-name> [-verbose]
Options
Refer to the running of the command as a whole:
  • -configfile:<name> - the path and file name of the database configuration file. This is optional if the MFDBFH_CONFIG environment variable is already in effect, but if set, will override the value of the MFDBFH_CONFIG.
  • -opt - turns on file I/O optimization when deploying files. This option is on by default.
  • -noopt - turns off file I/O optimization when deploying files.
  • -nobanner - display minimal output.
  • -urlhelp - display information about the URL syntax.
  • -verbose - displays additional information, such as the database configuration file and script folder locations in effect, and the deployment time for the current operation.
Category
Defines the item to be acted upon. Valid values are:
data
The item to be acted on is a data file.
For an add, delete, or extract action, the URL must be of the form: sql://server-name/datastore/filename[?folder=/path]

For a create or list operation, the URL must be of the form: sql://server-name/datastore[?folder=/path]

See The Datastore URL for full details of the required URL syntax.

ActionParameters
Action to perform and the data store to perform it on. Valid values are:
add path URL;attribs
Add data file specified in path to the datastore specified in URL.
Some file types require additional attributes, which can be:
type=seq|lseq|rrds|blob
The type of file (other than a VSAM file) that is being added.
reclen=min,max
The minimum and maximum length of each record within the file.
recterm=windows|linux|unix
The type of record terminator used in the file. This is used primarily for RRDS files, and is only required for files that have been created on a different platform to the one on which it is currently being deployed.
For example, the following command adds the sequential file file.dat to the USRA folder, in the NEWDEMO datastore in svr-mydb, where it is referred to as mydat and has a (minimum and maximum) record length of 80:
dbfhdeploy data add file.dat sql://svr-mydb/NEWDEMO/mydat?folder=/USRA;type=seq;reclen=80,80
create URL
Create a datastore in the specified URL.
For example, the following command creates the NEWDEMO datastore in the svr-mydb instance:
dbfhdeploy data create sql://svr-mydb/NEWDEMO -configfile:C:\dbconfig\mfdbfh.cfg
Warning: When dealing with Oracle, the physical database you are connecting to must already exist before the datastore can be created.
delete URL
Delete data files from datastore specified in URL.
For example, the following command deletes the mydat data file stored in the USRA folder, in the NEWDEMO datastore:
dbfhdeploy delete sql://svr-mydb/NEWDEMO/mydat?folder=/USRA
You can also delete multiple files/folders using one of the following:
  • The following command delete all files and sub-folders under the MyTests folder:
    dbfhdeploy delete sql://svr-mydb:50000/VSAM?type=folder;folder=/MyTests
  • The following command deletes all files and folders within the VSAM data store:
    dbfhdeploy delete sql://localhost:50000/VSAM?type=folder;folder=/
  • The following command deletes all files within the MyTests folder that start with 'a' or 'A':
    dbfhdeploy delete sql://localhost:50000/VSAM/a*?folder=/MyTests
Tip: Specifying the -verbose option with any of these commands displays the files and folders that are deleted.
extract URL path
Extracts a copy of the data file specified in URL to the path specified by path.
For example, the following command extracts a copy of mydat from the USRA folder of the NEWDEMO datastore, and saves it as my-extract.dat:
dbfhdeploy data extract sql://svr-mydb/NEWDEMO/mydat?folder=/USRA my-extract.dat
keys <key-options>
Perform operations on keys within an indexed file. See Key Options below.
list URL
Lists data files that are located in the specified URL.
For example, the following command lists all the data files and sub-folders stored in the VSAM folder of the ESDEMO datastore:
dbfhdeploy data list sql://svr-mydb/ESDEMO?folder=/VSAM
upgrade URL
Note: Only use this option when instructed to by a representative of OpenText Support for Micro Focus Products.
Upgrades the stored procedures associated with the data file specified in URL.
For example, the following command upgrades any stored procedures associated with the mydat2 data file stored in the USRB folder of the NEWDEMO datastore:
dbfhdeploy upgrade sql://svr-mydb/NEWDEMO/mydat2?folder=/USRB
Key Options:
list
This example lists all the keys (primary and alternate) that are defined for the my.dat file in the ESDEMO datastore:
dbfhdeploy keys list sql://svr-mydb/ESDEMO/my.dat
The result may be something like this, showing two keys - one that allows duplicates, and one that doesn't:
Key  Start  Length  Dupl  Dupl #
---  -----  ------  ----  ------
0    1      3       N     0
1    5      3       Y     0
<key-id>:<key-op>
Perform an operation on a specific key where <key-id> is the key number indicated in the keys list (see list URL action above). <key-op> is one of the following:
  • dup=n|no|false - change key to disallow duplicates. (No duplicate key values must exist before you can change to this setting.)
  • dup=y|yes|true - change key to allow duplicates.
For example: the following command disallows duplicate key values for key #1 in the key list for my.dat.
dbfhdeploy keys 1:dup=no sql://host/datastore/my.dat
@<response-file-name>
Multiple ActionParameters, as listed above, can be added to a text file, one command per line. When that response file is run, each line is executed in turn.
For example, the following contents of a response file adds two files to a datastore, and then extracts one of them to a local directory:
add my.dat sql://MYSRV/FILES/my.dat
add file.dat sql://MYSRV/FILES/file.dat?folder=/MyDir
extract sql://MYSRV/FILES/my.dat c:\MyDir\my.dat

If the file was saved with a name of commands.txt, you would run it using:

dbfhdeploy @commands.txt
Parent topic: Datastore Management
Related information
The Datastore URL
TXFILEP


The Datastore URL

There are a number of utilities and library routines that allow you to interact with data files and folders hosted in a database. In order to reference those files and folders within a datastore, you need to use a specific URL, as described below:

sql://<server-name>/<datastore-name>/<file-name>[?<file-attributes>]     *> file url
sql://<server-name>/<datastore-name>?type=folder;[folder=/<folder-name>] *> folder url

where:

server-name
The name of the server entry in the database configuration file. When "(local)" or "localhost" is specified as the server name, it is replaced at run time by the name of the machine running the process using it.
datastore-name
The name of the datastore.
file-name
The name of the data file.
file-attributes
Attributes for the data file, such as its type and its location in the datastore:
Attribute Values Example Description
type
  • blob
  • folder
  • lseq
  • rrds
  • seq
  • type=blob
  • type=folder
  • type=lseq
  • type=rrds
  • type=seq
File type. This only needs to be specified when deploying files into the database that do not have file headers
reclen <min[,max]>
  • type=lseq;reclen=0,80
  • type=seq;reclen=0,80
  • type=rrds;reclen=80
  • type=seq;reclen=80
Minimum and maximum max record lengths of variable-length sequential files, or the record length of fixed-length sequential or RRDS files. This only needs to be specified when deploying files into the database that do not have file headers
recterm
  • windows
  • linux
  • unix
  • recterm=windows
  • recterm=linux
  • recterm=unix
The type of record terminator the file has. Used primarily for RRDS files, and only required for files that have been created on a platform different to the one on which it is currently being deployed
folder <folder-name>
  • folder=/MyFolder
  • folder=/MyFolder/SubFolder
Folder name. If a folder name is not explicitly specified, the root folder is assumed (i.e. folder=/)
Note: On the command line, you can also run dbfhdeploy.exe -urlhelp to view syntax help.
MSSQL users: If your database instance is configured with a case-sensitive collating sequence, you must specify the files and folders in the dbfhdeploy command accordingly.

Using environment variables in the URL

You can use environment variables within the SQL URL, which can be specified in one of two formats:

  • $name - where the variable name is terminated by the next punctuation character or by the end of string.

    For example: sql://$MYSERVER/$MYDATASTORE/myfile.dat

  • ${name} - where the variable name is enclosed in the brackets.

    For example: sql://${MYSERVER}/${MYDATASTORE}/myfile.dat

Restriction: The second format is not supported if you are specifying SQL URLs within an Enterprise Server environment, for example, when defining the JES catalog location or file allocation folder.

Examples

  • The following example references a file (my.dat) held in the JCLTEST datastore housed in a database instance on the swt-bto host:
    sql://swt-bto/JCLTEST/my.dat
  • The following example references another file (another.dat) held in the MyData folder in the datastore indicated by the JCLDATASTORE environment variable:
    sql://swt-bto/$JCLDATASTORE/another.dat?folder=/MyData
  • The following example references a sequential file (newseq.dat) held in the MySeqData folder in the SEQDATA datastore located in the database instance held on the machine indicated by the ${MYSVR} environment variable:
    sql://${MYSVR}/SEQDATA/newseq.dat?folder=/MySeqData;type=seq;reclen=0,80
Parent topic: Datastore Management
Related information
The dbfhdeploy Command Line Utility


Database Management and Recovery

Use the dbfhadmin command-line tool to recover resources from region, cross-region, and datastore databases in the event of a system failure.

If an enterprise server process terminates abnormally, database resources used by the process (for example, open file handles, resource locks, and record locks) may not get freed up correctly.

In the case of region and cross-region databases, use the -list option with the -casprocess action to display all processes currently registered in a CAS cross-region database. Any processes displayed with an "In doubt" status need to be recovered. Processes get registered when an enterprise server process (for example: casmgr and cassi) initialise use of a region database. Processes get de-registered when an enterprise server process terminates normally. If a process is killed, or abnormally terminates, its associated process record in the cross-region database does not get removed. When the processes are listed, all active ones (i.e. registered, but not yet terminated) have an "Ok" status, whereas any process that has been killed, or abnormally terminated, will have an "In doubt" status. Any process with an "In doubt" status could potentially still be owning region database resources.

Use the -list option with the -region action to display a list of resource locks for a specified region or entire database server instance. If any files are erroneously locked (that is, not recovered correctly after a system failure), you can free them using the -recover action.

For database-hosted data files, use the -list action to display any data files still open. After ensuring that the host machine or (if specifying a process id) the process is no longer running, use the -recover option on any files that are still open. When files are forced closed, their file handles are removed from the datastore database and any associated record locks released.

You can also use the dbfhadmin command-line tool to manage the column types that correspond to the primary and alternate keys of your indexed files. This management is required when creating indexed data files independently of COBOL programs (for example, when using the CFCR CICS transaction or using the JCL MFJAMS utility), as there is no mechanism to generate the key type definitions, and so when those files are created in the datastore, each column type is binary. The -keytypes action of dbfhadmin enables you to inject different key types for a file's indexed keys. You will also need to use dbfhadmin to define key type definition if your indexed files were created via COBOL programs that were not compiled with the IXNUMKEY Compiler directive.
Upgrading datastores: Periodically, MFDBFH may need to upgrade an existing datastore to fix a problem, or provide the necessary support for new functionality. In most circumstances, the upgrade occurs automatically when a new version of MFDBFH detects that the datastore that it is running with does not support the latest level of functionality. However, it is possible that the upgrade process may fail if the currently connected user does not have sufficient database privileges to perform the operation. When this happens, MFDBFH outputs the following message to the console, indicating that a manual upgrade is required:

DBFH00034S MFDBFH failed to upgrade the datastore. Manual upgrade required. Use 'dbfhadmin -upgrade -datastore <datastore-url>' to generate an upgrade script and run the script as a user with sysadmin privileges

  • The dbfhadmin Command Line Utility
    Use the dbfhadmin command line utility to administer datastores and cross-region databases, enabling you to recover resources in the event of an abnormal termination of the database.
Parent topic: Database File Handling and Enterprise Server Region Database Management


The dbfhadmin Command Line Utility

Use the dbfhadmin command-line tool to recover resources from region, cross-region, and datastore databases in the event of a system failure. You can also use it to ensure that the database column used for primary and alternate indexed keys are set to the correct SQL type.

Note: You must run the command from an environment where the MFDBFH_CONFIG variable points to a configuration file that contains data source entries for the databases to be administered.

Syntax:

dbfhadmin [action][options]
Actions
Refer to the running of the command as a whole:
  • -casprocess - list or recover resources in CAS processes.
  • -createdb - create a database.
    Warning: This option is not supported for the creation of Oracle databases.
  • -diags - generate a diagnostics file containing details of the region and cross-region databases, the database configuration file contents, and the table contents of the cross-region database and region databases.
  • -keytypes - list, add, delete, import, or export key type metadata.
  • -openfiles - list files or close open files in a datastore.
  • -region - list or recover region resources. You may be required to free locked resources using this method if the automated recovery process has been unable to - console log error messages may indicate when this has been the case.
  • -script - generate an SQL script for creating databases.
  • -upgrade - generate an SQL script for upgrading datastores. Datastores are automatically updated from time to time (for example, when structural changes are required). Sometimes, these automatic updates fail (usually as the result of insufficient database permissions), and therefore must be rerun manually. This option generates the script file required to run the manual update. Once you have the required file, you should run it with sysadmin privileges, using the command-line tool appropriate for your database type.
  • -verify - list or recover the integrity of a datastore/region and cross-region database.
Options
Defines the options for the specified action. Valid values are:
-add
Specifies that keytype metadata is added or updated for a particular datastore. Use with the -keytypes action.
-collation:<id>
The collation type used when creating a Db2 database. The default is SYSTEM_1252_US for Windows, and SYSTEM_923_US for UNIX/Linux. Use with the -script -provider:db2 action/option.
-configfile:<name>
The path and file name of the database configuration file. This is optional if the MFDBFH_CONFIG environment variable is already in effect, but if set, will override the value of the MFDBFH_CONFIG.
-datastore:<url>
The URL of the datastore from which you want to list or recover files from. Use with the -openfiles, -upgrade, and the -keytypes -import/-export action/options.
-db:<dbname>
Name of database to be created or used. Use with the -script -provider:db2|pg|ss action/option.
-delete
Specifies that keytype metadata is deleted for a particular datastore. Use with the -keytypes action.
-ebcdic
Creates a database with EBCDIC support. Use with the -createdb -provider:db2 action/option.
-existdb:<db-name>
Name of an existing physical database into which a datastore, region, or cross-region database is to be created. Use with the -script -provider:db2|pg|ss and the -createdb -provider:ora -script action/options.
Note: For Oracle databases, this option is mandatory, as MFDBFH will not create the specified database if its underlying physical database does not already exist.
-export:<file-name>
Specifies a file with which to export the keytype metadata for a particular datastore. Use with the -keytypes -datastore action/option.
-file:<url>
Specifies the datastore data file that you want to add keytype metadata to, or remove keytype metadata from. Use with the -keytypes -add/-delete action/options.
-file:<file-name>
Specifies the input file name for database creation, or the output file name for generated scripts or region diagnostics. Use with the -createdb action for input files, the -script or -upgrade actions for generated script files, or -diags -usedb:<instance> -name:<object-name> action/options for diagnostics files .
-force
Forces closed an open file reguardless of its status. Use with the -openfiles -recover -pid action/options.
-hex
Displays the name of the specified region in hexadecimal. Use with the -region -list -usedb:<dbname> -name:<region-name> action/options.
-host:<name>
The host name targeted for process recovery, for forced file closure, or for PostgreSQL database creation. Use with the -casprocess -list/-recover, -openfiles -list/-recover, or -createdb -provider:pg actions/options.
-import:<file-name>
Specifies the file containing keytype metadata that is to be imported. Use with the -keytypes -datastore action/option.
The following example shows the required format for the import file, where file1.dat, located at the root of the datastore, has an alphanumeric primary key and a signed COMP-X first alternate key; file2.dat, located in the PAY1 sub-folder, has an alphanumeric primary key and first alternate key, and an unsigned COM-X second alternate key:
<?xml version="1.0" encoding="us-ascii" standalone="no"?>
<keytypes_definitions>
    <keytypes_definition filename="file1.dat" folder="/" types="AN,SCOMPX"/>
    <keytypes_definition filename="file2.dat" folder="/PAY1" types="AN,AN,UCOMPX"/>
</keytypes_definitions>
-list
Lists the results of the specified actions, for the specified database: -casprocess -list shows the active processes, -region -list -usedb:<dbname> shows region resource locks for a particular database, -openfiles -list -usedb:<dbname> shows the files currently open, or -verify -list -usedb:<dbname> shows the integrity of a datastore\region and cross-region database.
-name:<object-name>
The name of the datastore or region database script to be created, or region resource to be recovered. Use with the -script -type:datastore and -script -type:region actions/options, and the -region -list/recover action/options.
-nobanner
Synonym for -quiet
-password:<pwd>
The password used to connect to a database. Use with the -createdb -provider:pg|ss action/options.
-pid:<process-id>
The process ID applicable to the specified action. Use with the -casprocess -recover or -openfiles -recover actions/options.
-port:<number>
The port number required for PostgreSQL database creation. You are required to specify this when the database is using a non-default port number or is on a remote server. Use with the -createdb -provider:pg action/option.
-provider:<db-type>
The name of database provider for which the script is to be generated (-script), or database creation (-createdb). <db-type> can be one of:
db-type | Description
db2 | Db2
ora | Oracle
oracle | Oracle
postgresql | PostgreSQL
pg | PostgreSQL
sqlserver | Microsoft SQL Server and Azure SQL database
ss | Microsoft SQL Server and Azure SQL database
-recover
Recovers the resources owned by a CAS process, closes open datastore files with a status of Inactive or In doubt (as indicated by -openfiles -list), or repairs datastores\region and cross-region databases containing integrity issues. Use with the -casprocess, -region, -openfiles or -verify actions/options.
-regionid:<id>
Specifies a particular region within a PAC to recover - <id> is a PAC UUID, which you can locate by running dbfhadmin -casprocess -list. Use with the -casprocess -recover action/option.
-replace
Replaces keytype metadata that already exists for files. Use with the -keytypes, -add, or -import actions/options.
-reset
Reset the status of a region database. Use with the -region -status action/option.
-status
List or reset the status of a region database. Use with the -region action.
-type:<script-type>
Specifies the type of database creation script, which can be one of: crossregion, datastore, datastore_funcs, or region. Use with the -script and (with the exception of datastore_funcs) the -createdb actions.
datastore_funcs is used for the creation of script files used to install external functions into a database; see Installing Database Server Functions.
-types:<key-types>
Defines the column types for a file's primary and alternate keys. Specify the key types as a comma-delimited list, using the following types:
Type | Description
AN | Alphanumeric
BIN | Binary
SCOMPX | Signed COMP-X
UCOMPX | Unsigned COMP-X
Use with the -keytypes -add/-replace/-import/-export/-list action/options.
-usedb:<instance>
Use the specified database server instance. Use with the -casprocess -list/-recover, -createdb -provider:ss, -openfiles -list/-recover, or the -openfiles -list/-recover actions/options.
-user:<user-name>
The user name used to connect to a database. Use with the -createdb -provider:pg|ss action/options.
-verbose
Displays additional information, such as the database configuration file and script folder locations in effect, for the current operation.
  • Examples of the dbfhadmin Command Line Utility
Parent topic: Database Management and Recovery
Related reference
Configuring CICS Applications for Native Database File Handling
Configuring the JCL Environment for Native Database File Handling
Method 2 - Proxy users


Examples of the dbfhadmin Command Line Utility

CAS processes

Use the following commands to view the enterprise server processes that may be in error after an abnormal termination, and to recover such processes.

  • The following command lists the CAS processes still running for the svr-mydb database server instance:
    dbfhadmin -casprocess -list -usedb:svr-mydb

    The command will return a table, similar to that below, containing the name, host name, process ID, region name, last heartbeat time, and status for each enterprise server process:

    Status  Host      Region    Region Id  H/B (s)  Name    PID    TID
------  ----      ------    ---------  -------  ----    ---    ---
Ok      svr-mydb  ESDEMODB  ESDEMODB   0        cassi   1780   812
Ok      svr-mydb  ESDEMODB  ESDEMODB   0        cassi   9140   28524
Ok      svr-mydb  ESDEMODB  ESDEMODB   1        casmgr  10204  19392
Ok      svr-mydb  ESDEMODB  ESDEMODB   0        cassi   19324  28792
Ok      svr-mydb  ESDEMODB  ESDEMODB   2        castsc  19840  29036
Ok      svr-mydb  ESDEMODB  ESDEMODB   1        cassi   26048  26300

    If a process has died, or has lost connectivity to the cross-region database for at least 10 seconds, the status indicates 'in doubt'. When 'in doubt', there could be associated resource locks (ENQs) outstanding.

  • The following command lists the CAS processes still running for the svr-mydb database server instance, on the host MYHOST:
    dbfhadmin -casprocess -list -usedb:svr-mydb -host:MYHOST
    Warning: Using the following commands to force DEQ'ing of resource locks should be used with caution. You need to ensure that the associated ES regions have actually stopped (and if they haven't, whether the process is still running; although, this is unlikely as ES recovery processing should have detected this), or that the cross-region database connection has been lost. The ENQs that get removed by this command will be those that are explicitly associated with the given process.
  • The following command recovers the CAS process (DEQs all ENQs) for process ID 12345, for the svr-mydb database server instance on svr-01:
    dbfhadmin -casprocess -recover -usedb:svr-mydb -host:svr-01 -pid:12345 -configfile:C:\dbconfig\mfdbfh.cfg
    Note: Before the recovery process, the validity of the region/cross-region database is checked. If the check finds orphaned records, the recovery process is halted, and you are prompted to run the dbfhadmin -verify command to restore database integrity before continuing.
  • The following command recovers all CAS processes for the svr-mydb database server instance on svr-01:
    dbfhadmin -casprocess -recover -usedb:svr-mydb -host:svr-01
    Note: Before the recovery process, the validity of the region/cross-region database is checked. If the check finds orphaned records, the recovery process is halted, and you are prompted to run the dbfhadmin -verify command to restore database integrity before continuing.

Database creation

Use the following commands to create databases from a script file. Running these commands ahead of time ensures processing is not delayed when access is required and the databases are yet to be created.

  • The following command creates an ANSI-encoded MSSQL datastore database by running the mydb.sql script file:
    dbfhadmin -createdb -file:mydb.sql -type:datastore -provider:ss
  • The following command creates an EBCDIC-encoded Db2 datastore database by running the mydb.sql script file:
    dbfhadmin -createdb -file:mydb.sql -type:datastore -provider:db2 -ebcdic
  • The following command creates an Oracle region database in the existing MYORADB database, by running the myregdb.sql script file:
    dbfhadmin -createdb -file:myregdb.sql -type:region -provider:ora -existdb:MYORADB
    Note: Micro Focus recommends that the value for -existdb corresponds to the connection name as specified in your tnsnnames.ora configuration file.
  • The following command creates a PostgreSQL datastore database, on the MYREMOTEHOST server/port, by running the mypgdb.sql script file:
    dbfhadmin -createdb -file:mypgdb.sql -type:datastore -provider:pg -host:MYREMOTEHOST -port:33445

Data files

Use the following commands to view data files still open after an abnormal termination of an enterprise server, and to recover/release them. Also, there are a number of commands to administer the column types of indexed keys.

  • The following command lists the data files still open for the VSAM datastore hosted on svr-mydb. For each file, there could be associated outstanding record locks:

    dbfhadmin -openfiles -list -datastore:sql://svr-mydb/VSAM -host:svr-01

    The command will return a table, similar to that below, containing the status, host name, file and folder name, and process ID:

    Status    Host        Name         Folder   PID
------    ----        ----         ------   ---
Inactive  svr-mydb    catalog.dat  /ESDEMO  27180
Inactive  svr-mydb    SPLDSN.dat   /ESDEMO  27180
Inactive  svr-mydb    SPLJOB.dat   /ESDEMO  34132
Inactive  svr-mydb    SPLMSG.dat   /ESDEMO  27180
In doubt  svr-brs     catalog.dat  /ESDEMO  20300
In doubt  svr-brs     SPLDSN.dat   /ESDEMO  20300
In doubt  svr-brs     SPLJOB.dat   /ESDEMO  20300
In doubt  svr-brs     SPLMSG.dat   /ESDEMO  20300
Ok        svr-sdn     catalog.dat  /ESDEMO  34144
Ok        svr-sdn     SPLDSN.dat   /ESDEMO  34144
    Warning: Caution should be exercised with the following two commands as files are forced closed. You should ensure that the process(es) on the associated host are no longer running before deciding to close files associated with them - refer to the Status column displayed as the result of the previous command:
    • OK: the file is open within an active process.
    • Inactive: the file had been opened by a process on the same machine as the one running dbfhadmin, but is no longer running.
    • In doubt: the file has been opened by a process on a remote machine. You should check these manually before deciding on a course of action.
  • The following command recovers the data files with an Inactive or In doubt status, by closing them and then removing any associated record locks for all processes, for the VSAM datastore hosted on svr-mydb:
    dbfhadmin -openfiles -recover -datastore:sql://svr-mydb/VSAM -host:svr-01

    Files with an Ok status are left untouched - to also close files with an Ok status, include the -force option.

  • The following command is similar to that above but removes any associated record locks for the specified process (27180), for the VSAM datastore hosted on svr-mydb:
    dbfhadmin -openfiles -recover -datastore:sql://svr-mydb/VSAM -host:svr-01 -pid 27180
  • The following command specifies that the column type for the primary key of the MYFILE.dat file is alphanumeric, and the column type for the first alternate key is signed COMP-X:
    dbfhadmin -keytypes -add -file:sql://svr-mydb/VSAM/MYFILE.dat -types:AN,SCOMPX
  • The following command replaces existing key types for the specified data file:
    dbfhadmin -keytypes -add -replace -file:sql://svr-mydb/VSAM/MYFILE.dat -types:AN,SCOMPX
  • The following command deletes the key types that have been specified for MYFILE.dat, and the column types for indexed keys revert to type BINARY:
    dbfhadmin -keytypes -delete -file:sql://svr-mydb/VSAM/MYFILE.dat

  • The following command exports the list of key types for the VSAM datastore to the MYKEYTYPES.xml file:

    dbfhadmin -keytypes -export:MYKEYTYPES.xml -datastore:sql://svr-mydb/VSAM
  • The following command imports a list of key types to the VSAM datastore from the MYKEYTYPES.xml file:
    dbfhadmin -keytypes -import:MYKEYTYPES.xml -datastore:sql://svr-mydb/VSAM
  • The following command imports a list of key types to the VSAM datastore from the MYKEYTYPES.xml file, replacing any existing types that correspond to the ones in the file:
    dbfhadmin -keytypes -import:MYKEYTYPES.xml -datastore:sql://svr-mydb/VSAM -replace
  • The following command lists the key types set for each data file in the datastore:
    dbfhadmin -keytypes -list -datastore:sql://svr-mydb/VSAM

Script file creation

Use the following commands to create script files that can be used to create databases.

  • The following command creates a script file (createdb.sql) that can be run to create a Db2 cross-region database:
    dbfhadmin -script -type:crossregion -provider:db2 -file:createdb.sql
  • The following command creates a script file (createdb.sql) that can be run to create a Db2 cross-region database using the SYSTEM_1252_US Windows collating sequence:
    dbfhadmin -script -type:crossregion -provider:db2 -file:createdb.sql -collate:SYSTEM_1252_US
  • The following command creates a script file (createdb.sql) that can be run to create a PostgreSQL datastore called MYFILES:
    dbfhadmin -script -type:datastore -name:MYFILES -provider:pg -file:createdb.sql
  • The following command creates a script file (createdb.sql) that can be run to create an MSSQL region database called ESDEMO:
    dbfhadmin -script -type:region -name:ESDEMO -provider:ss -file:createdb.sql
  • The following command creates a script file (createinmydb.sql) that can be run to create a Db2 datastore called mySEQ, which will be stored in the existing Db2 database called masterSEQDB:
    dbfhadmin -script -type:datastore -name:mySEQ -provider:db2 -file:createinmydb.sql -existdb:masterSEQDB
  • The following command creates a script file (create_datastore_MYFILES_ora.sql) that can be run to create an Oracle datastore called MYFILES, which will be stored in an existing Oracle database - the existing database is specified (using the -existdb option) when running the -createdb action on the script file once it is created:
    dbfhadmin -script -type:datastore -name:MYFILES -provider:ora

Resource recovery

Use the following commands if you are receiving console log error messages that indicate resources are not available during startup. There is an automated recovery process that, in the event of a system failure, attempts to recover resources, but if not all were able to, you may be able to free them using these commands.

  • The following command lists each region associated with the DBHOST database server instance, the number of ENQs associated with processes and the number of ENQs that are associated with the region (that is, those which do not have process affinity).:
    dbfhadmin -region -list -usedb:DBHOST
  • The following command lists any region resources that are locked for the ESDEMO region, on the DBHOST database server instance:
    dbfhadmin -region -list -usedb:DBHOST -name:ESDEMO
  • Following on from the previous example, this command additionally displays the region name in hexadecimal:
    dbfhadmin -region -list -usedb:DBHOST -name:ESDEMO -hex
  • The following command releases the locks (that is, forces DEQ of those locks that do not have process affinity) for the ESDEMO region, on the DBHOST database server instance. Only run this command when the region is no longer running. :
    dbfhadmin -region -recover -usedb:DBHOST -name:ESDEMO

    To release locks that do have process affinity, use the -cassprocess -recover option above.

    Warning: Caution should be exercised with the next command. Only reset if, for example, you started an enterprise server region, but it failed because the region database was in use and you were absolutely certain that was not the case. To check, ensure that the process/program/host that was reported has having started the region was not actually running.
  • The following command displays the status of the ESDEMO region database, on the DBHOST database server instance:
    dbfhadmin -region -status -usedb:DBHOST -name:ESDEMO
  • The following command resets the status of the ESDEMO region database, on the DBHOST database server instance to "stopped"
    dbfhadmin -region -status -reset -usedb:DBHOST -name:ESDEMO

Upgrading datastores

  • Use the following command to generate the script file upgradeds.sql, required to manually upgrade the VSAM datastore. If you omit the -file option, a file named upgrade_datastore_VSAM_db-type.sql is generated (db-type is determined by the settings in the database configuration file).
    dbfhadmin -upgrade -datastore:sql://localhost/VSAM -file:upgradeds.sql

    If the datastore does not need to be upgraded, dbfhadmin outputs ADM0073I Datastore '<datastore-url>' does not need to be upgraded, and no script file is created. When an upgrade is required, dbfhadmin outputs ADM0045I Creating SQL script file '<sql-script-name>'.

    The resulting script should be run as a user with sysadmin privileges using the sqlcmd (SQL Server), psql (PostgreSQL), db2 (Db2), or sqlplus (Oracle) command-line tool.

Datastore integrity

Use the following commands to verify the integrity of a datastore, and if required, recover it from any integrity issues.

  • The following command runs a datastore integrity check of the VSAM datastore:
    dbfhadmin -verify -list -datastore:sql://localhost/VSAM

    Currently this check only detects orphaned record locks (that is, those record locks that exist without an associated file handle). Record locks would typically be orphaned if the associated file handle had been manually deleted from the database. When orphaned record locks are detected, dbfhadmin lists the associated file name for non-sequential files, or lists <Sequential files> for sequential files (the actual file name cannot be determined as a global record lock table is used for these files), with a count of the orphaned locks; for example:

    Orphaned record locks:  Name                Folder  Count
                        ----                ------   -----
                        SPLJOB.dat          /MyDir   3
                        <Sequential files>           1
  • The following command recovers the VSAM datastore from any orphaned record locks:
    dbfhadmin -verify -recover -datastore:sql://localhost/VSAM
  • The following command generates a diagnostic report names diags.txt, which contains details about ESDEMO region database (and associated cross-region database) in the DBHOST database:
    dbfhadmin -diags -usedb:DBHOST -name:ESDEMO -file diags.txt
  • The following command dumps lock information for the specified datastore to an MFDBFH_Diagnostics.txt file:
    dbfhadmin -diags -usedb:DBHOST -name:ESDEMO -datastore:sql://localhost/VSAM

See dbfhadmin Return Codes for a list of possible return codes used by the command:

  • dbfhadmin Return Codes
Parent topic: The dbfhadmin Command Line Utility


dbfhadmin Return Codes

The following table lists the return codes for the dbfhadmin command, for each of its operations:

dbfhadmin operation | Return code (errorlevel) | Description
-casprocess -list | 0 | Success
 | 16 | Any error occurring while retrieving process information
-casprocess -recover | 0 | Success
 | 16 | Any error occurring while recovering processes
-createdb | 0 | Success
 | 16 | Any error occurring while creating a datastore/region/cross-region
-keytypes -add | 0 | Success
 | 16 | Any error occurring while adding a key type definition
-keytypes -delete | 0 | Success
 | 16 | Any error occurring while deleting a key type definition
-keytypes -export | 0 | Success
 | 16 | Any error occurring while exporting key type definitions
-keytypes -import | 0 | Success
 | 4 | Did not replace key types
 | 16 | Any error occurring while importing key type definitions
-keytypes -list | 0 | Success
 | 16 | Any error occurring while listing key type definitions
-openfiles -list | 0 | Success
 | 16 | Any error occurring while retrieving file handle information
-openfiles -recover | 0 | Success
 | 16 | Any error occurring while closing file handles and removing record locks
-region -list | 0 | Success
 | 16 | Any error occurring while retrieving region or resource lock information
-region -recover | 0 | Success
 | 16 | Any error occurring while recovering region resource locks
-script | 0 | Success
 | 16 | Any error occurring while creating a datastore/region/cross-region script
-upgrade | 0 | Success
 | 16 | Any error occurring while checking if a datastore needs upgrading, or generating an upgrade script
-verify -list | 0 | Success
 | 4 | One or more orphaned record locks exists in the datastore
 | 16 | Any error occurring while verifying the integrity of a datastore
-verify -recover | 0 | Success - nothing to recover
 | 4 | One or more orphaned record locks were removed from the datastore
 | 16 | Any error occurring while verifying the integrity of a datastore
Parent topic: Examples of the dbfhadmin Command Line Utility


File View Generation

Individual records of datastore files are held as BLOBs. This is primarily for performance when inserting, updating, and retrieving records using COBOL file I/O. However, this does mean that the data in the records is not readily visible when attempting to view it using regular SQL SELECT statements (for example, when using a database management tool such as PostgreSQL's pgadmin or Oracle's SQL Developer).

The File View Generator (dbfhview) creates database views to make the viewing of your datastore data possible. Once a generated view is installed in your database, you can use all of the usual SQL tools and commands to manipulate the view of the data in table form.

The database views are based on file definitions contained within a structure files that was generated using the Data File Editor. Each field in a file definition is represented by a column in a view. Each column maps on to bytes at a given offset in the underlying BLOB and is represented with a database data type corresponding to the field's COBOL data type as defined in the structure file (that is, the view coerces the underlying BLOB bytes into the database data type represented by each column in the view).

Structure files can often contain more than one FD, and so you can use dbfhview to list the available FD structures, and then select the appropriate one for your database view.

Instead of installing the view directly into your database, you can generate a script file, which you can run manually to install the view. This gives you an opportunity to customize the view (for example, to remove columns) before it is installed in the database.

With the exception of Db2, the generated views use T-SQL functions that are installed in the associated datastores. For Db2, you must install some external functions instead to provide the equivalent functionality. External functions, equivalent to the T-SQL versions of the same name, can also be installed for SQL Server and PostgreSQL. You would typically only need to do this if the supplied T-SQL functions were not providing the desired performance. See Installing Database Server Functions for more information.

  • The dbfhview Command Line Utility
    Use the dbfhview command line utility to maintain a list of database views that you can use to view your datastore files once they have been uploaded to the database.
  • Installing Database Server Functions
    For Db2 databases (and optionally, the other database types), install external functions that are used to create database views.
Parent topic: Database File Handling and Enterprise Server Region Database Management
Related reference
Using the Structure File Editor
Create a Structure File


The dbfhview Command Line Utility

Use the dbfhview command line utility to maintain a list of database views that you can use to view your datastore files once they have been uploaded to the database.

Syntax:

dbfhview [action][options]

Or:

dbfhview @<response-file-name> [-verbose]
action
Can be one of the following:
  • -create - creates a new view or view definition.
  • -delete - deletes a view associated with a file.
  • -list - lists the structures available in a structure file, or the views associated with a file.
options
Specify one or more of the following:
-configfile:<name>
Specifies the path and file name of the database configuration file. This is optional if the MFDBFH_CONFIG environment variable is already in effect, but if set, will override the value of the MFDBFH_CONFIG. Use with the -create, -delete, and -list actions.
-file:<url>
Specifies the file URL for which the view is to be created. Use with the -create, -delete, and -list actions.
-id:<struct-id>
The structure ID with which to create the view. Use the -list -struct action/option to obtain the possible IDs. If this option is not specified, the default structure, as denoted by * when listed, is used for the view. Use with the -create action.
-name:<name>
Specifies the name of the view. Use with the -create and -delete actions.
-nobanner
Suppresses output to a minimum.
-outfile:<name>
Specifies the name of a file in which to output the SQL script that creates the view. Use with the -create action.
Use this option instead of installing the view directly into the database. With this option, you can edit the script before you install the view.
-struct:<name>
Specifies the name of the structure file, generated by the Data File Editor, that contains the structures from which the view will be created. Use with the -create and -list actions.
@<response-file-name>
Multiple actions, as listed above, can be added to a text file, one command per line. When that response file is run, each line is executed in turn.
For example, the following contents of a response file creates three views (STAFFALL, STAFFMAN, and STAFFTEMP) for the same datastore file (ACCTFIL). It takes the structure details for the 3 structures from the same structure file (my.str):
-create -struct:my.str -name:STAFFALL -file:sql://MYSRV/VSAM/ACCTFIL
-create -struct:my.str -id:2 -name:STAFFMAN-file:sql://MYSRV/VSAM/ACCTFIL
-create -struct:my.str -id:3 -name:STAFFTEMP -file:sql://MYSRV/VSAM/ACCTFIL

If the file was saved with a name of commands.txt, you would run it using:

dbfview @commands.txt
-verbose
Displays additional information as the command is run. Use with the -create -delete, and -list actions.
  • Examples of the dbfhview Command Line Utility
Parent topic: File View Generation


Examples of the dbfhview Command Line Utility

The following command creates a database view called ACCTFIL, using the default structure in my.str, for the ACCTFIL file in the VSAM datastore.

dbfhview -create -struct:my.str -name:ACCTFIL -file:sql://MYSRV/VSAM/ACCTFIL -configfile:C:\dbconfig\mfdbfh.cfg
The following command creates a database view called ACCTFIL, using the second structure (-id:2) in my.str, for the ACCTFIL file in the VSAM datastore. .
dbfhview -create -struct:my.str -id:2 -name:ACCTFIL -file:sql://MYSRV/VSAM/ACCTFIL
Tip: To show the structure that corresponds to -id:2, use dbfhview -list -struct:my.str.
The following command creates a script file my.sql, that when run, installs a database view called ACCTFIL, using the default structure in my.str, for the ACCTFIL file in the VSAM datastore.
dbfhview -create -struct:my.str -name:ACCTFIL -file:sql://MYSRV/VSAM/ACCTFIL
-outfile:my.sql
Tip: You can edit the script file before it is installed; for example, you may need to reduce the number of columns used in the view in order to fall below the limits allowed by the database type.

The following command deletes the ACCTFIL view that is associated with the ACCTFIL file in the VSAM datastore.

dbfhview -delete -name:ACCTFIL -file:sql://MYSRV/VSAM/ACCTFIL

The following command lists the structures that are defined in the my.str structure file. The index numbers displayed are used with the -id option when creating a view using a specific structure.

dbfhview -list -struct:my.str

The following command lists the installed views associated with the ACCTFIL file in the VSAM datastore.

dbfhview -list -file:sql://MYSRV/VSAM/ACCTFIL
Parent topic: The dbfhview Command Line Utility


Installing Database Server Functions

External database server functions are provided for SQL Server, PostgreSQL, and Db2 as part of MFDBFH's File View Generation support. These external functions can optionally be installed as alternatives to the T-SQL functions provided for SQL Server and PostgreSQL, but are mandatory for Db2. You would typically only need to install the external functions for SQL Server or PostgreSQL if the supplied T-SQL functions were not providing the desired performance.

Both the T-SQL and the external function types are supplied with your Micro Focus product.

Restriction: Oracle datastores do not currently support the use of these external functions.
  • Installing Functions for Db2
  • Installing Functions for Microsoft SQL Server and Microsoft Azure
  • Installing Functions for PostgreSQL
Parent topic: File View Generation


Installing Functions for Db2

Important: You must install these functions within the database housing your datastores before you can use dbfhview to create the database views.
  1. Do one of the following:
    • For Windows: copy DbfhFuncsDB2.dll, located in the etc\mfdbfh\dbfhfuncs\x86 (32-bit), or etc\mfdbfh\dbfhfuncs\x64 (64-bit) sub-folder of the installation folder, into the \function sub-folder of the PostgreSQL database server's installation folder.
    • For UNIX, copy DbfhFuncsDB2.so, located in the etc/mfdbfh/dbfhfuncs/x86 (32-bit), or etc/mfdbfh/dbfhfuncs/x64 (64-bit) sub-folder of the installation folder, into the /function sub-folder of the PostgreSQL database server's installation folder.
  2. Within Enterprise Developer, create the functions script:
    dbfhadmin -script -provider:db2 -type:datastore_funcs -name:<datastore_name>

    By default, the command creates a script file named create_datastore_funcs_<datastore_name>_db2.sql

  3. Using db2 command, run the created script file.

    The external functions are installed in the database.

Parent topic: Installing Database Server Functions


Installing Functions for Microsoft SQL Server and Microsoft Azure

Use the following instructions to replace the standard T-SQL functions with some external, non-T-SQL equivalent functions. You only need to do this if you are having problems (e.g. performance issues) with the standard database views.

  1. Using sqlcmd or the SQL Server Management Studio, run the following commands against the required database to enable it for CLR function execution:
    EXEC sp_configure 'clr enabled', 1;
RECONFIGURE;
  2. Within Enterprise Developer, create the functions installation script:
    dbfhadmin -script -provider:ss -type:datastore_funcs -name:<datastore_name>

    By default, the command creates a script file named create_datastore_funcs_<datastore_name>_ss.sql

  3. Using sqlcmd or the SQL Server Management Studio, run the created script file.

    The external functions replace the currently installed T-SQL ones within your database. Existing views should continue to work, using the new functions.

Parent topic: Installing Database Server Functions


Installing Functions for PostgreSQL

Use the following instructions to replace the standard T-SQL functions with some external, non-T-SQL equivalent functions. You only need to do this if you are having problems (e.g. performance issues) with the standard database views.

Restriction: MFDBFH currently only supports the installation of external functions for 64-bit PostgreSQL servers.
  1. Do one of the following:
    • For Windows: copy DbfhFuncsPG.dll, located in the etc\mfdbfh\dbfhfuncs\x64 sub-folder of the installation folder, into the \lib sub-folder of the PostgreSQL database server's installation folder.
    • For UNIX, copy DbfhFuncsPG.so, located in the etc/mfdbfh/dbfhfuncs/x64 sub-folder of the installation folder, into the /lib sub-folder of the PostgreSQL database server's installation folder.
  2. Within Enterprise Developer, create the functions script:
    dbfhadmin -script -provider:pg -type:datastore_funcs -name:<datastore_name>

    By default, the command creates a script file named create_datastore_funcs_<datastore_name>_pg.sql

  3. Using psql, run the created script file.

    The external functions replace the currently installed T-SQL ones within your database. Existing views should continue to work, using the new functions.

Parent topic: Installing Database Server Functions


Resource Locking

Prior to the introduction of MFDBFH, the locking and releasing of resources accessible to a group of enterprise server regions configured as a cluster was the responsibility of the Global Lock Manager (GLM): a dedicated enterprise server region whose role is to process global lock requests.

This process was required to allow jobs of the same name to run on different regions, and to also prevent concurrent access to data sets that have been allocated as DISP=OLD|NEW|MOD in JCL within their submitted jobs.

When your catalog and spool queues are stored in a database, a different process is required to handle the resource locking. The role of a GLM is replaced by the combination of region databases and a cross-region database. A region database will process step- and system-scoped ENQs, and a cross-region database will process system-scoped ENQs.

How you set up your resource locking depends on the enterprise server configuration you have:

A typical enterprise server cluster (ES_LOCKDB method)

Within a cluster where a GLM would previously been employed, the step- and system-scoped ENQs initiated by an enterprise server region must be processed by its own dedicated region database server. This is achieved by using the ES_LOCKDB=<region-db> environment variable. Note, the region database specified by the variable must be configured as part of the database configuration file currently in use.

The following excerpt from a database configuration file shows a Db2 configuration where one physical database houses a cross-region database, 3 region databases, and a datastore:

<?xml version="1.0" encoding="utf-8" ?>
<!-- MFDBFH server and database configuration -->
<datastores usevault="false">
    <server name="MYSERVER" type="db2" access="odbc">
        <dsn name="CrossRegion" type="crossregion.cas" dbname="REGNDEV" connect="db=REGNDEV;uid=myuser;pwd=mypassword" />
        <dsn name="Region1" type="region.cas" region="DEVL1" dbname="REGNDEV" feature="all" connect="db=REGNDEV;uid=myuser;pwd=mypassword" />
        <dsn name="Region2" type="region.cas" region="DEVL2" dbname="REGNDEV" feature="all" connect="db=REGNDEV;uid=myuser;pwd=mypassword" />
        <dsn name="Region3" type="region.cas" region="DEVL3" dbname="REGNDEV" feature="all" connect="db=REGNDEV;uid=myuser;pwd=mypassword" />
        <dsn name="VSAM" type="datastore" dsname="VSAM" connect="db=VSAM;uid=myuser;pwd=mypassword" />
    </server>
</datastores>

If a cluster of 3 enterprise servers were using this configuration file, each server must specify a different region database to process its locking resources; so you could specify ES_LOCKDB=DEVL1 on the first server, ES_LOCKDB=DEVL2 on the second, and ES_LOCKDB=DEVL3 on the third.

Important: The reason for ensuring that each server uses its own region database is because the region database is cold-started when the server that specifies it is started. During the cold start, a region database drops and reinstalls any associated database objects. If more than one server was using the region database, locks for the other servers could be lost. To ensure the same region database is not configured for multiple servers, a check is made during a server startup: if it is not using a unique region database, startup fails and the failure is written to the console log.

As well as specifying the region database on each server, you must also specify which MFDBFH server (that is, the server name entry in the configuration file) that the region database belongs to. Using the example above, each server in the cluster should also set the ES_SERVER=MYSERVER variable.

A Performance and Availability Cluster (PAC)

If you have configured a PAC, the setup is slightly different to that of a typical cluster. The same types of servers perform the same locking processes (region databases process step- and system-scoped ENQs; cross-region databases process system-scoped ENQs), but only a single region database is required for the step- and system-scoped ENQs for all enterprise server regions in the PAC.

Parent topic: Database File Handling and Enterprise Server Region Database Management
Related information
ES_LOCKDB


Record Locking Strategies

MFDBFH supports the following types of record locking strategy:

Table Record Locking
Record locks are maintained in a separate lock table, and the associated lock behavior when using the COBOL READ, WRITE, and REWRITE verbs is the same as when accessing disk files via non-MFDBFH file handling operations or when using Fileshare. This is the default.
Database Record Locking
With this record locking strategy, MFDBFH makes use of the RDBMS to directly lock records in the file table. When records are locked this way, they will remain locked until the end of the current database transaction. This means that database record locking is restricted to being only available when using transactional files.
The benefit of using database record locking instead of table record locking is performance, but this comes at the cost of loss of compatibility with regular COBOL file I/O, and the inability to concurrently access the file non-transactionally (that is, a transactional file opened using the database record locking strategy by CICS cannot be shared with batch programs, which will open files non-transactionally).

To enable the database record locking strategy for transactional files, set the following environment variable:

MFDBFH_RECORD_LOCKING=database
In-memory Record Locking
This record locking strategy is used for I/O operations performed on files that have been allocated for exclusive use (that is, DISP=OLD, DISP=NEW, or DISP=MOD) in batch jobs running under an enterprise server region. This is the most performant of all of the record locking strategies.
  • Summary of Differences Between Locking Strategies
  • Record Locking Scenarios
Parent topic: Database File Handling and Enterprise Server Region Database Management
Related information
MFDBFH_RECORD_LOCKING


Summary of Differences Between Locking Strategies

The following is a summary of differences when the database locking strategy is in place (as opposed to the default table record locking strategy):
  • A COBOL READ of a record that is locked by another run unit should return the record data and the 9/68 (LOCKED) condition. However, the RDBMS may not actually lock the record until it has been modified, resulting in data being returned and the file status set to 0/0 (SUCCESS). The actual behaviour is dependent upon the RDBMS being used
  • A COBOL READ using the WITH WAIT clause may not wait if the record has been locked by a different run unit, but that run unit has not yet modified the record. This is for the same reason as above.
  • The COBOL UNLOCK statement will not release a file's record locks until a syncpoint.
  • The RDBMS may decide to acquire a lock against an entire page or table, in which case records may appear as locked even though they were not explicitly locked by the user application.
Parent topic: Record Locking Strategies


Record Locking Scenarios

The following table indicates the record locking strategy that will be used for a file when it has been previously opened. The leftmost column indicates the strategy in use after the file was first opened. The cells in the table indicate the record strategy that will be used when the file is opened for a second or subsequent time, and may be different to the actual strategy requested by the OPEN. A column containing N/A indicates that the requested strategy was incompatible with the strategy already in effect for the file, and will result in the OPEN failing with a 9/100 file status (invalid operation):

First File Open Record Locking Strategy | Second and Subsequent File Open Record Locking Strategy Intent
 | Transactional |  |  |  |  |  | Non-transactional
 | Same Process |  |  | Different Process |  |  | Same Process |  | Different Process
 | Table (intent) | Database (intent) | In-memory(intent) | Table (intent) | Database (intent) | In-memory(intent) | Table (intent) | In-memory (intent) | Table (intent) | In-memory (intent)
Table | Table (used) | Table (used) | Table (used) | Table (used) | Table (used) | Table (used) | Table (used) | Table (used) | Table (used) | Table (used)
Database | Database (used) | Database (used) | Database (used) | Database (used) | Database (used) | Database (used) | N/A | N/A | N/A | N/A
In-memory | N/A | N/A | N/A | N/A | N/A | N/A | In-memory (used) | In-memory (used) | N/A | N/A
Parent topic: Record Locking Strategies


MFDBFH Error Messages

  • ADM - DBFHADMIN Messages
  • CFG - MFDBFH Configuration Messages
  • DBFH - MFDBFH General Messages
  • DEP - DBFHDEPLOY Messages
  • VGN - DBFHVIEW Messages
Parent topic: Database File Handling and Enterprise Server Region Database Management


ADM - DBFHADMIN Messages

  • ADM0000 - ADM0019
  • ADM0020 - ADM0039
  • ADM0040 - ADM0059
  • ADM0060 - ADM0079
  • ADM0080 - ADM0099
  • ADM0100 - ADM0119
Parent topic: MFDBFH Error Messages


ADM0000 - ADM0019

  • ADM0001E Cannot specify both -list and -recover with -casprocess
    dbfhadmin command-line includes both -list and -recover with -casprocess.
  • ADM0002E Must specify either -list or -recover with -casprocess
    dbfhadmin command-line must include either -list or -recover with -casprocess.
  • ADM0003E Must specify -usedb:<instance> with -casprocess -recover/-list
    dbfhadmin command-line must include -usedb:<instance> with -casprocess -recover/-list.
  • ADM0004E Must specify -host:<name> with -casprocess -recover
    dbfhadmin command-line must include -host<name> with -casprocess -recover.
  • ADM0005E Database server instance 'server-name' is not configured
    No configuration entry exists for the specified database server instance.
  • ADM0006E Cross-region database for database server instance 'server-name' is not configured
    No configuration entry exists for the cross-region database specified by the database server instance.
  • ADM0007S An error occurred while reading process records from the cross-region database: exception-message
    A serious error occurred while attempting to read process records from the cross-region database.
  • ADM0008I There are no registered process records for host 'host-name'
    No processes are registered for the given process-id on the given host.
  • ADM0009I There are no registered process records
    No processes are registered.
  • ADM0010E Cannot specify -pid:<process-id> with -casprocess -list
    dbfhadmin command-line must not include -pid:<process-id> with -casprocess -list.
  • ADM0011I There are no processes to recover
    There are no processes to recover for the specified host (and PID).
  • ADM0012I Recovered process: host='host-name', region = 'region-name', PID=process-id, TID=thread-id
    Details of a process that has been recovered.
  • ADM0013S An error occurred while attempting to recover processes: exception-message
    A serious error occurred while attempting to recover processes from the (cross-)region databases.
  • ADM0014E Cannot specify both -list and -recover with -openfiles
    dbfhadmin command-line includes both -list and -recover with -openfiles.
  • ADM0015E Must specify either -list or -recover with -openfiles
    dbfhadmin command-line must include either -list or -recover with -openfiles.
  • ADM0016E Must specify -datastore:<url> with -openfiles -recover/-list
    dbfhadmin command-line must include -datastore:<url> with -openfiles -recover/-list.
  • ADM0017E Must specify -host:<name> with -openfiles -recover
    dbfhadmin command-line must include -host<name> with -openfiles -recover.
  • ADM0018E Cannot specify -pid:<process-id> with -openfiles -list
    dbfhadmin command-line must not include -pid:<process-id> with -openfiles -list.
  • ADM0019E Invalid datastore URL specified
    An invalid (syntactically incorrect) datastore URL was specified.
Parent topic: ADM - DBFHADMIN Messages


ADM0001E Cannot specify both -list and -recover with -casprocess

dbfhadmin command-line includes both -list and -recover with -casprocess.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0002E Must specify either -list or -recover with -casprocess

dbfhadmin command-line must include either -list or -recover with -casprocess.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0003E Must specify -usedb:<instance> with -casprocess -recover/-list

dbfhadmin command-line must include -usedb:<instance> with -casprocess -recover/-list.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0004E Must specify -host:<name> with -casprocess -recover

dbfhadmin command-line must include -host<name> with -casprocess -recover.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0005E Database server instance 'server-name' is not configured

No configuration entry exists for the specified database server instance.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0006E Cross-region database for database server instance 'server-name' is not configured

No configuration entry exists for the cross-region database specified by the database server instance.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0007S An error occurred while reading process records from the cross-region database: exception-message

A serious error occurred while attempting to read process records from the cross-region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0008I There are no registered process records for host 'host-name'

No processes are registered for the given process-id on the given host.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0009I There are no registered process records

No processes are registered.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0010E Cannot specify -pid:<process-id> with -casprocess -list

dbfhadmin command-line must not include -pid:<process-id> with -casprocess -list.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0011I There are no processes to recover

There are no processes to recover for the specified host (and PID).
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0012I Recovered process: host='host-name', region = 'region-name', PID=process-id, TID=thread-id

Details of a process that has been recovered.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0013S An error occurred while attempting to recover processes: exception-message

A serious error occurred while attempting to recover processes from the (cross-)region databases.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0014E Cannot specify both -list and -recover with -openfiles

dbfhadmin command-line includes both -list and -recover with -openfiles.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0015E Must specify either -list or -recover with -openfiles

dbfhadmin command-line must include either -list or -recover with -openfiles.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0016E Must specify -datastore:<url> with -openfiles -recover/-list

dbfhadmin command-line must include -datastore:<url> with -openfiles -recover/-list.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0017E Must specify -host:<name> with -openfiles -recover

dbfhadmin command-line must include -host<name> with -openfiles -recover.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0018E Cannot specify -pid:<process-id> with -openfiles -list

dbfhadmin command-line must not include -pid:<process-id> with -openfiles -list.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0019E Invalid datastore URL specified

An invalid (syntactically incorrect) datastore URL was specified.
Destination:
Console and standard error.
Parent topic: ADM0000 - ADM0019


ADM0020 - ADM0039

  • ADM0020E Datastore 'datastore-url' is not configured
    No configuration entry exists for the specified datastore.
  • ADM0021S An error occurred while reading open file handle records: exception-message
    A serious error occurred while attempting to read open file handle records from the datastore database.
  • ADM0022I There are no open files
    There are no open files for the specified host (and PID).
  • ADM0023I There are no files to close
    No files to close.
  • ADM0024I Closed file: host='host-name', file name='file-name', folder='folder-name'
    Details of a process that has been recovered.
  • ADM0025E Can only specify one of -casprocess, -checkrbas, -createdb, -diags, -keytypes, -openfiles, region, -script, upgrade, or -verify
    dbfhadmin command-line must only specify one of -casprocess, -checkrbas, -createdb, -diags, -keytypes, -openfiles -region, -script, -upgrade, or -verify.
  • ADM0026E Can only specify one of -add, -delete, -export, -import or -list with -keytypes
    dbfhadmin command-line must only specify one of add, -delete, -export, -import or list with -keytypes.
  • ADM0027E Must specify one of -add, -delete, -export, -import or -list with -keytypes
    dbfhadmin command-line must specify one of add, -delete, -export, -import or -list with -keytypes.
  • ADM0028E Must specify -file:<URL> with -add or -delete
    dbfhadmin command-line must specify -file:<URL> with -keytypes -add/-delete.
  • ADM0029E Must specify -datastore:<url> with -keytypes -export/-import/-list/-upgrade
    dbfhadmin command-line must include -datastore:<url> with -keytypes -export/-import/-list/-upgrade.
  • ADM0030E Invalid file URL specified
    An invalid (syntactically incorrect) file URL was specified.
  • ADM0031S An error occurred while adding/updating a key type definition record: exception-message
    A serious error occurred while attempting to add/update a key type definition record in the datastore database.
  • ADM0032E Invalid key type 'key-type' specified
    The user specified an invalid key type.
  • ADM0033I The operation completed successfully
    The requested operation completed successfully.
  • ADM0034W Did not replace key types for file 'file-name' in folder 'folder-name'
    An key type definition already existed for the given filename and -replace was not specified.
  • ADM0035I There are no key type definitions
    There are no key type definitions in the datastore.
  • ADM0036S An error occurred while reading key type definition records: exception-message
    A serious error occurred while attempting to read key type definition records from the datastore database.
  • ADM0037E Must specify -types:<key-types> with -add
    dbfhadmin command-line must specify -types:<key-types> with -keytypes -add.
  • ADM0038S An error occurred while exporting key type definition records: exception-message
    A serious error occurred while attempting to export key type definition records to an XML file.
  • ADM0039S An error occurred while importing key type definition record for file 'file-name' in folder 'folder-name': exception-message
    A serious error occurred while attempting to add/update a key type definition record in the datastore database.
Parent topic: ADM - DBFHADMIN Messages


ADM0020E Datastore 'datastore-url' is not configured

No configuration entry exists for the specified datastore.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0021S An error occurred while reading open file handle records: exception-message

A serious error occurred while attempting to read open file handle records from the datastore database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0022I There are no open files

There are no open files for the specified host (and PID).
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0023I There are no files to close

No files to close.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0024I Closed file: host='host-name', file name='file-name', folder='folder-name'

Details of a process that has been recovered.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0025E Can only specify one of -casprocess, -checkrbas, -createdb, -diags, -keytypes, -openfiles, region, -script, upgrade, or -verify

dbfhadmin command-line must only specify one of -casprocess, -checkrbas, -createdb, -diags, -keytypes, -openfiles -region, -script, -upgrade, or -verify.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0026E Can only specify one of -add, -delete, -export, -import or -list with -keytypes

dbfhadmin command-line must only specify one of add, -delete, -export, -import or list with -keytypes.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0027E Must specify one of -add, -delete, -export, -import or -list with -keytypes

dbfhadmin command-line must specify one of add, -delete, -export, -import or -list with -keytypes.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0028E Must specify -file:<URL> with -add or -delete

dbfhadmin command-line must specify -file:<URL> with -keytypes -add/-delete.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0029E Must specify -datastore:<url> with -keytypes -export/-import/-list/-upgrade

dbfhadmin command-line must include -datastore:<url> with -keytypes -export/-import/-list/-upgrade.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0030E Invalid file URL specified

An invalid (syntactically incorrect) file URL was specified.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0031S An error occurred while adding/updating a key type definition record: exception-message

A serious error occurred while attempting to add/update a key type definition record in the datastore database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0032E Invalid key type 'key-type' specified

The user specified an invalid key type.
Resolution:
Correct the key type and re-run the command.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0033I The operation completed successfully

The requested operation completed successfully.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0034W Did not replace key types for file 'file-name' in folder 'folder-name'

An key type definition already existed for the given filename and -replace was not specified.
Resolution:
Specify -replace on the command-line if the key type definition needs to be updated.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0035I There are no key type definitions

There are no key type definitions in the datastore.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0036S An error occurred while reading key type definition records: exception-message

A serious error occurred while attempting to read key type definition records from the datastore database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0037E Must specify -types:<key-types> with -add

dbfhadmin command-line must specify -types:<key-types> with -keytypes -add.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0038S An error occurred while exporting key type definition records: exception-message

A serious error occurred while attempting to export key type definition records to an XML file.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0039S An error occurred while importing key type definition record for file 'file-name' in folder 'folder-name': exception-message

A serious error occurred while attempting to add/update a key type definition record in the datastore database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0020 - ADM0039


ADM0040 - ADM0059

  • ADM0040I number-key-types key types definitions were imported
    The number of key types definition records that were successfully imported.
  • ADM0041E Must specify both -provider and -type with -script
    dbfhadmin command-line must include both -type and -provider with -script.
  • ADM0042E Must specify a type of crossregion, datastore or region with -type:<script-type>
    dbfhadmin command-line must have a type of crossregion, datastore or region with -type:<script-type>!
  • ADM0043E Must specify a provider of 'az', 'db2', 'pg 'or 'ss' with -provider:<db-type>
    dbfhadmin command-line must have a provider of azuresqldb, db2, oracle, postgresql or sqlserver with -provider:<db-type>!
  • ADM0044E Must specify -name:<object-name> with -type:datastore or -type:region
    dbfhadmin command-line must specify -name:<object-name> with -type:datastore or -type:region!
  • ADM0045I Creating SQL script file 'file-name'
    The name of the file to which the SQL commands for creating a database are to be written!
  • ADM0046E Must specify -file, -provider and -type with -createdb
    dbfhadmin command-line must include -file, -type and -provider with -createdb.
  • ADM0047E -ebcdic can only be specified with -createdb -provider:db2 -type:datastore
    dbfhadmin command-line only allows -ebcdic to be specified with -createdb -provider:db2 -type:datastore.
  • ADM0048E An error occurred attempting to process file 'file-name'
    An error occurred when attempting to open, or read records from, the database creation script file.
  • ADM0049E 'create-database-command' statement not found
    A create database SQL command was not found in the script.
  • ADM0050I Creating database 'database-name'
    Database creation processing starting.
  • ADM0051E Database 'database-name' already exists
    Database already exists.
  • ADM0052E Error attempting to create database 'database-name' (error-code)
    Database already exists.
  • ADM0053E -collation can only be specified with -createdb -provider:db2
    dbfhadmin command-line only allows -collation to be specified with -createdb -provider:db2.
  • ADM0054E Must specify -user:<user-name> with -createdb -provider:postgresql
    dbfhadmin command-line must specify a user with -createdb -provider:oracle|postgresql!
  • ADM0055E Must specify -usedb:<instance> with -createdb -provider:sqlserver
    dbfhadmin command-line must include -usedb:<instance> with -createdb -provider:sqlserver.
  • ADM0056E Must specify -password:<pwd> with -createdb -provider:az|ss -user:<user-name>
    dbfhadmin command-line must specify a password with -createdb -provider:az|ora|ss -user:<user-name>!
  • ADM0059E Cannot specify both -db:<db-name> and -existdb:<db-name> with -script
    dbfhadmin command-line must not include -db:<db-name> and -existdb:<db-name> with -script.
Parent topic: ADM - DBFHADMIN Messages


ADM0040I number-key-types key types definitions were imported

The number of key types definition records that were successfully imported.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0041E Must specify both -provider and -type with -script

dbfhadmin command-line must include both -type and -provider with -script.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0042E Must specify a type of crossregion, datastore or region with -type:<script-type>

dbfhadmin command-line must have a type of crossregion, datastore or region with -type:<script-type>!
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0043E Must specify a provider of 'az', 'db2', 'pg 'or 'ss' with -provider:<db-type>

dbfhadmin command-line must have a provider of azuresqldb, db2, oracle, postgresql or sqlserver with -provider:<db-type>!
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0044E Must specify -name:<object-name> with -type:datastore or -type:region

dbfhadmin command-line must specify -name:<object-name> with -type:datastore or -type:region!
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0045I Creating SQL script file 'file-name'

The name of the file to which the SQL commands for creating a database are to be written!
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0046E Must specify -file, -provider and -type with -createdb

dbfhadmin command-line must include -file, -type and -provider with -createdb.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0047E -ebcdic can only be specified with -createdb -provider:db2 -type:datastore

dbfhadmin command-line only allows -ebcdic to be specified with -createdb -provider:db2 -type:datastore.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0048E An error occurred attempting to process file 'file-name'

An error occurred when attempting to open, or read records from, the database creation script file.
Resolution:
Correct the specified file name.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0049E 'create-database-command' statement not found

A create database SQL command was not found in the script.
Resolution:
Modify the script to include a create database command.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0050I Creating database 'database-name'

Database creation processing starting.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0051E Database 'database-name' already exists

Database already exists.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0052E Error attempting to create database 'database-name' (error-code)

Database already exists.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0053E -collation can only be specified with -createdb -provider:db2

dbfhadmin command-line only allows -collation to be specified with -createdb -provider:db2.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0054E Must specify -user:<user-name> with -createdb -provider:postgresql

dbfhadmin command-line must specify a user with -createdb -provider:oracle|postgresql!
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0055E Must specify -usedb:<instance> with -createdb -provider:sqlserver

dbfhadmin command-line must include -usedb:<instance> with -createdb -provider:sqlserver.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0056E Must specify -password:<pwd> with -createdb -provider:az|ss -user:<user-name>

dbfhadmin command-line must specify a password with -createdb -provider:az|ora|ss -user:<user-name>!
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0059E Cannot specify both -db:<db-name> and -existdb:<db-name> with -script

dbfhadmin command-line must not include -db:<db-name> and -existdb:<db-name> with -script.
Destination:
Console and standard error.
Parent topic: ADM0040 - ADM0059


ADM0060 - ADM0079

  • ADM0060I Updating existing database 'database-name'
    Database creation procesing starting.
  • ADM0061E Can only specify one of -list, -recover, or -status with -region
    dbfhadmin command-line must include just one of-list, -recover, and -status with -region.
  • ADM0062E Must specify -usedb:<instance> with -region -recover/-list/-status
    dbfhadmin command-line must include -usedb:<instance> with -region -recover/-list/-status.
  • ADM0063I No regions exist
    No configured regions exist.
  • ADM0064S An error occurred while reading ENQ requests for the region-name region: exception-message
    A serious error occurred while attempting to read ENQ requests for the given region.
  • ADM0065E Region 'region-name' is not configured
    No configuration entry exists for the specified region.
  • ADM0066I No resource locks exist
    No resource locks exist.
  • ADM0067I Recovered resource lock: QNAME='resource-qname', RNAME = 'resource-rname'
    Details of a resource lock that has been removed.
  • ADM0068S An error occurred while attempting to recover resource locks
    A serious error occurred while attempting to recover resource locks from the (cross-)region databases.
  • ADM0069E db-api-type error: 'odbc-oci-error-message'
    An ODBC or OCI error occurred attempting to perform a database operation.
  • ADM0070E -existdb:<db-name> must be specified with -script -provider:ora
    dbfhadmin command-line must specify -existdb:<db-name> with -script -provider:ora.
  • ADM0071E -existdb:<db-name> can only be specified with -script -provider:ora
    dbfhadmin command-line only allows -existdb:<db-name> to be specified with -script -provider:ora.
  • ADM0072E Must specify a type of crossregion, datastore, datastore_funcs or region with -type:<script-type>
    dbfhadmin command-line must have a type of crossregion, datastore or region with -type:<script-type>!
  • ADM0073I Datastore 'datastore-url' does not need to be upgraded
    The datastore does not need to be upgraded as it is already at the latest version level!
  • ADM0074E Error creating SQL script file 'file-name' (file-status)
    An error occurred attempting to create a SQL script.
  • ADM0075E Invalid port number specified. Must be in the range 0-65535
    An invalid port number was specified.
  • ADM0076E Cannot specify both -list and -recover with -verify
    dbfhadmin command-line includes both -list and -recover with -verify.
  • ADM0077E Must specify either -list or -recover with -verify
    dbfhadmin command-line must include either -list or -recover with -verify.
  • ADM0078E Must specify -datastore:<url> or -usedb:<instance> with -verify -recover/-list
    dbfhadmin command-line must include -datastore:<url> or -usedb:<instance> with -verify -recover/-list.
  • ADM0079S An error occurred while verifying the integrity of the datastore: exception-message
    A serious error occurred while attempting to verify the integrity the datastore database.
Parent topic: ADM - DBFHADMIN Messages


ADM0060I Updating existing database 'database-name'

Database creation procesing starting.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0061E Can only specify one of -list, -recover, or -status with -region

dbfhadmin command-line must include just one of-list, -recover, and -status with -region.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0062E Must specify -usedb:<instance> with -region -recover/-list/-status

dbfhadmin command-line must include -usedb:<instance> with -region -recover/-list/-status.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0063I No regions exist

No configured regions exist.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0064S An error occurred while reading ENQ requests for the region-name region: exception-message

A serious error occurred while attempting to read ENQ requests for the given region.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0065E Region 'region-name' is not configured

No configuration entry exists for the specified region.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0066I No resource locks exist

No resource locks exist.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0067I Recovered resource lock: QNAME='resource-qname', RNAME = 'resource-rname'

Details of a resource lock that has been removed.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0068S An error occurred while attempting to recover resource locks

A serious error occurred while attempting to recover resource locks from the (cross-)region databases.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0069E db-api-type error: 'odbc-oci-error-message'

An ODBC or OCI error occurred attempting to perform a database operation.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0070E -existdb:<db-name> must be specified with -script -provider:ora

dbfhadmin command-line must specify -existdb:<db-name> with -script -provider:ora.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0071E -existdb:<db-name> can only be specified with -script -provider:ora

dbfhadmin command-line only allows -existdb:<db-name> to be specified with -script -provider:ora.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0072E Must specify a type of crossregion, datastore, datastore_funcs or region with -type:<script-type>

dbfhadmin command-line must have a type of crossregion, datastore or region with -type:<script-type>!
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0073I Datastore 'datastore-url' does not need to be upgraded

The datastore does not need to be upgraded as it is already at the latest version level!
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0074E Error creating SQL script file 'file-name' (file-status)

An error occurred attempting to create a SQL script.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0075E Invalid port number specified. Must be in the range 0-65535

An invalid port number was specified.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0076E Cannot specify both -list and -recover with -verify

dbfhadmin command-line includes both -list and -recover with -verify.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0077E Must specify either -list or -recover with -verify

dbfhadmin command-line must include either -list or -recover with -verify.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0078E Must specify -datastore:<url> or -usedb:<instance> with -verify -recover/-list

dbfhadmin command-line must include -datastore:<url> or -usedb:<instance> with -verify -recover/-list.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0079S An error occurred while verifying the integrity of the datastore: exception-message

A serious error occurred while attempting to verify the integrity the datastore database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0060 - ADM0079


ADM0080 - ADM0099

  • ADM0080I Datastore 'datastore-url' has been successfully verified
    The datastore's integrity has been checked and no problems have been detected!
  • ADM0081I Removed orphaned record locks: file name='file-name', folder='folder-name', count=record-locks-count
    Details of a orphaned record locks associated with a given file that have been removed.
  • ADM0082I Removed orphaned record locks: sequential files, count=record-locks-count
    Details of a orphaned record locks associated with (line-)sequential files that have been removed.
  • ADM0083I Datastore 'datastore-url' has been successfully verified, and no recovery required
    The datastore's integrity has been checked, no problems have been detected, so no recovery was required!
  • ADM0084E Must specify -name:<region-name> with -region -status
    dbfhadmin command-line must include -usedb:<instance> with -region -recover/-list/-status.
  • ADM0085S An error occurred while processing the status of region region-name: exception-message
    A serious error occurred while attempting to process the status the given region.
  • ADM0088E Must specify -usedb:<instance> with -diags
    dbfhadmin command-line must include -usedb:<instance> with -diags.
  • ADM0089E Must specify -name:<region-name> with -diags
    dbfhadmin command-line must include -name:<region-name> with -diags.
  • ADM0090S An error occurred while generating diagnostics for the region-name region: exception-message
    A serious error occurred while attempting to generate fiagnostics for the given region.
  • ADM0091I Diagnostics for region 'region-name' written to file 'file-name'
    The region diagnostics were successfully output to a file.
  • ADM0092E Cannot specify both -datastore:<url> or -usedb:<instance> with -verify
    dbfhadmin command-line includes both -datastore:<url> and -usedb:<instance> with -verify.
  • ADM0093E Must specify -name:<region-name> with -verify -usedb:<instance>
    dbfhadmin command-line must include -name:<region-name> with -verify -usedb:<instance>.
  • ADM0094S An error occurred while verifying the integrity of the region: exception-message
    A serious error occurred while attempting to verify the integrity the region and cross-region database.
  • ADM0095I Region 'region-name' has been successfully verified
    The region's integrity has been checked and no problems have been detected!
  • ADM0096I Region 'region-name' has been successfully verified, and no recovery required
    The region's integrity has been checked and no problems have been detected, so no recovery was required!
  • ADM0097I Removed orphaned resource lock and/or associated records: orphaned-record-count
    Details of orphaned resource lock and/or associated records that have been removed.
  • ADM0098I Restored CSA record
    Indication that the CSA record has been restored in the region database.
  • ADM0099W Unable to recover processes for region 'region-name' - not configured
    Region name.
Parent topic: ADM - DBFHADMIN Messages


ADM0080I Datastore 'datastore-url' has been successfully verified

The datastore's integrity has been checked and no problems have been detected!
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0081I Removed orphaned record locks: file name='file-name', folder='folder-name', count=record-locks-count

Details of a orphaned record locks associated with a given file that have been removed.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0082I Removed orphaned record locks: sequential files, count=record-locks-count

Details of a orphaned record locks associated with (line-)sequential files that have been removed.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0083I Datastore 'datastore-url' has been successfully verified, and no recovery required

The datastore's integrity has been checked, no problems have been detected, so no recovery was required!
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0084E Must specify -name:<region-name> with -region -status

dbfhadmin command-line must include -usedb:<instance> with -region -recover/-list/-status.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0085S An error occurred while processing the status of region region-name: exception-message

A serious error occurred while attempting to process the status the given region.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0088E Must specify -usedb:<instance> with -diags

dbfhadmin command-line must include -usedb:<instance> with -diags.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0089E Must specify -name:<region-name> with -diags

dbfhadmin command-line must include -name:<region-name> with -diags.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0090S An error occurred while generating diagnostics for the region-name region: exception-message

A serious error occurred while attempting to generate fiagnostics for the given region.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0091I Diagnostics for region 'region-name' written to file 'file-name'

The region diagnostics were successfully output to a file.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0092E Cannot specify both -datastore:<url> or -usedb:<instance> with -verify

dbfhadmin command-line includes both -datastore:<url> and -usedb:<instance> with -verify.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0093E Must specify -name:<region-name> with -verify -usedb:<instance>

dbfhadmin command-line must include -name:<region-name> with -verify -usedb:<instance>.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0094S An error occurred while verifying the integrity of the region: exception-message

A serious error occurred while attempting to verify the integrity the region and cross-region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0095I Region 'region-name' has been successfully verified

The region's integrity has been checked and no problems have been detected!
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0096I Region 'region-name' has been successfully verified, and no recovery required

The region's integrity has been checked and no problems have been detected, so no recovery was required!
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0097I Removed orphaned resource lock and/or associated records: orphaned-record-count

Details of orphaned resource lock and/or associated records that have been removed.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0098I Restored CSA record

Indication that the CSA record has been restored in the region database.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0099W Unable to recover processes for region 'region-name' - not configured

Region name.
Destination:
Console and standard error.
Parent topic: ADM0080 - ADM0099


ADM0100 - ADM0119

  • ADM0100E Detected orphaned records in Cross-region/Region database. Run dbfhadmin -verify to validate. No recovery done
    Region/Cross-region DB orphaned records detected so cannot run recovery.
  • ADM0101E RC='return-code' from region/cross-region database verification. Cannot perform recovery. Contact Technical Support
    Unexpected RC from verify check.
  • ADM0102E Cannot access DB: 'Region name'. Check configuration and try again
    DbAccess nullptr, cannot access DB.
  • ADM0106S An error occurred while generating diagnostics for the blob-name datastore blob: exception-message
    A serious error occurred while attempting to generate diagnostics for the given datastore blob.
  • ADM0107I Diagnostics for region 'region-name' & for DataStore 'datastore-name' written to file 'file-name'
    The region & datastore diagnostics were successfully output to a file.
Parent topic: ADM - DBFHADMIN Messages


ADM0100E Detected orphaned records in Cross-region/Region database. Run dbfhadmin -verify to validate. No recovery done

Region/Cross-region DB orphaned records detected so cannot run recovery.

Must fixup with -verify first.

Destination:
Console and standard error.
Parent topic: ADM0100 - ADM0119


ADM0101E RC='return-code' from region/cross-region database verification. Cannot perform recovery. Contact Technical Support

Unexpected RC from verify check.
Destination:
Console and standard error.
Parent topic: ADM0100 - ADM0119


ADM0102E Cannot access DB: 'Region name'. Check configuration and try again

DbAccess nullptr, cannot access DB.
Destination:
Console and standard error.
Parent topic: ADM0100 - ADM0119


ADM0106S An error occurred while generating diagnostics for the blob-name datastore blob: exception-message

A serious error occurred while attempting to generate diagnostics for the given datastore blob.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: ADM0100 - ADM0119


ADM0107I Diagnostics for region 'region-name' & for DataStore 'datastore-name' written to file 'file-name'

The region & datastore diagnostics were successfully output to a file.
Destination:
Console and standard error.
Parent topic: ADM0100 - ADM0119


CFG - MFDBFH Configuration Messages

  • CFG0000 - CFG0019
  • CFG00040 - CFG00059
  • CFG0020 - CFG0039
  • CFG0040 - CFG0059
Parent topic: MFDBFH Error Messages


CFG0000 - CFG0019

  • CFG0001E Unrecognized command-line option 'command-line-option'
    An unrecognised command-line option has been entered.
  • CFG0002I Build svn-tag, svn-revision
    MFDBFH product build information.
  • CFG0003E Can only specify one of -add, -delete, -list, -novault, -update, or -vault
    dbfhconfig command-line must only specify one of -add, --delete, -list, -novault, -update, or -vault.
  • CFG0004I The operation completed successfully
    The requested operation completed successfully.
  • CFG0005E Must specify -server:<name> with -update
    dbfhconfig command-line must include -server:<name> with -update.
  • CFG0006E Error attempting to back up 'file-name'
    The requested operation completed successfully.
  • CFG0007S An error occurred while writing configuration file 'configuration-file-name': exception-message
    A serious error occurred while attempting to write an MFDBFH configuration file.
  • CFG0008I Configuration written to file 'configuration-file-name'
    A serious error occurred while attempting to write an MFDBFH configuration file.
  • CFG0009E Must specify -server:<name> with -add
    dbfhconfig command-line must include -server:<name> with -add.
  • CFG0010E Must specify -provider:<db-type> with -add -server:<name>
    dbfhconfig command-line must include -provider with -add -server:<name>.
  • CFG0011E Must specify a provider of 'az', 'db2', 'pg' or 'ss' with -provider:<db-type>
    dbfhconfig command-line must have a provider of azuresqldb, db2, oracle, postgresql or sqlserver with -provider:<db-type>!
  • CFG0012E Server 'server-name' already exists
    Cannot add a new server with a name that already exists.
  • CFG0013E Must specify -type:<dsn-type> with -add -dsn:<name>
    dbfhconfig command-line must include -type:<dsn-type> with -add -dsn:<name>.
  • CFG0014E Must specify a type of 'crossregion', 'database', 'datastore' or 'region' with -type:<dsn-type>
    dbfhconfig command-line must habe a type of 'crossregion', 'database', 'datastore' or 'region' with -type:<dsn-type>.
  • CFG0015E Must specify -name:<name> with -add -dsn:<name> -type:datastore|database|region
    dbfhconfig command-line must include -name:<name> with -add -dsn:<name> -type:datastore|database|region.
  • CFG0016E Server 'server-name' does not exist
    Cannot add a new dsn as the specified server name does not exist.
  • CFG0017E Dsn 'dsn-name' already exists
    Cannot add a new dsn with a name that already exists.
  • CFG0018E Invalid -optio options specified
    dbfhconfig command-line specifies invalid -optio:<options>.
  • CFG0019E Invalid -bitism options specified
    dbfhconfig command-line specifies invalid -bitism:<options>.
Parent topic: CFG - MFDBFH Configuration Messages


CFG0001E Unrecognized command-line option 'command-line-option'

An unrecognised command-line option has been entered.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0002I Build svn-tag, svn-revision

MFDBFH product build information.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0003E Can only specify one of -add, -delete, -list, -novault, -update, or -vault

dbfhconfig command-line must only specify one of -add, --delete, -list, -novault, -update, or -vault.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0004I The operation completed successfully

The requested operation completed successfully.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG00040 - CFG00059

  • CFG00049E Error running OS command. Check the executable is on PATH: os-command-line
    An error occurred when attempting to run an OS command due to the executable not being found.
Parent topic: CFG - MFDBFH Configuration Messages


CFG00049E Error running OS command. Check the executable is on PATH: os-command-line

An error occurred when attempting to run an OS command due to the executable not being found.
Resolution:
Check that the executable specified in the command-line is on PATH.
Destination:
Console and standard error.
Parent topic: CFG00040 - CFG00059


CFG0005E Must specify -server:<name> with -update

dbfhconfig command-line must include -server:<name> with -update.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0006E Error attempting to back up 'file-name'

The requested operation completed successfully.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0007S An error occurred while writing configuration file 'configuration-file-name': exception-message

A serious error occurred while attempting to write an MFDBFH configuration file.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0008I Configuration written to file 'configuration-file-name'

A serious error occurred while attempting to write an MFDBFH configuration file.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0009E Must specify -server:<name> with -add

dbfhconfig command-line must include -server:<name> with -add.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0010E Must specify -provider:<db-type> with -add -server:<name>

dbfhconfig command-line must include -provider with -add -server:<name>.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0011E Must specify a provider of 'az', 'db2', 'pg' or 'ss' with -provider:<db-type>

dbfhconfig command-line must have a provider of azuresqldb, db2, oracle, postgresql or sqlserver with -provider:<db-type>!
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0012E Server 'server-name' already exists

Cannot add a new server with a name that already exists.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0013E Must specify -type:<dsn-type> with -add -dsn:<name>

dbfhconfig command-line must include -type:<dsn-type> with -add -dsn:<name>.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0014E Must specify a type of 'crossregion', 'database', 'datastore' or 'region' with -type:<dsn-type>

dbfhconfig command-line must habe a type of 'crossregion', 'database', 'datastore' or 'region' with -type:<dsn-type>.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0015E Must specify -name:<name> with -add -dsn:<name> -type:datastore|database|region

dbfhconfig command-line must include -name:<name> with -add -dsn:<name> -type:datastore|database|region.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0016E Server 'server-name' does not exist

Cannot add a new dsn as the specified server name does not exist.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0017E Dsn 'dsn-name' already exists

Cannot add a new dsn with a name that already exists.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0018E Invalid -optio options specified

dbfhconfig command-line specifies invalid -optio:<options>.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0019E Invalid -bitism options specified

dbfhconfig command-line specifies invalid -bitism:<options>.
Destination:
Console and standard error.
Parent topic: CFG0000 - CFG0019


CFG0020 - CFG0039

  • CFG0020E Invalid -feature options specified
    dbfhconfig command-line specifies invalid -feature:<options>.
  • CFG0021E Must specify both -user:<user-name> and -password:<pwd>
    dbfhconfig command-line must specify both a user-id and password!
  • CFG0022E Cannot specify -user:<user-name> or -password:<pwd> with -connect:<string>
    dbfhconfig command-line must not specify a user-id or password with -connect:<string>!
  • CFG0024E Cannot specify -type:<dsn-type> with -update -dsn:<name>
    dbfhconfig command-line must not specify -type:<dsn-type> with -update -dsn:<name>.
  • CFG0025E Configuration file 'configuration-file-name' does not exist
    The specified configuration file does not exist.
  • CFG0026E Dsn 'dsn-name' does not exist
    The specified dsn does not exist.
  • CFG0027E An empty -name:<name> value cannot be specified
    The specified dsn does not exist.
  • CFG0028E Cannot specify -provider:<db-type> with -update -server:<name>
    dbfhconfig command-line must not specify -provider:<db-type> with -update -server:<name>.
  • CFG0029E Must specify -server:<name> with -delete
    dbfhconfig command-line must include -server:<name> with -delete.
  • CFG0030I No servers exist
    No server configuration entries exist for dbfhconfig to list.
  • CFG0031I No dsns exist
    No dsns configuration entries exist for dbfhconfig to list.
  • CFG0032S An error occurred while parsing 'configuration-file-name' (line line-number, column column-number): exception-message
    A serious error occurred while attempting to parse the XML file.
  • CFG0033E command-line-option1 cannot be specified with command-line-option2
    dbfhconfig command-line does not allow a command-line option to be specified with the specified action.
  • CFG0034W Secret not found in vault for attribute 'att-name': Server=server-name; Dsn=dsn-name
    The secret associated with the given <dsn/> element attribute does not exist in the vault.
  • CFG0035E Error attempting to read secret from the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name
    The secret associated with the given <dsn/> element attribute does not exist in the vault.
  • CFG0036E Error attempting to write secret to the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name
    The secret associated with the given <dsn/> element attribute could not be written to the vault.
  • CFG0037E Error attempting to delete secret from the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name
    The secret associated with the given <dsn/> element attribute could not be written to the vault.
  • CFG0038E Must specify one of -add, -delete, -list, -novault, -update, or -vault
    dbfhconfig command-line must specify one of -add, --delete, -list, -novault, -update, or -vault.
  • CFG0039I Processing command response file 'file-name'
    The name of the response dbfhdeploy will use to get its commands from.
Parent topic: CFG - MFDBFH Configuration Messages


CFG0020E Invalid -feature options specified

dbfhconfig command-line specifies invalid -feature:<options>.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0021E Must specify both -user:<user-name> and -password:<pwd>

dbfhconfig command-line must specify both a user-id and password!
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0022E Cannot specify -user:<user-name> or -password:<pwd> with -connect:<string>

dbfhconfig command-line must not specify a user-id or password with -connect:<string>!
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0024E Cannot specify -type:<dsn-type> with -update -dsn:<name>

dbfhconfig command-line must not specify -type:<dsn-type> with -update -dsn:<name>.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0025E Configuration file 'configuration-file-name' does not exist

The specified configuration file does not exist.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0026E Dsn 'dsn-name' does not exist

The specified dsn does not exist.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0027E An empty -name:<name> value cannot be specified

The specified dsn does not exist.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0028E Cannot specify -provider:<db-type> with -update -server:<name>

dbfhconfig command-line must not specify -provider:<db-type> with -update -server:<name>.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0029E Must specify -server:<name> with -delete

dbfhconfig command-line must include -server:<name> with -delete.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0030I No servers exist

No server configuration entries exist for dbfhconfig to list.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0031I No dsns exist

No dsns configuration entries exist for dbfhconfig to list.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0032S An error occurred while parsing 'configuration-file-name' (line line-number, column column-number): exception-message

A serious error occurred while attempting to parse the XML file.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0033E command-line-option1 cannot be specified with command-line-option2

dbfhconfig command-line does not allow a command-line option to be specified with the specified action.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0034W Secret not found in vault for attribute 'att-name': Server=server-name; Dsn=dsn-name

The secret associated with the given <dsn/> element attribute does not exist in the vault.
Resolution:
Update the configuration file with a valid attribute value.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0035E Error attempting to read secret from the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name

The secret associated with the given <dsn/> element attribute does not exist in the vault.
Resolution:
Update the configuration file with a valid attribute value.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0036E Error attempting to write secret to the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name

The secret associated with the given <dsn/> element attribute could not be written to the vault.
Resolution:
Review secrets/vault configuration.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0037E Error attempting to delete secret from the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name

The secret associated with the given <dsn/> element attribute could not be written to the vault.
Resolution:
Review secrets/vault configuration.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0038E Must specify one of -add, -delete, -list, -novault, -update, or -vault

dbfhconfig command-line must specify one of -add, --delete, -list, -novault, -update, or -vault.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0039I Processing command response file 'file-name'

The name of the response dbfhdeploy will use to get its commands from.
Destination:
Console and standard error.
Parent topic: CFG0020 - CFG0039


CFG0040 - CFG0059

  • CFG0040E Command response file 'file-name' does not exist
    The specified command response file does not exist.
  • CFG0041E Error reading command response file 'file-name'
    An error occurred attempting to read the contents of the specified command response file.
  • CFG0042I Commands processed = number-of-commands; warnings = number-of-warnings; errors = number-of-errors;
    A summary of the results of the commands processed in the command response file.
  • CFG0043E Invalid command-line-option value specified. Must be zero or positive
    dbfhconfig command-line option specifies an invalid numeric value.
  • CFG0044E Invalid -connopts options specified
    dbfhconfig command-line specifies invalid -connopts:<options>.
  • CFG0045E Invalid -dbopts options specified
    dbfhconfig command-line specifies invalid -dbopts:<options>.
  • CFG0046E Error running OS command. Check the executable is on PATH: os-command-line
    An error occurred when attempting to run an OS command due to the executable not being found.
  • CFG0047E Server 'server-name' does not exist, please make sure to use an existing server for adding a program
    Cannot add a new program name if the specified server name does not exist.
  • CFG0048E Dsn 'dsn-name' does not exists, please make sure to use an existing dsn for adding a program
    Cannot add a new perogram if the specified dsn does not exists.
  • CFG0049E Program 'dsn-name' already exists
    Cannot add a new perogram if the program does exist.
  • CFG0050E Programs node does not exist
    The specified programs node does not exist.
  • CFG0051E Program node does not exist
    The specified program node does not exist.
  • CFG0052E There is a program already present
    A program node with a specified program already exists.
  • CFG0053E Must specify -dsn:<name> with -add -program:<name>
    dbfhconfig command-line must include -dsn:<name> with -add -program:<name>.
  • CFG0054E Must specify -dsn:<name> with -update -program:<name>
    dbfhconfig command-line must include -dsn:<name> with -update -program:<name>.
  • CFG0055E Must specify -dsn:<name> with -delete -program:<name>
    dbfhconfig command-line must include -dsn:<name> with -delete -program:<name>.
Parent topic: CFG - MFDBFH Configuration Messages


CFG0040E Command response file 'file-name' does not exist

The specified command response file does not exist.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0041E Error reading command response file 'file-name'

An error occurred attempting to read the contents of the specified command response file.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0042I Commands processed = number-of-commands; warnings = number-of-warnings; errors = number-of-errors;

A summary of the results of the commands processed in the command response file.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0043E Invalid command-line-option value specified. Must be zero or positive

dbfhconfig command-line option specifies an invalid numeric value.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0044E Invalid -connopts options specified

dbfhconfig command-line specifies invalid -connopts:<options>.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0045E Invalid -dbopts options specified

dbfhconfig command-line specifies invalid -dbopts:<options>.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0046E Error running OS command. Check the executable is on PATH: os-command-line

An error occurred when attempting to run an OS command due to the executable not being found.
Resolution:
Check that the executable specified in the command-line is on PATH.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0047E Server 'server-name' does not exist, please make sure to use an existing server for adding a program

Cannot add a new program name if the specified server name does not exist.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0048E Dsn 'dsn-name' does not exists, please make sure to use an existing dsn for adding a program

Cannot add a new perogram if the specified dsn does not exists.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0049E Program 'dsn-name' already exists

Cannot add a new perogram if the program does exist.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0050E Programs node does not exist

The specified programs node does not exist.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0051E Program node does not exist

The specified program node does not exist.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0052E There is a program already present

A program node with a specified program already exists.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0053E Must specify -dsn:<name> with -add -program:<name>

dbfhconfig command-line must include -dsn:<name> with -add -program:<name>.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0054E Must specify -dsn:<name> with -update -program:<name>

dbfhconfig command-line must include -dsn:<name> with -update -program:<name>.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


CFG0055E Must specify -dsn:<name> with -delete -program:<name>

dbfhconfig command-line must include -dsn:<name> with -delete -program:<name>.
Destination:
Console and standard error.
Parent topic: CFG0040 - CFG0059


DBFH - MFDBFH General Messages

  • DBFH00000 - DBFH00019
  • DBFH00020 - DBFH00039
  • DBFH00040 - DBFH00059
  • DBFH0080 - DBFH0099
Parent topic: MFDBFH Error Messages


DBFH00000 - DBFH00019

  • DBFH00001I Created database 'database-name'
    The named database has been created.
  • DBFH00002W Service Broker is not enabled for database 'database-name'
    SQL Server Service Broker is not enabled for the named database.
  • DBFH00003S An error occurred while setting up the cross-region database: exception-message
    A serious error occurred while attempting to create or access the cross-region database.
  • DBFH00004I Cold start of region 'region-database-name' starting
    Indicating that a region database is being prepared by a region cold start.
  • DBFH00005I database-vendor-name instance created using 'database-version'
    Indicating which version of SQL Server the region database was created with.
  • DBFH00006I Using datasource 'database-datasource'
    Indicating the name of the SQL Server instance being used to host the region database.
  • DBFH00007I Using database 'region-database-name'
    Indicating the name of the region database.
  • DBFH00008I Successfully cold started region 'region-database-name'
    Indicating the the region has been successfully cold started.
  • DBFH00009S An error occurred while cold starting the 'region-database-name' region: exception-message
    A serious error occurred while attempting to create or access the region database.
  • DBFH00010S An error occurred while warm starting the 'region-database-name' region: exception-message
    A serious error occurred while attempting to create or access the region database.
  • DBFH00011I Shutdown of region 'region-database-name' starting
    Indicating that a region database is being shut down.
  • DBFH00012I Successfully shutdown region 'region-database-name'
    Indicating that a region database is being shut down.
  • DBFH00013S An error occurred while shutting down the 'region-database-name' region: exception-message
    A serious error occurred while attempting to access the region database.
  • DBFH00014I Warm start of region 'region-database-name' starting
    Indicating that a region database is being prepared by a region warm start.
  • DBFH00015I Successfully warm started region 'region-database-name'
    Indicating the the region has been successfully warm started.
  • DBFH00016S An error occurred while parsing 'configuration-file-name' (line line-number, column column-number): exception-message
    A serious error occurred while attempting to parse the XML file.
  • DBFH00017W An XA connection has not been registered to allow I/O operations for 'file-url' to occur
    Indicating that an XA connection has not been registered for a recoverable file that has been opened.
  • DBFH00018I Using configuration file: 'configuration-file-name'
    Indicating the name of the configuration file being used.
  • DBFH00019I Using SQL script file folder: 'script-file-folder-name'
    Indicating the name of the configuration file being used.
Parent topic: DBFH - MFDBFH General Messages


DBFH00001I Created database 'database-name'

The named database has been created.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00002W Service Broker is not enabled for database 'database-name'

SQL Server Service Broker is not enabled for the named database.
Resolution:
Manually enable SQL Server Service Broker for the named database (e.g. use SQL Server Management Studio to do this).
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00003S An error occurred while setting up the cross-region database: exception-message

A serious error occurred while attempting to create or access the cross-region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00004I Cold start of region 'region-database-name' starting

Indicating that a region database is being prepared by a region cold start.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00005I database-vendor-name instance created using 'database-version'

Indicating which version of SQL Server the region database was created with.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00006I Using datasource 'database-datasource'

Indicating the name of the SQL Server instance being used to host the region database.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00007I Using database 'region-database-name'

Indicating the name of the region database.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00008I Successfully cold started region 'region-database-name'

Indicating the the region has been successfully cold started.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00009S An error occurred while cold starting the 'region-database-name' region: exception-message

A serious error occurred while attempting to create or access the region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00010S An error occurred while warm starting the 'region-database-name' region: exception-message

A serious error occurred while attempting to create or access the region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00011I Shutdown of region 'region-database-name' starting

Indicating that a region database is being shut down.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00012I Successfully shutdown region 'region-database-name'

Indicating that a region database is being shut down.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00013S An error occurred while shutting down the 'region-database-name' region: exception-message

A serious error occurred while attempting to access the region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00014I Warm start of region 'region-database-name' starting

Indicating that a region database is being prepared by a region warm start.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00015I Successfully warm started region 'region-database-name'

Indicating the the region has been successfully warm started.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00016S An error occurred while parsing 'configuration-file-name' (line line-number, column column-number): exception-message

A serious error occurred while attempting to parse the XML file.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00017W An XA connection has not been registered to allow I/O operations for 'file-url' to occur

Indicating that an XA connection has not been registered for a recoverable file that has been opened.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00018I Using configuration file: 'configuration-file-name'

Indicating the name of the configuration file being used.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00019I Using SQL script file folder: 'script-file-folder-name'

Indicating the name of the configuration file being used.
Destination:
Console and standard error.
Parent topic: DBFH00000 - DBFH00019


DBFH00020 - DBFH00039

  • DBFH00020S Failed to load 'odbc-oci-db2-api-load-library'
    Attempt to load the ODBC/OCI/Db2 API load failed.
  • DBFH00021I Successfully registered XA connection 'xa-connection-name' for datastore 'datastore-url'
    Indicating the the region has been successfully warm started.
  • DBFH00022I Successfully de-registered XA connection 'xa-connection-name' for datastore 'datastore-url'
    Indicating the the region has been successfully warm started.
  • DBFH00023I Build svn-tag, svn-revision
    MFDBFH product build information.
  • DBFH00024S Failed to load Secrets/Vault API
    Attempt to load the Secrets/Vault API load failed.
  • DBFH00025W Failed to read secret from the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name
    The secret associated with the given <dsn/> element attribute does not exist in the vault.
  • DBFH00026E db-api-type error: 'odbc-oci-error-message'
    An ODBC or OCI error occurred attempting to perform a database operation.
  • DBFH00027E I/O error: io-error-message
    General I/O failure.
  • DBFH00028W Configuration file 'configuration-file-name' does not exist
    The specified configuration file does not exist.
  • DBFH00029W SQL script file folder 'script-file-folder-name' does not exist
    Indicating the name of the configuration file being used.
  • DBFH00030E Required stored procedure 'stored-procedure-name' does not exist
    The specified stored procedure required to warm start a region does not exist.
  • DBFH00031W The region must be cold started
    The region must be cold started to install the necessary database objects required for a subsequent warm start.
  • DBFH00032S MFDBFH requires the multi-threaded COBOL run-time system
    MFDBFH is unable to perform the operation is the application is not being run with the multi-threaded COBOL run-time system.
  • DBFH00033S SQL script file 'sql-script-file-name' does not exist
    Attempt to load the SQL script file failed.
  • DBFH00034S MFDBFH failed to upgrade the datastore. Manual upgrade required. Use 'dbfhadmin -upgrade -datastore datastore-url' to generate an upgrade script and run the script as a user with sysadmin privileges
    MFDBFH failed to auto-upgrade the datastore.
  • DBFH00035W Record lock strategy changed for file 'sql-url' Already opened by PID process-id on host 'host-name' with 'existing-record-lock-strategy'. Requested 'requested-record-lock-strategy'
    Attempt to open a file specifying a conflicting record lock strategy.
  • DBFH00036E Cannot cold start region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'
    The region database cannot be cold started as it has already been started by another process.
  • DBFH00037E Cannot warm start region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'
    The region database cannot be warm started as it has already been started by another process.
  • DBFH00038E Cannot stop region database 'region-database-name'. Not started
    The region database cannot be stopped as it has not been started.
  • DBFH00039W Force cold start of region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'
    The region database is being force cold started, but has already been started by another process.
Parent topic: DBFH - MFDBFH General Messages


DBFH00020S Failed to load 'odbc-oci-db2-api-load-library'

Attempt to load the ODBC/OCI/Db2 API load failed.
Resolution:
Ensure the ODBC, OCI, or Db2 API library is installed and the load library is in a folder on PATH (Windows) or LD_LIBRARY_PATH (Linux).
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00021I Successfully registered XA connection 'xa-connection-name' for datastore 'datastore-url'

Indicating the the region has been successfully warm started.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00022I Successfully de-registered XA connection 'xa-connection-name' for datastore 'datastore-url'

Indicating the the region has been successfully warm started.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00023I Build svn-tag, svn-revision

MFDBFH product build information.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00024S Failed to load Secrets/Vault API

Attempt to load the Secrets/Vault API load failed.
Resolution:
Ensure the Secrets/Vault API is installed and is in a folder on PATH (Windows) or LD_LIBRARY_PATH (Linux).
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00025W Failed to read secret from the vault for attribute 'attr-name' (RC=return-code): Server=server-name; Dsn=dsn-name

The secret associated with the given <dsn/> element attribute does not exist in the vault.
Resolution:
Update the configuration file with a valid attribute value.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00026E db-api-type error: 'odbc-oci-error-message'

An ODBC or OCI error occurred attempting to perform a database operation.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00027E I/O error: io-error-message

General I/O failure.
Resolution:
Review the message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00028W Configuration file 'configuration-file-name' does not exist

The specified configuration file does not exist.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00029W SQL script file folder 'script-file-folder-name' does not exist

Indicating the name of the configuration file being used.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00030E Required stored procedure 'stored-procedure-name' does not exist

The specified stored procedure required to warm start a region does not exist.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00031W The region must be cold started

The region must be cold started to install the necessary database objects required for a subsequent warm start.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00032S MFDBFH requires the multi-threaded COBOL run-time system

MFDBFH is unable to perform the operation is the application is not being run with the multi-threaded COBOL run-time system.
Resolution:
Re-link, or run, the application with the multi-threaded COBOL run-time system.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00033S SQL script file 'sql-script-file-name' does not exist

Attempt to load the SQL script file failed.
Resolution:
Ensure the MFDBFH_SCRIPT_DIR environment variable is correctly set.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00034S MFDBFH failed to upgrade the datastore. Manual upgrade required. Use 'dbfhadmin -upgrade -datastore datastore-url' to generate an upgrade script and run the script as a user with sysadmin privileges

MFDBFH failed to auto-upgrade the datastore.

This is usually due to insufficient user privileges.

Resolution:
Use the 'dbfhadmin -upgrade -datastore <datastore-url>' to generate an upgrade script, and run the script as a user with sysadmin privileges.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00035W Record lock strategy changed for file 'sql-url' Already opened by PID process-id on host 'host-name' with 'existing-record-lock-strategy'. Requested 'requested-record-lock-strategy'

Attempt to open a file specifying a conflicting record lock strategy.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00036E Cannot cold start region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'

The region database cannot be cold started as it has already been started by another process.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00037E Cannot warm start region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'

The region database cannot be warm started as it has already been started by another process.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00038E Cannot stop region database 'region-database-name'. Not started

The region database cannot be stopped as it has not been started.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00039W Force cold start of region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'

The region database is being force cold started, but has already been started by another process.
Destination:
Console and standard error.
Parent topic: DBFH00020 - DBFH00039


DBFH00040 - DBFH00059

  • DBFH00040W Force warm start of region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'
    The region database is being warm started, but has already been started by another process.
  • DBFH00041W Connected database name 'connected-database-name' and configured database name 'configured-database-name' are different (dsn entry ='dsn-entry-name')
    The name of the database connected to and the name of the database specified in the configuration file do not match.
  • DBFH00042S Failed to load configuration entry API
    Attempt to load the configuration entry API failed.
  • DBFH00043W A heartbeat interval of heartbeat-interval seconds has been configured. This may cause unwanted delays to region recovery
    Specifying a heartbeat interval of >15 seconds may cause unwanted delays when region recovery is required.
  • DBFH00044S An error occurred while verifying the integrity of region resources in the cross-region database: exception-message
    A serious error occurred while attempting to verify the integrity of region resources in the cross-region database.
  • DBFH00045W Removed orphaned resource lock and/or associated records: orphaned-record-count
    Details of orphaned resource lock and/or associated records that have been removed.
  • DBFH00046S An error occurred while recovering region resources in the cross-region database: exception-message
    A serious error occurred while attempting to recover region resources in the cross-region database.
  • DBFH00047W Removed orphaned record locks: orphaned-record-lock-count (datastore-url)
    Details of orphaned record locks that have been removed.
  • DBFH00048W Auto-closed closed-files-count files in datastore datastore-url
    Details of the number of files that have been automatically closed.
  • DBFH00050E Error connecting to database during region recovery processing
    Attempt to connect to region database whilst running region recovery failed.
  • DBFH00052W Datastore 'datastore-url' cannot be accessed
    Attempt to access this datastore failed.
Parent topic: DBFH - MFDBFH General Messages


DBFH00040W Force warm start of region database 'region-database-name' Already started by 'program-name (PID process-id)' on host 'host-name'

The region database is being warm started, but has already been started by another process.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00041W Connected database name 'connected-database-name' and configured database name 'configured-database-name' are different (dsn entry ='dsn-entry-name')

The name of the database connected to and the name of the database specified in the configuration file do not match.
Resolution:
Review the MFDBFH configuration and correct the corresponding <dsn/> entry's database connection details.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00042S Failed to load configuration entry API

Attempt to load the configuration entry API failed.
Resolution:
Ensure the configuration entry API is installed and is in a folder on PATH (Windows) or LD_LIBRARY_PATH (Linux).
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00043W A heartbeat interval of heartbeat-interval seconds has been configured. This may cause unwanted delays to region recovery

Specifying a heartbeat interval of >15 seconds may cause unwanted delays when region recovery is required.
Resolution:
A heartbeat interval of <= 15 seconds is recommended (default 5 seconds).
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00044S An error occurred while verifying the integrity of region resources in the cross-region database: exception-message

A serious error occurred while attempting to verify the integrity of region resources in the cross-region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00045W Removed orphaned resource lock and/or associated records: orphaned-record-count

Details of orphaned resource lock and/or associated records that have been removed.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00046S An error occurred while recovering region resources in the cross-region database: exception-message

A serious error occurred while attempting to recover region resources in the cross-region database.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00047W Removed orphaned record locks: orphaned-record-lock-count (datastore-url)

Details of orphaned record locks that have been removed.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00048W Auto-closed closed-files-count files in datastore datastore-url

Details of the number of files that have been automatically closed.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00050E Error connecting to database during region recovery processing

Attempt to connect to region database whilst running region recovery failed.
Resolution:
Ensure connection to the database is available.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH00052W Datastore 'datastore-url' cannot be accessed

Attempt to access this datastore failed.
Resolution:
Check if this datastore is needed, if so review host database along with relevant connection information.
Destination:
Console and standard error.
Parent topic: DBFH00040 - DBFH00059


DBFH0080 - DBFH0099

  • DBFH0086W Force stopped region database 'region-database-name' Previously started by 'program-name (PID process-id)' on host 'host-name'
    The region database has been force stopped, but had previously been started by another process.
  • DBFH0087I Region database 'region-database-name' is already stopped
    The region database is already in a stopped state.
Parent topic: DBFH - MFDBFH General Messages


DBFH0086W Force stopped region database 'region-database-name' Previously started by 'program-name (PID process-id)' on host 'host-name'

The region database has been force stopped, but had previously been started by another process.
Destination:
Console and standard error.
Parent topic: DBFH0080 - DBFH0099


DBFH0087I Region database 'region-database-name' is already stopped

The region database is already in a stopped state.
Destination:
Console and standard error.
Parent topic: DBFH0080 - DBFH0099


DEP - DBFHDEPLOY Messages

  • DEP0000 - DEP0019
  • DEP0020 - DEP0039
  • DEP0040 - DEP0059
  • DEP0100 - DEP0119
Parent topic: MFDBFH Error Messages


DEP0000 - DEP0019

  • DEP0001E Invalid data file URL for a create or list operation. The URL must be of the form: sql://host[/instance]/datastore[?folder=folder-spec]
    An invalid URL has been specified when using the dbfhdeploy tool's create or list operations.
  • DEP0002E Invalid data file URL for an add, delete, extract, or keys operation. The URL must be of the form: sql://host[/instance]/datastore/filename[?folder=folder-spec]
    An invalid URL has been specified when using the dbfhdeploy tool's add, delete, extract, or keys operations.
  • DEP0003E This action requires a full URL, including a file name
    An invalid URL has been specified when using the dbfhdeploy tool's with the current operation.
  • DEP0004E Datastore 'datastore-name' is not configured
    No configuration entry exists for the datastore specified by the URL.
  • DEP0005E Datastore 'datastore-name' does not exist
    The datastore specified by the URL does not exist.
  • DEP0006E An error occurred attempting to connect to datastore 'datastore-name': exception-message
    An error occurred when attempting to connect to the datastore specified by the URL.
  • DEP0007I The operation completed successfully
    The requested operation completed successfully.
  • DEP0008E Unable to perform the requested operation
    Unable to perform the requested operation.
  • DEP0009E File 'file-name' not found
    The file does not exist.
  • DEP0010I Uploading 'disk-file-name' to 'database-file-url'
    File upload details.
  • DEP0011E Upload failed with file status file-status
    An error occurred attempting to upload a file to a datastore.
  • DEP0012E Datastore 'datastore-name' already exists
    The datastore specified by the URL already exists.
  • DEP0013E Delete failed with file status file-status
    An error occurred attempting to delete a file from a datastore.
  • DEP0014E File 'database-file-url' not found in datastore
    The file specified by the URL does not exist in the datastore.
  • DEP0015I Downloading 'database-file-URL' from 'disk-file-name'
    File download details.
  • DEP0016E Download failed with file status file-status
    An error occurred attempting to download a file from a datastore.
  • DEP0017E Upgrade failed with file status file-status
    An error occurred attempting to upgrade a file in a datastore.
  • DEP0018E List failed with file status file-status
    An error occurred attempting to list files in a datastore folder.
  • DEP0019I No files/folders
    No files/folders were found in the specified datastore folder.
Parent topic: DEP - DBFHDEPLOY Messages


DEP0001E Invalid data file URL for a create or list operation. The URL must be of the form: sql://host[/instance]/datastore[?folder=folder-spec]

An invalid URL has been specified when using the dbfhdeploy tool's create or list operations.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0002E Invalid data file URL for an add, delete, extract, or keys operation. The URL must be of the form: sql://host[/instance]/datastore/filename[?folder=folder-spec]

An invalid URL has been specified when using the dbfhdeploy tool's add, delete, extract, or keys operations.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0003E This action requires a full URL, including a file name

An invalid URL has been specified when using the dbfhdeploy tool's with the current operation.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0004E Datastore 'datastore-name' is not configured

No configuration entry exists for the datastore specified by the URL.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0005E Datastore 'datastore-name' does not exist

The datastore specified by the URL does not exist.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0006E An error occurred attempting to connect to datastore 'datastore-name': exception-message

An error occurred when attempting to connect to the datastore specified by the URL.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0007I The operation completed successfully

The requested operation completed successfully.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0008E Unable to perform the requested operation

Unable to perform the requested operation.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0009E File 'file-name' not found

The file does not exist.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0010I Uploading 'disk-file-name' to 'database-file-url'

File upload details.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0011E Upload failed with file status file-status

An error occurred attempting to upload a file to a datastore.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0012E Datastore 'datastore-name' already exists

The datastore specified by the URL already exists.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0013E Delete failed with file status file-status

An error occurred attempting to delete a file from a datastore.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0014E File 'database-file-url' not found in datastore

The file specified by the URL does not exist in the datastore.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0015I Downloading 'database-file-URL' from 'disk-file-name'

File download details.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0016E Download failed with file status file-status

An error occurred attempting to download a file from a datastore.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0017E Upgrade failed with file status file-status

An error occurred attempting to upgrade a file in a datastore.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0018E List failed with file status file-status

An error occurred attempting to list files in a datastore folder.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0019I No files/folders

No files/folders were found in the specified datastore folder.
Destination:
Console and standard error.
Parent topic: DEP0000 - DEP0019


DEP0020 - DEP0039

  • DEP0020I 1 file/folder
    1 file/folder was found in the specified datastore folder.
  • DEP0021I number-files/folders files/folders
    n files/folders were found in the specified datastore folder.
  • DEP0022E Database server instance 'server-name' is not configured
    The database server instance specified is not configured in the MFDBFH configuration file.
  • DEP0023E Folder 'database-folder-url' not found in datastore
    The folder specified by the URL does not exist in the datastore.
  • DEP0024I Deleted 'database-file/folder-URL'
    The file/folder specified by the URL was successfully deleted from the datastore.
  • DEP0025E Failed to delete 'database-file/folder-url' (file-status)
    An error occurred attempting to delete file/folder specified by the URL from the datastore.
  • DEP0026I Files deleted: number-files-deleted; Sub-folders deleted: number-sub-folders-deleted
    The number of files and sub-folders successfully deleted from the datastore.
  • DEP0027I Files deleted: number-files-deleted
    The number of files successfully deleted from the datastore.
  • DEP0028I Processing command response file 'file-name'
    The name of the response dbfhdeploy will use to get its commands from.
  • DEP0029E Command response file 'file-name' does not exist
    The specified command response file does not exist.
  • DEP0030E Error reading command response file 'file-name'
    An error occurred attempting to read the contents of the specified command response file.
  • DEP0031I Commands processed = number-of-commands; warnings = number-of-warnings; errors = number-of-errors;
    A summary of the results of the commands processed in the command response file.
  • DEP0032E db-api-type error: 'odbc-oci-error-message'
    An ODBC or OCI error occurred attempting to perform a database operation.
  • DEP0033E I/O error: io-error-message
    General I/O failure.
  • DEP0034E The 'keys' action requires either 'list', or '<key-id>:<key-op>'
    An invalid option has been specified with the 'keys' action.
  • DEP0035E The 'keys' action '<key-id>:<key-op>' is invalid
    An invalid <key-id> or <key-op> has been specified with the 'keys' action.
  • DEP0036E 'database-file-url' does not have any keys
    The specified file does not have any keys.
  • DEP0037E Unable to update the primary key
    It is invalid to attempt to update a file's primary key.
  • DEP0038E 'database-file-url' only has number-of-keys alternate keys defined
    The specified file does not have an alternate key with the specified id.
  • DEP0039E Retrieving duplicate record counts failed with file status file-status
    An error occurred attempting to delete a file from a datastore.
Parent topic: DEP - DBFHDEPLOY Messages


DEP0020I 1 file/folder

1 file/folder was found in the specified datastore folder.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0021I number-files/folders files/folders

n files/folders were found in the specified datastore folder.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0022E Database server instance 'server-name' is not configured

The database server instance specified is not configured in the MFDBFH configuration file.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0023E Folder 'database-folder-url' not found in datastore

The folder specified by the URL does not exist in the datastore.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0024I Deleted 'database-file/folder-URL'

The file/folder specified by the URL was successfully deleted from the datastore.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0025E Failed to delete 'database-file/folder-url' (file-status)

An error occurred attempting to delete file/folder specified by the URL from the datastore.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0026I Files deleted: number-files-deleted; Sub-folders deleted: number-sub-folders-deleted

The number of files and sub-folders successfully deleted from the datastore.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0027I Files deleted: number-files-deleted

The number of files successfully deleted from the datastore.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0028I Processing command response file 'file-name'

The name of the response dbfhdeploy will use to get its commands from.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0029E Command response file 'file-name' does not exist

The specified command response file does not exist.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0030E Error reading command response file 'file-name'

An error occurred attempting to read the contents of the specified command response file.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0031I Commands processed = number-of-commands; warnings = number-of-warnings; errors = number-of-errors;

A summary of the results of the commands processed in the command response file.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0032E db-api-type error: 'odbc-oci-error-message'

An ODBC or OCI error occurred attempting to perform a database operation.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0033E I/O error: io-error-message

General I/O failure.
Resolution:
Review the message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0034E The 'keys' action requires either 'list', or '<key-id>:<key-op>'

An invalid option has been specified with the 'keys' action.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0035E The 'keys' action '<key-id>:<key-op>' is invalid

An invalid <key-id> or <key-op> has been specified with the 'keys' action.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0036E 'database-file-url' does not have any keys

The specified file does not have any keys.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0037E Unable to update the primary key

It is invalid to attempt to update a file's primary key.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0038E 'database-file-url' only has number-of-keys alternate keys defined

The specified file does not have an alternate key with the specified id.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0039E Retrieving duplicate record counts failed with file status file-status

An error occurred attempting to delete a file from a datastore.
Destination:
Console and standard error.
Parent topic: DEP0020 - DEP0039


DEP0040 - DEP0059

  • DEP0040E Updating the key definition failed with file status file-status
    An error occurred attempting to delete a file from a datastore.
  • DEP0041E Folder already exists
    The folder specified by the URL already exists.
  • DEP0042E Destination file name is empty
    Destination file name is empty.
Parent topic: DEP - DBFHDEPLOY Messages


DEP0040E Updating the key definition failed with file status file-status

An error occurred attempting to delete a file from a datastore.
Destination:
Console and standard error.
Parent topic: DEP0040 - DEP0059


DEP0041E Folder already exists

The folder specified by the URL already exists.
Destination:
Console and standard error.
Parent topic: DEP0040 - DEP0059


DEP0042E Destination file name is empty

Destination file name is empty.
Resolution:
Review the formating of the deploy command, user could be trying to create folder and upload file at the same time.
Destination:
Console and standard error.
Parent topic: DEP0040 - DEP0059


DEP0100 - DEP0119

  • DEP0103E Datastore 'datastore-name' does not exist
    The datastore specified by the URL does not exist.
  • DEP0104E An error occurred attempting to connect to datastore 'datastore-name': exception-message
    An error occurred when attempting to connect to the datastore specified by the URL.
  • DEP0105E Datastore 'datastore-name' is not configured
    No configuration entry exists for the datastore specified by the URL.
Parent topic: DEP - DBFHDEPLOY Messages


DEP0103E Datastore 'datastore-name' does not exist

The datastore specified by the URL does not exist.
Destination:
Console and standard error.
Parent topic: DEP0100 - DEP0119


DEP0104E An error occurred attempting to connect to datastore 'datastore-name': exception-message

An error occurred when attempting to connect to the datastore specified by the URL.
Destination:
Console and standard error.
Parent topic: DEP0100 - DEP0119


DEP0105E Datastore 'datastore-name' is not configured

No configuration entry exists for the datastore specified by the URL.
Destination:
Console and standard error.
Parent topic: DEP0100 - DEP0119


VGN - DBFHVIEW Messages

  • VGN0000 - VGN0019
  • VGN0020 - VGN0039
Parent topic: MFDBFH Error Messages


VGN0000 - VGN0019

  • VGN0001E Unrecognized command-line option 'Command-line option'
    An unrecognised command-line option has been entered.
  • VGN0002I The operation completed successfully
    The requested operation completed successfully.
  • VGN0003E Must specify -struct:<file-name> with -create
    dbfhview command-line must include -struct:<file-name> with -create.
  • VGN0004E Must specify -file:<file-url> with -create, or -delete
    dbfhview command-line must include -file:<file-url> with -create, or -delete.
  • VGN0005E Must specify -name:<view-name> with -create, or -delete
    dbfhview command-line must include -name:<view-name> with -create, or -delete.
  • VGN0006E Must specify -create, -delete, or -list
    dbfhconfig command-line must specify -create, -delete, or -list.
  • VGN0007E Command response file 'file-name' does not exist
    The specified command response file does not exist.
  • VGN0008E Error reading command response file 'file-name'
    An error occurred attempting to read the contents of the specified command response file.
  • VGN0009I Processing command response file 'file-name'
    The name of the response dbfhview will use to get its commands from.
  • VGN0010I Commands processed = number-of-commands; warnings = number-of-warnings; errors = number-of-errors;
    A summary of the results of the commands processed in the command response file.
  • VGN0011E Can only specify one of -create, -delete, or -list
    dbfhview command-line must only specify one of -create, -delete, or -list.
  • VGN0012E Can only specify one of -file or -struct with -list
    dbfhview command-line must only specify one of -file or -struct with -list.
  • VGN0013E Must specify one of -file or -struct with -list
    dbfhview command-line must specify one of -file or -struct with -list.
  • VGN0014E Error processing structure file (file-name)
    An error occurred while processing the structure file.
  • VGN0015I No structure definitions exist
    No structure definitions exist in the structure file for dbfhview to list.
  • VGN0016E Requested structure definition does not exist
    The request structure definition does not exist in the specified structure file.
  • VGN0017I Using structure definition 'structure-definition-name'
    No structure definitions exist in the structure file for dbfhview to list.
  • VGN0018E Invalid file URL specified
    An invalid (syntactically incorrect) file URL was specified.
  • VGN0019E Datastore 'datastore-url' is not configured
    No configuration entry exists for the specified datastore.
Parent topic: VGN - DBFHVIEW Messages


VGN0001E Unrecognized command-line option 'Command-line option'

An unrecognised command-line option has been entered.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0002I The operation completed successfully

The requested operation completed successfully.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0003E Must specify -struct:<file-name> with -create

dbfhview command-line must include -struct:<file-name> with -create.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0004E Must specify -file:<file-url> with -create, or -delete

dbfhview command-line must include -file:<file-url> with -create, or -delete.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0005E Must specify -name:<view-name> with -create, or -delete

dbfhview command-line must include -name:<view-name> with -create, or -delete.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0006E Must specify -create, -delete, or -list

dbfhconfig command-line must specify -create, -delete, or -list.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0007E Command response file 'file-name' does not exist

The specified command response file does not exist.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0008E Error reading command response file 'file-name'

An error occurred attempting to read the contents of the specified command response file.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0009I Processing command response file 'file-name'

The name of the response dbfhview will use to get its commands from.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0010I Commands processed = number-of-commands; warnings = number-of-warnings; errors = number-of-errors;

A summary of the results of the commands processed in the command response file.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0011E Can only specify one of -create, -delete, or -list

dbfhview command-line must only specify one of -create, -delete, or -list.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0012E Can only specify one of -file or -struct with -list

dbfhview command-line must only specify one of -file or -struct with -list.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0013E Must specify one of -file or -struct with -list

dbfhview command-line must specify one of -file or -struct with -list.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0014E Error processing structure file (file-name)

An error occurred while processing the structure file.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0015I No structure definitions exist

No structure definitions exist in the structure file for dbfhview to list.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0016E Requested structure definition does not exist

The request structure definition does not exist in the specified structure file.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0017I Using structure definition 'structure-definition-name'

No structure definitions exist in the structure file for dbfhview to list.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0018E Invalid file URL specified

An invalid (syntactically incorrect) file URL was specified.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0019E Datastore 'datastore-url' is not configured

No configuration entry exists for the specified datastore.
Destination:
Console and standard error.
Parent topic: VGN0000 - VGN0019


VGN0020 - VGN0039

  • VGN0020E Error creating SQL script file (file-name)
    An error occurred while attempting to create the SQL script file.
  • VGN0021I Definition for view 'view-name' written to SQL script file 'file-name'
    The SQL view definition was successfully output to a file.
  • VGN0022I View 'view-name' installed in datastore 'datastore-name'
    The SQL view was successfully installed in the datastore.
  • VGN0023E File 'file-name' not found
    The file does not exist.
  • VGN0024E Create failed with file status file-status
    An error occurred attempting to create a file view.
  • VGN0025E List failed with file status file-status
    An error occurred attempting to list file views.
  • VGN0026I No views exist
    No views are associated with the file for dbfhview to list.
  • VGN0027E Delete failed with file status file-status
    An error occurred attempting to delete a file view.
  • VGN0028W File 'file-name' does not have associated view 'view-name'
    The view does not exist.
  • VGN0029E db-api-type error: 'odbc-oci-error-message'
    An ODBC or OCI error occurred attempting to perform a database operation.
  • VGN0030W Function 'function-name' not found. Default column type defined for 'field-name'
    The named function does not exist in the datastore database.
  • VGN0031W Function 'function-name' found, but DbfhFuncDB2 not installed. Default column type defined for 'field-name'
    The named function exists in the datastore database, but cannot be accessed because DbfhFuncsDB2.dll/.so is not installed on the database server.
  • VGN0032W Maximum DECIMAL precision supported by Db2 is 31. Generating 'field-name' as VARCHAR
    The picture for the field exceeds the maximum precision supported by the Db2 DECIMAL type.
  • VGN0033E I/O error: io-error-message
    General I/O failure.
Parent topic: VGN - DBFHVIEW Messages


VGN0020E Error creating SQL script file (file-name)

An error occurred while attempting to create the SQL script file.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0021I Definition for view 'view-name' written to SQL script file 'file-name'

The SQL view definition was successfully output to a file.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0022I View 'view-name' installed in datastore 'datastore-name'

The SQL view was successfully installed in the datastore.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0023E File 'file-name' not found

The file does not exist.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0024E Create failed with file status file-status

An error occurred attempting to create a file view.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0025E List failed with file status file-status

An error occurred attempting to list file views.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0026I No views exist

No views are associated with the file for dbfhview to list.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0027E Delete failed with file status file-status

An error occurred attempting to delete a file view.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0028W File 'file-name' does not have associated view 'view-name'

The view does not exist.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0029E db-api-type error: 'odbc-oci-error-message'

An ODBC or OCI error occurred attempting to perform a database operation.
Resolution:
Review the exception message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0030W Function 'function-name' not found. Default column type defined for 'field-name'

The named function does not exist in the datastore database.
Resolution:
Run "dbfhadmin -script -type:datastore_funcs ..." to generate the function definitions, and then run the script to install them in the database. DbfhFuncsDB2.dll/.so also needs to be installed on the database server (typically copied to the sqllib\function (Windows), or sqllib/function (Linux) folder).
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0031W Function 'function-name' found, but DbfhFuncDB2 not installed. Default column type defined for 'field-name'

The named function exists in the datastore database, but cannot be accessed because DbfhFuncsDB2.dll/.so is not installed on the database server.
Resolution:
DbfhFuncsDB2.dll/.so needs to be installed on the database server (typically copied to the sqllib\function (Windows), or sqllib/function (Linux) folder).
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0032W Maximum DECIMAL precision supported by Db2 is 31. Generating 'field-name' as VARCHAR

The picture for the field exceeds the maximum precision supported by the Db2 DECIMAL type.

The column associated with the field is generated as a VARCHAR instead.

Resolution:
Review generated script for the view.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


VGN0033E I/O error: io-error-message

General I/O failure.
Resolution:
Review the message as this should provide an indication as to the cause of the problem. Running with CTF-enabled for the MFDBFH component may provide additional information about the problem.
Destination:
Console and standard error.
Parent topic: VGN0020 - VGN0039


MFDBFH (Known Issues)

There are a number of limitations to the Micro Focus Database File Handler currently. Some of the limitations may be permanent due to the database technologies in use, and some may just be temporary as the database file handling capabilities are developed.

The following is a list of current limitations:

  • The order in which duplicate keys in an indexed file are returned differs between disk-based and database-hosted files. For files stored on disk, duplicate keys are always returned in the order they were written in; for files stored in a database, they are returned in the order of the associated primary key.
  • The supported key types are currently limited to alphanumeric, binary, and numeric.
  • PostgreSQL does not support EBCDIC collating sequences - see Configure Datastores for Db2 for a way to work around this.
Parent topic: Database File Handling and Enterprise Server Region Database Management
Related concepts
Configure Datastores for Db2


Tools

  • Command Prompts
  • 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.
  • Terminal Emulation
Parent topic: Micro Focus Enterprise Test Server 10.0


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 Configuration File for CTF.
  • The emitters to produce the tracing information (such as text or binary). See Emitter List.
  • To Enable CTF Tracing
  • CTF Trace File Formats
  • Analyzing CTF Trace
  • Components Traced by CTF
  • Configuration File for CTF
  • Emitter List
  • Dynamic Tracing
  • Using the CTF Library Routines
    There are a number of library routines that allow you to add your own events to an application during the development phase.
  • CTF Tracing Examples
Parent topic: Tools
Parent topic: Diagnostics in Enterprise Server
Related concepts
RM Switch Module Diagnostics


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\x.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, for a .NET application targeting the .NET Framework:

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

For an application targeting .NET, replace MicroFocus.COBOL.Runtime.Win32 with MicroFocus.COBOL.Runtime.Net.

Note: If the MFTRACE_CONFIG variable is set, CTF uses it in preference to an app.config file.
Parent topic: Consolidated Tracing Facility


CTF Trace File Formats

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

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

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

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

  • Compressed format. Usually at least 50% the size of an equivalent text-format trace file.
  • No record format needs to be specified before tracing begins. All relevant information about a trace event is recorded, such as the process id, thread id, date, time, component id, event id, trace data and so on.
Parent topic: Consolidated Tracing Facility
Related information
Example CTF Configuration Files
TEXTFILE Emitter Properties
BINFILE Emitter Properties


Analyzing CTF Trace

CTF in text format is a list of data events that might not make much sense. In the product installation directory, under %COBDIR%\etc\mftrace\annotations, there are XML files that explain what each data item should refer to. Each XML file is named after the component you trace in the CTF configuration file. In general, the format of an annotations file lists the arguments as indexes, and what value that index is corresponds to what that data item refers to. An example of this is below:

CTF Analyze 1

And the example line in the textfile CTF:

CTF Analyze 2

You would normally have a timestamp, a thread id and then the component name. After that is the 'event', which is 6 here, and the data after the colon is what corresponds to the indexes in the annotations file. So in this example, we know this is a program entry, with flags = 81, program attributes = 0, a program name of dfh0mq and the entry point is MqAccess.

This can sometimes still be difficult to decipher, so instead the preferred way is to generate CTF as binary format. When you format the binary CTF into textfile, or view it in CTF viewer, it uses these annotations file to annotate the entries so you do not need to do the above.

Parent topic: Consolidated Tracing Facility


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.dbg Properties
    This component provides behavior of low-level debugging technology.
  • mf.idmr Properties
    This component handles the interface mapping between a SOAP/BINP message and COBOL fields.
  • mf.mfdbfh Properties
    This component provides tracing for activity undertaken by the Micro Focus Database File Handler.
  • 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: Consolidated Tracing Facility
Related concepts
RM Switch Module Diagnostics


mf.cci Properties

This component traces CCI function calls made by applications. As well as setting the following in the ctf.cfg file:

mftrace.level.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 | 0 | Switch load file loaded
START | Start of work units | DEBUG | 1 | Unit of work started
END | End of work units | DEBUG | 2 | 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 | 4 | MQI channel to the server queue manager closed
COMMIT | Commit decisions | DEBUG | 5 | Decision made to commit the unit of work
ROLLBACK | Rollback decisions | DEBUG | 6 | Decision made to rollback the unit of work
PREPARE | Commit preparation | DEBUG | 7 | Preparation to commit the unit of work started
OPEN-dfheibmq | XA OPEN | INFO | 8 | Traces LOAD of dfheibmq (where all the MQOPEN/MQPUT, etc... calls are).
ORIGINAL | XA OPEN | INFO | 9 | Original OPEN string
MODIFIED | XA OPEN | INFO | 10 | Modified Open String with full path for casaxlib.
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.

ALL
Enables or disables all of the other properties.
MSSQL
SQL Server switch module events:
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 | XA_START
INFO | 6 | Enlist in DTC transaction
INFO | 7 | XA_COMMIT
INFO | 8 | XA_ROLLBACK
INFO | 9 | XA_CLOSE
INFO | 10 | XA_END
INFO | 11 | De-enlist from DTC transaction
INFO | 12 | XA_OPEN
INFO | 13 | XA_CLOSE
INFO | 14 | XA_RECOVER
INFO | 15 | XA_FORGET
INFO | 16 | XA_COMPLETE
INFO | 17 | Register an XA data source with the current transaction
INFO | 18 | XA_PREPARE
ODBC
Generic ODBC switch module events:
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 | RESET CONNECTION
INFO | 31 | EXECUTE AS
INFO | 32 | REVERT
INFO | 33 | SET XA TRIGGER (for dynamic registration)
INFO | 34 | SYNC ROLLBACK
INFO | 35 | RESET HOST CONNECTION
INFO | 36 | SET CURRENT CONNECTION
INFO | 37 | SET ISOLATION LEVEL
DB2
DB2 switch module events:
Event Level | Event ID | Event Description
INFO | 41 | XA_START
INFO | 42 | XA_END
INFO | 43 | XA_OPEN
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
INFO | 49 | Register an XA data source with the current transaction
INFO | 51 | SET ISOLATION LEVEL
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
ORA
Oracle switch module events:
Event Level | Event ID | Event Description
INFO | 81 | XA_START
INFO | 82 | XA_END
INFO | 83 | XA_OPEN
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
INFO | 91 | XA_RECOVER
INFO | 92 | Register an XA Data Source with the current transaction
INFO | 93 | SET ISOLATION LEVEL
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
XDB
XDB switch module events:
Event Level | Event ID | Event Description
INFO | 160 | XA_START
INFO | 161 | XA_END
INFO | 162 | XA_OPEN
INFO | 163 | XA_CLOSE
INFO | 164 | XA_COMMIT
INFO | 165 | XA_ROLLBACK
INFO | 166 | XA_PREPARE
INFO | 167 | Load XDB functions
INFO | 168 | RESET CONNECTION
XDBOPC
XDB one-phase switch module events:
Event Level | Event ID | Event Description
INFO | 180 | CONNECT
INFO | 181 | COMMIT
INFO | 182 | ROLLBACK
INFO | 183 | CLOSE
INFO | 184 | Before CONNECT
INFO | 185 | Before COMMIT
INFO | 186 | Before ROLLBACK
INFO | 187 | Before CLOSE
PGSQL
PostgreSQL switch module events:
Event Level | Event ID | Event Description
INFO | 201 | Initialization of module
ERROR | 202 | Incorrect XA open string provided
INFO | 203 | SQL CONNECT
INFO | 204 | Microsoft Distributed Transaction Coordinator (DTC) initialization
INFO | 205 | XA_START
INFO | 206 | Enlist in DTC transaction
INFO | 207 | XA_COMMIT
INFO | 208 | XA_ROLLBACK
INFO | 209 | XA_CLOSE
INFO | 210 | XA_END
INFO | 211 | De-enlist from DTC transaction
INFO | 212 | XA_OPEN
INFO | 213 | XA_CLOSE
INFO | 214 | XA_RECOVER
INFO | 215 | XA_FORGET
INFO | 216 | XA_COMPLETE
INFO | 217 | Register an XA data source with the current transaction
INFO | 218 | XA_PREPARE
Parent topic: Components Traced by CTF


mf.dbg Properties

This component provides behavior of low-level debugging technology.

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

Name | Value | Description
ALL | true|false | Enables/disables all properties
API | true|false | API entry/exit information for internal APIs
CONTROL | true|false | Events relating to control of the debugee process
JIT | true|false | Just In Time synchronization events (Windows only)
MODULE | true|false | Loading and unloading events of modules used by the debugee process
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.idmr Properties

This component handles the interface mapping between a SOAP/BINP message and COBOL fields.

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

ALL
Enables/disables all of the other properties
API
API events.
Level | Event ID | Event Description
INFO | 211 | Mapper initialization
INFO | 212 | Mapper termination
INFO | 213 | Set implementation field
INFO | 214 | Get implementation field
INFO | 215 | API completed successfully
ERROR | 216 | API error
CLIENT
Enterprise Server client handler events.
Level | Event ID | Event Description
INFO | 31 | Start of client request
INFO | 32 | End of client request
INFO | 33 | Start of client response
INFO | 34 | End of client response
INFO | 35 | Start of client termination
INFO | 36 | End of client termination
INFO | 38 | Set behavior options
INFO | 39 | Set special registers
INFO | 40 | Get fault information
INFO | 41 | Call program
ERROR | 37 | Client handling error
GEN
IDT generation events.
Level | Event ID | Event Description
INFO | 121 | Start of IDT generation
INFO | 122 | Start of implementation section
INFO | 123 | Start of service section
INFO | 124 | Start of configuration section
INFO | 125 | Set schema location
INFO | 126 | Validate service definition
INFO | 128 | Operation completed successfully
INFO | 129 | Free IDT
INFO | 130 | Set behavior options
INFO | 131 | Load configuration information
INFO | 132 | Free configuration information
ERROR | 127 | IDT generation error
IDT
IDT processing events.
Level | Event Id | Event Description
INFO | 181 | Get configuration information
MAP
Run-time interface mapping events.
Level | Event ID | Event Description
INFO | 501 | External information events
INFO | 502 | Implementation information
INFO | 503 | IDT information
INFO | 504 | Configuration information
INFO | 505 | Exit handling information
INFO | 506 | Arguments size
INFO | 507 | External message size
INFO | 508 | External message argument count
INFO | 509 | Start of parameter
INFO | 510 | End of parameter
INFO | 511 | Set implementation field
INFO | 512 | Set implementation constant
INFO | 513 | Get implementation field
INFO | 514 | Start of server request mapping
INFO | 515 | End of server request mapping
INFO | 516 | Start of server response mapping
INFO | 517 | End of server response mapping
INFO | 518 | Start of client request mapping
INFO | 519 | End of client request mapping
INFO | 520 | Start of client response mapping
INFO | 521 | End of client response mapping
INFO | 522 | No execution
SERVER
Enterprise Server request handler events.
Level | Event ID | Event Description
INFO | 0 | Start of server request
INFO | 1 | End of server request
INFO | 2 | Start of server response
INFO | 3 | End of server response
INFO | 4 | Start of server termination
INFO | 5 | End of server termination
ERROR | 6 | Server handling error
SYS
System IDT events.
Level | Event ID | Event Description
INFO | 151 | Generate system IDT

Parent topic: Components Traced by CTF


mf.mfdbfh Properties

This component provides tracing for activity undertaken by the Micro Focus Database File Handler.

The following table list the properties can be enabled:

Name | Value | Description
api | true|false | Internal API entry/exit information
config | true|false | Configuration file and environment variable details
database | true|false | Low-level database operations
datastore | true|false | Datastore operations
fh | true|false | EXTFH<> database file handler interface operations
odbc | true|false | ODBC operations
region | true|false | Region operations
resource_locking | true|false | Region resource locking operations
vault | true|false | Secrets/vault operations

Example

To trace the datastore and file handling operations, set the following in your CTF configuration file:

...
mftrace.level.mf.mfdbfh           = debug
mftrace.comp.mf.mfdbfh#datastore  = true
mftrace.comp.mf.mfdbfh#fh         = true
...
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, In Hold, Active, and Complete queues. DEBUG 7 A job has been removed from one of these queues. 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 spool files. | DEBUG | 10 | Spool files are 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 Complete 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 Complete 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 Complete 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.

Name | Value | Description
ALL | true|false | Enables/disables all properties
API | true|false | API entry/exit information for both internal and external APIs
CONFIG | true|false | Run-time configuration events
CONTAINER | true|false | COBOL container events
DBG | true|false | Debugging events
ENV | true|false | Environment variable events
EXTERNAL | true|false | External data events
FSYS | true|false | Low-level file I/O level events
JIT | true|false | Just In Time synchronization events (Windows only)
JSEM | true|false | JCL events
LICENSE | true|false | Licensing events
MEMORY | true|false | Memory allocation and de-allocation events
MFENTMAP | true|false | Entry Point Mapper events
MFPM | true|false | Mainframe Pointer Mapper events (AMODE programs)
PGM | true|false | User program entry, exit, chain, and link events
PGMLOAD | true|false | Program load events
PGMSEARCH | true|false | Program searcher events
PROCESS | true|false | Child process and run unit events
SIGNAL | true|false | Signal handling events
SYSPGM | true|false | System program entry, exit, chain, and link events
THREAD | true|false | Thread creation and synchronization events
(none) | N/A | Some key events are always included in the output, such as the initialization and de-initialization of processes, containers and run units.
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.maxparams
    Specifies the maximum number of data items that may be emitted by a trace event.
  • mftrace.pthread_ids
    Specifies whether CTF evaluates the $(THREAD) component of a trace event as the current pthread_id (that is, a pointer), or a real Linux thread ID.
  • mftrace.time
    Specifies the time standard to use when time stamping CTF trace files.
  • Example CTF Configuration Files
Parent topic: Consolidated Tracing Facility


mftrace.application

Note: You cannot update this property after the specified application has started.
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.
Restriction: You can only specify one 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
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
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
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
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
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
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
Components Traced by CTF


mftrace.maxparams

Specifies the maximum number of data items that may be emitted by a trace event.

Syntax:

mftrace.maxparams=max-event-parameters

Parameter:

max-event-parameters
The maximum number of data items that may be associated with any trace event. This must be a non-negative integer.

Default:

mftrace.maxparams=16

Comments:

If a trace event attempts to emit more that maxparams data items, the output will be truncated by emitting the first maxparams data items and disregarding the remaining ones. If an invalid value for max-event-parameters is provided, the default value is used. You cannot set maxparams to be lower than the default (16).

Examples:

To specify a maximum of 30 data items per event:

...
mftrace.maxparams=30
...
Parent topic: Configuration File for CTF


mftrace.pthread_ids

Specifies whether CTF evaluates the $(THREAD) component of a trace event as the current pthread_id (that is, a pointer), or a real Linux thread ID.

Syntax:

mftrace.pthread_ids=bool

Parameter:

bool
  • True: evaluates $(THREAD) as the pthread_id.
  • False: evaluates $(THREAD) as a real Linux thread ID.

Default:

mftrace.pthread_ids=true

Comments:

Setting mftrace.pthread_ids=false makes CTF more readable when tracing programs with many threads, but comes with a small performance impact.

Examples:

To evaluate $(THREAD) to the real Linux thread ID:

...
mftrace.pthread_ids=false
...
Parent topic: Configuration File for CTF


mftrace.time

Note: You cannot update this property after the specified application has started.
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
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 configuration file for Assembler

This configuration file traces Assembler programs, and creates a text file:

#
#  Demo CTF config file for use with demo CTF programs.
#

mftrace.dest=textfile

mftrace.emitter.textfile#Format = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.emitter.es#level = 9999

# Where do you want the logs to go?
mftrace.emitter.textfile#location = c:\logs

# Maximum file size in "k" bytes
mftrace.emitter.textfile#MaxFilesize = 6000

# Maximum number of log files to keep.
mftrace.emitter.textfile#MaxGeneration = 4

################################################
# CASSPOOL Tracing
################################################

mftrace.level.mf.asm             = debug

mftrace.comp.mf.asm#INS          = true
mftrace.comp.mf.asm#SVC          = true
mftrace.comp.mf.asm#BAL          = true

mftrace.comp.mf.asm#ABEND        = true
mftrace.comp.mf.asm#LOAD         = true
mftrace.comp.mf.asm#DELETE       = true
mftrace.comp.mf.asm#LINK         = true
mftrace.comp.mf.asm#GETMAIN      = true
mftrace.comp.mf.asm#FREEMAIN     = true
#mftrace.comp.mf.asm#REGS         = true

where:

  • INS - trace all instructions
  • SVC - trace all svc calls
  • BAL - trace all branch instructions
  • ABEND - trace abends
  • LOAD - trace all loads
  • DELETE - trace all delete calls
  • LINK - trace all link commands
  • GETMAIN - trace all memory allocation commands
  • FREEMAIN - trace all free memory commands

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

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
$(RUNUNIT)
A unique number that represents the .NET RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the .NET RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the .NET 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. This is used when a trace file is created. 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.

10000 (KB), with a maximum file size of 1000000 KB.
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. The maximum value is 100. | 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 .NET 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

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 the debugger provided with Enterprise Developer, at the point where 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 the IDE, you must configure the run-time environment by setting the MFTRACE_CONFIG environment variable. When set, trace events appear in the IDE when the application is debugged.

For more information on setting run-time environment variables, see .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


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
$(RUNUNIT)
A unique number that represents the .NET RunUnit ID (applies to .NET COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the .NET RunUnit (applies to .NET COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the .NET RunUnit (applies to .NET 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. This is used when a trace file is created. 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.

10000 (KB), with a maximum file size of 1000000 KB.
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. The maximum value is 100. | 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 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 or .NET) 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 .NET COBOL application executes in a multi-user environment, the user of .NET 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

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


Dynamic Tracing

The Dynamic CTF command line utility is a tool that allows you to dynamically change the trace settings of an application that is currently running with CTF enabled.

You must run the utility from the same machine as is running the application that you are dynamically configuring.

Whilst your application is running, you can alter trace levels, and add or remove components to or from the trace. You can also configure the emitters in effect, as long as a qualifying event for the emitter has not already been written out to the logs; once that happens, you cannot alter the configuration of that emitter.

The command line utility also accepts these options from within a configuration file, allowing you to save common settings in one place, and easily apply them time and time again.

  • Dynamic CTF Syntax Options
  • Examples of Using the Dynamic CTF Command Line Utility
Parent topic: Consolidated Tracing Facility


Dynamic CTF Syntax Options

Use the following syntax from the Enterprise Developer command line to configure CTF dynamically.

At the prompt, enter:

cblctd <option-list>

where <option-list> is one or more of the following, separated by spaces:

Syntax | Overview | Description
-Ct <component-name>:<property>[,<property>...] Enable component properties Sets each of the properties for the given component-name to true.

Example: -Ct mf.rts:memory,api

-Cf <component-name>:<property>[,<property>...] Disable component properties Sets each of the properties for the given component-name to false.

Example: -Cf mf.rts:memory,api

-Cv <component-name>:<property>=<value> Set component property Sets the property of the given component-name to the given value.

Example: -Cv mf.rts:api=true

-Et <emitter>:<property>[,<property>...] Enable emitter properties Sets each of the properties for the given emitter to true. (This change will only apply if no events have yet been output by the emitter.)

Example: -Et textfile:MultiProc

-Ef <emitter>:<property>[,<property>...] Disable emitter properties Sets each of the properties for the given emitter to false. (This change will only apply if no events have yet been output by the emitter.)

Example: -Ef binfile:Rununitld

-Ev <emitter>:<property>=<value> Set emitter property Sets the property of the given emitter to the given value. (This change will only apply if no events have yet been output by the emitter.)

Example: -Ev textfile:file=myctf.log

-Dd <emitter> Add emitter to default emitter list Adds the given emitter to those used by default for the duration of the process. (This change will only apply if no events have yet been output by the emitter.)

Example: -Dd binfile

-Dr <emitter> Removes emitter from default list Removes the given emitter from those used by default. (This change will only apply if no events have yet been output by the emitter.)

Example: -Dr binfile

-Lc <component>:<level> Sets component trace level Set the component trace level that determines which events are emitted.

The level can be one of:

  • debug (or d)
  • info (or i)
  • warn (or w)
  • error (or e)
  • fatal (or f)
  • none (or n)

Examples: -Lc mf.rts:d and -Lc mf.rts:info

-f <filename> Include options from text file <filename> is a text file containing dynamic CTF options on one or more lines.

Example: -f myctf.log

-p <process-id> Application process ID

The <process-id> of the COBOL application whose CTF settings are to be modified. This must be an application already executing with CTF enabled using MFTRACE_CONFIG. This option is mandatory if any of the above options have been specified.

The <process-id> is the operating system's process identifier number for the COBOL application. It can be specified as a decimal integer, or an octal value (that is, base 8) if the integer begins with a leading zero. It can also be a hexadecimal value if it begins with a 0x.

The required <process-id> can be determined using tools that form part of your operating system. For example, Task Manager on Windows .

Examples: -p 1234 or -p 0x1234

-q Quiet output Suppresses output of the banner. A message is still output if the command is unsuccessful.

-h | Help | Displays help for the available options.
Restriction: The emitter options -D and -E will only be actioned for the particular emitter if a qualifying event has yet to be written out. This is because the emitter file is itself created when that happens and can only be configured up until that point.
Parent topic: Dynamic Tracing
Related information
Examples of Using the Dynamic CTF Command Line Utility


Examples of Using the Dynamic CTF Command Line Utility

The following example removes tracing for low-level I/O run-time events, but also adds tracing for memory allocation/deallocation and catalog events in the File Handler for the COBOL application running as process ID 6765.

cblctd -Cf mf.rts:fsys -Ct mf.mffh.xfh:memory,catalog -p 6765

The following example applies the CTF tracing options listed in the myctfopts.log file to the COBOL application running as process ID 1244. The options in the log file should take the same format as described in the Dynamic CTF Syntax Options section.

cblctd -f myctfopts.log -p 1244

The following example can be used to turn on CTF tracing dynamically while an application is executing.

Firstly, ensure that the CTF Configuration file being used defines the initial set of component events that you require to be traced. Then, disable the output of all component events by specifying mftrace.level=none in the CTF Configuration file. CTF tracing can now be enabled after the application has started executing by modifying the trace level. When no events are enabled there is no performance overhead on the application execution.

So, if your configuration file defined run-time events to be output and the COBOL application is running as process ID 4892, you could use the following to enable tracing:

cblctd –Lc mf.rts:debug –p 4892

Similarly, tracing can be disabled dynamically:

cblctd –Lc mf.rts:none –p 4892
Parent topic: Dynamic Tracing
Related information
Dynamic CTF Syntax Options


Using the CTF Library Routines

Ordinarily, you would configure CTF using the MFTRACE_CONFIG variable, to output Run-Time System events, which can be useful for debugging issues and understanding code behaviors. However, if you are developing a large application, you may also want to add your own events to trace high-level code paths, or change CTF tracer and emitter properties at run time. The CBL_CTF_* library routines allow you to do this.

Note: The code excerpts used in this topic are from an example application of a graphics component behind a text editor, which contains three discrete sub-components: a keypress handler, a glyph shaper, and a glyph renderer. The excerpts displayed do not form a complete program; they show certain tracing techniques that you could incorporate into your own programs.

Enterprise Developer supplies a copybook, mfctf.cpy, which contains structures that make it easier to use the CBL_CTF_* library routines. The application also uses a constant to determine the current component name:

       copy "mfctf.cpy".
       78 THIS-COMPONENT               value "GRAPHICS".

The application also contains the following items in working-storage, used to store data such as the tracer handle. The ctf-trace-event-* structures store data to be associated with the custom trace events.

       78  MAX-TRACE-DATA              value 5.

       01  ctf-event-data.
           03  ctf-tracer-handle       pic x(4) comp-5.
           03  ctf-trace-event         cblt-trc-event.
           03  ctf-trace-event-lens    pic x(4) comp-5
                                       occurs MAX-TRACE-DATA.
           03  ctf-trace-event-types   pic x(4) comp-5
                                       occurs MAX-TRACE-DATA.
           03  ctf-trace-event-ptrs    pointer
                                       occurs MAX-TRACE-DATA.

The CBL_CTF_TRACER_GET routine obtains the tracer that corresponds to the component to be traced. If the tracer does not already exist, it is created. The ls-api-flags parameter can be used to indicate if the tracer name string is null- or space-terminated.

       move 78-CTF-FLAG-COMP-NAME-NULL-TERM to ls-api-flags
       move THIS-COMPONENT & x"00" to ls-comp-name

       call "CBL_CTF_TRACER_GET" using
                                 by value     ls-api-flags
                                 by reference ls-comp-name
                                 by reference ctf-tracer-handle

Properties for the tracer can be created in working-storage; these can represent different event types, sub-components, etc.... The properties are used to turn the related tracing of them on and off.

       78  PROPNAME-ALL                value "ALL"
       78  PROPNAME-EVENTS             value "EVENT_HANDLING".
       78  PROPNAME-GLYPHS             value "GLYPH_SHAPING".
       78  PROPNAME-RENDER             value "RENDERER".

A working storage array (ws-prop-name) contains the names of each property:

       78  PROPNAME-ALL                value "ALL".
       78  PROPNAME-EVENTS             value "EVENT_HANDLING".
       78  PROPNAME-GLYPHS             value "GLYPH_SHAPING".
       78  PROPNAME-RENDER             value "RENDERER".

       01  ws-prop-names.
           03                          pic x(15) value PROPNAME-ALL.
           03                          pic x(15) value PROPNAME-EVENTS.
           03                          pic x(15) value PROPNAME-GLYPHS.
           03                          pic x(15) value PROPNAME-RENDER.
           03                          pic x(15) value spaces.
       01  ws-prop-name                redefines ws-prop-names
                                       pic x(15) occurs 5.

To create these properties in the tracer, CBL_CTF_COMP_PROPERTY_GET is used, which generates properties that don't already exist. In this example, the ws-prop-names is iterated to create each property. To show that the properties will store integer values, the INT-VALUE flag is supplied.

           move 78-CTF-FLAG-PROP-INT-VALUE to ls-api-flags

           perform varying ls-prop-id from 1 by 1
                     until ws-prop-names(ls-prop-id) = spaces

               call "CBL_CTF_COMP_PROPERTY_GET" using
                              by value     ls-api-flags
                              by reference ctf-tracer-handle
                              by reference ws-prop-name(ls-prop-id)
                              by value     0
                              by reference ls-prop-value

           end-perform

To decide which sub-components to trace, CBL_CTF_COMP_PROPERTY_SET sets the required properties. This example enables output events for the RENDERER property:

           move 78-CTF-FLAG-PROP-INT-VALUE to ls-api-flags

           move 1 to ls-prop-value

           call "CBL_CTF_COMP_PROPERTY_SET" using
                              by value     ls-api-flags
                              by reference ctf-tracer-handle
                              by reference "RENDERER"
                              by reference ls-prop-value

A callback can be posted when a property is updated. This allows a bitmask of the current tracer properties and tracer level to be automatically maintained, rather than having to call CBL_CTF_COMP_PROPERTY_GET each time to query a property. Note: this is only necessary to support dynamic CTF configuration.

To do this, a structure to hold the callback and tracer details is required. (This structure is defined in the mfctf.cpy copybook.)

           03  ls-install-param        cblt-trc-notif-install.

It must be Initialized to 0, then the tracer handle and a pointer to the callback function be placed into the structure, which then allows CBL_CTF_TRACER_NOTIFY to place the callback.

           move low-values to ls-install-param

           move ctf-tracer-handle to
                cblte-tni-handle of ls-install-param

           set cblte-tni-callback of ls-install-param to
               entry "ctf-tracer-notif-callback"

           call "CBL_CTF_TRACER_NOTIFY" using
                                        by value 0
                                        by reference ls-install-param

Additional flags are added, each one occupying a separate bit in the bitmask, before the callback is written. The bitmask can be quickly queried using ctf-trace-flags b-and TRACE_FLAGS-*.

           78  PROPID-ALL                        value 1.

           78  TRACE-FLAGS-RENDERER              value h'00000001'.
           78  TRACE-FLAGS-EVENT-HANDLER         value h'00000002'.
           78  TRACE-FLAGS-GLYPH-SHAPING         value h'00000004'.

           01  ctf-config-data.
                03  ctf-trace-level         pic x(4) comp-5.
                03  ctf-trace-flags         pic x(4) comp-5 value 0.

Bitmask querying is covered again later when events start to be traced.

Additional structures are required, which are defined in the mfctf.cpy copybook.

       linkage section.
       01  lk-ctf-tracer-handle        pic x(4) comp-5.
       01  lk-ctf-notif-type           pic x(4) comp-5.

       01  lk-ctf-notif-param          pic x.
       01  lk-ctf-notif-param-level    redefines lk-ctf-notif-param
                                       pic x(4) comp-5.
       01  lk-ctf-notif-param-property redefines lk-ctf-notif-param
                                       cblt-trc-notif-prop-change.
       01  lk-ctf-property-name        pic x.
       01  lk-ctf-property-value       pic x.

The callback determines whether the notification was for a change in the tracer level, or a change in the other properties, and then the callback can be written.

If the notification is for a change in one of the other properties (for example, ALL, RENDERER, EVENT-HANDLER, or GLYPH-SHAPING), a separate function is entered.

           entry "ctf-tracer-notif-callback" using
                                      by value     lk-ctf-tracer-handle
                                      by value     lk-ctf-notif-type
                                      by reference lk-ctf-notif-param.
           evaluate lk-ctf-notif-type
               when 78-TRC-NOTIF-TYPE-PROP-CHANGE
                   perform ctf-tracer-notif-property

               when 78-TRC-NOTIF-TYPE-LEVEL-CHANGE
                   move lk-ctf-notif-param-level to ctf-trace-level

               when other
                    continue
           end-evaluate

           goback
           .

To work out which property was changed, the list of property names defined earlier is iterated, checking against the name of the property that changed. When there is a match, the new value is copied into the ls-prop-value variable, and apply-property-value is performed.

           ctf-tracer-notif-property section.
           set address of lk-ctf-property-name to
               cblte-tnpc-name of lk-ctf-notif-param-property

           perform varying ls-prop-id from 1 by 1
                     until ws-prop-name(ls-prop-id) = spaces

               if ws-prop-name(ls-prop-id) =
                  lk-ctf-property-name
                   (1:cblte-tnpc-namelen of lk-ctf-notif-param-property)

                   move cblte-tnpc-valint of lk-ctf-notif-param-property
                        to ls-prop-value

                   perform apply-property-value
                   exit perform
               end-if
           end-perform
           .

Now that the property that changed and its new value is known, the bitmask can be updated accordingly. (There is a special case for the ALL property, which sets the whole bitmask to high values.)

           apply-property-value section.
           if ls-prop-id = PROPID-ALL
               if ls-prop-value not = 0
                  compute ctf-trace-flags = ctf-trace-flags b-or
                                            h'FFFFFFFF'
               else
                  move 0 to ctf-trace-flags
               end-if
           else
               compute ls-work-var = 2 ** (ls-prop-id - 2)

               if ls-prop-value not = 0
                   compute ctf-trace-flags = ctf-trace-flags b-or
                                             ls-work-var
               else
                   compute ctf-trace-flags = ctf-trace-flags b-and b-not
                                             ls-work-var
               end-if
           end-if
           .

An 'event level' is used to denote the importance of an event. Setting the 'tracer level' (in MFTRACE_CONFIG) determines the minimum importance an event must have for it to be traced. The permissible tracer levels are INFO, WARNING, ERROR, and FATAL.

If dynamic CTF configuration is not required, simply get the tracer properties at the start of the program using CBL_CTF_TRACER_LEVEL_GET and CBL_CTF_COMP_PROPERTY_GET; for example:

           move 78-CTF-FLAG-PROP-INT-VALUE to ls-api-flags

           move 1 to ls-prop-id

           call "CBL_CTF_COMP_PROPERTY_GET" using
                              by value     ls-api-flags
                              by reference ctf-tracer-handle
                              by reference ws-prop-name(ls-prop-id)
                              by value     0
                              by reference ls-prop-value

and

           move 0 to ls-api-flags

           call "CBL_CTF_TRACER_LEVEL_GET" using
                                       by value     ls-api-flags
                                       by reference ctf-tracer-handle
                                       by reference ctf-trace-level

At this point, trace events can be produced. A renderer event can be created, which should only be traced if the RENDERER or ALL properties are set. The event should also only appear if the tracer level is INFO or lower (that is, this particular trace event is not very important - it just supplies general information about what the program is doing). The following constants can be created to represent event IDs.

           78  EVENT-RENDERER-DRAW      value 0
           78  EVENT-GLYPH-SHAPE        value 1
           78  EVENT-EVENT-HANDLED      value 2

With these constants, the bitmask can be queried to see if the RENDERER property is set, and if its current tracer level is INFO or lower. If both queries are true, the event can be created and sent to the tracer. (The following example makes use of the ctf-event-data structure listed at the start of this topic.)

           if (TRACE-FLAGS-RENDERER b-and ctf-trace-flags) not = 0
           and 78-CTF-FLAG-LEVEL-INFO >= ctf-trace-level
               move EVENT-RENDERER-DRAW to ls-trace-event
               move 78-CTF-FLAG-LEVEL-INFO to ls-trace-level
               perform trace-event
           end-if

When creating the event, the event name and level is stored in the ctf-trace-event structure. Using an evaluate statement, specific functions can be called, for example, to load extra data into the event, such as the value stored in a variable. In the following example, the GLYPH-SHAPE event outputs the text to be processed. The RENDERER-DRAW event doesn't require any extra data, so there is no helper function for that: simply leave ls-trace-data-count at its default value of 0.

           trace-event section.
           move 78-TRACE-EVENT-FLAGS-NONE to
                cblte-trcevt-flags of ctf-trace-event
           move ls-trace-event to
                cblte-trcevt-event-id of ctf-trace-event
           move ls-trace-level to
                cblte-trcevt-level of ctf-trace-event

           move 0 to ls-trace-data-count

           evaluate ls-trace-event

               when EVENT-GLYPH-SHAPE
                   perform trace-event-glyph-shape

               when EVENT-RENDERER-DRAW
               ...
                   continue
           end-evaluate

           move ls-trace-data-count to
                cblte-trcevt-data-count of ctf-trace-event

           call "CBL_CTF_TRACE" using by value     0
                                      by reference ctf-tracer-handle
                                      by reference ctf-trace-event

           end-if
           .

For trace events that include some data, a helper function can be called to set up the variables. The ctf-event-data structure mentioned earlier can store up to MAX-TRACE-DATA values; in this example, that means that each event can have up to five extra data items. The tracer needs to know what kind of data is being provided (ctf-trace-event-types) and how large it is (ctf-trace-event-lens).

           03  ls-trace-data-desc      pic x(40).

           trace-event-glyph-shape section.

           move "Blah blah blah" to ls-trace-data-desc

           set ctf-trace-event-ptrs(1) to
               address of ls-trace-data-desc

           move 14 to ctf-trace-event-lens(1)

           move 78-TRACE-EVENT-TYPE-TEXT to
                ctf-trace-event-types(1)

           add 1 to ls-trace-data-count
           .

Now that the event has been set up so that the trace-event-glyph-shape function is returned, a call to CBL_CTF_TRACE sends the event to the tracer for the component. The tracer sends the data to any emitters that are enabled, which in turn outputs the trace events to a file on disk.

Parent topic: Consolidated Tracing Facility


CTF 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=c:\mydir\ctf.cfg

and c:\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        = 17356
4>  # Date             = 2018/09/13
5>  # Time             = 15:12:27.993
6>  # Operating System = Windows 10.0  (Build 16299)
7>  # Computer Name    = NWZ-ZINO10
8>  # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
9>  15:12:27.993 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        = 15364
# Date             = 2018/09/13
# Time             = 15:15:34.667
# Operating System = Windows 10.0  (Build 16299)
# Computer Name    = NWZ-ZINO10
# Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
15:15:34.667 MF.RTS 128 1
15:15:34.668 MF.RTS 74 1 "5.0.0.12"
15:15:34.670 MF.RTS 129 1
15:15:34.684 MF.RTS 255 3 173 1 "myprog"
15:15:36.403 MF.RTS 130 1
15:15:36.403 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        = 8012
    # Date             = 2018/09/13
    # Time             = 14:59:34.417
    # Operating System = Windows 10.0  (Build 16299)
    # Computer Name    = NWZ-ZINO10
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    14:59:34.417 MF.RTS 128 1
    14:59:34.419 MF.RTS 74 1 "5.0.0.12"
    14:59:34.420 MF.RTS 23 1 0 0 "vcruntime140" 00007FFDB8F00000
    14:59:34.420 MF.RTS 23 1 0 0 "api-ms-win-crt-conio-l1-1-0" 00007FFDBB890000
    14:59:34.420 MF.RTS 23 1 0 0 "api-ms-win-crt-convert-l1-1-0" 00007FFDBB890000
    14:59:34.420 MF.RTS 23 1 0 0 "api-ms-win-crt-environment-l1-1-0" 00007FFDBB890000
    14:59:34.420 MF.RTS 23 1 0 0 "api-ms-win-crt-filesystem-l1-1-0" 00007FFDBB890000
    14:59:34.420 MF.RTS 23 1 0 0 "api-ms-win-crt-heap-l1-1-0" 00007FFDBB890000
    14:59:34.420 MF.RTS 23 1 0 0 "api-ms-win-crt-locale-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-math-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-multibyte-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-private-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-process-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-runtime-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-stdio-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-string-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-time-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 23 1 0 0 "api-ms-win-crt-utility-l1-1-0" 00007FFDBB890000
    14:59:34.421 MF.RTS 129 1
    14:59:34.421 MF.RTS 19 1 0 0 "mymain" "" ""
    14:59:34.425 MF.RTS 6 1 17 0 "mymain" "MYMAIN"
    14:59:34.425 MF.RTS 19 1 0 0 "mysub" "" ""
    14:59:34.425 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    14:59:34.426 MF.RTS 7 1 "mysub"
    14:59:34.426 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    14:59:34.427 MF.RTS 7 1 "mysub"
    14:59:34.427 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    14:59:34.428 MF.RTS 7 1 "mysub"
    14:59:34.428 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    14:59:34.429 MF.RTS 7 1 "mysub"
    14:59:34.429 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    14:59:34.429 MF.RTS 7 1 "mysub"
1>  14:59:34.429 MF.RTS 20 1 0 0 "mysub"
    14:59:34.429 MF.RTS 140 1 1
    14:59:34.429 MF.RTS 141 1 1
    14:59:34.434 MF.RTS 255 3 173 1 "myprog"
    14:59:34.435 MF.RTS 140 1 2 "
    Load error : file 'myprog'
    error code: 173, pc=0, call=1, seg=0
    173     Called program file not found in drive/directory "
    14:59:37.619 MF.RTS 141 1 2
    14:59:37.619 MF.RTS 130 1
    14:59:37.619 MF.RTS 140 1 0 0 0 127
    14:59:37.619 MF.RTS 141 1 0
    14:59:37.619 MF.RTS 140 1 3 0
2>  14:59:37.619 MF.RTS 20 1 0 0 "mymain"
    14:59:37.619 MF.RTS 140 1 1
    14:59:37.619 MF.RTS 141 1 1
    14:59:37.619 MF.RTS 21 1 0 0 "mymain"
    14:59:37.619 MF.RTS 141 1 3
    14:59:37.619 MF.RTS 140 1 0 0 128 255
    14:59:37.619 MF.RTS 141 1 0
    14:59:37.619 MF.RTS 140 1 4 0
    14:59:37.619 MF.RTS 21 1 0 0 "mysub"
    14:59:37.619 MF.RTS 141 1 4
    14:59:37.620 MF.RTS 131 1

The entries marked 1> and 2> show event type 20 (logical cancel): 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:

    15:22:44.003 MF.RTS 66 1 0 "Micro Focus COBOL"
    15:22:44.003 MF.RTS 66 1 1 "SolarNativeRuntime" "1.0" 1 3
    15:22:44.003 MF.RTS 6 1 17 0 "mymain" "MYMAIN"
1>  15:22:44.004 MF.RTS 26 1 "MY_VAR" 9
    15:22:44.004 MF.RTS 19 1 0 0 "mysub" "" ""
    15:22:44.004 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    15:22:44.007 MF.RTS 7 1 "mysub"
    15:22:44.007 MF.RTS 6 1 17 0 "mysub" "MYSUB"
    15:22:44.008 MF.RTS 7 1 "mysub"
    ...
    15:22:45.726 MF.RTS 141 1 3
    15:22:45.726 MF.RTS 140 1 0 0 128 255
    15:22:45.726 MF.RTS 141 1 0
    15:22:45.726 MF.RTS 140 1 4 0
    15:22:45.726 MF.RTS 21 1 0 0 "mysub"
    15:22:45.726 MF.RTS 141 1 4
    15:22:45.727 MF.RTS 66 1 2 1 3
    15:22:45.727 MF.RTS 41 1 0
    15:22:45.727 MF.RTS 41 1 1
2>  15:22:45.727 MF.RTS 27 "MY_VAR"
    15:22:45.727 MF.RTS 56 1 158 0x0000013A3BAC3EB0
    15:22:45.727 MF.RTS 57 1 158

The entries marked 1> and 2> in the above excerpt show the start and end of the additional entries for an external data item.

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


Profiler

Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.

This section provides information about how to use the utility from the command line.

  • Introduction to Profiler
  • Producing Profiler Statistics
  • 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. It can be helpful in diagnosing performance related issues in your applications.

This profiling implementation is sometimes known as instrumented profiling. Instrumented profiling means the application is modified to include additional code to record performance information.

To enable profiling in your application, you need to compile the code you wish to profile with the PROFILE Compiler directive, and after executing your program, run the profiling tool to create a report.

Performance statistics are produced in binary format each time the application is run, and so must be converted to a readable format, using the Profiler tool, in order to view them.

Recording performance statistics will degrade application performance, so is not recommended for use in production systems.

Parent topic: Profiler
Related information
Producing Profiler Statistics
Running Profiler from the Command Line
Profiler Output
Time Spent in Called Programs
Directives for Profiler


Producing Profiler Statistics

To produce Profiler statistics for an application, you need to have compiled your COBOL programs with the PROFILE Compiler directive.

When you run a program with the PROFILE directive, the performance statistics are recorded in a file called program-name.ipf, where program-name is the name of the program for which the statistics are generated. This file is generated in binary format, and must be viewed with the Profiler tool; see Running or Invoking Profiler from the Command Line.

By default, the .ipf 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
Related information
Introduction to Profiler
Running Profiler from the Command Line
Profiler Output
Time Spent in Called Programs
Directives for 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
* Copyright (C) Micro Focus 1984-2016. All rights reserved.
* PROGRAM1
Total time:        156 milliseconds.      Module loaded once.
-------------------------------------------------------------------------------
Call Count  Program
-------------------------------------------------------------------------------
         1  program1
-------------------------------------------------------------------------------
% time      time   entries  micros/entry  (paragraph OF) Section
-------------------------------------------------------------------------------
79.00       123         1    123000      perf-log-1 OF main-logic-1
14.00        22        16      1375      perf-call-1 OF main-logic-1
 7.00        11         1     11000      main-logic-1
Parent topic: Profiler
Related information
Introduction to Profiler
Producing Profiler Statistics
Profiler Output
Time Spent in Called Programs
Directives for 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 lists an overview of the number of times that each program is loaded, and gives the total execution time (in milliseconds) for the program. The results are then broken 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 OF) Section | The section (and paragraph) to which the performance statistics apply.

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
Related information
Introduction to Profiler
Producing Profiler Statistics
Running Profiler from the Command Line
Time Spent in Called Programs
Directives for 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.

The tunable has valid values between 0-3:

  • 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, and time is recorded as CPU time (that is, the user + system time).
  • 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, and time is recorded as CPU time (that is, the user + system time).
  • If the profile_behavior run-time tunable is set to 2, then time spent in a profiled called program is recorded both in the called program and in the calling program, and time is recorded as elapsed time; otherwise known as real time or wall-clock time.
  • If the profile_behavior run-time tunable is set to 3, then time spent in a profiled called program is recorded only in the called program, and time is recorded as elapsed time; otherwise known as real time or wall-clock time.
Parent topic: Profiler
Related reference
profile_behavior
Related information
Introduction to Profiler
Producing Profiler Statistics
Running Profiler from the Command Line
Profiler Output
Directives for 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
Related information
Introduction to Profiler
Producing Profiler Statistics
Running Profiler from the Command Line
Profiler Output
Time Spent in Called Programs


Terminal Emulation

The user interface to CICS and IMS applications from the PC is often through 3270 terminal emulators. The 3270 terminal emulators enable the CICS and IMS applications to display input and output screens on the PC using 3270 data streams and to receive input from the PC. It is intended for programs that use BMS or build 3270 data streams. Emulation is provided for 3270 models 2 through 5.

We recommend that you use a Telnet 3270 (TN3270) client. The keyboard mapping and support for character level attributes is a property of the third-party TN3270 client you choose.

  • This product's installation installs the Micro Focus Host Access for the Cloud (HACloud) terminal emulator.
  • You can use other TN3270 emulators. For example, if you are a Micro Focus Rumba+ Desktop or a Micro Focus Reflection Desktop user, you can specify these emulators inside the IDE.

    In Enterprise Test Server you can use some special field types that are required by the 3270 sessions in Micro Focus Reflection Desktop and InfoConnect Desktop starting from version 17.0 Service Pack 1. See Working with Micro Focus Terminal Emulators.

When you start a 3270 terminal emulator, it is separate from the enterprise server region that runs the CICS or IMS application. Terminals do not need to be predefined. This means terminal emulation characteristics can be specified at terminal startup.

Enterprise Test Server needs to have a listener for requests from 3270 terminal emulators. You add this as part of configuring the enterprise server region that will run your CICS or IMS application.

  • Terminal Emulation with Micro Focus Host Access for the Cloud
  • Terminal Emulation with Reflection Desktop
  • Terminal Emulation with Rumba+ Desktop
Parent topic: Tools


Terminal Emulation with Micro Focus Host Access for the Cloud

Enterprise Test Server installs the Session Server component of Micro Focus Host Access for the Cloud (HACloud). HACloud provides browser-based HTML5 access to 3270 host applications on Windows and Linux.

HACloud is configured to work out-of-the-box with the default configuration for ESCWA and MFDS that you need to change before you start using it. For example, if your ESCWA and MFDS are configured with non-default settings or you want to use an HTTPS connection, secure credentials, and trusted certificates for the server sessions, you must specify these details in the HACloud configuration file.

For more information about HACloud and some specific software requirements, check its product Help.

  • Upgrading the HACloud Settings from Previous Releases
  • HACloud Configuration File
  • Authenticating HACloud for Work with ESCWA and the MFDS
  • Starting the HACloud Session Server
  • Running an HACloud TN3270 session
  • HACloud Session Customization Options
  • Host Access for the Cloud Macros
  • Troubleshooting the HACloud Session Server
Parent topic: Terminal Emulation
Related information
https://www.microfocus.com/documentation/host-access-for-the-cloud/2-7-1/user-guide/
https://www.microfocus.com/documentation/host-access-for-the-cloud/2-7-1/user-guide/deploying/system-requirements/


Upgrading the HACloud Settings from Previous Releases

HACloud shipped with releases 8.0 and 9.0 used a configuration settings file, hacloud.properties, in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer folder. This file has been deprecated in release 10.0, and is replaced by the application-userprefs.properties file.

In 10.0, when you start HACloud for the first time, the startup service or script will rename an existing hacloud.properties to hacloud_backup.properties. You need to manually migrate your configuration settings over to the application-useprefs.properties file after the upgrade, and delete the hacloud.properties file. The exceptions to this are:

  • The setting to enable HTTPS communications to the session server endpoint has changed. If TLS was previously enabled, you need to set server.ssl.enabled=true in the application-useprefs.properties file.
  • The spring.profiles.active setting has been deprecated.
Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud


HACloud Configuration File

HACloud Session Server comes with some out-of-the-box default configuration settings for ESCWA and MFDS. The settings are available in a configuration file in the product installation.

Micro Focus recommends that you edit this file before you start using HACloud and change the default passwords as a minimum in the configuration file. In addition, if ESCWA and MFDS are configured with non-default settings or you want to use an HTTPS connection, secure credentials, and trusted certificates for the server sessions, you need to configure these as well.

Settings available in the user preferences configuration file

Note: This is a change from releases 8.0 and 9.0. See Upgrading HACloud from Previous Releases for details.

The configuration settings file, application-userprefs.properties, is available in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hacloud folder.

You need to review and update the settings as required. To edit the file, start a text editor with administrator's permissions.

Important: Micro Focus recommends that you create a copy of this file before you modify it.
###############
# Log Levels  #
###############

# logging.level.com.microfocus.zfe.enterprise.ConfigurationServiceEnterprise: INFO
# logging.level.com.microfocus.zfe.enterprise.ConfigurationLoader: INFO
# logging.level.com.microfocus.zfe.enterprise.VaultAccess: INFO

####################
# Logfile Settings #
####################

# logging.file.max-size: 256MB
# logging.file.total-size-cap: 2GB
# logging.file.max-history: 30
# logging.file.clean-history-on-start: true

##############################
# ESCWA Integration Settings #
##############################

# HTTP URL on which ESCWA should be contacted
hacloud.es.escwaurl=http://localhost:10086
# MFDS host on which to query available 3270 endpoints
hacloud.es.mfdshost=127.0.0.1
hacloud.es.mfdsport=86

##########################
# Endpoint Configuration #
##########################
# server.port=7443
# server.ssl.enabled=false

############################
# Key/Trust Store Settings #
############################
# Session Server keystore password
server.ssl.key-store-password=changeit
# Trusted certificiate store password
server.ssl.trust-store-password=changeit

The parameters you can change in this file are as follows:

Logging parameters:
logging.level.com.microfocus.zfe.enterprise.ConfigurationServiceEnterprise
Specifies the level of verbosity for all Enterprise Server interactions. The default verbosity of the messages is ERROR. Uncomment this setting, if you want to change the verbosity level. The supported values are: ERROR, WARN, INFO, DEBUG, or TRACE.
logging.level.com.microfocus.zfe.enterprise.ConfigurationLoader
Specifies the level of verbosity when loading the HACloud settings. The default verbosity of the messages is ERROR. Uncomment this setting, if you want to change the verbosity level. The supported values are: ERROR, WARN, INFO, DEBUG, or TRACE.
logging.level.com.microfocus.zfe.enterprise.VaultAccess
Specifies the level of verbosity when accessing protected vault information. The default verbosity of the messages is ERROR. Uncomment this setting, if you want to change the verbosity level. The supported values are: ERROR, WARN, INFO, DEBUG, or TRACE.
logging.file.max-size
Maximum size for each log file.
logging.file.total-size-cap
Maximum total size for all log files.
logging.file.max-history
Maximum days until log files destroyed.
logging.file.clean-history-on-start
Log files cleaned according to rules on every startup.
ESCWA parameters:
hacloud.es.escwaurl
The URL on which ESCWA is running. The default one is http://localhost:10086.
hacloud.es.mfdshost
The host on which MFDS is running.
hacloud.es.mfdsport
The port on which MFDS is running.
Server connection and authentication parameters:
server.port
server.port=7443 is the HTTP server end-point on which you can contact the HACloud Session Server.
server.ssl.enabled
server.ssl.enabled=false/true specifies whether TLS should be enabled. This is a change from release 9.0, where this was controlled by the hacloud.properties file. If profiles.active=no-tls was set in that file, TLS was disabled. If no setting was explicitly set, TLS would be enabled.
server.ssl.key-store-password
Specify the password to use to secure the Server Session keystore. The default password for the keystore is changeit and Micro Focus recommends that you change it.
server.ssl.trust-store-password
Specify the password to use to secure the trust store. The default password for the keystore is changeit and you need to change it.
Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud
Related information
https://www.microfocus.com/documentation/host-access-for-the-cloud/2-7-0/user-guide/deploying/securing/stores-used-by-sessionserver/
https://www.microfocus.com/documentation/host-access-for-the-cloud/2-7-0/user-guide/deploying/securing/how/import-cert/
The mfsecretsadmin Utility
Troubleshooting the HACloud Session Server


Authenticating HACloud for Work with ESCWA and the MFDS

Out-of-the box credentials

By default, ESCWA is running in secured mode and has a security manager assigned to it. HACloud out-of-the-box is configured to retrieve the default credentials for the ESCWA connection from a secret which is shipped with the product in the microfocus/common/readonly location. You do not need to configure HACloud further, if the default ESCWA credentials are used.

Supplying non-default credentials

If ESCWA and MFDS are configured to use non-default credentials (such as if you want to limit the permissions to certain regions), you need to provide these credentials to HACloud. To do this you use the mfsecrecretsadmin utility and save the credentials in the microfocus/hacloud location. Passwords are stored in a vault which is either an encrypted file on the disk or a server that provides the information.

  • You supply the login credentials for ESCWA in the escwacreds secret.
  • You supply the MFDS credentials in the mfdscreds secret - this is required only if the MFDS credentials differ from the ones for ESCWA, or single sign-on is not enabled in ESCWA.

    The product checks whether explicit MFDS credentials have been provided. If they have not been provided, the product issues an MFDS logon command that uses { "mfUseSession": true} to reuse the ESCWA session credentials.

The format of these secrets is the JSON payload for the ESCWA logon. See ESCWA Client Web APIs.

In order to supply the credentials, you need to add them to a JSON file - one for ESCWA and one for the MFDS. The format in which you need to supply the username and the password for ESCWA or the MFDS, respectively, is:

{ "mfUser": "MyUserName", "mfPassword": "MyPassw"}

To supply these non-default credentials to the microfocus/hacloud location for HACloud:

  1. Start an Enterprise Developer command prompt or Enterprise Server command prompt.
  2. To write the credentials from the JSON file to the hacloud vault, execute:
    mfsecretsadmin write -file microfocus/hacloud/escwacreds filename

In order to verify that these secrets are available:

  1. To show a list of the secrets available for HACloud, execute mfsecrecretsadmin with the following option:
    mfsecretsadmin list microfocus/hacloud/*

    This should display the escwacreds and mfdscreds, if available.

  2. To read the contents of either file, execute mfsecrecretsadmin with the respective options - either escwacreds or mfdscreds. For example:
    mfsecretsadmin read microfocus/hacloud/escwacreds
Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud


Starting the HACloud Session Server

You need to start the HACloud session server before you can use the HACloud TN3270 emulator. To do this you need to start the respective Windows service.

To start the HACloud session server, you need to start the dedicated Windows service, Micro Focus HA Cloud, you need to start the service as follows:

  1. Ensure you have a 64-bit Java installed and added to the PATH environment variable.
  2. Open the Windows Services Manager.
  3. Click Micro Focus HA Cloud, and click Start the service.
  4. Alternatively, you can execute the following command from a command prompt to start the service:
    net start mfhacloud
Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud


Running an HACloud TN3270 session

Ensure that the HACloud session server is running before you can use the HACloud TN3270 emulator.

To open the HACloud emulator:

  1. In a browser, open the endpoint: http://localhost:7443. If you have configured any non-default settings, such as HTTPS connection, you need to specify this.

    This shows the Available Sessions dialog box. If any of the servers has a TN3270 listener defined, these appear in the list of available sessions in the following format: 3270 ServerName@HostIP:PortNumber.

    If this dialog box is not visible, click OPEN SESSION to start it.

  2. Click the row for the connection for the TN3270 emulator to start and connect to your region.

    This starts the HACloud TN3270 emulator and loads in it the application running in the region.

Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud


HACloud Session Customization Options

Micro Focus Host Access for the Cloud enables you to customize session settings for the selected region.

  • On the HACloud toolbar, click [image], then click the individual tabs in the settings.

    The session server saves the settings on disk and are they are stored based on the Enterprise Server region name.

You can specify the HACloud session options on the following pages:

Connection
Specify the TN3270 terminal protocol, terminal model and IT, device name, enable TLS security, specify the send of keep alive packages.
Display
Specify settings such as color mappings; enable or disable hotspots; configure the cursor, the fonts, and the keyboard; specify a national character set and a country extended graphics code.
Key Mappings
View and modify the key mappings for the region.
Macros
Specify whether to run a macro on a specific event such as region startup, or when connecting or disconnecting from a region.
Edit
Specify the behavior of the copy and paste operations.

For details on these settings, check the HACloud product Help.

Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud


Host Access for the Cloud Macros

Host Access for the Cloud enables you to create, update, and execute macros. Use the [image] button in the toolbar to access the functionality. The Host Access for the Cloud session server stores any macros you record on disk.

For more on macros, see the HACloud product Help.

Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud


Troubleshooting the HACloud Session Server

When you start the HACloud session server, Enterprise Developer records diagnostic messages start messages in a log file.

The default location of the file is:

  • On Windows: %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hacloud.log
  • On UNIX: /var/mfcobol/logs/hacloud.log

Use this log file to investigate any issues with the HACloud session server. The logging levels are consistent with the SLF4J standard, and that the rollover rules are available in the Spring Boot Reference documentation - see the Related Information section.

The default verbosity of the messages is ERROR. You can modify the verbosity and set it from level INFO to FATAL using the logging.level* settings in the HACloud configuration file. See Configuring the HACloud Session Server.

Parent topic: Terminal Emulation with Micro Focus Host Access for the Cloud
Related information
HACloud Configuration File
https://www.microfocus.com/docs/links.asp?vc=spring-logging


Terminal Emulation with Reflection Desktop

Reflection Desktop can be enabled from the IDE as the TN3270 emulator to run or debug your applications.

If you have configured Reflection Desktop to be the default TN3270 emulator (Preferences > Micro Focus > Enterprise Server > TN3270), it is launched when you right-click a server (associated with a Mainframe Subsystem application), from the Server Explorer view, and select Show TN3270 Display.

The session used to connect depends on the Use project specific Reflection session profile (if exists) option in the TN3270 preferences page. If this option is selected, you can specify the path to a session profile file in the project's Properties view (see below). When located, this session profile is used upon connection. If the option is not selected or the specified file cannot be located, a default mainframe session profile is used.

Project properties view showing reflection session profile file

See the Reflection Desktop product Help for more information on session profiles.

Parent topic: Terminal Emulation


Terminal Emulation with Rumba+ Desktop

Note:
  • If you have Micro Focus Rumba Desktop installed, you can enable it from the IDE as the TN3270 emulator to launch from within the IDE in order to run or debug your applications.
  • This functionality is only available for native Mainframe Subsystem projects.

If you have configured Rumba+ Desktop to be the default TN3270 emulator (Preferences > Micro Focus > Enterprise Server > TN3270), it is launched when you right-click a server (associated with a Mainframe Subsystem application), from the Server Explorer view, and select Show TN3270 Display.

The session used to connect depends on the Use project specific Rumba session profile (if exists) option in the TN3270 preferences. If this option is selected, you can specify the path to a session profile file in the project's Properties view (see below). When located, this session profile is used upon connection. If the option is not selected or the specified file cannot be located, a default mainframe session profile is used.

Project Properties view

See the Rumba+ Desktop product Help for more information on session profiles.

Parent topic: Terminal Emulation


Micro Focus Common Client

The Micro Focus Common Client (MFCC) provides a client-side networking framework for several components of your development and run-time environments.

It's used by COBOL web service proxy programs, the Interface Mapping Toolkit's service-deployment mechanism, Fileshare clients (when configured appropriately), various utilities such as cassub (depending on operating mode), CICS Web Interface, and product components such as MFCS and ESCWA.

MFCC is configurable through its configuration file. By default, the file is named mf-client.dat, which is located in the bin subdirectory of your product install directory. You can use the MFC_CONFIG environment variable to override this and specify your own configuration file; set it to the absolute pathname of the configuration file to use.

Refer to mf-client.dat Configuration Options for details on how you can edit or enable advanced functionality, such as TLS support or Web Service clients.

  • mf-client.dat Configuration Options
Parent topic: Micro Focus Enterprise Test Server 10.0


mf-client.dat Configuration Options

The MFCC configuration file mf-client.dat is divided into sections - section names are included in square brackets. Within each section, options are specified as name/value pairs, one per line. Blank lines and leading/trailing whitespace are ignored. Comment lines start with a hash (#) or semicolon (;) character and go to the end of the line.

The file contains the following sections:

[directories]
Use this section to configure one or more directories for Micro Focus Client Configuration (MFCC). MFCC uses directories to locate services hosted by Enterprise Server, such as deployment services. The default configuration is for MFCC to connect to MFDS on the local system.
The port specification ":0" means MFCC will first look for the CCITCP2_PORT environment variable for the port to connect to. If that is not set, it will try to look up the "mfcobol" service name in the /etc/services directory %WINDIR%\system32\drivers\etc\services (Windows), and use that port. If that is not found either, it will use the official Micro Focus Directory Server directory port, which is 86.
For example:
[directories]
mrpi://127.0.0.1:0
Note: The list keyword can also be used here. See [service list] section for more information.
[mldap]
Use this optional section to provide default credentials for binding to the Micro Focus Directory Server (MFDS).
If these are not set, and the application does not specify any, an anonymous bind is attempted.
These credentials can be literal strings, or they can refer to secrets in a 'vault' accessed through the Micro Focus Vault feature. Vault secrets are specified as mfsecret:<config>:<name>, where <config> is an optional vault configuration tag (leave blank for the default vault), and <name> is the name given to the secret in the vault.
To use a literal string containing a colon, you can prefix it with "literal:" to prevent it being interpreted as another type of value.
For example:
username=mf_dep
password=mf_dep

Another option in this section is credentials, which can be set to the location of a vault secret which contains a username and password in ESCWA JSON format:

{ "mfUser": "username", "mfPassword": "password" }

If this option is set and the vault secret location is valid and contains valid data, MFCC will use that username and password to bind to MFDS.

From release 10.0 onwards, this is set to:

[mldap]
credentials=mfsecret::microfocus/common/readonly

which contains the credentials for an account with read-only access to MFDS data.

By default, if MFCC receives an invalid-credentials error from MFDS when trying to bind using the credentials configured with any of these options (username, password, and credentials), it will try again using an anonymous bind. This behavior can be disabled by adding the following configuration setting to this section:

try anonymous if bind fails=no
Note: This account is created at installation time, as part of the default VSAM ESM Module Security configuration.
[tracing]
Use this section to enable MFCC tracing; higher numbers log more information.
For example:
[tracing]
level=3
[defaults]
Use this section to specify default values for some MFCC parameters when they are not specified by the application:
connect-timeout
Changes the default MFCC timeout for connecting to a server and waiting to receive a response. This value is used if the application does not set timeouts directly (by calling the MFCC API), and the environment variable MFC_CONNECT_TIMEOUT is not set.
timeout
Changes the default MFCC timeout. This value is used if the application does not set timeouts directly (by calling the MFCC API), and the environment variable MFC_TIMEOUT is not set.
availability
Controls which instances of a service are considered available when requesting a list of service providers, or attempting to connect to any available instance of a service:
available
Only listeners that are listed as available and started are returned. This is the default option.
non-responding
Listeners that are listed as 'Not responding' in the directory can also be returned.
any
Returns any listener, even if it is listed as stopped in the directory.
mfbinp-digest
Enables the data-integrity digest option for MFBINP requests, which are used for COBOL EJBs and a number of internal services such as JCL job submission. The digest is disabled by default. For TLS (SSL) connections,l the digest is unnecessary, as TLS will guarantee data integrity.
For example:
[defaults]
connect-timeout=15
timeout=30
availability=available
mfbinp-digest=md5
[options]
Use this section to specify the following processing options:
relax-URL-rules

Allows characters forbidden by the standard in HTTP URLs.

proxy

Specifies the URL of a proxy for HTTP. This feature is experimental.

For example:
[options]
relax-URL-rules=true
proxy=https://proxy.host.com
[operation]
Use this section to control some aspects of MFCC operation:
preferred-server

This value can be set to either the name of an enterprise server region, or to an environment variable specified as $NAME or %NAME%, in which case the value of the environment variable will be used. If this setting is configured, when MFCC is asked to search for a service and it finds a suitable service under more than one server, it will prefer the instance of the service that belongs to the preferred server. This is mostly useful for controlling service deployment in systems that have multiple enterprise server region configured.

For example:
[operation]
preferred-server=$ES_SERVER
[TLS]
Use this section to set default values for connections using TLS (also known as SSL), such as HTTPS connections.
Note: In product releases prior to Enterprise Developer 5.0, this section was called [SSL]. The old section name can still be used. If both sections are present and have conflicting settings, the settings in the [TLS] section will be used.
You can specify the following parameters:
root
The collection of trusted certificates. Typically this file contains one or more CA root certificates. It might include roots for commercial CAs, roots for a private CA run by your organization, and/or a root for development purposes, such as one generated by the DemoCA product component. It can also contain trusted intermediate and even entity certificates. It should be a file in PEM format.
This is the root for a local Demo CA installation.
Note: Demo CA is not automatically installed. The installer is included in the product but must be run manually if you need Demo CA. See Tutorial: Configuring SSL Security in the Server.

If you use MFCC to connect to HTTPS servers on the public Internet, a useful root-certificate collection file is CARootCerts.pem, found in the bin directory of your Enterprise Developer product installation. It contains root and intermediate certificates for many public CAs.

You can concatenate multiple PEM files together to assemble whatever root collection meets your needs.

certificate
The optional default client certificate. An MFCC application can override this value. Most servers do not ask clients to provide certificates also known as symmetric authentication. This value should be the pathname of a file in PEM or DER format.
key
The file with the private key corresponding to the client certificate. The supported file types are PEM and DER.
passphrase
Private keys are often stored encrypted, in which case MFCC needs a passphrase to use the key. The passphrase can be a literal string or a vault reference, as with the values in the [mldap] section described above.
verify peer

If the client should verify the server's certificate, set this option to a string beginning with "y", "t", or "1" (case-insensitive), then peer verification is enabled; otherwise it is disabled. The default is to enable peer verification.

Applications can override this setting, but rarely do.

Verification is critical to TLS security. It should only be disabled for testing, for example, to diagnose a certificate name-matching problem and similar purposes, and only temporarily.

verify depth
Set the maximum number of intermediate certificates in the server's certificate chain. The server's certificate chain is the certificate that identifies the server itself, the CA's root certificate, and any intermediate certificates between them. For example, the CA might have used its root certificate to sign an intermediate issuing certificate, which it then used to sign the server's certificate; or there might be two or more intermediates.

A depth of 1 allows one intermediate certificate between the root and the server's certificate, and so on.

Historically, this setting was used to prevent misusing entity certificates to sign other certificates. With modern (X.509v3) certificates, it is largely unnecessary, and should be set to a large enough value to accommodate all the server certificate chains that MFCC clients will see.

MFCC applications can override this value, but usually do not. If the application does not set a value, the configured value is used. If it is not specified in the configuration, the default is 2.

This setting has no effect if peer verification is disabled. See verify peer setting above.

The value must be non-negative (0 or greater).

verify peer name
Enables or disables verifying that a name in the server's certificate matches the hostname (or IP address) used to connect to the server. A certificate includes one or more names, indicating who or what the certificate is meant to identify. Typically, a client must check to see that the certificate it receives from the server matches the host it wants to connect to.

If this option is set to a string beginning with "y", "t", or "1" (case-insensitive), then name verification is enabled; otherwise it is disabled. The default is enabled.

By default, this is enabled, MFCC attempts to match each of the names in the server's certificate against the hostname that the application specified when MFCC requests to open the connection. The comparison is case-insensitive. Some CAs will issue certificates with wildcard names like *.foo.bar.com, which should match any hostname like a.foo.bar.com. Support in MFCC for wildcard names is experimental. Also, certificates can include IP addresses, which would be used for comparison if the application specifies an address rather than a hostname. Support for IP addresses is experimental.

Note: The name that the application gives to MFCC must match one of the names in the certificate. If the certificate only identifies myhost but the application tries to connect to myhost.mydomain.com, the conversation is rejected.

Name matching is critical to TLS security. It should only be disabled for testing, for example, to diagnose a certificate name-matching problem or similar purposes, and only temporarily.

This setting has no effect if peer verification is disabled. See verify peer setting above.

protocols

The TLS protocols option specifies the list of protocols (TLS versions) to be used, and the order of preference in which they are to be used. By default, TLS 1.0 through 1.3 are enabled, and later versions are preferred.

cipher suites
Set the list of cipher suites the client can use. This list also sets the client's order of preference, but many servers use their own preference when deciding which suite to use.

See Configuring a Cipher Suites List for more information on setting the cipher suites and what suites are enabled by default. The default list includes only ciphers still considered secure for normal use when the product release was developed.

TLS1.3 cipher suites

TLS version 1.3 has different cipher suites from previous protocol versions, and so it has its own cipher suite list. It is rarely necessary to set this configuration option.

min dh size
The minimum size in bits of the modulus length of the Diffie-Hellman (DH) group that is used to negotiate with connecting peers when using DH cipher suites. The default is suitable for normal application needs. See Using Diffie-Hellman Cryptography for more information.
cipher groups
The Cipher Groups option (previously known as "ECC curves") configures ECC parameters. For TLS 1.3, it sets the ECC group list; for earlier protocol versions, it sets the permitted curves. It is rarely necessary to use this configuration option. See Using Elliptic Curve Cryptography for more information.
middlebox workaround

Enables or disables the TLS 1.3 "middlebox workaround", a feature which lets TLS 1.3 work on some connections that traverse routers, firewalls, and other systems which do not correctly handle TLS 1.3. It is enabled by default, and it is rarely necessary to change this setting. Possible values are disable and enable.

For example:
[TLS]
root=/path/to/root/cert.type
certificate=/path/to/client/cert.type
key=/path/to/client/keyfile.type
passphrase=keyfile passphrase
middlebox workaround=enable
verify peer name=yes
verify depth=2
verify peer=yes
[credentials]

Use this (optional) section to set credentials (username and password) for HTTP and HTTPS requests to a given host and port, if the application does not specify them. This can be used to supply credentials to HTTP hosts that use HTTP Basic Authentication. The username and password are separated by a colon, as they would be in a URL (http://user:pass@host:port/path).

For example:
[credentials]
www.tempuri.org=username:password
myhost:9000=someuser:somepass
[service list]
Use this optional section to provide a simple directory in the configuration file itself, rather than using an MFDS server and repository. If "list" appears in the directory list (see [directories] section above), then when MFCC reaches that point in the directory list, it will search this section.

Each entry in this section takes one of two forms:

service name=location
The location string is interpreted as the location of the service. It can be a URL or an MFDS location string, for example, protocol:hostname:port.
service name=[section name]
MFCC will look for a section with the given name. It must contain an entry named 'location' with the location specified as above. It can also contain an entry named 'config', which names yet another section, holding service configuration values. This is potentially useful for defining deployment services in the service list.
For example:
[service list]
service1=http://tempuri.com
service2=[service2 definition]

[service2 definition]
location=tcpssl:myhost:9443
config=[service2 config]

[service2 config]
name1=value1
name2=value2
Parent topic: Micro Focus Common Client
Related information
CCITCP2_PORT


Configuring CCI

The Common Communications Interface (CCI) is the technology used by Micro Focus products such as Mainframe Express, 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 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 Test Server 10.0


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 systems.
  • 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
  • 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, two executable modules are provided:

  • CCITC32.DLL- 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.
  • MFDS.EXE- replaces the legacy CCITCP2 module. This is 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.
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


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


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.

  • Using Directory Server Instead of CCITCP2
  • CCITCP2 Search Order
  • CCITCP2 Troubleshooting
Parent topic: CCI Support For TCP/IP
Related information
CCITCP2
CCITCP2_PORT


Using Directory Server Instead of CCITCP2

If you have installed Enterprise Test 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 Test 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


Advanced Features

  • Using CCI Over TCP/IP Without CCITCP2
Parent topic: CCITCP Configuration


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
  • CCITCP Security Options in the CCI.INI File
Parent topic: Using CCI Over TCP/IP Without CCITCP2


CCITCP Environment Variables

  • 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


CCITCP Security Options in the CCI.INI File

ssl_only_verify_literally

By default, in this and previous releases an SSL/TLS client can trust a server which resides on an IP address that is not an intended connection target.

This trust is possible if the server has DNS aliases of the target name that is used as a Subject Alternate Name (SAN) or Common Name (CN) of the identification certificate that the server is using. This feature is deprecated and will be removed in a future release. To preserve backward compatibility this behavior has been maintained.

The ssl_only_verify_literally option enables you to restrict the certificate check to improve security. This stricter behavior can be enforced with global effect when specified as an CCI.INI option. Alternatively, you can use it as a specific application configuration. Specific application configuration is documented with the applications that support this option.

When using applications that do not yet support the configuration of this option the following CCI.INI setting can be used to override the applications behavior:

[ccitcp-base]
ssl_only_verify_literally=[yes|true|no|false]

where:

yes|true
Enforce strict checking of SAN and CN identities. Use of DNS lookup is not permitted. The connection address specified MUST match either a SAN or CN string of the appropriate type, that is IP addresses must be a SAN with type "IP Address:" and server names must match a SAN entry with type "DNS:" or a CN.
no|false
Default, enables DNS lookup of IP addresses to derive a text based location name with which to compare the contents of the peer's certificates.
Note: Some individual applications might expose this option as part of their configuration options.

Close Negotiation

The use of a controlled connection closure negotiation sequence enables you to close connections as an alternative to the typical socket linger options.

A controlled connection closure negotiation works in the following sequence:

  1. A call shutdown of the writable part of the connection. This enables other threads that may be receiving data on the connection to complete their receiving sequence and process any received data. This action causes a FIN flag to be sent to the peer.
  2. If a timeout is set for close negotiation, wait for any incoming data to complete. At this point you have either received a FIN acknowledgement from the peer or it has timed out.
  3. You have closed the shutdown and the reading side of the socket.
  4. The socket is closed.

This ensures the socket descriptor is valid until the conversation-closing handshake has completed. Alternatively, you can use a socket linger option.

You can use the close_negotiate_msecs option in the CCI.INI to specify the time to wait and control the preference of the controlled connection closure negotiation method versus the use of the socket linger method to close connections:

[ccitcp_base]

close_negotiate_msecs=[yes|no|disabled|<n>]

where:

yes|-2
Default, wait for 2 seconds for the peer to close.
no|disabled|0
Disable controlled connection closure negotiation behavior and close using SO_LINGER.
-1
Wait forever for the peer to close its end of the socket. Micro Focus recommends that you do not use this option.
>0
Wait for the specified time in milliseconds for the peer to close.
Note: Some applications support the configuration of the close_negotiate_msecs option. If the option is present in the application, then this will be used in preference to the option specified in the CCI.INI.
Parent topic: Environment Variables and the CCI.INI File


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
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.level.mf.cci = info

Once that has been set, you must then configure the degree of information traced using the ctf.cfg file.

Note: As in earlier product releases, the CCITRACE environment variable and the CCI.INI configuration file can be used to control the amount of information traced. Micro Focus recommends that you use the CTF configuration file.

If you need 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
  • Tracing Options for CTF.CFG
  • Tracing Options for CCI SSL
  • Activating CCI Tracing for Fileshare
Parent topic: CCI Tracing
Related information
To Enable CTF Tracing


CCITRACE Environment Variable

You can specify the type of information that will be recorded by CCI tracing. To do this, configure the CCITRACE environment variable as follows:

CCITRACE=options

where any, or all, of the following options can be specified with a preceding / 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
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 might be greatly increased.
D
Logs the contents of all buffers passed to and from the CCI functions. The default is OFF.
Warning: This type of tracing might not produce the desired results if the application has been coded to prohibit data tracing.

The ctf.cfg and 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
Tracing Options for CTF.CFG
Tracing Options for CCI SSL
Activating CCI Tracing for Fileshare
mf.cci Properties
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:

force_trace_on=yes|no
If yes is specified then details of CCI API calls are logged to the trace file.

The default value is no. Tracing will not be generated, even if the other options are set to yes.

protocol_trace=yes|no
If yes is specified then details of protocol-level calls are logged to the trace file and the level of function tracing can be greatly increased. The default value is no.
data_trace=yes|no
If yes is specified then the contents of all buffers passed to and from the CCI functions are logged. The default value is no.
Warning: This type of tracing might 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 the CCI.INI file.

Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Tracing Options for CTF.CFG
Tracing Options for CCI SSL
Activating CCI Tracing for Fileshare
mf.cci Properties
To Enable CTF Tracing


Tracing Options for CTF.CFG

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 ctf.cfg configuration file. The options are:

mftrace.comp.mf.CCI.TCP#on=true|false
If true is specified then details of CCI API calls are logged to the trace file. The default value is false, no tracing will be generated, even if the other options are set to true.
#mftrace.comp.mf.CCI.TCP#protocol=true|false
If true is specified then details of protocol-level calls are logged to the trace file and the level of function tracing can be greatly increased which might affect performance. The default value is false.
#mftrace.comp.mf.CCI.TCP#data=true|false
If true is specified then the contents of all buffers passed to and from the CCI functions are logged. The default value is false.
CAUTION:
This type of tracing might expose sensitive data. Some applications might disable data tracing.

For example, to enable CCI API tracing and data tracing, but not protocol-level tracing, add the following:

mftrace.level.mf.cci=info
mftrace.comp.mf.CCI.TCP#on=true
mftrace.comp.mf.CCI.TCP#protocol=false
mftrace.comp.mf.CCI.TCP#data=true

The CCITRACE environment variable or the CCI.INI file can also be used to control trace options.

Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Tracing Options for CCI.INI
Tracing Options for CCI SSL
Activating CCI Tracing for Fileshare
CCITRACE
To Enable CTF Tracing


Tracing Options for CCI SSL

SSL connection failure can be difficult to diagnose. A trace facility has been added to provide details of the reason for connection failures that occur during SSL session negotiation sequences.

CCI SSL tracing can be enabled in two ways, configuring the ctf.cfg file and/or the cci.ini file. If SSL tracing is enabled via CTF then any SSL tracing output will go to the output files configured in ctf.cfg. If SSL tracing is configured via the cci.ini file, then any SSL tracing output will go to the file specified in the cci.ini file.

Enabling SSL tracing via the ctf.cfg file

To enable CCI SSL tracing via CTF, you must first enable CTF tracing, then edit the ctf.cfg configuration file to trace the CCI component:

mftrace.level.mf.cci = info

Then specify the TLS tracing options in the ctf.cfg file. The options are:

mftrace.comp.mf.CCI.TCP#ssl_cipher=true|false
Display the negotiated cipher.
mftrace.comp.mf.CCI.TCP#ssl_cert=true|false
Display details of the peer certificate, if any.
mftrace.comp.mf.CCI.TCP#ssl_cert_fail_report=true|false

Display why the certificate could not be verified.

mftrace.comp.mf.CCI.TCP#ssl_cert_connection_details=true|false
Display all information available about the offered certificate.
mftrace.comp.mf.CCI.TCP#ssl_options_all=true|false
Switch on or off all of the SSL options listed above.

The following example ctf.cfg file configuration enables all CCI SSL tracing options:

mftrace.level.mf.cci                              = debug
mftrace.comp.mf.CCI.TCP#ssl_options_all           = true

The following example ctf.cfg file configuration enables only cipher and connection details:

mftrace.level.mf.cci                                  = debug
mftrace.comp.mf.CCI.TCP#ssl_cipher                    = true
mftrace.comp.mf.CCI.TCP#ssl_cert_connection_details   = true
mftrace.comp.mf.CCI.TCP#ssl_cert                      = false
mftrace.comp.mf.CCI.TCP#ssl_cert_fail_report          = false

Enabling SSL tracing via CCI.ini file

SSL tracing can also be enabled by configuring the [ccitrace-base] section of the CCI configuration file, cci.ini. The options are:

ssl_display_cipher=yes|no
Display the negotiated cipher.
ssl_display_cert=yes|no
Display details of the peer certificate, if any.
ssl_display_cert_fail_report=yes|no
Display why the certificate content failed its trust test.
ssl_display_cert_connection_details=yes|no
Display all details available about the offered certificate.
ssl_display_options_on=yes|no
Switch on or off all of the SSL options above.
ssl_display_destination=file path
Specify the path to a file where the tracing output is written to.
Note: The file path specifies the path to a file where the SSL tracing output will be written. For example, C:\path\to\sslout.txt. If no file is specified, then SSL tracing output will l be written to stderr instead.

The following example cci.ini file configuration enables all CCI SSL tracing options:

[ccitrace-base]
ssl_display_options_on=yes
ssl_display_destination=C:\path\to\sslout.txt

The following example cci.ini file configuration enables only cipher and connection details:

[ccitrace-base]
ssl_display_cipher=yes
ssl_display_cert=no
ssl_display_cert_fail_report=no
ssl_display_cert_connection_details=yes
ssl_display_destination=C:\path\to\sslout.txt
Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Tracing Options for CCI.INI
Tracing Options for CTF.CFG
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
Tracing Options for CTF.CFG
Tracing Options for CCI SSL


CCI.INI - The CCI Configuration File

The CCI.INI file is used to specify selective configuration options for all or some CCI modules installed.
  • 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
CCIERRLOG
CCITRACE


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 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 | Resolution
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.
0056 | Error | Client found a registered service but could not make a connection. |
0057 | Error | Insufficient permission to complete an operation. | Check the process permissions for the configuration files being used. Note: If this error is reported during a failure to start CCITCP2, MFDS, or a listener on UNIX. All UNIX and Linux environments require root user permission to start TCP/IP services on reserved ports. These are typically port values lower than 1024
0060 | Error | Protocol does not support the requested operation. | Use a different protocol or do not attempt this operation.
0061 | Error | The requested operation has been disabled. | Internal error, please contact OpenText Support for Micro Focus Products.
0062 | Error | CCITCP SSL_new call failed - internal resource limitation error. | A system or process limit has been reached. Please retry using fewer TCP/IP connections to the system. If this does not resolve the issue then reduce the number of listeners being used in this process.
0063 | Error | CCITCP SSL_Connect call failed - maybe an un-trusted Server. | CCITCP cannot connect to the specified server because of a cryptographic configuration mismatch between peer and this system. Check your SSL options and ensure that they are compatible between server and client. For example, ECDSA clients may not be able to connect to an RSA certified server.
0064 | Error | SSL could not obtain a certificate from the peer on this link. | The local end is configured to require a trust in the peer. The peer is not providing an identity certificate that can be checked. Confirm that the peer's configuration matches your connection requirements.
0065 | Error | SSL Configuration Error, All connection methods disabled - could not connect. | The local SSL options are incorrectly configured to enable a connection between server and client. Try extending the range of ciphers and/or protocols used in the server configuration.
0066 | Error | CCITCP SSL_accept call failed due to invalid client credentials. | The connecting client does not have the required certificated credentials resulting in the connection being rejected. Correct the client configuration or reduce the server's peer checking requirements.
0067 | Error | An error was found in the 'publicname' parameter syntax. |
0068 | Error | An error was found in the 'machinename' parameter syntax. |
0069 | Error | SSL Configuration requires a CA Root certificate, none was found. |
0070 | Error | SSL Configuration error, ID certificate file not found or corrupted. |
0071 | Error | SSL Configuration error, ID certificate format not acceptable. |
0072 | Error | SSL Configuration error, ID certificate password incorrect. |
0073 | Error | SSL Configuration error, ID private keyfile not found or corrupted. | If the wrong password is used with some types of keyfile then this error message is returned instead of 74. Check the password being used is correct. If the password is correct, check that the keyfile has not been corrupted.
0074 | Error | SSL Configuration error, ID keyfile password incorrect. |
0075 | Error | SSL Configuration error, Password incorrect or Certificate and Keyfiles do not match |
0076 | Error | SSL Server connection context error, internal error. |
0077 | Error | SSL Connection error, Peer ID certificate location content and actual address do not match. |
0078 | Error | SSL Connection error, peer certificate has no subject field content. |
0079 | Error | SSL Connection error, peer certificate has no issuer detail - cannot verify with a CA issuer |
0080 | Warning | SSL Connection error, peer certificate has no revocation list address. | This can be ignored if you do not require certificate revocation list checking. To avoid this warning, modify your certificate to contain the correct information fields to support revocation checks.
0089 | Error | SSL Configuration error, Invalid or unsupported SSL/TLS Protocol. | Check the protocol list configuration.
0090 | Error | SSL Configuration error, Invalid SSL/TLS Cipher List. | Check the cipher list configuration with the OpenSSL cipher list specification.
0091 | Error | SSL Configuration error, Invalid ECC curve list. | Check that you are using a valid range of ECC curve definitions for products that support a per-connection initial ECC curve specification.
Parent topic: CCI Status Messages
Related information
CCITCP2


Error Messages

For a full list of the error messages, see the General Reference > Error Messages section in the Enterprise Developer documentation available from the OpenText Support and Services Documentation Web site for Micro Focus products.

Parent topic: Micro Focus Enterprise Test Server 10.0
Related reference
Directory Server Error Messages
Enterprise Server Error Messages
HCOSS Error Messages
JCL Error Messages


Troubleshooting Enterprise Server Applications

Describes how to set about diagnosing common problems that can occur with running applications in Enterprise Server and gives some advice about overcoming them.
Important: In addition to this collection of topics, many of the topics contained in the Troubleshooting COBOL Applications section could also help you to resolve problems with Enterprise Server applications.
  • Minimum Diagnostic Configuration Recommendations for Production Systems
  • Determining the Failure Type
  • Diagnostics in Enterprise Server
  • Performance Issues
    Provides information on the types of scenarios that can affect performance issues, and provides recommendations to improve performance.
  • Collecting Information
  • Additional Troubleshooting Topics for Enterprise Server Applications
Parent topic: Micro Focus Enterprise Test Server 10.0


Minimum Diagnostic Configuration Recommendations for Production Systems

Diagnostics are essential to troubleshooting your production systems running on Enterprise Server. We recommend that you configure each enterprise server region running either a development or a production application as follows. This ensures that you have a good starting point for problem determination as and when you encounter one:

Enable Dump on System Abend
The server produces 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. To enable this setting:
  1. In ESCWA, click NATIVE.
  2. In the navigation pane, expand Directory Servers > Default, and then select your enterprise server instance.
  3. On the GENERAL drop-down list, select Diagnostics.
  4. Check Dump on System Abend, and then click APPLY.
Enable Auxiliary Tracing
The server flushes trace records to disk before the trace table is overwritten.
Note: Be sure you have adequate disk space available, because this 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. Also, this setting can affect performance.
To enable this setting:
  1. In ESCWA, click NATIVE.
  2. In the navigation pane, expand Directory Servers > Default, and then select your enterprise server instance.
  3. On the GENERAL drop-down list, select Diagnostics.
  4. Check Auxiliary Trace Active, and then click APPLY.
Enable core dumps
See To configure an enterprise server instance to produce a core dump for instructions.
Parent topic: Troubleshooting Enterprise Server Applications
Related concepts
Determining the Failure Type


Determining the Failure Type

If you have not set up your application with the recommended minimum diagnostic configuration, do this as specified in the Minimum Diagnostic Configuration Recommendations for Production Systems

The types of failures you might encounter when running your application on Enterprise Server are varied. Once you are familiar with the types of failures that can occur, take a look at the tools for initial diagnosis to help you decide the type of failure you have encountered.

Important:

Types of failures

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.

Key initial classifiers

  • Incorrect Output
  • Unexpected System Termination
  • Invalid Credentials Error
  • Tools for Initial Diagnosis
Parent topic: Troubleshooting Enterprise Server Applications
Related concepts
Minimum Diagnostic Configuration Recommendations for Production Systems


Incorrect Output

When application output is not what it should be, the first step in determining the problem is to identify application problems vs. Enterprise Server infrastructure problems.

Application failures other than abends are often application problems. Start by consulting the 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 OpenText Support for Micro Focus Products.

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 credentials (user id and/or password) that are being provided to the Directory Server. The user id or password are missing or are incorrect, and/or the Directory Server is not using the expected security configuration.

The credentials casstart uses to bind to the Directory Server can be specified in a number of ways: as literal command line parameter values using /u and /p (Micro Focus recommends that you do not use this method), or via /z so that the values are input from standard input. For example, using this method, the credentials could be input from the configured vault. If credentials are stored in the vault, ensure the correct vault location is specified and the operating system id under which the casstart process is executing has access to the vault. The mfsecretsadmin utility can confirm vault access and credentials values. In addition, credentials can be specified in ESCWA if the enterprise server region is being started that way.

If it is confirmed the expected credentials are being specified, then the Directory Server security configuration must be checked. This can be performed using ESCWA. Check that the expected Security Managers are in use and the specified user id exists.

If the enterprise server region is started from ESCWA, and ESCWA itself is secured, then check the credentials used to login to ESCWA are valid for the Directory Server. The best way to do this is to ensure that ESCWA, the Directory Server, and the enterprise server region are all using consistent security configurations and Security Managers. Check that the Directory Server has the Use ES Default Security Managers option checked for its Security Facility configuration. In Enterprise Developer 10.0, this is the default configuration for new product installs. Another possible reason for credentials specified to casstart to be invalid when connecting to the Directory Server is if the enterprise server region is using an external Security Manager and the Directory Server is using Directory Server Internal Security. Or the enterprise server region is not configured to use security but the Directory Server is. A useful facility to check security configuration is the ESCWA Security Configuration Report tool which will highlight whether the Directory Server, enterprise server regions, or ESCWA are using external Security Managers or not, as well as other common security configuration issues.

Parent topic: Determining the Failure Type


Tools for Initial Diagnosis

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
In the Communications Log, 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.
A 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. You can obtain this list using a third-party tool such as Process Explorer.

These classifiers coupled with the external symptoms should provide enough information to assign the failure to one of the types of failure listed.

Parent topic: Determining the Failure Type
Related concepts
Console Log
Related information
Communications Log


Diagnostics in Enterprise Server

Micro Focus Enterprise Server includes a varied set of tools to assist you in problem analysis. These tools are the result of numerous implementations, and the realization that different sorts of problems can occur, each requiring its own type of approach.

As a minimum, we recommend that anyone involved in a COBOL implementation should know, for each diagnostic tool or utility:

  • What it does
  • How to configure it
  • What output is produced, and where to find it

Depending on the type of problem, you might need to use several diagnostic tools together to solve a problem. For example, you could use the Console log to identify the failing process, and a trace and dump output to see processing details including critical interactions with the other processes. When used together, these tools can pinpoint what led to the failure.

Notes:
  • The diagnostic tools and utilities listed here are specifically for use with Enterprise Server applications. In addition, you can use most if not all of the diagnostic tools and utilities listed in the Diagnostics for COBOL Applications section under Troubleshooting COBOL Applications. Many of these are important diagnostic tools and should not be overlooked.
  • This documentation attempts to explain each diagnostic tool such that you should be able to analyze the output and resolve problems yourself in many circumstances. In cases where you are unable to do this, raise a OpenText Support for Micro Focus Products case for additional help. See Reporting a Problem for complete information.
  • Application Diagnostic Reporting for Enterprise Server
    Application diagnostic reporting can be enabled and configured to collect and package a number of reports, trace, and log files into a single report file.
  • Auxiliary Trace
    This provides a trace of activity over a time period within the main CAS facilities.
  • Communications Log
  • Console Log
  • 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.
  • Developer Tools
    Describes the use of your browser's Developer Tools feature to capture diagnostic information.
  • Directory Server Journal
  • Dumps
    Describes the dumps you can create with Enterprise Server to help you identify the source and type of a problem encountered while running an application.
  • 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.
  • Fileshare Trace
    This facility provides specialist tracing of the transactional file handler technology.
  • Global Tracing and Logging
    Describes the ESCWA tracing and logging settings that apply to all Directory Servers.
  • Historical Statistical Facility (HSF)
    Provides the ability to record statistics related to the time spent in a COBOL program.
  • Memory Strategy
    Memory strategy can be enabled where memory corruption is detected or suspected.
  • MFCS Connector Tracing
    Each MFCS listener has an associated connector module.
  • MFESDIAGS Utility
  • Micro Focus Support Scan Utility
  • Protection Violations
  • Security Tracing
    Security trace messages can be written to the console.log, the MFDS journal.log, and the AUX trace.
  • Security Auditing
  • Stack Dump Production
  • System Directory Location
  • XA Switch Module Tracing
    Additional trace can be enabled to provide more detail regarding the XA Resource Manager interface.
  • Using a Diagnostics Server
  • How to
Parent topic: Troubleshooting Enterprise Server Applications
Related concepts
Reporting a Problem


Application Diagnostic Reporting for Enterprise Server

Application diagnostic reporting can be enabled and configured to collect and package a number of reports, trace, and log files into a single report file.

The diagnostic report reduces the time spent searching for relevant diagnostic information stored at multiple locations. The diagnostic report will collect information on CICS API failures, Run-Time System (RTS) errors, and JCL process failures.

To enable application diagnostic reporting, add the following to your enterprise server region's Configuration Information field on the Properties page in ESCWA:

[ES-Environment]
ES_FAILURE_REPORT_ENABLED=Y

The default value is N.

Note: To enable a failure report you must set either Dump on ABEND Sys or Dump on ABEND Tran. An RTS error requires the Dump on ABEND Sys to be set, and a CICS API failure requires Dump on ABEND Tran to be set. See ES Control for more information.

You can perform additional report configuration using the following variables:

ES_FAILURE_REPORT_CORE=Y|N
Set this option to disable the generation of the core dump component of the diagnostic report.

If failure reporting has been enabled the default value is Y.

ES_FAILURE_REPORT_PRINTENV=Y|N
Set this option to disable printing of the contents of COBCONFIG and MFTRACE_CONFIG.

If failure reporting has been enabled the default value is Y.

ES_FAILURE_REPORT_LOCALTRACE=Y|N
Set this option to disable printing the local trace table.

If failure reporting has been enabled the default value is Y.

ES_DUMP_LIMIT=number
Specifies the limit for minimum time interval (ms) between storage dumps/reports created for errors with the same DUMPCODE and CALLER.
Note: Micro Focus recommends that you use the Advanced Region Properties page in the Enterprise Server Common Web Administration (ESCWA) interface to configure these environment variable. See Advanced Region Properties for more information.

The diagnostic reporting can also be configured from the ESCWA ES Control page. See ES Control for more information.

The following message is displayed in the console log when an application diagnostic report is created:

DU0006I Failure report file (%1$s) created

Or if it fails to create the report:

DU0007W Unable to create failure report file (%1$s)

The diagnostic report is written to the default System Directory, located by default in %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName. This is typically the location of the console.log file.

The following is an example of the start of the diagnostic report:

Start of Enterprise server failure report       Date: 12/18/2020 (mm/dd/yyyy)  Time: 13:49:10.24                                                Process ID: 00001818  Thread ID: 69914880  Failure type: RTS-Err
...

Where the Failure type can be:

RTS-Err
Run-Time System (RTS) errors.
CICS-API
CICS API failures.
JES
JCL process failures.

A failure summary is then displayed. This is specific to the failure type and the report configuration.

Parent topic: Diagnostics in Enterprise Server


Auxiliary Trace

This provides a trace of activity over a time period within the main CAS facilities.

When active, this feature flushes trace records to disk before the trace table is overwritten.

Note: Be sure that you have adequate disk space available before activating auxiliary trace because the output file can become very big very quickly. If you have a high-activity system, you can limit the size of the output file by also configuring the maximum size of the diagnostics file. Writing out to a file also degrades performance.

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.

Trace file datasets

For auxiliary traces, you have the option in Enterprise Server, to write trace output to either an A or a B dataset file. The default is A, but you can toggle between the two.

Output files

Trace output files are written to your system directory, and take the following form:

casauxta.rec
Output file for the A dataset.
casauxtb.rec
Output file for the B dataset.

Archiving auxiliary trace files

To archive the auxiliary trace file, set the archive_auxiliary_trace property to true. Once set, every time you toggle between writing to casauxta.rec and casauxtb.rec the currently active .rec file is moved to a new archive file, named casauxt.nnn. Where the nnn file name component is an incremental count of the switches that have previously occurred, starting from 001. The archive file is reset to casauxt.001 on the thousandth switch.

You can set the archive_auxiliary_trace property in the Enterprise Server Common Web Administration (ESCWA) interface on the Advanced Region Properties page.

Note: To view a video on the Micro Focus YouTube channel, on how to enable AUX tracing for Enterprise Server using the Legacy Enterprise Server Administration User Interface, click here. While the UI is different than ESCWA, the concepts are the same.
Parent topic: Diagnostics in Enterprise Server
Related concepts
System Directory Location
Related tasks
To change the trace dataset
To configure trace information
To enable auxiliary tracing
To view a local trace for a SEP


Communications Log

This log contains a cumulative, chronological list of all communications processes run by an enterprise server region. It contains messages from the communications manager and any associated listeners including a date and time stamp for each. Messages show information related to specific processes including the addresses and port numbers used.

When 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].

Uses
Use the communications log to review server communications for individual enterprise server regions and to identify communications problems when troubleshooting.
Output file
Name | Location
log-1.html | The enterprise server region's system directory folder
The default configuration for communications logs is to have one communications log for each enterprise server region. Communications messages generated for the enterprise server region are added to the file during each session, creating a cumulative log of all communications processes run on that server. You can manually archive and then delete the communications log to begin a new one at the next server startup.
Note: To keep cumulative logs from growing to unmanageable sizes, your Enterprise Server administrator can activate the rotating log files feature. This might change the number of log-n files for each server. Check with your administrator for details.
Parent topic: Diagnostics in Enterprise Server
Related concepts
Tools for Initial Diagnosis
Related tasks
To view the communications log in ESCWA
Related information
To view the communications log in ESCWA
Communications Log


Console Log

The Console log contains the activity of your enterprise server region since startup, showing all processes leading up to a failure. It is automatically generated during each server session.

Uses
Start your troubleshooting by reviewing this log to see what errors occurred, when they occurred, and the process ID and timestamp for each. Compare this information to output from other diagnostic tools to determine which errors match up with the activity reported by those other tools.
Output file
Name | Location
console.log | The enterprise server region's system directory folder. See System Directory Location for the default location, or check the General Properties server page in ESCWA and the System Directory setting.

At startup, an enterprise server region renames the most recent console.log file to console.bak, overwriting any existing console.bak file.

Important: When gathering information for a OpenText Support for Micro Focus Products case, include both the console.log and console.bak files. Be sure to back these up before restarting the server after a failure.
Parent topic: Diagnostics in Enterprise Server
Related concepts
Preparing to Raise a Support Case
Tools for Initial Diagnosis
System Directory Location
Reporting a Problem
Security Tracing
XA Switch Module Tracing
Related tasks
To view the console log in ESCWA
Related information
System Directory Location
To view the console log in ESCWA


Developer Tools

A useful trace option for ESCWA issues is to use the Developer Tools feature within the web browser itself to inspect the network requests. Almost all requests within ESCWA are sent and received in JSON format, so errors within ESCWA itself can be caused by malformed JSON.

Note: The following instructions are generic with regard to the browser you are using. For complete instructions on using your browser's developer tools, see the documentation provided by your browser.
  1. To access the Developer Tools for ESCWA, open Enterprise Server Administration in a browser of your choice, and then consult your browser docmentation for specific instructions.
    Hint: Developer Tools are often found under the More Tools option on your browser's customization or settings menu.
  2. In the Developer Tools window, click the Network tab.
  3. In ESCWA, run the series of steps that caused the problem.

    You should see each step appear on a list in Developer Tools.

  4. On the Network tab, click on the name of the enterprise server region or page where the error occurs.
  5. In the right pane of the Developer Tools window, click Response.

    This shows the JSON response that was sent, and should allow you to identify the particular area of the request that might trigger the error.

Important: If you want to log a OpenText Support for Micro Focus Products case for an error found using Developer Tools, copy and save the JSON response, and send it along with the other required information for your support case. See Reporting a Problem for details.
Parent topic: Diagnostics in Enterprise Server
Related concepts
Reporting a Problem


Directory Server Journal

If MFDS is enabled with TLS encryption,

You can access the journal from clicking on the Directory Server node and then the JOURNAL button.

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
Note: There is an additional level, in which extra file and internal operations are written to the journal, but this level should only be enabled on request of OpenText Support for Micro Focus Products.

Output is written to the journal.dat file.

For troubleshooting purposes, you might want to set the maximum level of logging.

Parent topic: Diagnostics in Enterprise Server


Dumps

You can configure Enterprise Server to create system and transactional dumps that help you identify the source of a problem and the type of issue. You can view the contents of most dump files in Enterprise Server, and you can use the dump output files to help OpenText Support for Micro Focus Products help you to resolve the issue encountered.

Types of Enterprise Server dumps

You can generate the following types of dumps from Enterprise Server

System dump
Created when the failure is due to a problem originating with Enterprise Server itself.
Transaction dump
Created when the failure is due to a problem originating in a program running on the enterprise server instance.
Core dump
This type of dump file is created when either a system or transaction failure occurs, and can be used to debug the application. See To configure an enterprise server to produce a core dump for details.
casdump
You can create a dump file externally using the casdump command. Use this when a dump cannot be obtained normally; for example, when the enterprise server instance is not responding and shared memory is locked. See casdump for details.

Dump file datasets

For system and transaction dumps, you have the option in Enterprise Server to write dump output to either an A or a B dataset file. The default is A, but you can toggle between the two.

Output files

With the exception of core dump output, dump output files are written to the Enterprise Server system directory, and take the following form:

casdumpa.rec
Output file for the A dataset.
casdumpb.rec
Output file for the B dataset.
casdumx.rec
Output file for the casdump /d external command.

For core dump files, you specify the filename and directory when you configure your enterprise server instance to create core dumps. See To configure an enterprise server instance to produce a core dump for details.

Parent topic: Diagnostics in Enterprise Server
Related concepts
Reporting a Problem
Related tasks
To initiate a system dump on stop server
To configure system and transaction dumps
To view a dump file in ESCWA
Related reference
casdump
Related information
System Directory Location


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: Diagnostics in Enterprise Server


Fileshare Trace

This facility provides specialist tracing of the transactional file handler technology.

Fileshare is a transactional File Handler for VSAM and other Micro Focus COBOL files, and Fileshare trace would be required only if you have Fileshare configured for use.

To enable tracing, in the case of standalone Fileshare, you can start the Fileshare server with the /tr f option - this option will write the trace information to the console window and also to a file called fsscreen.lst in your Fileshare directory. (If you are starting Fileshare as a service, only the .lst file is written to.)

Whilst Fileshare is running, you can also toggle tracing on/off using either of the following methods: if you have access to the Fileshare console window, press F2 to toggle on/off; or, if you have Fileshare administrative privileges, log on to FSVIEW and execute the trace toggle command.

When toggling the tracing on/off, where the tracing information is recorded depends on how Fileshare was started. If started with the option above, both the console window and fsscreen.lst record the tracing information (unless it was started as a service - see above). If Fileshare was started without the tracing option, only the console window will record the tracing information, and when started as a service, only fsscreen.lst will record the tracing information.

Micro Focus recommends that you delete any existing fsscreen.lst files before starting a Fileshare server, otherwise your new trace output will be concatenated to the existing file, which can be confusing when trying to diagnose problems.

Generally, Fileshare trace should be used only for specific cases during testing, because it can have a great impact on performance.

Parent topic: Diagnostics in Enterprise Server


Global Tracing and Logging

ESCWA provides some built-in tracing and logging capabilities that apply to all enterprise server instances. When you enable global tracing, Enterprise Server generates a CTF-style diagnostics file. In addition, you can create a global communications log that can help you to diagnose connection issues errors within the ESCWA process itself.

Parent topic: Diagnostics in Enterprise Server
Related tasks
To set global tracing and logging options


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 or tasks, SQL operations and JCL jobsteps, as well as associated file and TSQ accesses.

Note: When a CICS abend occurs, the 4 letter abend code appears after the transaction ID in HSF records.
Parent topic: Diagnostics in Enterprise Server


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: Diagnostics in Enterprise Server
Related tasks
To transfer in-memory trace data to an auxiliary dataset at rollover


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: Diagnostics in Enterprise Server


MFESDIAGS Utility

OpenText Support for Micro Focus Products can provide you with the MFESDIAGS utility to help you solve a problem. This utility pulls together the various diagnostics that OpenText Support for Micro Focus Products needs to assist in solving some problems. For more information, contact your OpenText Support for Micro Focus Products engineer.

The data collected by MFESDIAGS needs to be provided to OpenText Support for Micro Focus Products as a zip file named using the following convention:

case-number_YYYY-DD-MM_HH-MM-SS-snapshot.zip

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.

See Raising and Managing Support Cases for more information.

Parent topic: Diagnostics in Enterprise Server
Related concepts
Raising and Managing Support Cases


Micro Focus Support Scan Utility

We provide the Micro Focus Support Scan Utility to gather information about your computer environment, the status of Micro Focus products installed, and other statistics relevant to troubleshooting problems on your machine, including:

  • The amount of memory in your computer
  • Computer storage capacity
  • Details of your operating system
  • Set environment variables
  • Running processes
  • Status of services
  • Details of any networking software you are using
  • The names, release numbers, install dates, and install locations of all Micro Focus products
  • The names, release numbers, install dates, and install locations of all non-Micro Focus products
  • Micro Focus entries in the registry
  • Micro Focus licensing information

While you certainly can and should use the information provided to aid you in diagnosing and correcting problems yourself, it is particularly helpful as an aid to OpenText Support for Micro Focus Products as we work to help you to resolve cases you log with us.

To run the Support Scan utility:
  1. Start an Enterprise Developer command prompt. If you need instructions, see To start an Enterprise Developer command prompt.
  2. At the command prompt, enter:
    MFSupportInfo
    Note: Using the Support Scan utility is intuitive. Take some time to look around the user interface and discover the information it has collected.
To save Support Scan information to an XML file
  1. On the Micro Focus Support Scan Utility menu, click File > Save.
  2. Browse to the directory where you want to save the XML file.
  3. Click Save.

    You can optionally attach the log file to your support case. See Reporting and Managing Support Cases for details.

To save Support Scan information to a .zip archive
  1. On the Micro Focus Support Scan Utility menu, click Tools > Create Zip Package.
  2. Browse to the directory where you want to save the .zip file.
  3. Click Save.

    You can optionally attach the zipped archive to your support case. See Reporting and Managing Support Cases for details.

To email Support Scan output directly to OpenText Support for Micro Focus Products
  1. On the Micro Focus Support Scan Utility menu, click Tools.
  2. Select Email Log to SupportLine.
  3. In the From field, type your email address.
  4. In the Find attached... field, type your OpenText Support for Micro Focus Products case number. See Reporting and Managing Support Cases for details.
  5. Optionally provide additional Customer notes.
  6. Click Send.
Important: All output files are named using the following convention:
MFSupportInfo_Log_computer-name_YYYY-MM-DD_HH-MM-SS.ext

Where ext can be either xml or zip depending on the type of output file.

Do not rename any output files before sending them to OpenText Support for Micro Focus Products.

Parent topic: Diagnostics in Enterprise Server
Related concepts
Raising and Managing Support Cases


Protection Violations

  • Types of Protection Violations
  • Correcting Protection Violations
  • Debugging Techniques
Parent topic: Diagnostics in Enterprise Server


Types of Protection Violations

Protection violations occurs when a machine instruction tries to execute and is found to be illegal in the context of the currently running process. There are two classes of protection violation, general and COBOL protections violations.

Your COBOL development system is thorough in preventing or trapping potentially illegal code. However, it is still possible for your programs to generate code that is illegal in some way, and when this happens the error might be trapped as a general protection violation by the operating system or a COBOL protection violation by this COBOL system.

  • What Are Protection Violations?
  • General Protection Violations
  • COBOL Protection Violations
  • Unflagged Protection Violations
Parent topic: Protection Violations


What Are Protection Violations?

A protection violation occurs when a machine instruction tries to execute and is found to be illegal in the context of the currently running process. This might be because the instruction is not recognized by the processor (as is the case if data is executed as if it were a procedure), or if a valid instruction references a memory location or other resource that is invalid in the context of the currently running process. There are two classes of protection violation, general and COBOL protections violations.

Parent topic: Types of Protection Violations


General Protection Violations

Operating systems typically allocate only a portion of a computer's resources to each process and monitor each process to see that it does not exceed its allocation. If the operating system detects a process exceeding its allocation, it takes some error action. The action it takes is a general protection violation (also known as an exception) or some other action, depending on the operating system.When the operating system detects a general protection violation, it runs a special program called an exception handler before abandoning the process that caused the exception. The exception handler might be one specifically associated with the program that caused the exception. Alternatively, if there is no specific handler, the operating system runs its own default exception handler.

Parent topic: Types of Protection Violations
Related information
Correcting Protection Violations


COBOL Protection Violations

Where appropriate, this COBOL system provides facilities to monitor a COBOL application (or non-COBOL program running under the control of the COBOL system) to ensure that it does not exceed the resources allocated to it by the COBOL system. A COBOL protection violation occurs when your COBOL system sees a program behaving in this way. Whether the COBOL system detects a protection violation depends on which resources are monitored, how they are monitored, and how the resources are allocated. The hardware and operating system determine how effectively the COBOL system can monitor COBOL protection violations. A COBOL program might appear to run correctly in one environment, but might fail if available resources change or the operating system changes.

Parent topic: Types of Protection Violations


Unflagged Protection Violations

Protection violations typically occur when a process tries to access a memory location that lies outside the memory allocated to that process for the type of access it is attempting. Clearly the process miscalculated the location it wants to access.

However, if the same process moves, is rearranged in memory, or grows in size, the memory location might eventually lie in the range of the process. In such a case, the process would not give rise to a protection violation even though we would like it to.

If this is the case, the primary effect is that a statement in the program returns an incorrect result. If the application does not use that result, you will not notice a problem. However, if subsequent execution relies on the value returned by that statement, the program might exhibit unexpected behavior. Possible secondary effects can be split into two categories depending on the memory area that your program modifies:

  • If the memory area lies in an unprotected COBOL system area, the COBOL system might exhibit unexpected behavior, including that resulting from executing data as if it were procedure. This could lead to a general protection violation or infinite loop.
  • If the memory area lies in the program area, the program could produce incorrect results or fail at a later point as a result of a legitimate access to the memory area that had previously been corrupted.
Parent topic: Types of Protection Violations


Correcting Protection Violations

This section describes some of the common causes of protection violations (and RTS errors associated with COBOL protection violations) and suggests how you can overcome these problems.

  • Errors in Non-COBOL Portions of an Application
  • Parameter Mismatches in a CALL Statement
  • Stack Overflow
  • Illegal Reference Modification
  • Illegal Values for Pointers
  • Subscript Out of Range
  • Incorrect Linking Options or Procedures
Parent topic: Protection Violations


Errors in Non-COBOL Portions of an Application

Because of the success of this COBOL system at detecting COBOL protection violations, it is uncommon for COBOL applications to result in general protection violations. In contrast, other programming languages, such as C, typically make heavy use of pointers which increase the probability of causing general protection violations. If your application fails with a general protection violation and contains a part that is written in a language other than COBOL, we recommend that you closely investigate the part of the application that is not written in COBOL. In most cases, that is where the general protection violation is caused.

Parent topic: Correcting Protection Violations


Parameter Mismatches in a CALL Statement

The CALL statement provides a number of areas where general protection violations can occur if you make a mistake in specifying the call.The following are things you should check if you suspect that a CALL statement might be causing a general protection violation:

  • The number, size, and usage of parameters in the calling program must match those in the called program.
  • The REFERENCE, CONTENT, and VALUE clauses in the calling program must match the definitions of the parameters in the called program.These factors become more difficult to manage when one of the calling or called programs is not COBOL. As a result, protection violations are more likely in such applications. You must ensure that the non-COBOL language conforms with the default calling convention for COBOL, or COBOL conforms to the calling convention of the non-COBOL language (by using the CALL-CONVENTION clause). The effects of a mismatch in the calling interface between two programs can be extremely varied depending on the interaction between the mismatch in question and the calling conventions used.
Parent topic: Correcting Protection Violations


Stack Overflow

A less obvious cause for a general protection violation is stack overflow. The stack is the system area in which called parameters and the calling program return address are temporarily stored for a CALL statement. Stack overflow occurs when the level of nesting of called subprograms, or the size or number of passed parameters is greater than the stack can manage.Stack overflow can occur due to excessive use of the stack, or because the default or requested stack size is small. You should bear in mind that operating system support routines might also make use of the stack and reduce its effective size, and that different versions of the same operating system can make different use of the stack, thus varying its effective size.

Parent topic: Correcting Protection Violations


Illegal Reference Modification

Using reference modification you can easily reference an area of memory that lies outside the named data item. The results of illegal reference modification depend on the location of the area of memory that your program accesses:

  • The area of memory lies outside the data item but still in the program's data area. This does not usually result in a general protection violation.
  • The area of memory lies in the program's procedure area. The operating system might trap a general protection violation.
  • The area of memory lies outside the address range allocated to the program. This COBOL system recognizes this, and produces RTS error 114 ("Attempt to access item beyond bounds of memory").

In the example below, the reference modification results in RTS error 114 ("Attempt to access item beyond bounds of memory") when run. This is caused by setting a to be greater than the maximum length of b. The first use of a reference modified item is a source field, so results in incorrect data being passed into c. This problem is detected by this COBOL system.The second use of a reference modified item is potentially more dangerous, as the reference modified item is a target field. Again, this COBOL system detects this problem and produces RTS error 114 ("Attempt to access item beyond bounds of memory").This example is used in the following sections to illustrate how to debug the program in various environments.

 program-id. "buggy".
 working-storage section.
 01 a pic 9(6).
 procedure division.
     move 999999 to a
     call "bug" using a
     stop run.
 end program "buggy".

 program-id. "bug".
 working-storage section.
 01 b pic x(20).
 01 c pic x.
 linkage section.
 01 a pic 9(6).
 procedure division using a.
     move b(a:1) to c
     move "1" to b(a:1)
 exit program.
Parent topic: Correcting Protection Violations


Illegal Values for Pointers

Data items that you define with usage POINTER or PROCEDURE-POINTER must contain valid addresses when they are used. Using a pointer that does not contain a valid address results in RTS error 114 ("Attempt to access item beyond bounds of memory"), because this COBOL system traps the error that would otherwise result in a general protection violation.

In the example below, data item undefined-pointer is defined as a pointer to a procedure, but is not given a value before it is used. As a result, the CALL statement fails, giving RTS error 114 ("Attempt to access item beyond bounds of memory").

 working-storage section.
 01 undefined-pointer  usage procedure-pointer.
 procedure division.
     call undefined-pointer
 stop run.
Parent topic: Correcting Protection Violations


Subscript Out of Range

The values of subscripts and index items are checked by this COBOL system, with an RTS error 153 ("Subscript out of range") given if they are found to be out of range. However, checking subscripts and index items decreases the performance of your application to some extent. To avoid this decrease in performance you can use the NOBOUND directive to disable such checking. If the NOBOUND directive is used and a subscript or index item is out of range when referencing a table, a protection violation might occur. If you get unexpected results or a protection violation error in an application that has been compiled or generated with the NOBOUND directive, you should recompile the program without the directive and rerun it to determine if the fault is caused by a subscript error.

The following programs show how you could experience unexpected results as a result of inadvertently using an out-of-range subscript when the NOBOUND directive is specified. Because of the value passed from Bound-main, Build-sub moves "1" to the 21st element of an array that is only 20 elements in size. Because the NOBOUND directive is specified, this COBOL system permits this operation, which overwrites the next data item, c. If the NOBOUND directive was not set, the COBOL system would have given RTS error 153 ("Subscript out of range") when the MOVE was performed.

 program-id. "bound-main".
 working-storage section.
 01 a pic 99.
 procedure division.
     move 21 to a
     call "bound-sub" using a
     stop run.
 end program "bound-main".

$set align(2 fixed) nobound
 program-id. "bound-sub".
 working-storage section.
 01 b pic x occurs 20.
 01 c pic xx.
 linkage section.
 01 a pic 99.
     procedure division using a.
     move (1) to b(a)
 exit program.
Parent topic: Correcting Protection Violations


Incorrect Linking Options or Procedures

There are a number of linking options that if used incorrectly might indirectly cause a general protection violation. Problems commonly occur when either the wrong objects or libraries are linked, or the correct objects or libraries are used, but incorrect versions of them. If you suspect that this might be the case, you should check that old versions of objects or libraries have not been left in search paths and that new versions have been installed correctly.

Parent topic: Correcting Protection Violations


Debugging Techniques

The techniques you use to debug a program when you encounter a protection violation or an RTS error depend on how the program is loaded or built. For example, if a program is built as an operating system executable file (such as an .exe file or a .dll file), the operating system loads the program and uses special privileges to partition memory for different usages and trap inappropriate references. For example it might split data and procedures and trap attempts to execute data or write over procedure code. When you run a program as an .int file or .gnt file, the operating system loads the run-time system, and the run-time system dynamically loads your COBOL program. In general, the run-time system cannot use the operating system's special privileges to load the COBOL program into protected areas. Instead, where appropriate, the COBOL system sets up its own COBOL traps in conjunction with the operating system general protection violation traps.

Parent topic: Protection Violations


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.

Parent topic: Diagnostics in Enterprise Server
Related concepts
Console Log


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: Diagnostics in Enterprise Server


Stack Dump Production

Restriction: This only applies to Linux platforms.

The Micro Focus COBOL Run-Time System enables you produce a stack dump when a run-time system error occurs for native COBOL applications that are built to an executable or shared object. .NET COBOL programs, or programs built to INT/GNT format, are not supported by this functionality.

If the stackdump_on_error tunable is enabled, a stackdump file is generated at the point of the application's failure. The file is created in the program's working directory unless a different location has been set using the stackdump_filename tunable.
Note: If the core_on_error tunable is also in effect and set to produce a core file, then due to the order in which the two tunables a processed, a stackdump file is only generated if core_on_error is set to 3.

The stackdump file contains a stack trace for each thread within the program. The level of detail within a trace can depend on how the program was compiled: compilation for debug generates a more comprehensive stack trace, with most (if not all) COBOL statements appearing in the stack; compilation for a production environment produces a more optimized code and therefore may produce a less comprehensive stack. In either case, the top-most entry indicating the COBOL program and its line number should give a strong indication of where the program is failing.

  • To Produce a Stackdump File
Parent topic: Diagnostics in Enterprise Server


To Produce a Stackdump File

Restriction: This only applies to Linux platforms.

A stackdump file is not produced by default when a run-time system error occurs; to produce the file, the first tunable in this list needs to be set to 1:

  • stackdump_on_error - determines if a stackdump file is produced.
  • stackdump_filename - overrides the default name and location of a stackdump file. This tunable is optional.

You can set these on the command line using the methods described in Run-Time Tunables, or you can set them in the Eclipse IDE.

Note: For certain platforms, you can also generate a stackdump file using the CBL_CREATE_STACKDUMP library routine; see CBL_CREATE_STACKDUMP for more details.
Parent topic: Stack Dump Production


System Directory Location

You can view the output generated by most diagnostic facilities in ESCWA; however, if you need to send diagnostic output files to a colleague or to OpenText Support for Micro Focus Products, then you need to know where to find them.

Unless otherwise noted, diagnostic output files are written to a subdirectory bearing the same name as its enterprise server region, and is located under the defined Enterprise Server system directory. The default system directory is:

%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA

For example, if the name of your enterprise server region is MYSVR, diagnostic output files for the MYSVR enterprise server region would be

%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\MYSVR

To learn how to change the location of the system directory, see To change the system directory.

Parent topic: Diagnostics in Enterprise Server
Related concepts
Dumps
Console Log
Auxiliary Trace
Related tasks
To change the system directory
Related information
Moving the Diagnostics Data
Console Log
Moving the Diagnostics Data
To view the console log in ESCWA


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: Diagnostics in Enterprise Server
Related concepts
Console Log


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: Diagnostics in Enterprise Server


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
System Directory Location
System Directory Location


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 ES Monitor & Control to access the diagnostic server's ESMAC screen.
  3. In the Diagnostics area in the left pane, check Trace, and select either the A or B to select the A or B dataset.
    Note: Do not 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 value.

    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 column, check 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 characters are used:
    A
    SNA service
    B
    JES initiator
    C
    Communications process (MFCS)
    D
    IMS DB Manager (IMSD) - DB control
    E
    TRC service
    F
    Fileshare server (internal)
    H
    Temporary Storage, Channels and Containers Control (TSC)
    I
    IMS Communications Manager (IMSC) - TM Control
    J
    Journal control
    l
    Common Communications Interface (CCI)
    L
    MQB service process
    M
    Server manager
    O
    RAS scale-out process
    P
    IMS Message (IMSM) Processing Region
    Q
    MQ service
    R
    Recovery
    S
    Service Execution Process (SEP)
    T
    JES printer
    U
    Unknown
    Z
    Generic terminal or client
    3
    3270 terminal or client service
  • In Task IDs column, 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 do not 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: 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.

The following 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.
hhmmssttt
A time stamp that indicates when the trace entry was written. The time stamp is in hours, minutes, seconds, and milliseconds.
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 value.

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


How to

  • To change the trace dataset
  • To configure system and transaction dumps
  • To configure trace information
  • To enable auxiliary tracing
  • To initiate a system dump on stop server
  • To set global tracing and logging options
  • To transfer in-memory trace data to an auxiliary dataset at rollover
  • To view a dump file in ESCWA
  • To view a local trace for a client process
  • To view a local trace for a SEP
  • To view a system trace
  • To view the communications log in ESCWA
  • To view the console log in ESCWA
Parent topic: Diagnostics in Enterprise Server


To change the trace dataset

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Control.
  4. In the DIAGNOSTICS group, click SWITCH TRACE SET.

    By default, Enterprise Server uses the A dataset for output files. 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: How to
Related concepts
Auxiliary Trace


To configure system and transaction dumps

Note: To use these options, your enterprise server instance must have a started Web listener. See Listeners for details.
  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Control.
  4. In the DIAGNOSTICS group, check Dump on ABEND Sys and/or Dump on ABEND Tran, depending on what type(s) of information you need:
    Dump on ABEND Sys
    Check this to produce a dump if an abend occurs due to an error in Enterprise Server itself.
    Dump on ABEND Tran
    Check this to produce a dump if an abend occurs due to a problem with any of your transaction programs. When checked, you can further control the contents of the dump file on the program level by checking or unchecking Dump on abend on the PCT Properties dialog box for a specific program. When unchecked, the setting of Dump on abendis ignored.
  5. Click APPLY.
    Note: By default, Enterprise Server uses the A dataset for output files. If you want to change the dataset, click SWITCH DUMP SET. 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: How to
Related concepts
Dumps


To configure trace information

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Control.
  4. Click TRACE.
  5. Check the boxes that correspond to the information you want to include in the trace file.
    Note: For a description of each check box, click Help Help.
  6. Click APPLY.
Parent topic: How to
Related concepts
Auxiliary Trace


To enable auxiliary tracing

  1. In ESCWA with your enterprise server instance in Stopped mode, select your enterprise server instance on the list of default servers in the tree view.
  2. Click GENERAL > Diagnostics.
  3. In the DIAGNOSTIC OPTIONS section, check Auxiliary Trace Active.
  4. In the TRACE FLAGS section, check the trace flags you want to include in the trace output.
    Note: For a description of each trace flag, click Help Help.
  5. Click APPLY.
Parent topic: How to
Related concepts
Auxiliary Trace


To initiate a system dump on stop server

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Control.
  4. Check Dump.
  5. Click STOP.
    Dump files are written to your system directory with a filename of casdumpn.rec, where n is either a or b depending on the currently specified dataset.
    Note: By default, Enterprise Server uses the A dataset for output files. If you want to change the dataset, click SWITCH DUMP SET. 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: How to
Related concepts
Dumps


To set global tracing and logging options

  1. In ESCWA, click Settings Settings.
  2. On the Enterprise Server Administration Configuration window, click TRACING AND LOGGING SETTINGS.
  3. Check Enable Tracing.
  4. In the File Name field, optionally type the full path and filename for the trace output file. The default path is your system WORKAREA directory, and the default filename is ESCommonWebAdmin.trace.txt.
    Note: You can interpret the output file using the MF.ES.COMMONWEBADMIN.xml file located in the in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer.
  5. Under Enable Tracing for, check the boxes that correspond to the components for which you want to generate trace information.
    Note: For a description of each check box, click Help Help.
  6. In the Logging Directory field, type the full path to the directory where you want to store the global communications log.
  7. Click APPLY.
  8. Click BACK to close the Enterprise Server Administration Configuration window.
Parent topic: How to
Related concepts
Global Tracing and Logging


To transfer in-memory trace data to an auxiliary dataset at rollover

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Control.
  4. In the DIAGNOSTICS section, check Trace Active.
  5. Click APPLY.
Note: By default, the enterprise server uses the A dataset to record trace information.
Parent topic: How to
Related concepts
Memory Strategy


To view a dump file in ESCWA

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Logs > Dumps.
  4. To optionally change the level of dump information displayed, click LEVEL and then select one of the following:
    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.

    Each level includes all lower-level information. Local trace tables (traces for SEPs) only have levels 0 and 1.

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: How to
Related concepts
Dumps


To view a local trace for a client process

Note: Local traces are available only for WebSphere MQ listeners and communications processes (MFCS).
  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Clients.
  4. Click the row for a client process.
  5. At the end of the row, click Display Display.
Parent topic: How to


To view a local trace for a SEP

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > SEPs.
  4. Click the TYPE drop-down list, and select Auxiliary: ES TRC Service from the list.
  5. Click the Auxiliary: ES TRC Service row on the list.
  6. At the end of the row, click Display Display.
Parent topic: How to
Related concepts
Auxiliary Trace


To view a system trace

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. Click Monitor > Logs > Trace.
  4. To optionally change the level of trace information displayed, click LEVEL and then select one of the following:
    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.

    Each level includes all lower-level information. Local trace tables (traces for SEPs) only have levels 0 and 1.

  5. Click DETAILS to see details of the trace.
Note: The X dataset contains traces 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: How to


To view the communications log in ESCWA

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. On the MONITOR drop-down list, click Logs > Communications Log.
Parent topic: How to
Related concepts
Communications Log
Related information
Communications Log


To view the console log in ESCWA

  1. While your enterprise server instance is in Start mode, start or access the ESCWA Web interface.
  2. Select your enterprise server instance on the list of default servers in the tree view.
  3. On the MONITOR drop-down list, click Logs > Console Log.
Parent topic: How to
Related concepts
Console Log
Related information
Console Log
System Directory Location


Performance Issues

Many projects identify performance issues at some point, and occasionally slow-downs can occur in production systems. These two types of performance issues are different, and should be approached differently.

For performance testing during implementation, we recommend that the following protocol be followed as closely as possible:

  • Define what acceptable performance is. This can be:
    • The same as an alternative platform, for example, the IBM mainframe
    • The acceptable processing rate as determined by a set of particular users
    • Some other criteria

    This gives you a target to aim for, and to measure how close you are to being complete.

  • Identify a representative benchmark program or execution scenario
  • 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 affect
    • 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: Troubleshooting Enterprise Server Applications


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

  • Data Capture
  • Checking the Communications Process
  • Production System Failure Data Capture
Parent topic: Troubleshooting Enterprise Server Applications


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 Server\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 .
  • The Directory Server configuration directory, usually under the %ALLUSERS%\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 OpenText Support for Micro Focus Products.
  • 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: Collecting Information
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. Record 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. Record 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 will 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: Some of your communications processes for a given server might be disabled; they do not need to be checked.

You can also append /file to URL for the MF_STATISTICS request (for example, http://hostname:port/MF_STATISTICS/file). This will cause MFCS to append the statistics report to a file named statistics.txt in the system directory, the file is created if it does not already exist. The system directory is the same location as the MFCS log files log*.html. MFCS does this before attempting to send the HTTP response, so it might work even in circumstances where MFCS is unable to send the response to the browser. This can also be used to periodically collect information about the MFCS workload.

Parent topic: Collecting Information


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.

The script is MFESdiags.cmd which can be obtained from OpenText Support for Micro Focus Products. 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.

The script invokes the '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 data sets, 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 , 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
  • Windows System and Application Event logs
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: Collecting Information


Additional Troubleshooting Topics for Enterprise Server Applications

In addition to the topics contained in this Troubleshooting Enterprise Server Applications section of this documentation set, additional topics that pertain to troubleshooting other Enterprise Server features are interspersed throughout the Deployment section of this documentation set. The following links take you directly to these additional topics.

Note: This list is not necessarily an exhaustive representation of all helpful troubleshooting topics contained herein.
CICS

MSS Aspects of Troubleshooting for CICS

CICS Web services

Troubleshooting CWI SSL

MSS Aspects of Troubleshooting

Clustering

Recovery

EZASOKET Tracing

[ezasoket] Section

File Handling

TRACE

JCL

JCL Aspects of Troubleshooting

Performance Availability Clusters

Troubleshooting a PAC

Reporting Issues

Security

Troubleshooting a Secure Connection

Troubleshooting Certificate Problems

XA-compliant resources

XA Troubleshooting

Parent topic: Troubleshooting Enterprise Server Applications


Reporting a Problem

Describes best practices in reporting a problem, describes the information we need from you to resolve your problem, and provides step-by-step instructions for raising a Case via the Support Portal or by directly contacting OpenText Support for Micro Focus Products via telephone.

  • Preparing to Raise a Support Case
  • Different Types of Cases
  • Raising and Managing Support Cases
Parent topic: Micro Focus Enterprise Test Server 10.0
Related concepts
Dumps


Preparing to Raise a Support Case

We recommend that you follow the guidelines presented here to prepare to log a support case.

All Problems

The following is good practice for gathering information about your problem so you can pass it on to OpenText Support for Micro Focus Products. This information is required for all support cases:

Micro Focus product serial number
To locate your product serial number, look in the subject line and body of either your Electronic Delivery Receipt email or Micro Focus Software Activation Information email that you received from Micro Focus when you activated or got a license key.
Computer make and model
You should be able to find this information somewhere on your physical computer.
Product and environment information
The best way to collect information about the software installed on your computer and the environment in which it runs is to run the Micro Focus Support Scan utility, which automatically gathers this information for you.

See Micro Focus Support Scan Utility for details on how to run this utility, and options for adding its output to your support case.

Details about your problem
When you raise a support case, you are asked to provide the following as you log the case:
  • An accurate subject line that briefly and succinctly describes your problem. For example, a subject line such as:

    Source won't compile, getting error code ###

    or

    Enterprise Server shows error code ### during restart

    rather than a more general and less useful description such as:

    Error with source compile

    or

    Enterprise server is crashing

  • A full description that provides:
    • Context for the problem
    • Your own observations and knowledge
    • Step-by-step instructions that your Micro Focus engineer can follow to reproduce the problem
    • For compilation problems, compiler directive options used
  • Additional details specific to your type of case. See Different Types of Cases for complete information.

Easily reproducible problems

An easily reproducible problem is one that occurs reliably when using the product. For these, in addition to the information outlined in the All Problems section above, be ready to provide a zipped copy of your project and/or source code to enable Micro Focus to reproduce the problem quickly and easily.

Complex problems

Complex problems are classified as infrequent problems in production systems, or problems based on random timing and factors. Resolution often requires low-level analysis, review of logs and traces, and possible multiple iterations.

In addition to those listed in the All problems section above, use these best practices for more complex problems to significantly improve the likelihood that your Micro Focus engineer can give you a quick and satisfactory response. Cases that receive the best support responses include the following:

  • The full description provided when you log your case includes details such as:
    • Chronology
    • Symptoms
    • Configuration specifications
    • Workload levels
    • What else was happening in the environment at the time
    • Any third-party software involved
  • A zipped archive of the source code in development when the problem occurs
  • A zipped archive of all relevant first point-of-failure diagnostics files
    Attention: Failure diagnostics are critical; please always provide them when available. See Diagnostics for COBOL Applications and/or Diagnostics for Enterprise Server Applications to help you determine which diagnostic tools you can use to provide this information.
We recommend that your set of diagnostics:
  • Includes complete diagnostics such as traces, dumps, the console log, and other relevant logs.
  • Be chronological, meaning that all of the logs for the same failure should be in sequence.
  • Be specific enough to allow us to identify the exact failure, the date and time of the failure, the symptoms demonstrated, whether or not recovery was achieved, and if so, if it was achieved automatically or manually.

The Raising and Managing Support Cases section provides detailed information on how to log a support case, and how a OpenText Support for Micro Focus Products engineer can help you to resolve your problem.

Parent topic: Reporting a Problem
Related concepts
Information We Need
Console Log


Different Types of Cases

We recognize that you can run into a variety of problems as you test and use your applications. In this section, we address four particular problem types for which you can raise a support case, and also provide a list of information you should gather before reporting each type.

  • Compiler-related Failures
  • Debugging Failures
  • Reproducible Run-time Failures
  • Unpredictable Run-time Failures
Parent topic: Reporting a Problem


Compiler-related Failures

For this type of issue, the minimum that we request you supply is:

  • A cut-down sample 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.
    Tip: If you compile to .lst and supply this to us, you can see all included copybooks and the directives being used. Upload the .lst file to your support case.
  • 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 Cases


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 case 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.
  • Associated debugging files, including CTF trace files.
Parent topic: Different Types of Cases


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.

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 Cases


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.

The long description in particular should provide as much context and detail as possible, including chronology and timeline.

Parent topic: Different Types of Cases


Raising and Managing Support Cases

If you cannot resolve your issue on your own, and you have an active Business Support agreement for your product, you may raise a support case with OpenText Support for Micro Focus Products.

Important:
  • Please report only one problem for each case.
  • If a solution or workaround has been provided, and you encounter a further problem, open a new case with new details.

This allows us to assign the appropriate engineer to each unique issue, and allows for several engineers to progress cases simultaneously.

Reporting high-and critical-severity issues by phoning OpenText Support for Micro Focus Products

For high- and critical-severity issues, meaning either a production system is down or you are experiencing a major feature or function failure, call OpenText Support for Micro Focus Products at the appropriate telephone number listed on the Contact Support page.

Reporting new issues via the Support Portal

For low- and medium-severity issues, open the case on the Micro Focus Support Portal page. Detailed instructions can be found here.

Managing existing cases

To manage existing cases:

  1. Log into the Support Portal.
  2. Click Cases on the menu ribbon at the top of page, and then select the class of cases you want to view.
    Tip: When viewing the list of support cases, you can use settings Settings and filters Filters to adjust how they are displayed.
  3. On the list of cases, click the Case Number link for the case you want to manage.

Uploading attachments

Before you can upload sample and diagnostic files, you need to get a Dropbox account user name and password from your OpenText Support for Micro Focus Products contact. To do this:

  1. Have the case open in the Support Portal. See Managing existing cases above if you need instructions.
  2. Hover over the name of your contact for the case, which appears under Contact Name at the top of the page.

    The contact information appears in a popup.

  3. Contact your contact and obtain a Dropbox account user name and password to use for your incident.
  4. On your Case page, click the link under the Exchange files field to invoke the Micro Focus File Transfer Service, and use your Dropbox account credentials to upload your files.
Parent topic: Reporting a Problem
Related concepts
Micro Focus Support Scan Utility
MFESDIAGS Utility


Copyright and Legal Information

  • Copyright and Trademarks
  • Secure Communications (SSL) Legal Information
  • NET SNMP Copyright
Parent topic: Micro Focus Enterprise Test Server 10.0


Copyright and Trademarks

© Copyright 1984 - 2024 Micro Focus or one of its affiliates. 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.

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.

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.

2024-10-28

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 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 Test Server 10.0


Added/changed in Release 12.20

The specified text and/or functionality has been added for Release 12.20.


Added/changed in Patch Update 20

The specified text and/or functionality has been added for Patch Update 20.


Added/changed in Patch Update 8

The specified text and/or functionality has been added for Patch Update 8.


MAX_POOL_THREAD_CASTRC

Sets the maximum number of pool threads for CASTRC.
Restriction: You only need to use this variable when recommended by OpenText Support for Micro Focus Products.

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


Added/changed in Patch Update 24

The specified text and/or functionality has been added for Patch Update 24.


Create an XA Resource

You will require one XA resource for each datastore that contains one or more transactional files.
  1. Open the ESCWA Administration page, and then select the enterprise server that references the transactional data file from the left pane.
  2. In the right pane, click General > XA Resources.
  3. Click NEW.
  4. Specify the following XAR details:
    Option | Description
    ID | Unique ID for the XAR
    Name | Unique name for the XAR
    Module | Specify the location of the RM switch module executable file (.dll on Windows or .so on UNIX platforms). This is database specific: esmssql.dll/.so for MSSQL and Azure SQL, ESPGSQLXA.dll/.so for PostgreSQL, and ESDB2XA.dll/.so for Db2. Refer to Building RM Switch Modules for more information.
    Enabled | Enable the resource for immediate use.
    Open string DSN=<datastore-dsn>

    where <datastore-dsn> is the ODBC data source name of the datastore you are configuring.

    Note: These are only the mandatory options required, with the addition of USRPASS=userid.password if you are using a PostgreSQL database. You can also specify further options as required, as detailed in To define an XA resource (XAR) for an enterprise server region.
  5. Click SAVE.

    The XA resource should be effective immediately.

Related concepts
Building RM Switch Modules


MAX_POOL_THREAD_CASGATE

Sets the maximum number of pool threads for CASGATE.
Restriction: You only need to use this variable when recommended by OpenText Support for Micro Focus Products.

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


MAX_POOL_THREAD_CASDBC

Sets the maximum number of pool threads for CASDBC.
Restriction: You only need to use this variable when recommended by OpenText Support for Micro Focus Products.

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


Added/changed in Patch Update 1

The specified text and/or functionality has been added for Patch Update 1.


Added/changed in Patch Update 12

The specified text and/or functionality has been added for Patch Update 12.


PAC Scale-Out Repository (PSOR)

Regions in a Performance and Availability Cluster (PAC) need to share synchronized user and system data. To facilitate the sharing and synchronicity requirement, a PAC uses a data store referred to as a Scale-Out Repository (SOR). The mandatory PAC SOR (or PSOR) stores system configuration, and other data that needs to be accessible by all regions in the PAC.

A PAC must have only one PSOR.

PAC Scale-Out Repository (PSOR)

PSOR


Added/changed in Patch Update 4

The specified text and/or functionality has been added for Patch Update 4.


File Handling

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.
Related concepts
Configuration File Options


MAX_POOL_THREAD_CASTMC

Sets the maximum number of pool threads for CASTMC.
Restriction: You only need to use this variable when recommended by OpenText Support for Micro Focus Products.

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 Mainframe Access
Related concepts
Compare and Synchronize Monitor


Performance and Availability Cluster (PAC)

A Performance and Availability Cluster can be used to specify where resources, queues, and files will be stored and accessed within a group of scale-out regions.
Important: Before you start working with PACs you need to specify SORs for use in your PACs.

Performance and Availability Cluster (PAC)

PAC


Added/changed in Patch Update 22

The specified text and/or functionality has been added for Patch Update 22.


Added/changed in Patch Update 5

The specified text and/or functionality has been added for Patch Update 5.


Added/changed in Patch Update 14

The specified text and/or functionality has been added for Patch Update 14.


Scale-Out Repository (SOR)

You can configure one or more Scale-Out repositories (SOR) to store specific types of user data, currently limited to non-recoverable TS and TD queues. You can choose which instances of user data are stored in a SOR using a SOR Model. For example, if only a subset of TSQs need to be shared, then a SOR Model can be used to specify which TSQs are directed to the SOR. Instance data that does not match a SOR Model rule continues to be stored on its local enterprise server instance.

Scale-Out Repository (SOR)

SOR


Added/changed in Patch Update 10

The specified text and/or functionality has been added for Patch Update 10.


Added/changed in Patch Update 15

The specified text and/or functionality has been added for Patch Update 15.


Added/changed in Patch Update 16

The specified text and/or functionality has been added for Patch Update 16.


Added/changed in Patch Update 25

The specified text and/or functionality has been added for Patch Update 25.


Enter the required information

Specify the name of the Panvalet user code on which to filter the data set.
Parent topic: Using Mainframe Access
Related concepts
Drag and Drop


Added/changed in Patch Update 13

The specified text and/or functionality has been added for Patch Update 13.


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 Mainframe Access
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 OpenText Support for Micro Focus Products.

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


Setup and Licensing

Read these topics to learn how to setup and license your product.

  • Setup
  • Deployment Licensing
  • Managing Licenses
Parent topic: Welcome


Added/changed in Patch Update 11

The specified text and/or functionality has been added for Patch Update 11.


Added/changed in Patch Update 2

The specified text and/or functionality has been added for Patch Update 2.


Added/changed in Patch Update 7

The specified text and/or functionality has been added for Patch Update 7.


Added/changed in Patch Update 29

The specified text and/or functionality has been added for Patch Update 29.


MAX_POOL_THREAD_CASMQB

Sets the maximum number of pool threads for CASMQB.
Restriction: You only need to use this variable when recommended by OpenText Support for Micro Focus Products.

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


Added/changed in Patch Update 30

The specified text and/or functionality has been added for Patch Update 30.


Added/changed in Patch Update 28

The specified text and/or functionality has been added for Patch Update 28.


Added/changed in Patch Update 19

The specified text and/or functionality has been added for Patch Update 19.


Catalog Location

Enter the path and name of your catalog file (CATALOG.DAT).
Parent topic: Using Mainframe Access
Related concepts
The Local Catalog


Added/changed in Patch Update 23

The specified text and/or functionality has been added for Patch Update 23.


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 Mainframe Access
Related concepts
The Local Catalog


Added/changed in Patch Update 27

The specified text and/or functionality has been added for Patch Update 27.


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 Mainframe Access
Related concepts
Compare and Synchronize Monitor


Added/changed in Patch Update 3

The specified text and/or functionality has been added for Patch Update 3.


Added/changed in Patch Update 21

The specified text and/or functionality has been added for Patch Update 21.


Added/changed in Patch Update 17

The specified text and/or functionality has been added for Patch Update 17.


Added/changed in Patch Update 6

The specified text and/or functionality has been added for Patch Update 6.


Added/changed in Patch Update 9

The specified text and/or functionality has been added for Patch Update 9.


Added/changed in Patch Update 26

The specified text and/or functionality has been added for Patch Update 26.


Data File Tools

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.


Added/changed in Patch Update 18

The specified text and/or functionality has been added for Patch Update 18.


WADM010: userid is not a registered user.

The user you are attempting to update or delete does not exist. Add the user, or enter another UserID.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM011: Unknown table format in table name.

Internal error. Contact Micro Focus Technical Support.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM012: No password specified.

There is no password specified for this user. A password is required in order to add or update this user. Enter a password.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM013: User userid is already registered.

The user you have specified already has an entry in the SYSXDB.SYSACFUSERS table. UserIDs must be unique. Enter a new UserID.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM014: No UserID specified.

You must specify a UserID in order to add, delete or update the user.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM016: No User Comment specified.

You must specify a user comment in order to add or update the user.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM017: Memory allocated insufficient for the number of groups found.

Memory allocated insufficient for the number of groups found.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM018: Group name already exists.

You have attempted to create a new group using a group authorization ID that already exists in the SYSXDB.SYSACFGROUPS table. Group auth-IDs must be unique.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM019: No Group Authorization ID specified.

You have attempted to add, update, or delete a group but did not specify a group authorization ID. The auth-ID is required to identify the group.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM020: Group name does not exist.

You have attempted to delete or update a group, but no group was found in the SYSXDB.SYSACFGROUPS table whose authorization ID matches the one you entered.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM022: name is not a valid group name.

The group name you have entered is not a valid database object name. See the SQLWizard online help for the allowable syntax for database object names.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM023: The priority name does not exist.

You must enter an existing priority in order to update or delete.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM027: The User ID entered is invalid.

The User ID should conform to Ordinary Identifiers. See the SQL Reference for more details.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM028: Valid range for value value is > 0 and < number.

One of the governor values was out of the legal range. Enter a valid value.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM029: name is not a valid priority name.

The priority name you have entered is not valid.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM030: No Priority Name specified.

You must specify a priority in order to add, delete or update a priority.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM031: Priority name already exists.

You have attempted to create a new priority using a priority that already exists in the SYSXDB.SYSGOVERNOR table. Priorities must be unique.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM032: An error occurred while updating an internal list (name).

Internal error. Contact Micro Focus Technical Support.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM033: The SecondaryID name is invalid.

The SecondaryID should conform to Ordinary Identifiers. See the SQL Reference for more details.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM034: Cannot delete yourself ('name') as a User.

You are currently logged in as user 'name', so it is not possible to delete 'name' as a user.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM002: Passwords don't match.

The password you re-entered did not match the one entered previously. Make sure you enter the same password twice.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM003: You must enter a UserID before entering a password.

A UserID must be entered before you will be permitted to enter a password. Enter a UserID.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM004: Expected number record(s), got number.

Internal error. Contact Micro Focus Technical Support.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM005: Password must have at least number characters.

The password you have entered does not meet the length criterion required by the password enforcement level specified in the Configuration utility.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM006: Password must contain at least one digit.

Each password entered must contain at least one digit in order to meet the criteria required by the password enforcement level specified in the Configuration utility.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM007: Password must contain the characters character and character.

Each password entered must contain the specified characters in order to meet the criteria required by the password enforcement level specified in the Configuration utility.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM008: Incomplete information retrieved from table name.

Internal error. Contact Micro Focus Technical Support.

Parent topic: WADM - SQLWizard Administrator Error Messages


WADM009: User userid belongs to unregistered group name.

According to the SYSXDB.SYSACFMEMBERS table in the SYSTEM location, user userid belongs to group name. However, group name is missing from the SYSXDB.SYSACFGROUPS table. Any group in SYSASCMEMBERS must also be in SYSACFGROUPS. You may remedy this situation by inserting group name into SYSACFGROUPS by selecting the Insert Group option under the Groups menu in XADMIN. Or you can delete group name from SYSACFMEMBERS by running the following interactive SQL command:

DELETE FROM SYSTEM.SYSXDB.SYSACFMEMBERS WHERE GROUPAUTHID = userid;

Parent topic: WADM - SQLWizard Administrator Error Messages


XU010: Error deleting file name. error-descr.

The system could not delete the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.

Parent topic: XU - Library Error Messages


XU011: Error seeking file name. error-descr.

The system could not seek the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.

Parent topic: XU - Library Error Messages


XU014: Incorrect file version in file name.

The file specified is not the current version. If it is a help file or error file, you must recompile the file using the current version of the help compiler, XDBHELPC. If the file is a message file, you must recompile it using the message compiler, XDBMSGC.

Parent topic: XU - Library Error Messages


XU015: Corrupted file format in file name.

The file specified could not be entirely read. Check to see if it is the correct file. You may consider trying a backup file name.

Parent topic: XU - Library Error Messages


XU016: Invalid file or path specification.

The directory you have specified cannot be accessed.

Check that you have typed the path name correctly. Also check that the directory exists and that you have permission to access it.

Parent topic: XU - Library Error Messages


XU017: The file FileName does not have correct read/write permissions.

FileName has permission settings that prevent the software from reading or writing to it.

If FileName is on your local computer, change the file's permissions using a utility such as the DOS ATTRIB or Windows' Attribute command (in most cases you will need to disable the file's read-only attribute).

If FileName is on a network, check with your network administrator to obtain the needed access rights.

Parent topic: XU - Library Error Messages


XU018: Invalid drive in search path.

The drive letter you have specified does not exist.

Check to make sure that you have specified the correct drive. If you are using a network, also make sure that the drive letter is mapped to a physical device.

Parent topic: XU - Library Error Messages


XU020: Maximum of 3 unsuccessful attempts to login.

You have attempted to log on to a XDB Server using an invalid user ID and/or password three consecutive times, so XDB Server will automatically exit the client application.

Restart the client application and try logging on again, ensuring that you:

  • Log on to the correct server
  • Enter the correct user ID
  • Enter the correct password using the correct combination of upper and lowercase letters
Note:

XDB Server passwords are CASE-SENSITIVE! Make sure that CAPS LOCK is off if all or part of your password is lowercase.

If you enter this information correctly and still cannot log on, contact your XDB Server Administrator to check your User ID and/or reset your password.

Parent topic: XU - Library Error Messages


XU021: More than 15 errors...

The active program has issued more error messages than this dialog box can display. Only the first 15 are shown.

Correct the displayed errors and re-execute the operation.

Parent topic: XU - Library Error Messages


XU022: Invalid server name.

The string of characters you have entered does not constitute a valid server name. For example, the string contains an illegal character (such as a space) or is too long.

Correct the server name and re-execute the operation. See your SQL Reference for valid server names.

Parent topic: XU - Library Error Messages


XU023: Invalid location name.

The string of characters you have entered does not constitute a valid location name. For example, the string contains an illegal character (such as a space) or is too long.

Correct the location name and re-execute the operation. See your SQL Reference for valid location names.

Parent topic: XU - Library Error Messages


XU025: Unknown system error. Errno = ErrNumber. Doserrno = DErrNumber.

An internal error has occurred, and the error number is out of range.

Do the following:

  • Record the error numbers reported by this error message.
  • Note which operation was in process when the error occurred.
  • Contact Micro Focus Technical Support.
Parent topic: XU - Library Error Messages


XU030: Object name not found in SYSIBM.SYSTABLES while checking if it's an alias.

An internal operation did not find a record for the requested alias in SYSIBM.SYSTABLES. This usually indicates an inconsistency in your catalog tables.

Check that the SYSIBM setting in Options is correct. Also check that the values in SYSIBM.SYSTABLES are correct. Often the problem is caused by an out-of-sync catalog cache location. If this is the case, rebuild the catalog cache. If this is not the case, or if rebuilding the catalog cache does not correct the problem, contact Micro Focus Technical Support.

Parent topic: XU - Library Error Messages


XU031: Object name is not an alias.

The alias requested by an internal operation is not defined as an alias in the SYSIBM.SYSTABLES. This usually indicates an inconsistency in your catalog tables.

Check that the SYSIBM setting in Options is correct. Also check that all aliases are defined in SYSIBM.SYSTABLES, and that they are denoted with an "A" in the TYPE column.

Often this problem is caused by an out-of-sync catalog cache location. If this is the case, rebuild the catalog cache. If this is not the case, or if rebuilding the catalog cache does not correct the problem, contact Micro Focus Technical Support.

Parent topic: XU - Library Error Messages


XU032: Error Querying SYSTABLES

An internal operation encountered an error while attempting to get alias information from SYSTABLES.

Check that the SYSIBM setting in Options is correct. Also check that the values in SYSIBM.SYSTABLES are correct and that you have SELECT privileges on this table.

Often this problem is caused by an out-of-sync catalog cache location. If this is the case, rebuild the catalog cache. If this is not the case, or if rebuilding the catalog cache does not correct the problem, contact Micro Focus Technical Support.

Parent topic: XU - Library Error Messages


XU001: No more RAM memory available to application.

Insufficient memory (RAM) was available to execute a command sent to the SQL Engine. Try running the application from outside the main or application menu to see if that gives you enough memory to continue. If you have other memory resident programs loaded, remove them and try again. Load network drivers into high memory or remove them. Reduce DOS memory consumption by using fewer FILES= and fewer BUFFERS= in CONFIG.SYS.

Parent topic: XU - Library Error Messages


XU002: No more EXTENDED memory available to application.

Insufficient extended memory is available to run the application. Try bypassing the XDB Server Main Menu, or removing other programs from memory. See error XU001.

Note: Add the following line to your AUTOEXEC.BAT file:
SET XM = /Z 12288
Parent topic: XU - Library Error Messages


XU004: Filename name is too long.

The filename you have entered exceeded the maximum length. Filenames must be 8 characters or fewer. Enter a shorter filename.

Parent topic: XU - Library Error Messages


XU005: File name not found.

Cannot find the file specified. Check to make sure that the correct directory is being used, and that the specified file exists there.

Parent topic: XU - Library Error Messages


XU006: Error opening file name. error-descr.

The system could not open the file named due to the specific operating system error. See your operating system manual for the error described and make any necessary corrections.

Parent topic: XU - Library Error Messages


XU007: Error reading file name. error-descr.

The system could not read from the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.

Parent topic: XU - Library Error Messages


XU008: Error writing file name. error-descr.

The system could not write to the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.

Parent topic: XU - Library Error Messages


XU009: Error closing file name. error-descr.

The system could not close the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.

Parent topic: XU - Library Error Messages


COBSQ0015 Host variables data types in UNION do not match.

One of the data types for host variables used in a UNION does not match

You cannot select different column types where the result column is the same ordinal position returned. For example, if the first column returned on SQL statement 1 is a numeric column and the first column returned in SQL statement 2 is a character column, that is invalid.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0016 This statement will Delete an entire table

The SQL statement will delete the entire contents of a table if executed.

No action is required, as this is a warning. Qualify the SQL statement with a WHERE clause if you do not want to delete the entire table.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0017 HostVariable is not preceded by a colon.

The SQL Option preprocessor has detected a host variable in an EXEC SQL SET statement that is not preceded by a colon. Although DB2 and XDB Server currently accept host variables without colons, this practice is unconventional and it may not be supported in future releases.

No action is required, as this is a warning. However, you might want to include the colon now to avoid problems in future releases of this software.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0018 SQL statement not currently supported - converted to comment.

The SQL Option preprocessor has detected an EXEC SQL statement that is not currently supported by the SQL Option run-time system. This statement may be valid on the database engine that the code was ported from, so the processor converts the statement to comments in order that the program can compile cleanly.

No action is required at this time. However, if SQL Option ever does support this statement, you will need to recompile this program.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0019 Operation is assumed to apply to Allocate Cursor.

The cursor name in a FETCH statement was not found.

No action is required at this time, provided that the cursor name is subsequently defined with an ALLOCATE CURSOR statement.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0021 SQL Option must be selected and available

You have installed both Host Compatibility Option (HCO) and SQL Option for DB2, and HCO is the current selection.

Make SQL Option for DB2 the currently active database.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0101: Expected token1 found token2.

The preprocessor was expecting a reserved word and did not find it.

Check the syntax of the SQL statement.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0102: Host variable mismatch.

The preprocessor was expecting host variables for the SQL statement and did not find any, or found an invalid amount of host variables.

Correct the SQL statement in error and recompile your program.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0104: Illegal symbol variable.

The SQL Option preprocessor found an invalid token in the SQL statement. The token can be a variable that should have had a colon to indicate it was a host variable. In DB2 V6 mode this is an error; it is a warning in DB2 V5 mode. This error can also result when an invalid token (such as a semi-colon) is found in the SQL statement, or a qualified host variable has more than two levels of qualification and points at a variable defined as a level 49 variable.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0106: variable Invalid/Not Declared

The preprocessor could not find the host variable variable.

Check to make sure that the host variable is declared in the program and that the picture or usage is correct. See the appropriate XDB COBOL Precompiler manual for the correct picture and usage.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0107: INTO not allowed for DECLARE.

An INTO is not allowed on a DECLARE CURSOR statement.

See the SQL Reference for the correct usage of the DECLARE CURSOR statement.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0110: No INTO clause specified.

An INTO is required for SQL FETCH or SELECT ... INTO statements.

See the SQL Reference for the correct usage of the FETCH and SELECT statements.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0111: No FROM clause specified.

A FROM clause is required for SELECT statements.

Add a FROM clause to this statement. See the SQL Reference for the correct syntax.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0112: Invalid positioning of FROM.

The FROM clause specified into the SELECT statement is before the INTO specification.

The FROM clause must follow the INTO clause. See the SQL Reference for the correct syntax.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0114: Invalid file name.

The copybook filename was not found. Check for spelling errors.

Check to ensure that the copybook exists, with the correct extensions, either in COBCPY directory or locally.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0115: Token array overflow.

The statement identified has gone over the limit set by XDB. The limit was set for memory considerations.

Call Micro Focus Technical Support.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0117: Invalid in data division.

A SQL statement in question was not defined in the PROCEDURE DIVISION.

Some SQL statements such as UPDATE, DELETE, INSERT, and SELECT..INTO can only be coded in the PROCEDURE DIVISION. Move the statement in question to the PROCEDURE DIVISION and then recompile the program.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0118: Invalid WHENEVER.

The invalid function was used as a WHENEVER argument.

If using SQL Option extensions, check to ensure that the XDBFUNCS directive is set.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0120: Not valid in current compatibility mode.

SQL Option extensions are not allowed if the XDBFUNCS directive is not set.

Recompile the program with the XDBFUNCS directive set.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0124: Group variable token is not allowed in the WHERE clause.

The group variable in token was used in a WHERE clause. This is not valid.

Do one of the following:

  • break up the group variable into its elementary items and compare each item to its corresponding field in the table
  • redefine the group variable into a single elementary item
Parent topic: COBSQ0100 - COBSQ0149


COBSQ0125: Cursor not found.

An OPEN, FETCH or CLOSE statement references a cursor name that was not DECLAREd.

The DECLARE CURSOR statement must be coded before an OPEN, FETCH or CLOSE SQL statement. If defined, move the DECLARE CURSOR statement before the statement in error. Otherwise, check to make sure the cursor name used in the DECLARE CURSOR statement matches the cursor name used in the SQL statement in error.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0126: A _ is illegal in a host variable.

An underscore (_) was found in a host variable name in the SQL statement in error.

Underscores are only valid in column names for SQL tables. A hyphen (-) is valid for host variable names. Change the underscore to a hyphen and recompile your program.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0127: A ( is illegal in the INTO clause.

A left parenthesis "(" was found in the SQL statement in error.

Correct the syntax and recompile your program. See the SQL Reference for the correct syntax.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0131: SQLCA not found OR comp/comp-5 mixup in SQLCA.

An SQLCA was not found and the directive STRICT-DB2 was set.

Check to see if an SQLCA is included and declared correctly.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0135: Host variable type mismatch.

The host variable data definition does not match the column type associate with it in the SQL statement. For example, you are trying to use a host variable defined as PIC X(n) with a column defined as SMALLINT.

Verify that the host variable that corresponds to the column definition and make any changes to correct error or use the SQL Option DCLGEN tool to generate a copybook of host variable for the SQL table in question.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0137: Indicator variable token is not SMALLINT type.

The indicator variable data definition does not match the data type associate with it in the SQL statement. For example, you are trying to use an indicator variable defined as PIC X(n) rather than PIC S9(04) COMP. SMALLINT.

Correct the picture clause for the indicator variable identified in the error message and recompile the program.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0184 Illegal token ':' found. Check to see if previous token was an indicator variable.

The SQL Option preprocessor found a colon in an SQL statement and the previous token was an indicator variable. This could be caused by a missing comma in the list of host and indicator variables in the SQL statement.

Correct the statement and recompile the program.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0185 Syntax error, last symbol read is token.

The SQL Option generic syntax parser found an error in the SQL statement.

Verify that the SQL statement is valid. Make any corrections that are required and then recompile. If the error persists and the statement is valid, contact Micro Focus Technical Support.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0189 'ORDER BY' clause not permitted.

The SQL Option preprocessor found an ORDER BY clause in an embedded SELECT...INTO statement. This is not valid on the mainframe.

Remove the ORDER BY clause or convert the statement into a DECLARE CURSOR statement, then recompile the program.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0190 GROUP BY clause on a SELECT INTO will not bind.

The SQL Option preprocessor found a GROUP BY clause in an embedded SELECT ... INTO statement. This is not valid on the mainframe.

Remove the HAVINGclause or convert the statement into a DECLARE CURSOR statement, then recompile the program.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0191 HAVING clause on a SELECT INTO will not bind.

The SQL Option preprocessor found a HAVING clause in an embedded SELECT ... INTO statement. This is not valid on the mainframe.

Remove the GROUP BY clause or convert the statement into a DECLARE CURSOR statement, then recompile the program.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0198: DB2 emulation mismatch - SERVER is in DB2 V6 mode

The SQL Option preprocessor is in DB2 V5 mode and the server is in DB2 V6 mode. Run time errors could result if you try to execute this program compiled this way.

Either change build settings to compile the program specifying the directive XDB(DB2VER=V6).

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0199: DB2 emulation mismatch - SERVER is in DB2 V5 mode

The SQL Option preprocessor is in DB2 V6 mode and the server is in DB2 V5 mode. Run time errors could result if you try to execute this program compiled this way.

Either change build settings to compile the program specifying the directive XDB(DB2VER=V5).

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0201 Illegal token variable found on SET line.

The SQL Option preprocessor found an invalid variable in a SET statement.

Locate and correct the SET statement. For a description of this statement, see the SET command in the SQL Reference.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0202 Number of host variables specified in UNION do not match.

The number of host variables specified in each SQL statement in a UNION statement is different.

Make sure that the number of host variables match for each SQL statement that are specified within UNION.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0299 Internal EXEC SQL statement table overflow - use directive MAXSQL to override default.

The SQL Option preprocessor predefines space for 750 SQL statements. This error is produced if more than 750 SQL statements have been coded in the program.

Specify the directive XDB(MAXSQL=nnnn), where nnnn is a number greater than 750 to allow more than 750 SQL statements, then recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0312 Undefined or unusable host variable token

The SQL Option found an unusable host variable in the SQL statement. This error can result when a qualified host variable has more than two levels of qualification or points at a variable defined as a level 49 variable defined with two levels of qualification.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0324 SQLDA fields defined with incompatible fields for XDB OPTIMIZE directive setting.

When emulating DB2 for OS/390, you must use COMP fields in your SQLDA definition. If you specify OPTIMIZE=PC, you must use COMP-5 fields.

Change the XDB OPTIMIZE directive or modify your SQLDA definition, then recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0325 Multiple types of SQLDA's detected - all SQLDA's must use same structure.

The SQL Option preprocessor supports multiple types of SQLDA definitions. When coding them in a program, they all must be defined using the same structure or data corruption or a protection violation could occur. The preprocessor found multiple types of SQLDAs in the program. If you use a DB2 for OS/390-style SQLDA, you also need to specify the XDB directive XDB(SQLDA-VER=1)

Change your SQLDA definitions to be consistent and recompile your program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0326 SQL statements not supported in nested subroutine.

The XDB directive IGNORE-NESTED was specified but a SQL statement was found in a nested subroutine. This directive stops the SQL Option preprocessor from generating any code for SQL statements.

Remove the SQL statements from the nested subroutine and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0327 Invalid BLOCKING option specified – valid options are: FSR, SR, or LB.

The SQL Option preprocessor found an invalid option for the preprocessor directive BLOCKING.

Correct the directive and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0328 Invalid DEFAULT-CHAR option specified – valid options are: BITS, SBCS, DBCS, or SYSDEFAULT.

The SQL Option preprocessor found an invalid option for the preprocessor directive DEFAULT-CHAR.

Correct the directive and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0329 Invalid EXIST-CHECK option specified – valid options are: REQUIRED or OPTIONAL.

The SQL Option preprocessor found an invalid option for the preprocessor directive EXIST-CHECK.

Correct the directive and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0330 Required directive AUTOBIND not specified with directive directive.

The SQL Option preprocessor did not find the AUTOBIND directive specified with the preprocessor directive specified in the error message.

Add the AUTOBIND directive and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0331 Invalid DATE format specified - valid options are: ISO, EUR, JIS, USA or LOCAL.

The SQL Option preprocessor did not find option for the DATE directive. It must be one of ISO, EUR, JIS, USA, or LOCAL.

Correct the DATE directive and recompile the program

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0332 Invalid TIME format specified - valid options are: ISO, EUR, JIS, USA or LOCAL.

The SQL Option preprocessor did not find option for the TIME directive. It must be one of ISO, EUR, JIS, USA, or LOCAL.

Correct the TIME directive and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0333 Invalid number of values specified, maximum is 10 per option: token .

The SQL Option preprocessor found more than 10 options specified for the directive identified by the token in the error message.

Remove the excess options and recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0334 Only one DBRM specified when multiple other directives specified for AUTOBIND.

The SQL Option preprocessor found more than one option specified in either the AUTHID, COLLECTION-ID, or LOCATION directives but only one DBRM specified.

If you want to create multiple bind files with multiple options, you need to specify more than one DBRM filename. If you want only one DBRM file, remove the option(s) that have multiple entries. Once you have made the relevant changes, recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0335 No collection-id specified, option required for AUTOBIND.

The AUTOBIND directive was specified but no collection-id was specified.

Add the required directive or remove the AUTOBIND directive and then recompile the program.

Parent topic: COBSQ0200 - COBSQ0399


COBSQ0401 Statement is too long.

The SQL statement passed to the SQL Option preprocessor is more than 65536 characters long. The SQL Option preprocessor gets passed a compressed version of the SQL statement rather than the original source, which may have comments included in the source as well as leading and trailing blanks.

Break the SQL statement into multiple SQL statements, then recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0402 Statement contains too many host variables.

The SQL statement contains more than 8000 host and indicator variables.

Break the SQL statement into multiple SQL statements, then recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0403 variable does not have a suitable definition to be used as a host variable.

The host variable displayed in the error message is not recognized with a data definition suitable for SQL data types.

See your SQL Reference to review valid data definitions for host variables.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0002: token is badly defined

One of three things has happened:

  • The SQLCA is defined to be less than 136 characters long
  • The SQLCODE variable is not defined as an elementary field with definition of PIC S9(8) COMP.
  • The SQLSTATE variable is not defined as an elementary field with definition of PIC X(5).

Correct the definition or use the supplied SQLCA copybook. If the problem persists, report this error to your support representative. Trace files may be needed to resolve this problem.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0415 Statement not allowed in the PROCEDURE DIVISION.

A SQL statement such as EXEC SQL DECLARE TABLE was coded in the Procedure Division. This statement cannot be coded in the Procedure Division.

Move the statement into the Working-Storage Section then recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0416 An error occurred whilst processing the trace file.

A file error occurred while trying to write information to the SQL Option preprocessor trace file.

Make sure you have write permissions for the drive/directory where the file is being written to and that there is enough space left on the drive.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0418 Mismatched DECLARE.

More than one DECLARE statement was found within an EXEC SQL statement.

Correct the statement then recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0419 Host variable name is too long.

The host variable name is too long. The maximum length of the host variable is 30 characters.

Make sure the host variable is a valid COBOL name. It should be no more than 30 characters long.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0420 Internal error - dictionary handle is too big.

The SQL Option preprocessor creates an internal dictionary of all host variables used in a program. A system error has occurred while working with this dictionary.

Report this error to your support representative, who might need you to supply trace files in order to resolve this problem.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0422 Nested INCLUDE's not supported.

An EXEC SQL INCLUDE was found inside another EXEC SQL INCLUDE. This is not allowed on DB2 for OS/390.

Remove the EXEC SQL INCLUDE from the copybook and then recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.

An unexpected error occurred in the SQL Option preprocessor.

Report this error to your support representative, who might need you to supply trace files in order to resolve this problem.

Parent topic: COBSQ0900 - COBSQ0999


COBSQ0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.

If a severe SQL error occurs, any additional EXEC SQL statements will not be processed by the SQL Option preprocessor.

Correct the severe error then recompile the program.

Parent topic: COBSQ0900 - COBSQ0999


COBSQ0024 EXEC SQL statement found within COPY statement, COPY directive not set. May cause compile error on mainframe.

An EXEC SQL statement was found in a COPY statement. On the mainframe this could cause compilation errors unless you are using a preprocessor that expands copybooks before the source is passed to the DB2 precompiler.

If you are using a preprocessor, set the XDB(COPY) directive to remove the warning message. Otherwise, remove the EXEC SQL statement from the copy statement if you will be porting the code back to the mainframe.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0003 Program contains more than one definition of token

More than one definition exists of one or more of the following fields: SQLCA, SQLCODE or SQLSTATE.

Remove the duplicate definitions and recompile the program.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0004 Nested or multi-source programs not allowed.

You are trying to compile a program that is nested or multi-source.

Use Micro Focus Net Express if you want to develop applications using nested or multi-source programs, or specify the XDB directive: XDB(IGNORE-NESTED).

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0005: An error occurred whilst processing the internal dictionary.

A system error has occurred trying to read the internal dictionary that the preprocessor creates of all host variables used in the program.

Report this error to your support representative. Trace files may be needed to resolve this problem.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0006 No DB engine could be found.

The required SQL Option system software was not installed.

Install one of the required SQL Option software products.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0007 Source file name is invalid.

A system error has occurred. The source file name passed to SQL Option preprocessor is not valid.

Report this error to your support representative, who might need you to supply trace files in order to resolve this problem.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0012: Host variable used without a colon.

The host variable is defined without a colon in the SQL statement.

No action is required, as this is a warning. For compatibility across multiple SQL syntaxes, a colon should always precede host variables. Currently, SQL Option and DB2 support the use of host variables without a colon, but this feature may be revoked at some time in the future.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0013: Login failed. : program-name.

The XDB Server was not started when the specified DB2 program was compiled. The XDB Server must be started in order for the SQL statements in the program to be validated.

Before trying to compile the program again, either start the XDB Server or turn off the VALIDATE directive.

Parent topic: COBSQ0000 - COBSQ0099


COBSQ0138: The length of a host variable on CONNECT is greater than 16.

The host variable data definition used in CONNECT statement has a data length greater than 16 characters long.

The host variable length must be 16 characters or less on a CONNECT statement. Change the length of the variable and then recompile the program.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0141: PREPARE before DECLARE is illegal.

The PREPARE statement must follow the DECLARE CURSOR that references it.

Move the DECLARE CURSOR statement before the PREPARE statement, then recompile the program.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0144: Statement not identified.

The SQL statement did not contain a SQL verb recognized by the SQL Option preprocessor.

Check the spelling of the SQL verb. If SQL Option extensions are being used, check to ensure that the XDBFUNCS directive is active.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0147: Multiple INTO's only allowed with a UNION.

Multiple INTO clauses were found in a SELECT INTO statement – this is only allowed if UNION is specified.

Correct the syntax and recompile your program. See the SQL Reference for the correct syntax.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0149: Illegal token found on CONNECT line.

The CONNECT statement contains syntax that is not recognized.

Correct the syntax and recompile your program. See the SQL Reference for the correct syntax.

Parent topic: COBSQ0100 - COBSQ0149


COBSQ0151: Cursor already DECLARED.

The cursor name in the DECLARE CURSOR statement has already been declared in the program.

Make sure the cursor name specified in the DECLARE CURSOR statement has not already been used in a previous DECLARE CURSOR statement, then recompile the program.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0154: Login failed.

If the VALIDATE directive is specified, the SQL Option preprocessor tries to login to the XDB server. This error is produced if the login fails. This could be caused by a wrong location or AUTHID specification in the Options settings.

Go into Option settings and check that the correct location and AUTHID are specified.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0163: Invalid Cursor name

An invalid character, often a hyphen, was found in the cursor name.

If you are using the DB2 directive, check that your cursor name does not contain a hyphen. If it does, do one of the following:

  • Remove it from the cursor name (or change it to an allowed character), or...
  • Use the HYPHEN-IN-CURSOR SQL Option preprocessor directive.

Note: Although MVS DB2 currently allows hyphens in a cursor name, this practice may not be supported in future releases.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0164: Syntax error in INTO Clause

The SQL Option preprocessor found an invalid INTO clause in an embedded SELECT statement.

Correct the syntax and recompile your program. See the SQL Reference for the correct syntax.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0170: Login failed. Unable to VALIDATE SQL

If the VALIDATE directive is specified, the SQL Option preprocessor tries to login to the XDB server. This error is produced if the login fails.

Ensure that the SQL Option server is started and that a valid AUTHID is specified.

Parent topic: COBSQ0150 - COBSQ0199


COBSQ0404 Bad SQL data declaration.

An unexpected SQL declaration has been passed to the SQL Option preprocessor. This error typically occurs only for a host variable defined as follows:

host-variable-name SQL TYPE IS ....

and the SQL Option preprocessor has not been setu p to handle that definition.

Report this error to your support representative, who might need you to supply trace files in order to resolve this problem.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0405 Syntax error.

The SQL statement includes invalid syntax or does not include required information. For example, this error would be generated if you only coded:

EXEC SQL INCLUDE END-EXEC

and did not specify the name of the copybook file to include.

Correct the SQL statement and recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0406 Filename too long.

A filename used in the program to specify a copybook or INCLUDE file is more than 260 characters long.

Correct the filename and recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0407 File token not found.

The copybook specified in token was not found.

The SQL Option preprocessor looks first in the current directory, and then down the paths specified by environment variables XDBCPY and COBCPY. Either correct the filename or update the Copybook folder to include the drive/directory to look in to find the copybook.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0408 token is non-unique and should be qualified.

The host variable displayed in token is not unique.

You must fully qualify a host variable in a SQL query if the variable-name is not unique. For example, if ORD-NO exists in both the ORDERS and ITEMS copybooks, you would need to specify something like the following if you wanted the host variable from the ORDERS copybook to be used in the query:

:ORDERS.ORD-NO

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0409: token is not a data item

The precompiler found a host variable that is referenced in an SQL statement but has no valid COBOL definition.

Verify that the host variable exists. If it does not, make the necessary changes to correct the error or use the SQL Option DCLGEN tool to generate a copybook of host variable for the SQL table in question.

If the variable in error message is defined in a COBOL copybook, you may need to specify the XDB(COPY) directive.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0410 Statement contains more than one SQLDA.

More than one SQLDA has been defined in the Working-Storage Section.

The SQL Option preprocessor currently has a limit of one SQLDA definition per program. If you cannot work around this limit, contact your support representative.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0411 token is not a table of null indicator variables.

The SQL Option preprocessor was expecting the token displayed to be a null indicator or a null indicator table.

Correct the SQL statement and recompile the program. If you are using a null indicator table, make sure you do not use the group-name. For example, if the following is a definition of a null indicator table:

01 staff-null-tbl.

03 staff-null-ind occurs 7 times pic s9(04) comp.

You should specify staff-null-ind instead of staff-null-tbl in your query.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0412 token should not be a defined with an OCCURS clause.

A host variable is defined as part of an OCCURS clause. The SQL Option preprocessor does not allow host variables to be defined this way.

Change the definition of the host variable and recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


COBSQ0413 token should not be a subordinate to an item defined with an OCCURS clause.

A host variable is defined as part of an OCCURS clause or as part of a structure that includes an OCCURS clause. The SQL Option preprocessor does not allow host variables to be defined this way.

Change the definition of the host variable and recompile the program.

Parent topic: COBSQ0400 - COBSQ0499


WE009: No more Export windows can be created.

You have created the maximum allowable number of Export windows. The maximum is 10. To create a new window you must close an existing window.

Parent topic: WE000 - WE049


WE010: Table table is empty.

No data can be exported because the table specified is empty.

Parent topic: WE000 - WE049


WE011: Invalid value value for TIMESTAMP command in group number, groupname.

The batch file command TIMESTAMP can only take the values "y" or "n".

Parent topic: WE000 - WE049


WE012: Invalid field type specified for field fieldname.

An illegal field type was specified for the field named. Check the documentation for a list of valid field types.

Parent topic: WE000 - WE049


WE013: Unable to retrieve field information.

An error occurred when attempting to retrieve field information from a batch specification.

Parent topic: WE000 - WE049


WE014: Batch Export file file-name not found.

Select a batch export file that exists.

Parent topic: WE000 - WE049


WE015: Keyboard navigation error.

An error occurred when trying to resolve the next/previous object in the keyboard navigation list. Contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE016: No fields in table specification.

The export cannot proceed because there are no fields in the 'Included' listbox on the screen.

Parent topic: WE000 - WE049


WE017: Internal error getting text from screen. Contact Micro Focus Technical Support.

The system could not process an entry on the screen. Contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE018: Internal error opening table window. Contact Micro Focus Technical Support.

The system was unable to open the export specification. Contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE019: Internal error opening query window. Contact Micro Focus Technical Support.

The system was unable to open the export specification.

Parent topic: WE000 - WE049


WE020: Batch Export file file-name does not contain a group heading

The first line of a batch export file must be a group heading.

Parent topic: WE000 - WE049


WE024: Query result does not contain any records.

The current query does not retrieve any rows, so there is nothing to export. Check the WHERE condition to make certain it is correct.

Parent topic: WE000 - WE049


WE025: Data file filename is empty.

The file you wish to view does not contain any data.

Parent topic: WE000 - WE049


WE026: Float value in field fieldname is larger than the IBM370 limit.

The float value is not supported by IBM370.

Parent topic: WE000 - WE049


WE027: Data exceeds 4K page size.

The size of a record in the table you are exporting is greater than 4K. When exporting to the DSNTIAUL format, each record must fit within a 4K page size. If the record contains one or more columns of type LONG VARCHAR, the data in those columns is truncated if possible to make the record fit into 4K. However, if the other column lengths are large enough, this won't reduce the size sufficiently.

Parent topic: WE000 - WE049


WE028: No output filename specified.

You have not specified a filename for your export file.

Parent topic: WE000 - WE049


WE030: Invalid output file specification filename.

The file name specified is not a valid file specification.

Parent topic: WE000 - WE049


WE031: Invalid table name.

You have entered a table name that does not satisfy table-naming criterion. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE000 - WE049


WE032: No table name specified.

You have not specified the name of the table you wish to export. The table name is required when exporting and when saving an export specification to a batch export or batch import file.

Parent topic: WE000 - WE049


WE033: Error writing to file filename.

It was not possible to write to the specified DSNTIAUL file. Your hard disk may be full.

Parent topic: WE000 - WE049


WE034: Can't display a join of multiple tables on Export's Design screen.

You cannot switch to the Design view because the current query contains multiple tables in the FROM clause.

Parent topic: WE000 - WE049


WE035: Field fieldname specified in query does not exist in table tablename.

You have specified a field that is not found in the table named in the FROM clause.

Parent topic: WE000 - WE049


WE036: Invalid query.

The query was not recognized as a valid SQL statement.

Parent topic: WE000 - WE049


WE037: Invalid record delimiter delimiter.

When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. SQLWizard allows you to specify an alternate end-of-record delimiter to handle other file structures.

Parent topic: WE000 - WE049


WE038: Invalid field delimiter delimiter.

When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. When selecting a field delimiter, be sure you do not use a character found in your data or in the default masks for the data types in the exported table. For example, do not use a comma as the delimiter if your data contains numeric or money values grouped with a comma.

Parent topic: WE000 - WE049


WE050: PRIQTY value must be an integer in the range 12 to 4,194,304.

See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.

Parent topic: WE050 - WE099


WE051: SECQTY value must be an integer in the range 0 to 131,068.

See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.

Parent topic: WE050 - WE099


WE052: FREEPAGE value must be an integer in the range 0 to 255.

See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.

Parent topic: WE050 - WE099


WE053: PCTFREE value must be an integer in the range 0 to 99.

See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.

Parent topic: WE050 - WE099


WE054: No tables found with authid auth-id in location location-name.

See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.

Parent topic: WE050 - WE099


WE055: Invalid DATABASE name.

Database names must follow the rules for short identifiers. The database name used is invalid.

Parent topic: WE050 - WE099


WE056: Invalid TABLESPACE name.

Tablespace names must follow the rules for long identifiers. The Tablespace used is invalid.

Parent topic: WE050 - WE099


WE057: Invalid EDITPROC name.

EDITPROC names must follow the rules for short identifiers. The name used is invalid.

Parent topic: WE050 - WE099


WE058: Invalid VALIDPROC name.

VALIDPROC names must follow the rules for short identifiers. The name used is invalid.

Parent topic: WE050 - WE099


WE059: Internal error reading batch file.

The system was unable to read the batch file. Check to make sure the file is a valid Export batch script.

Parent topic: WE050 - WE099


WE060: Unable to access code page information.

The system encountered an error when attempting to access the specified code page. Make sure that the code page has been defined in SYSTEM.SYSIBM.SYSSTRINGS, and that it has been correctly specified in the batch script.

Parent topic: WE050 - WE099


WE061: Invalid error log file name file-name specified in batch file.

The specified name is an invalid filename for the underlying operating system. Check your operating system documentation for a description of valid filenames.

Parent topic: WE050 - WE099


WE062: Float value in field fieldname is smaller than the IBM370 limit.

The float value is not supported by IBM370.

Parent topic: WE050 - WE099


WE063: Unable to open View Batch window, probably out of memory.

The system tried to open the view window, but was unable to do so. Try closing down other SQLWizard windows, or other applications that are using system resources.

Parent topic: WE050 - WE099


WE064: Unable to open View Data window, probably out of memory.

The system tried to open the view window, but was unable to do so. Try closing down other SQLWizard windows, or other applications that are using system resources.

Parent topic: WE050 - WE099


WE065: Unrecognized value value for SQL_OPTS command in group number, groupname.

Export found an illegal setting in the batch file. The syntax of this command is:

SQL_OPTS = statement-type [, statement-type, ...];

where statement-type is one of the following types:

CREATE | (CREATE TABLE and CREATE VIEW commands)
INSERT | (INSERT INTO commands)
INDEX | (CREATE INDEX commands)
SYNONYM | (CREATE SYNONYM commands)
CHECK | (ALTER TABLE...CHECK commands)
COMMENT | (COMMENT ON commands)

For example:

SQL_OPTS = CREATE, INDEX;

selects CREATE TABLE, CREATE VIEW, and CREATE INDEX SQL commands for use in the target file.

Parent topic: WE050 - WE099


WE066: Invalid value value for ASCII_CODEPAGE in group number, groupname.

Export found an error in the current batch export file. The syntax of this command is:

ASCII_CODEPAGE = n;

where n is the codepage number. Use the default ASCII character set for your country.

Parent topic: WE050 - WE099


WE067: Invalid value value for EBCDIC_CODEPAGE in group number, groupname.

Export found an error in the current batch export file. The syntax of this command is:

EBCDIC_CODEPAGE = n;

where n is the codepage number. Use the default EBCDIC character set for your country.

Parent topic: WE050 - WE099


WE068: Invalid value value for FORMAT command in group number, groupname.

Export found an error in the current batch export file. The syntax of this command is:

FORMAT = target-file-type;

where target-file-type is one of the following options:

FIXASC | used for fixed format ASCII files
FREASC | used for free format ASCII files
DSNTIAUL | used for IBM DSNTIAUL files
SQL | used for SQL statements
Parent topic: WE050 - WE099


WE069: Batch file filename is empty.

The specified file does not contain any batch specifications.

Parent topic: WE050 - WE099


WE070: Unknown batch command command in group number, groupname.

The batch export file contains invalid or unknown commands.

Parent topic: WE050 - WE099


WE071: Invalid value value for FLD_DELIMITER command in group number, groupname.

The syntax of this command is:

FLD_DELIMITER = { xx | <ascii> };

where xx is a character string delimiter and ascii is and ASCII decimal code. The angled brackets around the ASCII code are required. Be sure not to use a character found in your data as a delimiter. For example, do not use a comma as the delimiter if your data contains numeric or money fields grouped with a comma.

Parent topic: WE050 - WE099


WE072: Invalid value value for REC_DELIMITER command in group number, groupname.

The syntax of this command is:

REC_DELIMITER = { xx | <ascii> };

where xx is a character string delimiter and ascii is an ASCII decimal code. The angled brackets around the ASCII code are required. Be sure not to use a character found in your data as your delimiter. For example, do not use a comma as the delimiter if your data contains numeric fields grouped with a comma.

Parent topic: WE050 - WE099


WE073: Invalid value value for HEADING command in group number, groupname.

The syntax of this command is:

HEADING = {Y | N};

If HEADING is set to N, no heading is included in the target file. If HEADING is set to Y, the column headings are included as the first record of the file.

Parent topic: WE050 - WE099


WE074: Invalid value value for FILENAME command in group number, groupname.

The syntax of this command is:

FILENAME = filename;

where filename is the full path specification and filename for the target file.

Parent topic: WE050 - WE099


WE075: Invalid value value for TABLE command in group number, groupname.

The syntax of this command is:

TABLE = table-name;

where table-name is the name of the table or view.

Parent topic: WE050 - WE099


WE001: Unable to create document window, XVT error error.

An error occurred while attempting to create a child window. You may be low on resources. Try unloading some programs, or closing other child windows. If you are still having problems, please contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE086: Invalid value value for AUDIT command in group number, groupname.

AUDIT value must be one of NONE, CHANGES or ALL.

Parent topic: WE050 - WE099


WE087: Invalid value value for VCAT command in group number, groupname.

VCAT value must be one of WITH, ROOT, PATH or NAME.

Parent topic: WE050 - WE099


WE088: Invalid value value for STOGROUP command in group number, groupname.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE050 - WE099


WE089: Invalid value value for PRIQTY command in group number, groupname.

PRIQTY value must be a number from 0 to 4,194,309.

Parent topic: WE050 - WE099


WE090: Invalid value value for SECQTY command in group number, groupname.

SECQTY value must be a number from 0 to 131,068.

Parent topic: WE050 - WE099


WE091: Invalid value value for ERASE command in group number, groupname.

ERASE value must be either Y or N.

Parent topic: WE050 - WE099


WE092: Invalid value value for FREEPAGE command in group number, groupname.

FREEPAGE value must be a number from 0 to 255.

Parent topic: WE050 - WE099


WE093: Invalid value value for PCTFREE command in group number, groupname.

PCTFREE value must be a number from 0 to 99.

Parent topic: WE050 - WE099


WE094: Invalid value value for DUPQTY command in group number, groupname.

DUPQTY value must be either 8, 16, 32, 64 or 128.

Parent topic: WE050 - WE099


WE095: Invalid value value for CLUSTER command in group number, groupname.

CLUSTER value must either Y or N.

Parent topic: WE050 - WE099


WE096: Invalid value value for SUBPAGES command in group number, groupname.

SUBPAGES value must be either 1, 2, 4, 8 or 16.

Parent topic: WE050 - WE099


WE097: Invalid value value for BUFFERPOOL command in group number, groupname.

BUFFERPOOL value must be in one of the following formats:

  • BP0 - BP49 for indexes with 4K page sizes;
  • BP32K or BP32K1 - BP32K9 for indexes with 32K page sizes.
Parent topic: WE050 - WE099


WE098: Invalid value value for DSETPASS command in group number, groupname.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE050 - WE099


WE099: Invalid value value for CLOSE command in group number, groupname.

CLOSE value must be either Y or N.

Parent topic: WE050 - WE099


WE100: Invalid value value for DEFER command in group number, groupname.

DEFER value must be either Y or N.

Parent topic: WE100 - WE149


WE101: Error opening batch file for writing.

Unable to open file for writing import or export specifications.

Make sure the file exists, that you have privileges to access it, that it is not in use by another application, that there is enough disk space available, and that the target directory is a valid path.

Parent topic: WE100 - WE149


WE102: Error writing to batch file.

Unable to write import or export specifications to current batch file.

Parent topic: WE100 - WE149


WE103: Invalid value value for SRC_ASCII_CODEPAGE command in group number, groupname.

Codepage must be a positive integer or 0.

Parent topic: WE100 - WE149


WE104: Invalid value value for DST_ASCII_CODEPAGE command in group number, groupname.

Codepage must be a positive integer or 0.

Parent topic: WE100 - WE149


WE105: Warning: No translation table matches the default ASCII source and destination codepages pagenopageno in XDB.INI.

The values in XDB.INI in the [Export] section for AscSrcCodePage and AscDstCodePage do not correspond to the INCCSID and OUTCCSID values of any record in SYSTEM.SYSIBM.SYSSTRINGS.

Parent topic: WE100 - WE149


WE106: Invalid Where clause.

The WHERE condition specified in the Export window is invalid. Check it for syntax errors.

Parent topic: WE100 - WE149


WE107: Export to SQL can't export a query that contains more than one table.

There is more than one table specified in the FROM clause of your Export query statement. This is not allowed when you are exporting to SQL Statements. In SQL mode, edit the FROM clause so that it contains a single table name, or change to another export format.

Parent topic: WE100 - WE149


WE108: Query doesn't start with SELECT.

The Export query statement doesn't begin with the SELECT keyword. In SQL mode, edit the statement so that it begins with the word SELECT. Make sure that it forms a valid query statement.

Parent topic: WE100 - WE149


WE109: Export doesn't understand the query. Last symbol read was symbol.

SQLWizard could not interpret the SELECT statement in the Export window. Check it for syntax errors. Symbol indicates where the error occurred. See the SQL Reference for a description of the SELECT statement syntax.

Parent topic: WE100 - WE149


WE110: Query contains a string that is too long for Export to process.

The SELECT statement in the Export window contains a name (e.g., field name, table name) that is too long. Names exceeding 1024 characters cannot be processed by Export.

Parent topic: WE100 - WE149


WE002: No query exists on the query screen.

An internal error has occurred. Please contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE003: Index is damaged.

An internal error has occurred. Please contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE004: Unable to query auth-id.SYSTABLES to get information about item.

An internal error has occurred. Please contact Micro Focus Technical Support.

Parent topic: WE000 - WE049


WE005: Invalid value value for APPEND_ERR_FILE command in group number, groupname.

The batch file command APPEND_ERR_FILE can only take the values "y" or "n".

Parent topic: WE000 - WE049


WE006: No translation table exists with specified INCCSID and OUTCCSID.

There is no record in the SYSIBM.SYSSTRINGS table whose values in the INCCSID and OUTCCSID fields match the numbers found in XDB.INI. If you are exporting in the DSNTIAUL format, check InCCSID and OutCCSID in the [Export] section of XDB.INI. If you are exporting in a different format, check AscSrcCodePage and AscDstCodePage.

Parent topic: WE000 - WE049


WE007: Unable to add field name name to Included list.

The system was unable to add the specified name to the name of columns that are to be included in the current export specification. You may be out of memory.

Parent topic: WE000 - WE049


WE008: Cannot open file filename.

Couldn't open the specified file.

The file may not exist, may be in use, disk may be full or you may be out of memory.

Parent topic: WE000 - WE049


WE039: Invalid value for number of spaces between fields.

The number of spaces between fields should be an integer from 0 to 99.

Parent topic: WE000 - WE049


WE040: Batch file filename is invalid.

The specified batch file is not a valid batch export file.

Parent topic: WE000 - WE049


WE041: Batch file contains more than one transaction.

Export cannot display a batch file that contains more than one transaction.

Parent topic: WE000 - WE049


WE042: Error opening log file filename.

An attempt to open the specified log file failed.

Parent topic: WE000 - WE049


WE043: Invalid error log file name filename.

The specified name is an invalid file name for the underlying operating system. Check your operating system documentation for a description of valid file names.

Parent topic: WE000 - WE049


WE044: Invalid ON_ERROR value value.

The ON_ERROR value must be PROMPT, CONTINUE, QUIT, or END_ALL.

Parent topic: WE000 - WE049


WE045: Invalid batch file name filename.

The specified file name is not a valid file name for your operating system. See your operating system documentation for a description of valid file names.

Parent topic: WE000 - WE049


WE046: Invalid data file name filename.

The specified file name is not a valid file name for your operating system. See your operating system documentation for a description of valid file names.

Parent topic: WE000 - WE049


WE048: Invalid value for DSETPASS.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE000 - WE049


WE049: Invalid STOGROUP name.

STOGROUP names must follow the rules for short identifiers. The STOGROUP used is invalid.

Parent topic: WE000 - WE049


WE076: Invalid value value for PAGE_SIZE command in group number, groupname.

The syntax of this command is:

PAGE_SIZE = {4K | 32K};

If PAGE_SIZE is set to 4K, the storage size for each record in the table is 4K bytes; if it is set to 32K, the storage size is 32K bytes.

Parent topic: WE050 - WE099


WE077: Invalid value value for FIELDS command in group number, groupname.

The syntax of this command is:

FIELDS = field-name1 [, field-name2]. . .;

where the field names are listed in order, and separated by commas.

Parent topic: WE050 - WE099


WE078: Invalid value value for QUOTES command in group number, groupname.

The syntax of this command is:

QUOTES = {Y | N};

If QUOTES is set to N, quotes will not be placed around character strings. If QUOTES is set to Y, character strings will be surrounded by quotes.

Parent topic: WE050 - WE099


WE079: Invalid value value for SPACES command in group number, groupname.

The syntax of this command is:

SPACES = n;

where n is an integer between 0 and 99, corresponding to the number of spaces to be inserted between the columns of data.

Parent topic: WE050 - WE099


WE080: Unable to get information about fields in table tablename.

The system failed in an attempt to get information about the columns in the specified table. Make sure you have privileges on the catalog tables or views, and that the SYSIBM and SYSXDB items in the SQL page of the Options are set to the correct AuthID values.

Parent topic: WE050 - WE099


WE081: Invalid value value for REPLACE command in group number, groupname.

The syntax of this command is:

REPLACE = {Y | N};

If REPLACE is set to N and the destination file exists, the data is appended to the end of the file. If REPLACE is set to Y, the data in the target file will be replaced. This statement is supported for the following formats: Free ASCII, Fixed ASCII, and SQL. With all other formats, the file is replaced instead of being appended to regardless of how REPLACE is set.

Parent topic: WE050 - WE099


WE082: Invalid value value for DATABASE command in group number, groupname.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE050 - WE099


WE083: Invalid value value for TABLESPACE command in group number, groupname.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE050 - WE099


WE084: Invalid value value for EDITPROC command in group number, groupname.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE050 - WE099


WE085: Invalid value value for VALIDPROC command in group number, groupname.

The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WE050 - WE099


WE112: Internal error getting For Bit Data info. Contact Micro Focus Technical Support.

Export has experienced an internal error while processing the SELECT statement. Contact Micro Focus Technical Support.

Parent topic: WE100 - WE149


WE113: Internal error getting Nullable info. Contact Micro Focus Technical Support.

Export has experienced an internal error while processing the SELECT statement. Contact Micro Focus Technical Support.

Parent topic: WE100 - WE149


WE114: Invalid record delimiter – escape character character is not allowed.

The escape character specified on the SQL tab of Options cannot be used as a record delimiter.

Parent topic: WE100 - WE149


WE115: Invalid field delimiter – escape character character is not allowed.

The escape character specified on the SQL tab of Options cannot be used as a field delimiter.

Parent topic: WE100 - WE149


WDG019: No table on command line.

The Declaration Generator was run in batch mode with no batch filename or table name on the command line. Please reissue the batch command with a legal batch filename or a table name on the command line.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG020: Invalid option on command line.

The Declaration Generator was run in batch mode with an illegal parameter on the command line. Please check you parameters.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG021: No filename on command line.

The Declaration Generator was run in batch mode with no batch filename or output file name on the command line. Please reissue the batch command with a legal output filename on the command line.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG022: Can't create batch file.

The Declaration Generator cannot create the selected file to contain a batch file. Make sure that the path exists and the destination file is not read only or locked by another user.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG023: No table name.

No table name was specified. There is nothing to do.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG024: No filename.

No output filename was specified. Declaration Generator needs to know where to put the output.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG025: No structure name.

No output structure name was specified. Declaration Generator needs to know the name of the output structure.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG026: Error updating the status bar.

Internal error. Declaration Generator could not display a message on its status bar. Please note what operation was being performed and contact Micro Focus Technical Support.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG001: name is not a legal table name.

The table name you have entered is invalid. Select a valid table name.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG005: Unknown field type in table tablename.

An illegal field type was specified in the table named.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG008: name is not a legal language name.

The target language you have entered is invalid. Valid language names are COBOL, PL/I and C. Enter a valid name.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG010: Illegal computational value.

The computation value must be > 0 and < 10.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG015: Error number spawning editor name.

This error is not used. May be used in future versions.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG016: Accessing file name.

The Declaration Generator cannot access the specified file. Please make sure that it exists and is not locked by any other user.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG017: Invalid location name nameerrortype.

The specified location does not exist. Please select an existing location.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WDG018: No filename on command line.

The Declaration Generator was run in batch mode with no batch filename on the command line. Please reissue the batch command with a legal batch filename.

Parent topic: WDG - SQL Wizard Declaration Generator Error Messages


WI009: Keyboard navigation error.

Internal error. Contact Micro Focus Technical Support.

Parent topic: WI000 - WI049


WI010: Invalid value value for DSN_CRLF command in group number, groupname.

The batch file command DSN_CRLF can only take the values "y" or "n".

Parent topic: WI000 - WI049


WI011: No source file name specified.

You must enter the full pathname of the data file you want to import in the File Name edit box of the Source File Information area.

Parent topic: WI000 - WI049


WI012: Unable to open Grid window.

An internal error is preventing SQLWizard from creating the table area in the Import window. This may be caused by insufficient memory. Close any unnecessary applications, then retry the Import command. If this does not resolve the problem, clear memory by restarting SQLWizard or by rebooting.

Parent topic: WI000 - WI049


WI013: Data in field fieldname of record record-name is number characters long but field definition inumber characters.

The data found in a character field in the source file is longer than the length of that field in the target table.

Parent topic: WI000 - WI049


WI014: End-of-line delimiter delimiter not found while counting fields in record.

The current record in your free format ASCII file does not contain the Field Delimiter specified on the screen.

Parent topic: WI000 - WI049


WI015: Invalid value value for APPEND_ERR_FILE command in group number, groupname.

The batch file command APPEND_ERR_FILE can only take the values "y" or "n".

Parent topic: WI000 - WI049


WI016: Invalid value value for APPEND_REC_FILE command in group number, groupname.

The batch file command APPEND_REC_FILE can only take the values "y" or "n".

Parent topic: WI000 - WI049


WI017: DSNTIAUL file file-name does not contain a complete record.

A record in the DSN file contains a record with size that is smaller than the record size in the destination table.

Parent topic: WI000 - WI049


WI018: Invalid value value for TIMESTAMP command in group number, groupname.

The batch file command TIMESTAMP can only take the values "y" or "n".

Parent topic: WI000 - WI049


WI019: Batch import file file-name not found.

Select a batch import file that exists.

Parent topic: WI000 - WI049


WI020: Batch Import file filename does not contain a group heading.

The first line of a batch import file has to be a group heading.

Parent topic: WI000 - WI049


WI021: Record number contains more than the maximum of number fields, or end of record not found.

Import has detected more fields in the current record than are specified in the table definition. Either your data file contains extra fields in this record, or the record delimiter is missing from this record, causing Import to interpret the data in the next record as part of the data for this record.

Parent topic: WI000 - WI049


WI022: Table name is not specified in group number, groupname.

No value was assigned to the batch file command TABLE.

Parent topic: WI000 - WI049


WI023: Error writing to logfile filename, errno = error-number.

The attempt to write to the specified log file failed. Check your operating system documentation for the meaning of the error specified by the errno value.

Parent topic: WI000 - WI049


WI024: Error opening logfile filename.

An attempt to open the specified log file failed. Either it does not exist or is in use.

Parent topic: WI000 - WI049


WI025: End quote missing in field fieldname, record record of data file filename.

A quote is missing from a character field in a free format ASCII file.

Parent topic: WI000 - WI049


WI026: Data exceeds 4K page size.

The size of a record in a DSNTIAUL file must be no greater than 4096 bytes.

Parent topic: WI000 - WI049


WI027: Length specification missing from Char, Varchar, Graphic, or, VarGraphic data type, line line-number.

Specify these types in the following format:

Character: | CH(length)
VarChar: | VC(length)
Graphic: | GR(length)
VarGraphic: | VG(length)

Example: TYPE = CH(100), VC(250), GR(45), VG(20);

Parent topic: WI000 - WI049


WI029: Number fields were specified, but number fields were found in file.

There are more fields in the fixed-ASCII source file than there are in the target table. Check the source file to make sure that the length of its records matches that of your destination table.

Parent topic: WI000 - WI049


WI030: Unable to open file filename.

Either the file was not found in the indicated directory, is in use, or is invalid. Check to be sure that you have specified the correct file name and directory.

Parent topic: WI000 - WI049


WI031: More field names were found than the number of fields specified.

The number of fields specified for your table is less than the number of fields found in your data file.

Parent topic: WI000 - WI049


WI034: Field name for field number, fieldname, is longer than number characters.

Field names may not be longer than number characters.

Parent topic: WI000 - WI049


WI035: Incorrect field type type in ConvertDataStrToInternal().

Internal error. Call Micro Focus Technical Support.

Parent topic: WI000 - WI049


WI036: Invalid field delimiter delimiter.

When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. See your SQLWizard User's Guide for further information on entering delimiters.

Parent topic: WI000 - WI049


WI049: Invalid length in Graphic type specification type, field number.

Graphic length must be no longer than 127.

Parent topic: WI000 - WI049


WI050: Invalid length in Vargraphic type specification type, field number.

Vargraphic length must be no longer than 2028.

Parent topic: WI050 - WI099


WI051: Batch file contains more than one transaction.

SQLWizard cannot create an Import window for a batch file that contains more than one transaction.

Parent topic: WI050 - WI099


WI052: Batch file filename is invalid.

The file does not exist, or the file is not a valid Batch Import file.

Parent topic: WI050 - WI099


WI054: Can't get info from fixed ASCII file that doesn't contain a header line.

You must provide a complete specification for the ASCII file, since the system is unable to use a header line to help build a specification.

Parent topic: WI050 - WI099


WI055: Error opening table file filename.

Import in Local Direct Write mode encountered an error when trying to open the file specified. The file may not exist, you may not have privileges on the file or on the path, or the file may be in use.

Parent topic: WI050 - WI099


WI057: Error writing to table file filename.

Import in Local Direct Write mode encountered an error when trying to write to an underlying table file directly. Make certain that the table file can be accessed from the client machine.

Parent topic: WI050 - WI099


WI058: Can't access table file filename, probably locked by the XDB Server.

The table file may already be in use by the database server. You must have exclusive use of the file in order to proceed.

Parent topic: WI050 - WI099


WI059: Invalid error log file name filename.

The file name is not a valid file name.

Parent topic: WI050 - WI099


WI060: Invalid record log file name filename.

The file name is not a valid file name.

Parent topic: WI050 - WI099


WI063: Invalid error log file name filename specified in batch file filename.

The file name is not a valid file name for the underlying operating system. Check your operating system documentation for valid filename format.

Parent topic: WI050 - WI099


WI064: Invalid record log file name filename specified in batch file filename.

The file name is not a valid file name for the underlying operating system. Check your operating system documentation for valid file name format.

Parent topic: WI050 - WI099


WI065: Unable to access code page information.

You have specified a translation table to use for DSNTIAUL EBCDIC-to-ASCII conversion, or non-DSNTIAUL ASCII-to-ASCII conversion. However, Import was unable to load the translation from the system table SYSIBM.SYSSTRINGS.

Parent topic: WI050 - WI099


WI066: Number of records to recalculate must be an integer from 0 to 4,294,967,296.

The number you specified is not in range.

Parent topic: WI050 - WI099


WI067: Commit interval must be an integer from 0 to 4,294,967,296.

The number you specified is not in range.

Parent topic: WI050 - WI099


WI069: Quotes missing around character value string.

You have specified that character values are enclosed in quotes, but the specified character value is not quoted.

Parent topic: WI050 - WI099


WI071: Float value in field number, fieldname of record number is larger than IBM370's limit.

The float value is not supported by IBM370.

Parent topic: WI050 - WI099


WI072: Float value in field number, fieldname of record number is smaller than IBM370's limit.

The float value is not supported by IBM370.

Parent topic: WI050 - WI099


WI073: Unable to open View Batch window, probably out of memory.

Check system resources. Close down other SQLWizard windows, or other applications to free resources.

Parent topic: WI050 - WI099


WI074: Unable to open View Data window, probably out of memory.

Check system resources. Close down other SQLWizard windows, or other applications to free resources.

Parent topic: WI050 - WI099


WI077: Internal error reading batch file.

An error occurred when trying to read the batch file. It is most likely a memory allocation error.

Parent topic: WI050 - WI099


WI078: Invalid value value for PAGE_SIZE command in group number, groupname.

The syntax of this command is:

PAGE_SIZE = {4K | 32K};

If PAGE_SIZE is set to 4K, the storage size for each record in the table is 4K bytes; if it is set to 32K, the storage size is 32K bytes.

Parent topic: WI050 - WI099


WI079: Invalid value string for FORMAT command in group number, groupname.

Valid formats are FREASC, FIXASC, and DSNTIAUL.

Parent topic: WI050 - WI099


WI080: Can't import into a non-XDB Server location using Engine Direct Write

Engine Direct Write mode is only supported against XDB Server locations.

Parent topic: WI050 - WI099


WI082: Data file filename does not contain any data.

The file appears to be empty.

Parent topic: WI050 - WI099


WI083: Invalid value value for ASCII_CODEPAGE command in group number, groupname.

This must be a positive integer or 0.

Parent topic: WI050 - WI099


WI001: Premature end of line found, record record.

Encountered an unexpected end of line on the record specified.

Parent topic: WI000 - WI049


WI094: Invalid value value for INSERT_MODE command in group number, groupname.

The syntax of this command is:

INSERT_MODE = { NORMAL | EDR };

where NORMAL indicates regular import mode and EDR indicates Engine Direct Write import

Parent topic: WI050 - WI099


WI095: Invalid value value in position number for NULL_PERM command in group number, groupname.

The syntax of this command is:

NULL_PERM = {Y | N | D} [, {Y | N | D}] ...;

where the specification is listed in the same order as the corresponding field names, and delimited by commas.

If NULL_PERM is set to Y, NULL values are permitted in the column. If NULL_PERM is set to N, the column is prevented from containing NULL values. If NULL_PERM is set to D, NULL values are converted to a specified default value for the column.

Parent topic: WI050 - WI099


WI096: Invalid value value in position number for USE_PIC command in group number, groupname.

The syntax of this command is:

USE_PIC = {Y | N | NA} [, {Y | N | NA}] ...;

where the specification (Y, N, or NA) is listed in the same order as the corresponding field names, and delimited by commas. If USE_PIC is set to Y for one of the fields, Import will apply the appropriate profile mask to the data in that field. If USE_PIC is set to N for a field, the mask will not be applied to that field. If USE_PIC is set to NA, the field is not of a type that format pictures apply to.

The USE_PIC command only applies to date, time, decimal and money fields. Masks defined in Options must be changed to match the format of the file you are importing.

Parent topic: WI050 - WI099


WI097: Invalid value value in position number for TYPES command in group number, groupname.

The syntax of this command is:

TYPES = field-type1 [, field-type2]. . .;

where field types are listed in the same order as corresponding field names, and delimited by commas. Valid field types are as follows:

CH[(n)] | Char (Character)
CB[(n)] | Character For Bit Data
DT[(p[s])] | Date
DC | Decimal
SF | Float (4-byte)
FL | Float
GR | Graphic
LI | Integer
LV | Long Varchar
LB | Long Varchar For Bit Data
LG | Long Vargraphic
MN | Money
SI | Smallint (Small Integer)
TM | Time
TS | Timestamp
VC[(n)] | Varchar (Variable Character)
VB[(n)] | Varchar For Bit Data
VG[(n)] | Vargraphic
Parent topic: WI050 - WI099


WI098: Invalid value value in position n for FIELDS command in group number, groupname.

The syntax of this command is:

FIELDS = field-name1 [, field-name2]. . .;

where the field names are listed in order, and separated by commas.

Parent topic: WI050 - WI099


WI099: Invalid value value for TABLE command in group number, groupname.

The syntax of this command is:

TABLE = table-name;

where table-name is the name of the table.

Parent topic: WI050 - WI099


WI100: Invalid value value for FILENAME command in group number, groupname.

The syntax of this command is:

FILENAME = filename;

where filename is the full path specification and file of the source file. For example:

FILENAME = C:\XDB\APPS\employee.asc;

specifies the location of the source file as C:\XDB\APPS\ and the file name EMPLOYEE.ASC.

Parent topic: WI100 - WI149


WI101: Invalid value value for ON_ERROR command in group number, groupname.

The syntax of this command is:

ON_ERROR = { SKIP | INS_NULL | QUIT | END_ALL | PROMPT };

If ON_ERROR is set to SKIP, a record that contains invalid data is skipped and Import goes on to the next record. If ON_ERROR is set to INS_NULL, a NULL is placed in the field if the field is nullable. If ON_ERROR is set to QUIT, the batch import will be terminated if invalid data is found. If ON_ERROR is set to END_ALL, all batch import processing is terminated. If ON_ERROR is set to PROMPT, the user is prompted for further action.

Parent topic: WI100 - WI149


WI102: Invalid value value for COMMIT_INTERVAL command in group number, groupname.

The syntax of this command is:

COMMIT_INTERVAL = {n};

where n is a number between 0 and 2,147,483,647.

Parent topic: WI100 - WI149


WI103: The number of values for the FIELDS command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI104: The number of values for the TYPES command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI105: The number of values for the USE_PIC command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI106: The number of values for the NULL_PERM command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI107: The number of values for the OFFSETS command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI108: The number of values for the SRC_LENS command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI109: The number of values for the EBCDIC_TO_ASCII command in group number, groupname does not match the number of fields found in a previous command.

The number of items in all of the field-list commands must be consistent.

Parent topic: WI100 - WI149


WI110: Batch file filename is empty.

The file does not contain any batch import specifications.

Parent topic: WI100 - WI149


WI111: Unknown batch command command in group number, groupname.

There are invalid commands in the batch file. See your SQLWizard User's Guide for valid batch commands.

Parent topic: WI100 - WI149


WI112: Short float value in field number, fieldname of record number is larger than IBM370's limit.

Float value not supported for IBM370.

Parent topic: WI100 - WI149


WI113: Short float value in field number, fieldname of record number is smaller than IBM370's limit.

Float value not supported for IBM370.

Parent topic: WI100 - WI149


WI115: Error opening batch file for writing.

There is not enough memory to create the internal structure required to write an Import specification file (an IMP file). Close any unnecessary applications, then retry the operation. If this does not resolve the problem, clear memory by restarting SQLWizard or by rebooting.

Parent topic: WI100 - WI149


WI116: Error writing to batch file.

An error has occurred while writing an Import specification file (an IMP file). Check that nothing is preventing a file from being written. For example, check that the drive is operational and that it has sufficient space. Also check that the file is not write protected.

Parent topic: WI100 - WI149


WI117: Invalid value value for SRC_ASCII_CODEPAGE command in group Tnumber, Tname.

The value assigned to a SRC_ASCII_CODEPAGE statement in your Import specification file (IMP file) is incorrect. It must be a positive integer. The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Allowed values are listed in the SQLWizard User's Guide.

Parent topic: WI100 - WI149


WI118: Invalid value value for DST_ASCII_CODEPAGE command in group Tnumber, Tname.

The value assigned to a DST_ASCII_CODEPAGE statement in your Import specification file (IMP file) is incorrect. It must be a positive integer. The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Allowed values are listed in the SQLWizard User's Guide.

Parent topic: WI100 - WI149


WI119: Invalid batch file name filename.

An invalid file name has been given to an Import specification file (IMP file). If you are saving an IMP file, check that you have typed a name allowed by your operating system. If you are running a batch import from the command line, verify that a valid IMP filename was entered on the command line. See your SQLWizard User's Guide for command line syntax.

Parent topic: WI100 - WI149


WI121: Can't import data file filename into table tablename because data file has number columns but table has number columns.

The source file and the target table in your Import operation do not have the same number of fields. If you are running a batch import, verify that the TABLE statement in the IMP file is set to the correct target table. Also verify that the FIELDS, TYPES, NULL_PERM, SRC_LENS, OFFSETS, USE_PIC and EBCDIC_TO_ASCII statements in your IMP file reflect the actual number of columns in your source and destination. See your SQLWizard User's Guide for a complete description of the IMP file and its contents.

Parent topic: WI100 - WI149


WI002: Number field(s) were found in record number; record should contain number field(s).

A record containing the wrong number of fields exists in the file you are importing. Check the record in your source file (record n) and make sure that it has the same number of fields as the target table.

Parent topic: WI000 - WI049


WI003: The character character in position position in heading line of Fixed ASCII file filename is not allowed in a column name.

A field name in your fixed-ASCII data file contains a character that is not permitted in a database object name. See your SQL Reference for a list of characters that can be used in a column name.

Parent topic: WI000 - WI049


WI004: The maximum number of open Import windows has been reached.

You have opened the maximum number of Import windows. Close some of the Import windows before you continue.

Parent topic: WI000 - WI049


WI005: Table name is not specified.

You must provide a table name for the target table.

Parent topic: WI000 - WI049


WI007: Invalid value number for varchar length; length must be no greater than number.

The length of a varchar field is greater than the page size set for each record.

Parent topic: WI000 - WI049


WI008: No translation table exists with specified INCCSID and OUTCCSID.

There is no record in the SYSIBM.SYSSTRINGS table whose values in the INCCSID and OUTCCSID fields match the numbers found in XDB.INI. If you are importing in the DSNTIAUL format, check InCCSID and OutCCSID in the [Import] section of XDB.INI. If you are importing in a different format, check AscSrcCodePage and AscDstCodePage.

Parent topic: WI000 - WI049


WI037: Invalid record delimiter delimiter.

When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255.

Parent topic: WI000 - WI049


WI038: Invalid source file name filename.

See your operating system documentation for an explanation of valid file names.

Parent topic: WI000 - WI049


WI039: Invalid table name.

See your documentation for an explanation of valid table names. Also see WSQL045.

Parent topic: WI000 - WI049


WI040: Invalid value for number of spaces between fields.

The number of spaces between fields should be an integer from 0 to 99.

Parent topic: WI000 - WI049


WI041: Data file filename is empty.

It is not possible to import the specified data file, as it contains no data.

Parent topic: WI000 - WI049


WI044: Invalid character (character) found in field name in field number in header line of data file.

An illegal column name was found in the source file. See the SQL Reference for rules for identifiers for XDB Server and DB2. Also see WSQL045.

Parent topic: WI000 - WI049


WI047: Invalid length in type specification type, field number.

The length in the specified field is invalid for the field type.

Parent topic: WI000 - WI049


WI048: Invalid length in Character or Varchar type specification type, field number.

Character and Varchar lengths must be no longer than 4048.

Parent topic: WI000 - WI049


WI084: Invalid value value for EBCDIC_CODEPAGE command in group number, groupname.

This must be a positive integer or 0.

Parent topic: WI050 - WI099


WI085: Invalid value value for FLD_DELIMITER command in group number, groupname.

The syntax of the FLD_DELIMITER command is:

FLD_DELIMITER = {'xx'|'<ascii1>'} {'xx'|'<ascii2>'} [...];

where 'xx' is one or more keyboard characters and 'ascii' is an ASCII decimal code. The angle brackets around the ASCII code are required. Quote marks around delimiters are optional.

For example, to instruct the SQLWizard Import utility to use a comma as the delimiter in your file, use the command:

FLD_DELIMITER = , ;
Parent topic: WI050 - WI099


WI086: Invalid value value for REC_DELIMITER command in group number, groupname.

The syntax of the REC_DELIMITER command is:

REC_DELIMITER = {'xx' | '<ascii>' ...} ;

where 'xx' is a character string delimiter and 'ascii' is an ASCII decimal code. The angled brackets around the ASCII code are required. The default delimiter is a space character (ASCII code <032>).

Parent topic: WI050 - WI099


WI087: Invalid value value for HEADING command in group number, groupname.

The correct syntax of this command is:

HEADING={Y | N};

Set HEADING equal to N if there is no heading in the source file. Set HEADING equal to Y if the first row is to be considered a heading in the source file.

Parent topic: WI050 - WI099


WI088: Invalid value value in position number for EBCDIC_TO_ASCII command in group number, groupname.

The syntax of this command is:

EBCDIC_TO_ASCII = {Y | N | NA} [, {Y | N | NA}]...;

where the number of Ys, Ns and NAs is equal to the number of fields in the table. If EBCDIC_TO_ASCII is set to N, data are not converted to ASCII. If EBCDIC_TO_ASCII is set to Y (default), the data are assumed to be EBCDIC and are converted to the ASCII equivalent. If EBCDIC_TO_ASCII is set to NA, conversion is not applicable for the field type.

Parent topic: WI050 - WI099


WI089: Invalid value value in position number for SRC_LENS command in group number, groupname.

The syntax of this command is:

SRC_LENS = length1 [, length2] ...;

where the lengths are listed in the same order as the corresponding field names, and delimited by commas. For example:

SRC_LENS = 8,10,20,15,2,5,4,20,30;

specifies the column widths of the Fixed ASCII source file being read.

Parent topic: WI050 - WI099


WI090: Invalid value value in position number for OFFSETS command in group number, groupname.

The syntax of this command is:

OFFSETS = start-pos1 [, start-pos2]. . .;

where the starting positions are listed in the same order as the corresponding field names, and delimited by commas. For example:

OFFSETS = 1,11,23,35,57,74,85,91,113;

specifies the starting positions of the columns in a Fixed ASCII source file.

To determine the starting positions, it may be necessary to examine the file using the SOURCE FILE command from the View menu or a text editor.

Parent topic: WI050 - WI099


WI091: Invalid value value for SPACES command in group number, groupname.

The syntax of this command is:

SPACES = {n};

where n is some number between 0-99. The default is 2.

Parent topic: WI050 - WI099


WI092: Invalid value value for QUOTES command in group number, groupname.

The syntax of this command is:

QUOTES = {Y | N};

Set QUOTES to N if there are no quotes around character strings in the source file. Set QUOTES to Y if the character strings in the source file are surrounded by quotes.

Parent topic: WI050 - WI099


WI093: Invalid value value for REPLACE command in group number, groupname.

The syntax of this command is:

REPLACE = {Y | N};

If REPLACE is set to N, the imported data will append to the existing data. If REPLACE is set to Y, the imported data will replace the data in the table.

Parent topic: WI050 - WI099


WI122: Batch specification in group Tnumber, Tname in file filename is not sufficient to create new table tablename.

A TYPES and/or FIELDS statement for this transaction was not found in the Import specification file (IMP file). The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Edit your IMP file and enter the missing statement(s). See your SQLWizard User's Guide for a complete description of the IMP file and its contents.

Parent topic: WI100 - WI149


WI123: Table tablename contains number columns but batch file specifies number columns.

The target table specified in the Import specification file (IMP file) doesn't contain the same number of fields as the source file. Verify that the TABLE statement in the IMP file is set to the correct target table. Also verify that the FIELDS, TYPES, NULL_PERM, SRC_LENS, OFFSETS, USE_PIC and EBCDIC_TO_ASCII statements in your IMP file reflect the actual number of columns in your source and destination. See your SQLWizard User's Guide for a complete description of the IMP file and its contents.

Parent topic: WI100 - WI149


WI124: Invalid value Value for varchar length. Length must be no greater than page size Size.

The import process has been terminated because the DSNTIAUL file you are importing contains a varchar value that exceeds the current page size.

If the current page size is set to 4K, increase it to 32K in the Import dialog box and try importing the file again. If this does not correct the problem, verify that the DSNTIAUL file contains valid, non-corrupted data.

Parent topic: WI100 - WI149


WI125: Invalid record delimiter - escape character character is not allowed.

The escape character specified on the SQL tab of Options cannot be used as a record delimiter.

Parent topic: WI100 - WI149


WI126: Invalid field delimiter – escape character character is not allowed.

The escape character specified on the SQL tab of the Options utility cannot be used as a field delimiter.

Parent topic: WI100 - WI149


L104: Illegal symbol token. Valid symbols are token-list.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -104, for information.

Parent topic: L100 - L149


L105: Invalid string.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -105, for information.

Parent topic: L100 - L149


L107: The name name is too long. Maximum allowable size is size.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -107, for information.

Parent topic: L100 - L149


L108: THE NAME name IS QUALIFIED INCORRECTLY

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -108, for information.

Parent topic: L100 - L149


L109: clause clause is not permitted.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -109, for information.

Parent topic: L100 - L149


L110: Invalid hex literal beginning string.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -110, for information.

Parent topic: L100 - L149


L111: A column function does not include a column name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -111, for information.

Parent topic: L100 - L149


L112: The operand of a column function is another column function.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -112, for information.

Parent topic: L100 - L149


L113: Invalid character found in name: name. Reason code - reason-code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -113, for information.

Parent topic: L100 - L149


L114: THE LOCATION NAME location DOES NOT MATCH THE CURRENT SERVER

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -114, for information.

Parent topic: L100 - L149


L115: A predicate is invalid because operation operation is followed by a list, any or all.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -115, for information.

Parent topic: L100 - L149


L117: The number of insert values is not the same as the number of object columns.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -117, for information.

Parent topic: L100 - L149


L118: The object table or view of the insert/delete/update is in a FROM clause.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -118, for information.

Parent topic: L100 - L149


L119: A column in a HAVING clause is not included in the GROUP BY clause.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -119, for information.

Parent topic: L100 - L149


L120: A WHERE clause or a SET clause includes a column function.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -120, for information.

Parent topic: L100 - L149


L121: Column name is used more than once in insert or update.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -121, for information.

Parent topic: L100 - L149


L122: Select with no GROUP BY has column name/function or a column name not in GROUP BY.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -122, for information.

Parent topic: L100 - L149


L123: THE PARAMETER IN POSITION n IN THE FUNCTION name MUST BE A CONSTANT OR KEYWORD

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -123, for information.

Parent topic: L100 - L149


L125: An integer in the ORDER BY clause does not identify a column of the result.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -125, for information.

Parent topic: L100 - L149


L126: The SELECT statement contains both an UPDATE clause and an ORDER BY clause.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -126, for information.

Parent topic: L100 - L149


L127: Distinct is specified more than once in a subselect.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -127, for information.

Parent topic: L100 - L149


L128: Invalid use of NULL in a predicate.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -128, for information.

Parent topic: L100 - L149


L129: The statement contains too many table names.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -129, for information.

Parent topic: L100 - L149


L130: Escape clause with more than one char or string contains invalid esc char.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -130, for information.

Parent topic: L100 - L149


L131: Statement with LIKE predicate has incompatible data types.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -131, for information.

Parent topic: L100 - L149


L132: AN OPERAND OF value IS NOT VALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -132, for information.

Parent topic: L100 - L149


L151: Update is invalid because the descr of column name cannot be updated.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -151, for information.

Parent topic: L150 - L199


L152: THE DROP clause CLAUSE IN THE ALTER STATEMENT IS INVALID BECAUSE constraint-name IS A constraint-type

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -152, for information.

Parent topic: L150 - L199


L153: The CREATE VIEW statement does not include a required column list.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -153, for information.

Parent topic: L150 - L199


L154: CREATE VIEW failed because definition with union, union all, or remote object.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -154, for information.

Parent topic: L150 - L199


L156: The statement does not identify a table.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -156, for information.

Parent topic: L150 - L199


L157: name is not the name of a table needed for a foreign key clause.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -157, for information.

Parent topic: L150 - L199


L158: Number of columns specified for view is not equal to number of columns in select.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -158, for information.

Parent topic: L150 - L199


L159: DROP or COMMENT ON token identifies a(n) token.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -159, for information.

Parent topic: L150 - L199


L160: The WITH CHECK OPTION cannot be used for the specified view.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -160, for information.

Parent topic: L150 - L199


L161: INSERT or UPDATE not allowed because result row does not satisfy view definition.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -161, for information.

Parent topic: L150 - L199


L164: authid does not have privilege to create a view with qualification authorization.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -164, for information.

Parent topic: L150 - L199


L170: The number of arguments specified for function is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -170, for information.

Parent topic: L150 - L199


L171: The data type, length, or value of argument argument of function is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -171, for information.

Parent topic: L150 - L199


L173: UR IS SPECIFIED ON THE WITH CLAUSE BUT THE CURSOR IS NOT READ-ONLY

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -173, for information.

Parent topic: L150 - L199


L180: The string representation of a datetime value has invalid syntax.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -180, for information.

Parent topic: L150 - L199


L181: The string representation of a datetime value is not a valid datetime value.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -181, for information.

Parent topic: L150 - L199


L182: An arithmetic expression with a datetime value is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -182, for information.

Parent topic: L150 - L199


L183: Arithmetic operation on date or timestamp has result not in valid range.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -183, for information.

Parent topic: L150 - L199


L184: Arithmetic expression with a datetime value contains a parameter marker.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -184, for information.

Parent topic: L150 - L199


L185: Local format option was used with date or time with no local exit.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -185, for information.

Parent topic: L150 - L199


L186: Local date or time length was increased and the execute program uses old length.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -186, for information.

Parent topic: L150 - L199


L187: Reference to a current date/time special register is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -187, for information.

Parent topic: L150 - L199


L188: The string representation of a name is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -188, for information.

Parent topic: L150 - L199


L189: CCSID ccsid is unknown or invalid for the data type or subtype.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -189, for information.

Parent topic: L150 - L199


L190: ATTRIBUTES OF column-name IN table-name ARE NOT COMPATIBLE WITH EXISTING COLUMN

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -190, for information.

Parent topic: L150 - L199


L191: A string cannot be used because it is invalid mixed data.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -191, for information.

Parent topic: L150 - L199


L007: Statement contains the illegal character character.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -007, for information.

Parent topic: L000 - L099


L219: The required explanation table name does not exist.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -219, for information.

Parent topic: L200 - L299


L220: Column name in explanation table name is not defined properly.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -220, for information.

Parent topic: L200 - L299


L221: "opt cols" in explanation table name is incomplete. Opt col name is missing.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -221, for information.

Parent topic: L200 - L299


L240: THE PART CLAUSE OF A LOCK TABLE STATEMENT IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -240, for information.

Parent topic: L200 - L299


L250: Local location name is not defined when procession a 3-part object name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -250, for information.

Parent topic: L200 - L299


L251: Token name is not valid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -251, for information.

Parent topic: L200 - L299


L301: Value of input host variable number number not used because wrong data type.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -301, for information.

Parent topic: L300 - L399


L302: Value of input variable number number is invalid for the target column.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -302, for information.

Parent topic: L300 - L399


L303: Cannot assign value to output host variable number number. Types not comparable.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -303, for information.

Parent topic: L300 - L399


L304: Value with data type type cannot go in host variable at position number.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -304, for information.

Parent topic: L300 - L399


L305: Output host variable number number cannot be NULL when there is no indicator.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -305, for information.

Parent topic: L300 - L399


L309: Predicate is invalid because a referenced host variable has the NULL value.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -309, for information.

Parent topic: L300 - L399


L310: DECIMAL HOST VARIABLE OR PARAMETER number CONTAINS NON-DECIMAL DATA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -310, for information.

Parent topic: L300 - L399


L311: Length of input host variable number number is negative or greater than the max.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -311, for information.

Parent topic: L300 - L399


L312: Undefined or unusable host variable name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -312, for information.

Parent topic: L300 - L399


L313: Number of host variables specified "< >" to number of parameter markers.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -313, for information.

Parent topic: L300 - L399


L314: The statement contains an ambiguous host variable reference.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -314, for information.

Parent topic: L300 - L399


L327: CANNOT INSERT ROW BECAUSE IT IS OUTSIDE THE BOUND OF THE PARTITION RANGE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -327, for information.

Parent topic: L300 - L399


L330: String cannot be translated. Reason reason, char code-point, host var number.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -330, for information.

Parent topic: L300 - L399


L331: String cannot be assigned to a host variable. Reason reason, char code-point, pos number.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -331, for information.

Parent topic: L300 - L399


L332: SYSSTRINGS does not define a translation CCSID ccsid to ccsid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -332, for information.

Parent topic: L300 - L399


L333: String variable subtype not same as bind time and diff cannot be resolved.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -333, for information.

Parent topic: L300 - L399


L338: AN ON CLAUSE IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -338, for information.

Parent topic: L300 - L399


L350: INVALID SPECIFICATION OF A LARGE OBJECT COLUMN

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -350, for information.

Parent topic: L300 - L399


L351: UNSUPPORTED SQLTYPE IN POSITION position-number OF SELECT-LIST

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -351, for information.

Parent topic: L300 - L399


L352: UNSUPPORTED SQLTYPE IN POSITION position-number OF INPUT-LIST

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -352, for information.

Parent topic: L300 - L399


L010: The string constant beginning character is not terminated.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -010, for information.

Parent topic: L000 - L099


L402: Arithmetic function/operator "< >" applied to character/datetime data.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -402, for information.

Parent topic: L400 - L449


L404: THE SQL STATEMENT SPECIFIES A STRING THAT IS TOO LONG

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -404, for information.

Parent topic: L400 - L449


L405: Numeric literal literal is out of range.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -405, for information.

Parent topic: L400 - L449


L406: A calculated or derived numeric value not within range of its object column.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -406, for information.

Parent topic: L400 - L449


L407: COLUMN column-name CANNOT CONTAIN NULL VALUES IN INSERT, UPDATE OR SET

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -407, for information.

Parent topic: L400 - L449


L408: THE VALUE IS NOT COMPATIBLE WITH THE DATA TYPE OF ITS TARGET

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -408, for information.

Parent topic: L400 - L449


L409: Invalid operand of a count function.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -409, for information.

Parent topic: L400 - L449


L410: Floating point literal literal contains more than 30 characters.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -410, for information.

Parent topic: L400 - L449


L411: Current datetime, SQLID or user keyword cannot be used as specified.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -411, for information.

Parent topic: L400 - L449


L412: The SELECT clause of a subquery specifies multiple columns.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -412, for information.

Parent topic: L400 - L449


L413: OVERFLOW OCCURRED DURING NUMERIC DATA TYPE CONVERSION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -413, for information.

Parent topic: L400 - L449


L414: Numeric or datetime column name is specified in a LIKE predicate.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -414, for information.

Parent topic: L400 - L449


L415: Cols, number, of the operands of a union do not have comparable col. descr.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -415, for information.

Parent topic: L400 - L449


L416: An operand of a union contains a long string column.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -416, for information.

Parent topic: L400 - L449


L417: PREPARE string includes parameter markers as operand of same operator.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -417, for information.

Parent topic: L400 - L449


L418: A string to be prepared contains an invalid use of parameter markers.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -418, for information.

Parent topic: L400 - L449


L419: Decimal divide operation is invalid because the result has a negative scale.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -419, for information.

Parent topic: L400 - L449


L420: STRING ARGUMENT VALUE NOT ACCEPTABLE TO FUNCTION function-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -420, for information.

Parent topic: L400 - L449


L421: Operand of a union or union all does not have the same number of columns.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -421, for information.

Parent topic: L400 - L449


L423: INVALID VALUE FOR LOCATOR IN POSITION position-number

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -423, for information.

Parent topic: L400 - L449


L426: Dynamic commit not valid at application server where updates not allowed.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -426, for information.

Parent topic: L400 - L449


L427: Dynamic rollback not valid at application server where updates not allowed.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -427, for information.

Parent topic: L400 - L449


L430: routine-typeroutine-name (specific-name) HAS ABNORMALLY TERMINATED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -430, for information.

Parent topic: L400 - L449


L433: VALUE value IS TOO LONG

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -433, for information.

Parent topic: L400 - L449


L435: INVALID SQLSTATE sqlstate SPECIFIED IN RAISE_ERROR OR IN A SIGNAL SQLSTATE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -435, for information.

Parent topic: L400 - L449


L438: APPLICATION RAISED ERROR WITH DIAGNOSTIC TEXT: text

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -438, for information.

Parent topic: L400 - L449


L029: INTO clause required.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -029, for information.

Parent topic: L000 - L099


L456: FUNCTION function-name, SPECIFIC specific-name EXISTS IN THE SCHEMA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -456, for information.

Parent topic: L450 - L499


L457: ILLEGAL USE OF name; IT IS RESERVED FOR SYSTEM USE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -457, for information.

Parent topic: L450 - L499


L458: FUNCTION function-name COULD NOT BE FOUND BY SIGNATURE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -458, for information.

Parent topic: L450 - L499


L461: VALUE OF TYPE source-data-type CANNOT BE CAST TO target-data-type

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -461, for information.

Parent topic: L450 - L499


L463: routine-name (specific-name) RETURNED sqlstate, DIAGNOSTIC TEXT text

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -463, for information.

Parent topic: L450 - L499


L469: CALL STATEMENT NEEDS AN OUTPUT HOST VARIABLE FOR PARAMETER number

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -469, for information.

Parent topic: L450 - L499


L470: CALL STATEMENT SPECIFIED A NULL VALUE FOR INPUT PARAMETER number

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -470, for information.

Parent topic: L450 - L499


L471: INVOCATION OF FUNCTION/PROCEDURE name FAILED DUE TO REASON rc

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -471, for information.

Parent topic: L450 - L499


L472: CURSOR cursor-name LEFT OPEN BY FUNCTION function-name (specific-name)

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -472, for information.

Parent topic: L450 - L499


L473: USER DEFINED TYPE CANNOT BE THE SAME NAME AS A BUILT-IN TYPE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -473, for information.

Parent topic: L450 - L499


L475: type-1 RESULT CANNOT BE CAST TO type-2 RETURN TYPE OF THE function-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -475, for information.

Parent topic: L450 - L499


L476: FUNCTION function-name NAMED WITHOUT SIGNATURE, FUNCTION NOT UNIQUE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -476, for information.

Parent topic: L450 - L499


L478: ACTION ON type1 CANNOT BE PROCESSED; name OF TYPE type2 DEPENDENT ON IT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -478, for information.

Parent topic: L450 - L499


L480: PROCEDURE procedure-name HAS NOT YET BEEN CALLED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -480, for information.

Parent topic: L450 - L499


L482: PROCEDURE procedure-name RETURNED NO LOCATORS

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -482, for information.

Parent topic: L450 - L499


L483: PARMS FOR function-name DOES NOT MATCH NUMBER OF PARMS OF SOURCE FUNCTION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -483, for information.

Parent topic: L450 - L499


L487: object-typeobject-name USED SQL BUT WAS CREATED WITH NOSQL OPTION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -487, for information.

Parent topic: L450 - L499


L491: FUNCTION function-name MUST HAVE RETURNS, AND EITHER EXTERNAL OR SOURCE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -491, for information.

Parent topic: L450 - L499


L492: function-name PARAMETER number HAS MISMATCH WITH A SOURCE FUNCTION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -492, for information.

Parent topic: L450 - L499


L495: EST COST OF estimate-amount1 PROCESSOR SECONDS EXCEEDS RESOURCE LIMIT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -495, for information.

Parent topic: L450 - L499


L496: SQL STATEMENT REFERENCES A RESULT SET NOT CREATED BY THE CURRENT SERVER

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -496, for information.

Parent topic: L450 - L499


L497: INTERNAL IDENTIFIERS LIMIT HAS BEEN EXCEEDED FOR DATABASE database-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -497, for information.

Parent topic: L450 - L499


L499: CURSOR cursor-name ALREADY ASSIGNED TO procedure-name RESULT SET

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -499, for information.

Parent topic: L450 - L499


L500: IDENTIFIED CURSOR WAS CLOSED WHEN THE CONNECTION WAS DESTROYED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -500, for information.

Parent topic: L500 - L549


L501: Cursor identified in a FETCH or CLOSE statement is not open.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -501, for information.

Parent topic: L500 - L549


L502: The cursor identified in an OPEN statement is already open.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -502, for information.

Parent topic: L500 - L549


L060: Invalid type specification: spec.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -060, for information.

Parent topic: L000 - L099


L516: The described statement does not identify a prepared statement.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -516, for information.

Parent topic: L500 - L549


L517: Cursor name does not identify a prepared SELECT statement.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -517, for information.

Parent topic: L500 - L549


L518: The EXECUTE statement does not identify a valid prepared statement.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -518 for information.

Parent topic: L500 - L549


L519: PREPARE identifies SELECT statement of the open cursor name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -519, for information.

Parent topic: L500 - L549


L525: SQL cannot execute, error at bind for section sectno, package pkgname, consistency token Xcontoken.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -519, for information.

Parent topic: L500 - L549


L526: REQUESTED FUNCTION DOES NOT APPLY TO GLOBAL TEMPORARY TABLES

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -526, for information.

Parent topic: L500 - L549


L530: The INSERT or UPDATE value of foreign key name is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -530, for information.

Parent topic: L500 - L549


L531: Primary key in parent has dependent rows in relation name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -531, for information.

Parent topic: L500 - L549


L532: The relation name restricts the deletion of row with RID X number.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -532, for information.

Parent topic: L500 - L549


L533: Invalid multiple-row insert.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -533, for information.

Parent topic: L500 - L549


L534: The primary key cannot be updated because of multiple-row update.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -534, for information.

Parent topic: L500 - L549


L535: Invalid update or delete with WHERE CURRENT OF.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -535, for information.

Parent topic: L500 - L549


L536: Delete is invalid because table name can be affected by the operation.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -536, for information.

Parent topic: L500 - L549


L537: Primary key/foreign key identifies column name more than once.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -537, for information.

Parent topic: L500 - L549


L538: Foreign key name does not match description of primary key of table name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -538, for information.

Parent topic: L500 - L549


L539: Table name does not have a primary key.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -539, for information.

Parent topic: L500 - L549


L540: Definition of table name does not have primary index.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -540, for information.

Parent topic: L500 - L549


L541: FOREIGN KEY key-name HAS DUPLICATE REFERENTIAL CONSTRAINT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -541, for information.

Parent topic: L500 - L549


L542: name cannot be a column of primary key because it can contain NULL values.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -542, for information.

Parent topic: L500 - L549


L543: CANNOT DELETE ROW IN PARENT TABLE; RESTRICTED BY CONSTRAINT check-constraint

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -543, for information.

Parent topic: L500 - L549


L544: CANNOT ADD CHECK CONSTRAINT; EXISTING ROW VIOLATES THE CHECK CONSTRAINT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -544, for information.

Parent topic: L500 - L549


L545: The requested operation is not allowed because of the check constraint CheckConstraint.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -545, for information.

Parent topic: L500 - L549


L546: CHECK CONSTRAINT constraint-name IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -159, for information.

Parent topic: L500 - L549


L548: A CHECK CONSTRAINT THAT IS DEFINED WITH column-name IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -548, for information.

Parent topic: L500 - L549


L549: The Statement statement is not allowed for ObjectType1ObjectName because the bind option dynamicrules in the ObjectType2 is in effect.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -549, for information.

Parent topic: L500 - L549


L551: Authid does not have privileges to perform operation Name on this object.

If you are using the ODBC Smart Driver to monitor or record SQL, check that the specified authid has permission to access the ODBC_* tables used by the Static Bind Administrator. For a list of these tables and the permissions required to access them, see the GRANT statements in the ODBCSQL.SQL file located in your Micro Focus program directory.

Parent topic: L550 - L599


L084: UNACCEPTABLE SQL STATEMENT.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -084, for information.

Parent topic: L000 - L099


L573: table-name DOES NOT HAVE UNIQUE KEY WITH SPECIFIED COLUMN NAMES

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -573, for information.

Parent topic: L550 - L599


L574: THE DEFAULT VALUE CONFLICTS WITH DEFINITION OF COLUMN column-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -574, for information.

Parent topic: L550 - L599


L577: DEFINITION OF object-typeobject-name DID NOT SPECIFY MODIFY DATA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -577, for information.

Parent topic: L550 - L599


L579: DEFINITION OF object-typeobject-name DID NOT SPECIFY READ OR MODIFY DATA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -579, for information.

Parent topic: L550 - L599


L580: THE RESULT-EXPRESSIONS OF A CASE EXPRESSION CANNOT ALL BE NULL

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -580, for information.

Parent topic: L550 - L599


L581: RESULT-EXPRESSION DATA TYPES OF CASE EXPRESSION ARE NOT COMPATIBLE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -581, for information.

Parent topic: L550 - L599


L582: WHEN-CLAUSE CONDITION CANNOT BE QUANTIFIED, IN, OR EXISTS PREDICATE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -582, for information.

Parent topic: L550 - L599


L583: INVALID USE OF FUNCTION; function-name NOT DETERMINISTIC/EXTERNAL ACTION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -583, for information.

Parent topic: L550 - L599


L585: SCHEMA NAME schema-name CANNOT APPEAR MORE THAN ONCE IN THE CURRENT PATH

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -585, for information.

Parent topic: L550 - L599


L586: TOTAL LENGTH OF CURRENT PATH SPECIAL REGISTER CANNOT EXCEED 254 CHARACTERS

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -586, for information.

Parent topic: L550 - L599


L587: A LIST OF ITEM-REFERENCES ARE NOT IN THE SAME FAMILY

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -587, for information.-587, for information.

Parent topic: L550 - L599


L590: PARAMETER parameter-name NOT UNIQUE FOR ROUTINE routine-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -590, for information.

Parent topic: L550 - L599


L592: NOT AUTHORIZED TO CREATE FUNCTIONS/PROCEDURES IN WLM ENV env-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -592, for information.

Parent topic: L550 - L599


L601: Name of the object to be created identical to existing name name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -601, for information.

Parent topic: L600 - L649


L602: Too many columns specified in a CREATE INDEX.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -602, for information.

Parent topic: L600 - L649


L603: Unique index cannot be created. The table has rows with duplicate columns.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -603, for information.

Parent topic: L600 - L649


L604: Column definition specifies an invalid length, precision, or scale attribute.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -604, for information.

Parent topic: L600 - L649


L607: Operation operation is not defined for system tables.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -607, for information.

Parent topic: L600 - L649


L611: ONLY LOCKMAX 0 CAN BE SPECIFIED WHEN LOCK SIZE IS TABLESPACE OR TABLE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -611, for information.

Parent topic: L600 - L649


L612: name is a duplicate column name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -612, for information.

Parent topic: L600 - L649


L613: The primary key is too long or has too many columns.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -613, for information.

Parent topic: L600 - L649


L614: Cannot create index. Sum of internal lengths of columns > allowable.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -614, for information.

Parent topic: L600 - L649


L615: op is not allowed on a package in use.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -615, for information.

Parent topic: L600 - L649


L616: obj-typeobj-name CANNOT BE DROPPED; REFERENCED BY obj-typeobj-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -616, for information.

Parent topic: L600 - L649


L617: TYPE 1 INDEX IS NOT VALID FOR TABLE table-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -617, for information.

Parent topic: L600 - L649


L618: Operation operation is not allowed on system databases.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -618, for information.

Parent topic: L600 - L649


L101: The statement is too long or too complex.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -101, for information.

Parent topic: L100 - L149


L629: No set NULL because foreign key name cannot contain NULL values.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -629, for information.

Parent topic: L600 - L649


L630: WHERE NOT NULL SPECIFICATION IS INVALID FOR TYPE 1 INDEXES

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -630, for information.

Parent topic: L600 - L649


L631: Foreign key name is too long or has too many columns.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -631, for information.

Parent topic: L600 - L649


L632: Cannot define table as dependent of name due to delete rule restriction.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -632, for information.

Parent topic: L600 - L649


L633: The delete rule must be delete.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -633, for information.

Parent topic: L600 - L649


L634: The delete rule must not be cascade.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -634, for information.

Parent topic: L600 - L649


L635: The delete rules cannot be different or cannot be set NULL.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -635, for information.

Parent topic: L600 - L649


L636: Partitioning keys not specified in ascending/descending order.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -636, for information.

Parent topic: L600 - L649


L637: Duplicate keyword keyword.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -637, for information.

Parent topic: L600 - L649


L638: Table name cannot be created. Column definition is missing.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -638, for information.

Parent topic: L600 - L649


L639: Column of foreign key with delete rule of set NULL cannot be in partition index.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -639, for information.

Parent topic: L600 - L649


L640: LOCKSIZE ROW CANNOT BE SPECIFIED; TABLE HAS TYPE 1 INDEX

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -640, for information.

Parent topic: L600 - L649


L642: TOO MANY COLUMNS IN UNIQUE CONSTRAINTS

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -642, for information.

Parent topic: L600 - L649


L643: CHECK CONSTRAINT EXCEEDS MAXIMUM ALLOWABLE LENGTH

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -643, for information.

Parent topic: L600 - L649


L644: INVALID VALUE SPECIFIED FOR KEYWORD keyword IN statement-type STATEMENT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -644, for information.

Parent topic: L600 - L649


L646: Cannot create table name in partitioned default tablespace name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -646, for information.

Parent topic: L600 - L649


L647: Bufferpool name cannot be specified. It has not been activated.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -647, for information.

Parent topic: L600 - L649


L652: Violation of installation-defined edit or validation procedure proc.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -652, for information.

Parent topic: L650 - L699


L650: THE ALTER INDEX CANNOT BE EXECUTED, REASON reason-code

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -650, for information.

Parent topic: L650 - L699


L651: TABLE DESCRIPTION EXCEEDS MAXIMUM SIZE OF OBJECT DESCRIPTOR

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -651, for information.

Parent topic: L650 - L699


L653: Table name in partitioned tablespace name not available.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -653, for information.

Parent topic: L650 - L699


L655: CREATE OR ALTER STOGROUP IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -655, for information.

Parent topic: L650 - L699


L658: object-type CANNOT BE DROPPED USING THE statement STATEMENT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -658, for information.

Parent topic: L650 - L699


L660: Cannot create index name on partitioned tablespace name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -660, for information.

Parent topic: L650 - L699


L661: Cannot create index name on partitioned tablespace name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -661, for information.

Parent topic: L650 - L699


L662: Cannot create a partitioned index on a non-partitioned tablespace name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -662, for information.

Parent topic: L650 - L699


L102: Size of string constant starting string is too great.

See the Error SQLCODES section of your IBM Database Messages and Codes Manual, message -102, for information.

Parent topic: L100 - L149


L676: A 32K page bufferpool may not be used for an index.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -676, for information.

Parent topic: L650 - L699


L677: Insufficient virtual storage for bufferpool expansion.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -677, for information.

Parent topic: L650 - L699


L678: literal specified for index limit key must conform to data type type.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -678, for information.

Parent topic: L650 - L699


L679: Object name cannot be created. A drop is pending on the object.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -679, for information.

Parent topic: L650 - L699


L680: Too many columns specified for a table.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -680, for information.

Parent topic: L650 - L699


L681: Column name in violation of installation-defined field procedure name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -681, for information.

Parent topic: L650 - L699


L682: Field procedure proc could not be loaded.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -682, for information.

Parent topic: L650 - L699


L683: Invalid column type for fieldproc or bit data option, column.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -683, for information.

Parent topic: L650 - L699


L684: The length of literal list beginning string is too long.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -684, for information.

Parent topic: L650 - L699


L685: Invalid field type column.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -685, for information.

Parent topic: L650 - L699


L686: Cannot compare column defined by one field procedure to one defined by another.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -686, for information.

Parent topic: L650 - L699


L687: Field types incomparable.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -687, for information.

Parent topic: L650 - L699


L688: Incorrect data returned from field procedure, column, msgno.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -688, for information.

Parent topic: L650 - L699


L689: Too many columns defined for a dependent table.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -689, for information.

Parent topic: L650 - L699


L690: Statement is rejected by data def ctrl support, reason reason.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -690, for information.

Parent topic: L650 - L699


L691: The required registrations table table does not exist.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -691, for information.

Parent topic: L650 - L699


L692: Unique index index-name in table table-name does not exist.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -692, for information.

Parent topic: L650 - L699


L693: Column column is not defined properly.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -693, for information.

Parent topic: L650 - L699


L694: DDL STMT CANNOT EXECUTE; DROP PENDING ON DDL REGISTRATION TABLE table-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -694, for information.

Parent topic: L650 - L699


L696: TRIGGER trigger-name CONTAINS INVALID USE OF NAME name, REASON reason-code

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -696, for information.

Parent topic: L650 - L699


L697: CORR. NAMES NOT ALLOWED IN TRIGGER WITH "FOR EACH STATEMENT" OR "BEFORE"

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -697, for information.

Parent topic: L650 - L699


L713: REPLACEMENT VALUE value FOR special-register IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -713, for information.

Parent topic: L700 - L799


L715: Prog program dep on function of the release from which fallback has occurred.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -715, for information.

Parent topic: L700 - L799


L716: Program program precompiled with wrong level for this release.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -716, for information.

Parent topic: L700 - L799


L717: object dependent on function of release from which fallback has occurred.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -717, for information.

Parent topic: L700 - L799


L718: REBIND failed because IBMREQD of ibmreqd is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -718, for information.

Parent topic: L700 - L799


L103: literal is an invalid numeric literal.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -103, for information.

Parent topic: L100 - L149


L730: The parent of a table in a read-only database must also be in the database.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -730, for information.

Parent topic: L700 - L799


L731: User-defined dataset dsname must be defined with SHAREOPTIONS(1,3).

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -731, for information.

Parent topic: L700 - L799


L732: Table space or index space has not been defined on the owning subsystem.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -732, for information.

Parent topic: L700 - L799


L733: The description of a table space, index space or ROSHARE READ db must be consistent.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -733, for information.

Parent topic: L700 - L799


L734: The ROSHARE attr of a database cannot be altered from ROSHARE READ.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -734, for information.

Parent topic: L700 - L799


L735: Database dbid is not longer a shared database.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -735, for information.

Parent topic: L700 - L799


L736: Invalid OBID obid specified.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -736, for information.

Parent topic: L700 - L799


L737: Implicit table space not allowed.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -737, for information.

Parent topic: L700 - L799


L739: ALTER function-name FAILED; PARALLEL PROCESSED FUNCTIONS CANNOT MODIFY DATA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -739, for information.

Parent topic: L700 - L799


L740: FUNCTION name THAT MODIFIES SQL DATA IS NOT VALID IN CURRENT CONTEXT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -740, for information.

Parent topic: L700 - L799


L741: WORK FILE DATABASE IS ALREADY DEFINED FOR MEMBER member-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -741, for information.

Parent topic: L700 - L799


L742: DSNDB07 IS THE IMPLICIT WORK FILE DATABASE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -742, for information.

Parent topic: L700 - L799


L746: SQL STATEMENT IN name VIOLATES THE NESTING SQL RESTRICTION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -746, for information.

Parent topic: L700 - L799


L747: table-name NOT AVAILABLE UNTIL AUX TABLES AND INDEXES HAVE BEEN CREATED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -747, for information.

Parent topic: L700 - L799


L748: AN INDEX ALREADY EXISTS ON AUXILIARY TABLE table-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -748, for information.

Parent topic: L700 - L799


L750: TABLE source-name CANNOT BE RENAMED; REFERENCED BY EXISTING DEFINITIONS

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -750, for information.

Parent topic: L700 - L799


L751: object-typeobject-name (specific-name) ATTEMPTED TO EXECUTE statement

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -751, for information.

Parent topic: L700 - L799


L752: CONNECT statement invalid because the process is not in the connectable state.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -752, for information.

Parent topic: L700 - L799


L763: INVALID TABLE SPACE NAME table-space-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -763, for information.

Parent topic: L700 - L799


L764: LOB TABLE SPACE AND ITS BASE TABLE SPACE MUST BE IN SAME DATABASE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -764, for information.

Parent topic: L700 - L799


L765: TABLE IS NOT COMPATIBLE WITH DATABASE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -765, for information.

Parent topic: L700 - L799


L766: REQUESTED OPERATION NOT PERMITTED ON AUXILIARY TABLE OF STATEMENT OBJECT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -766, for information.

Parent topic: L700 - L799


L767: MISSING OR INVALID COLUMN SPECIFICATION FOR INDEX index-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -767, for information.

Parent topic: L700 - L799


L768: AUXILIARY TABLE ALREADY EXISTS FOR THE SPECIFIED COLUMN OR PARTITION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -768, for information.

Parent topic: L700 - L799


L769: SPECIFICATION OF AUX TABLE DOES NOT MATCH CHARACTERISTICS OF BASE TABLE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -769, for information.

Parent topic: L700 - L799


L770: TABLE table-name CANNOT HAVE LOB COLUMN UNLESS IT ALSO HAS ROWID COLUMN

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -770, for information.

Parent topic: L700 - L799


L133: Column function in subquery of HAVING invalid because expression applies op to corr ref.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -133, for information.

Parent topic: L100 - L149


L134: IMPROPER USE OF LONG STRING COLUMN column-name OR AN EXPRESSION OF MAXIMUM LENGTH GREATER THAN 255.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -134, for information.

Parent topic: L100 - L149


L136: Sort cannot be executed because sort key length > 4000 bytes.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -136, for information.

Parent topic: L100 - L149


L137: THE LENGTH RESULTING FROM operation IS GREATER THAN maximum-length

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -137, for information.

Parent topic: L100 - L149


L138: The second or third argument of the SUBSTR function is out of range.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -138, for information.

Parent topic: L100 - L149


L142: THE SQL STATEMENT IS NOT SUPPORTED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -142, for information.

Parent topic: L100 - L149


L144: Invalid section number number.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -144, for information.

Parent topic: L100 - L149


L147: ALTER FUNCTION function-name FAILED BECAUSE SOURCE FUNCTIONS CANNOT BE ALTERED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -147, for information.

Parent topic: L100 - L149


L148: THE SOURCE TABLE source-name CANNOT BE RENAMED OR ALTERED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -148, for information.

Parent topic: L100 - L149


L150: The INSERT, DELETE or UPDATE object is a view and is not permitted.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -150, for information.

Parent topic: L150 - L199


L197: QUALIFIED NAMES IN ORDER BY NOT PERMITTED WITH UNION OR UNION ALL

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -197, for information.

Parent topic: L150 - L199


L198: Operand of the PREPARE or EXECUTE IMMEDIATE statement is blank or empty.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -198, for information.

Parent topic: L150 - L199


L199: Illegal use of keyword keyword. Token token was expected.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -199, for information.

Parent topic: L150 - L199


L203: A reference to column name is ambiguous.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -203, for information.

Parent topic: L200 - L299


L204: name is an undefined name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -204, for information.

Parent topic: L200 - L299


L205: col is not a column of table tablename.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -205, for information.

Parent topic: L200 - L299


L206: name is not a column of a table in an INSERT, UPDATE or FROM clause.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -206, for information.

Parent topic: L200 - L299


L207: ORDER BY invalid because the column name applies to result of UNION or UNION ALL.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -207, for information.

Parent topic: L200 - L299


L208: ORDER BY invalid because column name is not part of the result table.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -208, for information.

Parent topic: L200 - L299


L212: name IS MULTIPLY SPECIFIED IN TRIGGER REFERENCING CLAUSE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -212, for information.

Parent topic: L200 - L299


L355: A LOB COLUMN IS TOO LARGE TO BE LOGGED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -355, for information.

Parent topic: L300 - L399


L372: ONLY ONE COLUMN DEFINED AS ROWID IS ALLOWED IN A TABLE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -372, for information.

Parent topic: L300 - L399


L390: FUNCTION function-name (specific-name), NOT VALID IN THAT CONTEXT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -390, for information.

Parent topic: L300 - L399


L392: SQLDA PROVIDED FOR cursor HAS BEEN CHANGED FROM PREVIOUS FETCH

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -392, for information.

Parent topic: L300 - L399


L396: object-typeobject-name EXECUTED SQL STATEMENT DURING FINAL CALL PROCESSING

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -396, for information.

Parent topic: L300 - L399


L397: GENERATED OPTION SPECIFIED ON COLUMN THAT IS NOT TYPE ROW ID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -397, for information.

Parent topic: L300 - L399


L398: LOCATOR REQUESTED FOR HOST VARIABLE position-number BUT VARIABLE NOT A LOB

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -398, for information.

Parent topic: L300 - L399


L399: ATTEMPTED TO INSERT AN INVALID VALUE INTO A ROWID COLUMN

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -399, for information.

Parent topic: L300 - L399


L400: THE CATALOG HAS THE MAXIMUM NUMBER OF USER DEFINED INDEXES

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -400, for information.

Parent topic: L400 - L449


L401: Operands of an arithmetic or comparison operation are not comparable.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -401, for information.

Parent topic: L400 - L449


L440: NO routine-type NAMED routine-name WITH COMPATIBLE ARGUMENTS WAS FOUND

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -440, for information.

Parent topic: L400 - L449


L441: INVALID USE OF 'DISTINCT' OR 'ALL' WITH SCALAR FUNCTION function-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -441, for information.

Parent topic: L400 - L449


L443: function-name (specific-name) RETURNED WITH DIAGNOSTIC TEXT msg-text

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -443, for information.

Parent topic: L400 - L449


L444: USER PROGRAM name COULD NOT BE FOUND

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -444, for information.

Parent topic: L400 - L449


L449: INVALID EXTERNAL NAME CLAUSE FOR FUNCTION OR PROCEDURE routine-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -449, for information.

Parent topic: L400 - L449


L450: FUNCTION/STORED PROCEDURE name, PARAMETER NUMBER parmnum, OVERLAYED MEMORY

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -450, for information.

Parent topic: L450 - L499


L451: INVALID data-item DEFINITION IN function-name, INVALID DATA TYPE type

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -451, for information.

Parent topic: L450 - L499


L453: PROBLEM WITH THE RETURNS CLAUSE FOR FUNCTION function-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -453, for information.

Parent topic: L450 - L499


L454: SIGNATURE FOR FUNCTION function-name NOT UNIQUE WITHIN SCHEMA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -454, for information.

Parent topic: L450 - L499


L455: function-name, SCHEMA schema-name1 IN SPECIFIC NAME DOES NOT MATCH schema-name2

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -455, for information.

Parent topic: L450 - L499


L503: Column cannot be updated because it is not in the UPDATE clause of the select.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -503, for information.

Parent topic: L500 - L549


L504: The cursor name name is not defined.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -504, for information.

Parent topic: L500 - L549


L507: The cursor identified in the UPDATE or DELETE statement is not open.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -507, for information.

Parent topic: L500 - L549


L508: Cursor identified in an update or delete is not positioned on a row.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -508, for information.

Parent topic: L500 - L549


L509: The table in an UPDATE or DELETE is not a table designated by cursor.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -509, for information.

Parent topic: L500 - L549


L510: Table designated by cursor of UPDATE/DELETE statement cannot be modified.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -510, for information.

Parent topic: L500 - L549


L511: FOR UPDATE clause invalid because cursor cannot be modified.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -511, for information.

Parent topic: L500 - L549


L512: Statement reference to remote object is invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -512, for information.

Parent topic: L500 - L549


L513: The alias name must not be defined by another local or remote alias.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -513, for information.

Parent topic: L500 - L549


L514: The cursor name is not in a prepared state.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -514, for information.

Parent topic: L500 - L549


L552: authid does not have the privileges to perform operation operation.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -552, for information.

Parent topic: L550 - L599


L553: authid specified is not one of the valid AuthIDs.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -553, for information.

Parent topic: L550 - L599


L554: An AuthID cannot grant a privilege to itself.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -554, for information.

Parent topic: L550 - L599


L555: An AuthID cannot revoke a privilege from itself.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -555, for information.

Parent topic: L550 - L599


L556: A privilege cannot be revoked because it is not possessed by authid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -556, for information.

Parent topic: L550 - L599


L557: Inconsistent grant/revoke keyword keyword. Permitted keywords are keyword-list.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -557, for information.

Parent topic: L550 - L599


L558: Invalid clause or combination of clauses on a grant or revoke.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -558, for information.

Parent topic: L550 - L599


L559: All authorization functions have been disabled.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -559, for information.

Parent topic: L550 - L599


L567: bind-type AUTHORIZATION ERROR FOR auth-idpackage-nameprivilege

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -567, for information.

Parent topic: L550 - L599


L571: The statement would result in a multiple site update.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -571, for information.

Parent topic: L550 - L599


L619: Operation disallowed because the workfile database is not stopped.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -619, for information.

Parent topic: L600 - L649


L620: Keyword keyword not allowed for tablespace in workfile database.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -620, for information.

Parent topic: L600 - L649


L621: Duplicate dbid dbid was detected and previously assigned to dbname.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -621, for information.

Parent topic: L600 - L649


L622: FOR MIXED DATA is invalid because MIXED DATA inst opt is NO.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -622, for information.

Parent topic: L600 - L649


L623: A clustering index already exists on table name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -623, for information.

Parent topic: L600 - L649


L624: Table name already has a primary key.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -624, for information.

Parent topic: L600 - L649


L625: TABLE table-name DOES NOT HAVE INDEX TO ENFORCE UNIQUENESS OF PARENT KEY

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -625, for information.

Parent topic: L600 - L649


L626: ALTER statement is not executable because the pageset is not stopped.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -626, for information.

Parent topic: L600 - L649


L627: ALTER statement is invalid because the pageset has user-managed data set.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -627, for information.

Parent topic: L600 - L649


L628: THE CLAUSES ARE MUTUALLY EXCLUSIVE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -628, for information.

Parent topic: L600 - L649


L663: Number of key limit values is 0, or > number of columns in key of index.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -663, for information.

Parent topic: L650 - L699


L664: Internal length of limit-key fields for partitioned index name is too long.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -664, for information.

Parent topic: L650 - L699


L665: The PART clause of an ALTER statement is omitted or invalid.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -665, for information.

Parent topic: L650 - L699


L666: stmt-verbobject cannot be executed because of something in progress.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -666, for information.

Parent topic: L650 - L699


L667: Clustering index for partitioned tablespace cannot be explicitly dropped.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -667, for information.

Parent topic: L650 - L699


L668: Cannot add column to the table because the table has an edit procedure.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -668, for information.

Parent topic: L650 - L699


L669: A table in a partitioned tablespace cannot be explicitly dropped.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -669, for information.

Parent topic: L650 - L699


L670: The record length of the table exceeds the page size limit.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -670, for information.

Parent topic: L650 - L699


L671: Cannot alter buffpool attr of tablespace because pg size of tablespace would change.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -671, for information.

Parent topic: L650 - L699


L672: OPERATION DROP NOT ALLOWED ON TABLE table-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -672, for information.

Parent topic: L650 - L699


L719: BIND ADD error, package package already exists.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -719, for information.

Parent topic: L700 - L799


L720: Attempt to replace package package with existing version version.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -720, for information.

Parent topic: L700 - L799


L721: BIND err CONTOK = contoken X cannot be created because it is not unique.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -721, for information.

Parent topic: L700 - L799


L722: Package package does not exist.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -722, for information.

Parent topic: L700 - L799


L723: ERROR IN TRIGGER trigger-name, SECTION NUMBER section-number

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -723, for information.

Parent topic: L700 - L799


L724: ACTIVATION OF object-typeobject-name WOULD EXCEED MAXIMUM OF SQL CASCADING

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -724, for information.

Parent topic: L700 - L799


L725: SPECIAL REGISTER register AT location WAS SUPPLIED INVALID VALUE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -725, for information.

Parent topic: L700 - L799


L726: Cannot replace package package. Enable or disable entries also with package.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -726, for information.

Parent topic: L700 - L799


L728: DATA TYPE data-type IS NOT ALLOWED IN DB2 PRIVATE PROTOCOL PROCESSING

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -728, for information.

Parent topic: L700 - L799


L729: COMMIT ON RETURN STORED PROCEDURE CANNOT BE IN NESTED CALL STATEMENT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -729, for information.

Parent topic: L700 - L799


L771: INVALID SPECIFICATION OF A ROWID COLUMN

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -771, for information.

Parent topic: L700 - L799


L797: ATTEMPT TO CREATE TRIGGER trigger-name WITH AN UNSUPPORTED SQL STATEMENT

Parent topic: L700 - L799


L798: ATTEMPT TO INSERT VALUE INTO ROWID GENERATED ALWAYS COLUMN column-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -798, for information.

Parent topic: L700 - L799


L802: EXCEPTION ERROR exception-type OCCURRED DURING operation-type OPERATION ON data-type DATA

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -802, for information.

Parent topic: L800 - L899


L803: INSERT/UPDATE INVALID;INDEX SPACE index-space-name RESTRICTS DUP COLUMNS, RID row-id

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -803, for information.

Parent topic: L800 - L899


L804: Error found in application program input parameters for the SQL statement.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -804, for information.

Parent topic: L800 - L899


L805: Program name name not found in plan name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -805, for information.

Parent topic: L800 - L899


L807: Access denied to package pkg.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -807, for information.

Parent topic: L800 - L899


L808: CONNECT STATEMENT IS NOT CONSISTENT WITH THE FIRST CONNECT STATEMENT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -808, for information.

Parent topic: L800 - L899


L811: Result of embedded select statement is a table with more than one row.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -811, for information.

Parent topic: L800 - L899


L812: BLANK COLLECTION-ID IN CURRENT PACKAGE SET; PGM program-name.consistency-token USING PLAN plan-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -812, for information.

Parent topic: L800 - L899


L815: GROUP BY/HAVING clause specified in embedded select statement/subquery.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -815, for information.

Parent topic: L800 - L899


L817: Cannot execute INSERT/UPDATE/DELETE/DLL/AUTHORIZATION statement.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -817, for information.

Parent topic: L800 - L899


L818: Timestamp in load module is not the same as bind timestamp built from the DBRM.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -818, for information.

Parent topic: L800 - L899


L819: Cannot process view. Length of its parse tree in the catalog is zero.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -819, for information.

Parent topic: L800 - L899


L820: Cannot process SQL statement. catalog contains a value not valid in version.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -820, for information.

Parent topic: L800 - L899


L822: SQLDA contains invalid data address or indicator variable address.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -822, for information.

Parent topic: L800 - L899


L840: Too many items returned in a select or insert list.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -840, for information.

Parent topic: L800 - L899


L842: A CONNECTION TO location-name ALREADY EXISTS

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -842, for information.

Parent topic: L800 - L899


L843: SET CONNECTION OR RELEASE STATEMENT MUST SPECIFY AN EXISTING CONNECTION

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -843, for information.

Parent topic: L800 - L899


L870: NUMBER OF HOST VARIABLES IN STATEMENT NOT EQUAL TO NUMBER OF DESCRIPTORS

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -870, for information.

Parent topic: L800 - L899


L872: A VALID CCSID HAS NOT YET BEEN SPECIFIED FOR THIS SUBSYSTEM

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -872, for information.

Parent topic: L800 - L899


L873: DATA ENCODED WITH DIFFERENT CCSIDS CANNOT BE REFERENCED IN SAME STATEMENT

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -873, for information.

Parent topic: L800 - L899


L874: object-type ENCODING SCHEME MUST BE SAME AS THE CONTAINING TABLE SPACE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -874, for information.

Parent topic: L800 - L899


L875: operand CANNOT BE USED WITH THE ASCII DATA REFERENCED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -875, for information.

Parent topic: L800 - L899


L876: 'object' CANNOT BE CREATED, REASON 'reason'

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message

Parent topic: L800 - L899


L877: CCSID ASCII IS NOT ALLOWED FOR THIS DATABASE OR TABLE SPACE

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -877, for information.

Parent topic: L800 - L899


L878: THE PLAN_TABLE USED FOR EXPLAIN CANNOT BE ASCII

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -878, for information.

Parent topic: L800 - L899


L879: object-name CANNOT DEFINE OBJECT MIXED/GRAPHIC WITH ENCODING SCHEME encoding-scheme

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -879, for information.

Parent topic: L800 - L899


L900: Cannot EXEC SQL because application is not connected to application server.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -900, for information.

Parent topic: L900 - L999


L901: System error caused failed execution so subsequent SQL may be successful.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -901, for information.

Parent topic: L900 - L999


L902: Pointer to the essential ctrl block (CT/RDA) has value 0, rebind required.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -902, for information.

Parent topic: L900 - L999


L904: Unavailable resource caused failed exec. type type of resource name.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -904, for information.

Parent topic: L900 - L999


L905: Fail exec due to resource limit, resource name name limit amount.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -905, for information.

Parent topic: L900 - L999


L906: Cannot execute SQL statement. Function disabled due to a prior error.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -906, for information.

Parent topic: L900 - L999


L907: Unable to determine if commit of updates made at a remote site failed.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -907, for information.

Parent topic: L900 - L999


L908: bind error using authid authority no bind or rebind are allowed.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -908, for information.

Parent topic: L900 - L999


L909: The object has been deleted.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -909, for information.

Parent topic: L900 - L999


L910: SQL statement cannot access object on which a drop/alter is pending.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -910, for information.

Parent topic: L900 - L999


L911: Rollback due to a deadlock/timeout. Reason code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -911, for information.

Parent topic: L900 - L999


L913: Failed execution cause by deadlock/timeout. Reason code code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -913, for information.

Parent topic: L900 - L999


L917: Bind package failed.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -917, for information.

Parent topic: L900 - L999


L918: SQL cannot be executed because connection has been lost.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -918, for information.

Parent topic: L900 - L999


L919: A ROLLBACK OPERATION IS REQUIRED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -919, for information.

Parent topic: L900 - L999


L922: AUTHORIZATION FAILURE: error-type ERROR. REASON reason-code

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -922, for information.

Parent topic: L900 - L999


L923: CONNECTION NOT ESTABLISHED: DB2 condition REASON reason-code, TYPE resource-type, NAME resource-name

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -923, for information.

Parent topic: L900 - L999


L924: DB2 CONNECTION INTERNAL ERROR, function-code, return-code, reason-code

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -924, for information.

Parent topic: L900 - L999


L925: Commit not valid in IMS/VS or CICS environment.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -925, for information.

Parent topic: L900 - L999


L926: Rollback not valid in IMS/VS or CICS environment.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -926, for information.

Parent topic: L900 - L999


L927: Language interface called when the connecting environment was not established.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -927, for information.

Parent topic: L900 - L999


L929: FAILURE IN A DATA CAPTURE EXIT: token

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -929, for information.

Parent topic: L900 - L999


L939: ROLLBACK REQUIRED DUE TO UNREQUESTED ROLLBACK OF A REMOTE SERVER

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -939, for information.

Parent topic: L900 - L999


L947: STATEMENT FAILED;WILL CHANGE TABLE DEFINED BUT DATA CANNOT BE PROPAGATED

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -947, for information.

Parent topic: L900 - L999


L948: DISTRIBUTED OPERATION IS INVALID

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -948, for information.

Parent topic: L900 - L999


L950: Location name is invalid or not in comm db.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -950, for information.

Parent topic: L900 - L999


L981: STATEMENT FAILED;CONNECTION DOES NOT ALLOW SQL OPERATIONS, REASON reason-code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -981, for information.

Parent topic: L900 - L999


L991: CrossAccess Data Access error ErrorNum (ConditionCode) for IMS/VSAM. Consult CrossAccess System Messages documentation.

CrossAccess experienced the specified data error while processing an SQL request against IMS/VSAM. For additional information about this error, see your CrossAccess User Documentation.

Parent topic: L900 - L999


L992: CrossAccess System error ErrorNum while accessing IMS/VSAM. Contact mainframe systems programming.

CrossAccess has experienced the specified system error while attempting to access IMS/VSAM. For additional information about this error, see your CrossAccess User Documentation.

Parent topic: L900 - L999


L1000: Exec failed. Protocol error: Reason reason (type)

Reason | Type | Description
220a DSCINVRM | 0113 MDDTYPE | A data descriptor was detected with an invalid DRDA type.
220a DSCINVRM | 0105 NOSUPPORT | A data descriptor was detected with an unsupported late descriptor field.
220a DSCINVRM | 0107 BADVALUE | A data descriptor was detected that contains more fields than the describe indicated.
220e DTAMCHRM | 0000 | The data returned is inconsistent with the descriptor supplied.
124c SYNTAXRM | 010b LENGTH | The length of a long data stream structure is too great or is not supported.
124c SYNTAXRM | 0101 HEADER | A general data stream header is incomplete.
124c SYNTAXRM | 010C LONGDSS | A long dss data stream structure is too large to fit in memory.
124c SYNTAXRM | 0104 FORMAT | An invalid data stream type has been detected.
124c SYNTAXRM | 010e CPNTNFD | An unsupported DDM code point has been detected.
Parent topic: L1000 - L1099


L1020: Exec failed with dealloc. Protocol error: reason 1218 (02)

Manager dependency error detected at other node.

Parent topic: L1000 - L1099


L1021: :Execution failed. Manager manager at level level not supported.

Managers must support certain levels.

Parent topic: L1000 - L1099


L1040: Unavail resource caused perm failure. Reason Alloc type type.

Type = Semaphore

Parent topic: L1000 - L1099


L1041: Unavail resource caused perm failure. Reason Alloc type type.

Type = Semaphore

Parent topic: L1000 - L1099


L1050: command command or SQL invalid while bind in progress.

A binding must be completed before other SQL can be issued.

Parent topic: L1000 - L1099


L1051: Bind with specified package name and consistency token not active.

A section of a package could not be bound because a BEGIN BIND has not been called.

Parent topic: L1000 - L1099


L1052: Program preparation assumptions are incorrect.

The program preparation assumptions in effect for binding a statement (i.e. BINDSQLSTT command) are incorrect.

Parent topic: L1000 - L1099


L1053: Owner authorization failure.

A command could not be executed because the user is not authorized.

Parent topic: L1000 - L1099


L1060: RDB authorization failure.

The user is not authorized to access the location specified.

Parent topic: L1000 - L1099


L1061: RDB not found.

The location name is not valid.

Parent topic: L1000 - L1099


L1070: command command not supported.

The code point indicates a request data stream structure that is not supported.

Parent topic: L1000 - L1099


L1071: object object not supported error.

The code point indicates an object data stream structure that is not supported.

Parent topic: L1000 - L1099


L1072: parameter parameter not supported error.

The code point indicates that a data stream structure parameter is not supported.

Parent topic: L1000 - L1099


L1073: value parameter value not supported error.

The code point indicates that a data stream structure parameter value is not supported.

Parent topic: L1000 - L1099


L1074: Reply message with codepoint (severity) not supported.

The reply message returned from the target is not recognized.

Parent topic: L1000 - L1099


L1080: Communication error primary (secondary).

An unmapped APPC error has occurred.

Parent topic: L1000 - L1099


L1090: Remote operation invalid for application execution environment.

An update operation or a dynamic commit or rollback was attempted at a server that was supporting an application that was in a read-only execution environment (IMS or CICS).

Parent topic: L1000 - L1099


L30000: Distribution protocol error: reason reason-code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30000, for information.

Parent topic: L30000 - L30099


L30020: Distribution protocol error cause deallocation reason: reason-code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30020, for information.

Parent topic: L30000 - L30099


L30021: Distribution protocol error: manager manager at level level not supported.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30021, for information.

Parent topic: L30000 - L30099


L30030: Not committed, SQLCODE = orig-sqlcode and SQLSTATE = orig-sqlstate.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30030, for information.

Parent topic: L30000 - L30099


L30040: Unavailable resource. Reason reason-code type rsrc-type, name rsrc-name, id pppvvrrm, RDBNAME rdbname.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30040, for information.

Parent topic: L30000 - L30099


L30041: Unavailable resource. Reason reason-code type resource-type name resource-name id pppvvrrm RDBNAME rdbname.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30041, for information.

Parent topic: L30000 - L30099


L30050: command or SQL statement invalid while bind.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30050, for information.

Parent topic: L30000 - L30099


L30051: Bind process with specified package name and consistency token not active.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30051, for information.

Parent topic: L30000 - L30099


L30052: Program preparation assumptions are incorrect.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30052, for information.

Parent topic: L30000 - L30099


L30053: Owner authorization failure.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30053, for information.

Parent topic: L30000 - L30099


L30060: RDB authorization failure.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30060, for information.

Parent topic: L30000 - L30099


L30061: RDB not found.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30061, for information.

Parent topic: L30000 - L30099


L30070: command command not supported.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30070, for information.

Parent topic: L30000 - L30099


L30071: object object not supported.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30071, for information.

Parent topic: L30000 - L30099


L30072: parameter: subcode parameter not supported.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30072, for information.

Parent topic: L30000 - L30099


L30073: parameter: subcode parameter value not supported.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30073, for information.

Parent topic: L30000 - L30099


L30074: Reply message with codepoint (SRVCOD) not supported.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30074, for information.

Parent topic: L30000 - L30099


L30080: Communication error code.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30080, for information.

Parent topic: L30000 - L30099


L30090: Remote operation invalid for application execution.

See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30090, for information.

Parent topic: L30000 - L30099


XMIG008: Table tablename does not exist.

The table name was not found in the specified source location.

Check that the correct table name and source location has been specified. Check also that the table exists at the specified source location and that the source location's system catalog is accurate.

Parent topic: XMIG - Migrate Error Messages


XMIG009: Check source location data consistency.

Migrate cannot create a foreign key because there is invalid value in the table.

This can occur because:

  • The foreign key on the source table was created after illegal data was inserted into the table.
  • The data in the primary key table was inserted with one of the following:
    • a subsetting query
    • Every Nth Row migration
    • First N Rows migration

    and, therefore, does not contains the rows to make the data in this table valid.

Select a different data subset for this table or drop the foreign key.

Parent topic: XMIG - Migrate Error Messages


XMIG010: Error saving file name.

Migrate experienced an error when saving the named file.

Verify that you have privileges to access the specified drive, that there is enough disk space available on the specified drive, and that the target directory is valid.

Parent topic: XMIG - Migrate Error Messages


XMIG011: Query window contains more than one query.

Migrate has found an end-of-statement delimiter in the Query window. Only a single SELECT statement is allowed in this window.

If there is only one query in this window, remove the end-of-statement delimiter (e.g., a quote character). If there are multiple queries in this window, split them into separate Query windows (place only one query in each window).

Parent topic: XMIG - Migrate Error Messages


XMIG012: Query must be a SELECT statement.

Migrate has found an invalid SQL statement in the Query window. Only a single SELECT statement is allowed in this window.

Remove the invalid statement from the Query window. To include additional SQL in a migration, use the Prologue and Epilogue functions. See your Migrate User's Guide for information about using Prologue and Epilogue scripts.

Parent topic: XMIG - Migrate Error Messages


XMIG013: Table already exists. Illegal with current settings.

Select Table/Query Options from the Object menu, and check the "If table already exists" settings.

Parent topic: XMIG - Migrate Error Messages


XMIG014: Field names in query may not match the field names of the destination table.

An X009 was returned when the query from a Query window was executed. The database table has been altered since the .MIG file was saved, or there is some other problem with the validity of the SELECT statement in the Query window.

Generate and test your SQL using SQLWizard and paste it into the Migrate window.

Parent topic: XMIG - Migrate Error Messages


XMIG015: No key fields specified in replication query.

A Query window used for replication must have at least one column defined as the key. Click the Update Rules button, and select True or False under the Key heading for each column returned by the SQL statement defined in the Query window.

Parent topic: XMIG - Migrate Error Messages


XMIG049: SELECT error. May not have privileges.

Migrate cannot complete this task because you do not have privileges on the specified object.

Verify that you are running with the correct SQLID for the task, and that you have the permissions necessary to access the object. See the owner of the object or your database administrator to request access to an object for which you do not have privileges.

Parent topic: XMIG - Migrate Error Messages


XMIG017: Cannot find information in system_table for 'table_name'.

SQL Migrate failed to retrieve information for the specified table from a system table when attempting to add it to the schema viewer.

Parent topic: XMIG - Migrate Error Messages


XMIG053: Filters yield no results. Filters are reset.

The filter value entered for the immediate sub-item (database, or AuthID) beneath the location level returned an empty result set. The Catalog Browser display will be refreshed using the latest valid set of filter values stored in XDB.INI.

Parent topic: XMIG - Migrate Error Messages


XMIG000: Error system error: Unknown error errorID.

Migrate attempted to display an error that was not found in the error file. This usually happens because an obsolete copy of the error file, XMIG.XRR, has somehow been copied into the directory.

Reinstall Migrate or contact Micro Focus Technical Support for a copy of the correct XMIG.XRR file.

Parent topic: XMIG - Migrate Error Messages


XMIG001: No more RAM memory available.

Migrate has experienced an internal error caused by a shortage of memory.

Close all other applications and re-execute the operation. If the error persists, check that your system has adequate swap-file space. Or, reduce the complexity of the migration to work within the available memory.

Parent topic: XMIG - Migrate Error Messages


XMIG002: No Column in table.

Migrate has experienced a serious internal error.

Do the following:

  • Save the migration specifications to a MIG file.
  • Back up your source location.
  • Record the version of XDB Server and Migrate software you are using.
  • Contact Micro Focus Technical Support.
Parent topic: XMIG - Migrate Error Messages


XMIG003: Cannot open file filename.

Migrate is not able to open the specified file.

Check that nothing is preventing Migrate from accessing this file. For example, check that this file is present, that it is not "read-only" and that the drive on which it is stored is available and operational.

Parent topic: XMIG - Migrate Error Messages


XMIG004: Syntax Error.

Migrate is unable to interpret an SQL command that has been included in your migration.

Check the syntax of the SQL statements specified by any of the following components used in the migration:

  • The Prologue script file
  • The Epilogue script file
  • The Query window(s)

Often, this error is caused by comments that are included in these components. If any of this SQL contains comments, remove them and rerun the migration.

If you are executing the migration from a MIG file, check that each QUERY statement in the file defines a valid SELECT statement.

Parent topic: XMIG - Migrate Error Messages


XMIG005: Destination location has not been defined.

Migrate is attempting to copy records, but a destination location has not been specified.

Specify a destination location and rerun the migration. If you are executing the migration from a MIG file, check that the file contains a DESTINATION statement, and that this statement specifies a valid location name.

Parent topic: XMIG - Migrate Error Messages


XMIG006: Destination table has not been defined.

Migrate is attempting to copy records, but a destination table name has not been specified.

Specify a destination table and rerun the migration. If you are executing the migration from a MIG file, check that the file contains a NAME statement in the TABLE section, and that this statement contains a valid table name.

Parent topic: XMIG - Migrate Error Messages


XMIG007: Error in internal query querystring.

Migrate is attempting to access the SYSXDB.SYSQUERY table and the table is not in the expected format. Usually this is because the table is in an older format that does not include two fields required by Migrate.

Update SYSXDB.SYSQUERY to include the required fields. Micro Focus provides a script to do this. See "SQLWizard Upgrade Procedures" in your Setup guide for details.

Parent topic: XMIG - Migrate Error Messages


N010: Session # number closed.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N011: Command canceled.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N012: Undocumented NetBIOS error.

Undocumented NetBIOS error.

Parent topic: N000 - N099


N013: Duplicate name name in local name table.

This error should not be reported to the user. Contact Micro Focus Technical Support if you receive this error.

Parent topic: N000 - N099


N014: Network name table is full.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N015: Command completed, name has active session and is now de-registered.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N017: Local session table is full.

Either the maximum number of users specified through the XDB Server Configuration utility are logged into the XDB Server, or the maximum number of NetBIOS sessions allowed by the network software has been reached. In case of the latter, check with your LAN supervisor.

Parent topic: N000 - N099


N018: Cannot open network session.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N019: Illegal session name identification number.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N020: Cannot find name called or no answer.

Either the XDB Server is not running, or you are trying to log into an XDB Server that does not exist. Access Options and change the server name. See the XDB Server Administration Guide for instructions on configuring the XDB Server. You may need to increase the timeout period on the client. Also check that NetBIOS is loaded and that your NetBIOS settings are compatible between the server and the client.

Also make sure you are using the same type of NetBIOS (for example IBM to IBM). This also may be related to not having a bridge for NetBIOS. If you are in a WAN environment, you need to have a bridge established to have connectivity to a server on another LAN.

Parent topic: N000 - N099


N021: Name name not found.

Either the XDB Server is not running, or you are trying to log into an XDB Server that does not exist. Access Options and change the server name. See the XDB Server Administration Guide for instructions on configuring the XDB Server. You may need to increase the timeout period on the client. Also check that NetBIOS is loaded and that your NetBIOS settings are compatible between the server and the client.

Also make sure you are using the same type of NetBIOS (for example IBM to IBM). This also may be related to not having a bridge for NetBIOS. If you are in a WAN environment, you need to have a bridge established to have connectivity to a server on another LAN.

Parent topic: N000 - N099


N022: Name name in use on remote adapter.

Either the specified server name (if error was received on an XDB Server) or the workstation node name already exists on the network. Try using a different node name. See your Setup guide or the XDB Server Administration Guide for information about configuring the node name for a client workstation or an XDB Server, respectively.

Parent topic: N000 - N099


N023: Name name was deleted.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N024: Session ended abnormally.

This error message will appear when the connection between the client and the server is broken. Check to see that the server is up and that there is no problem with the network.

Parent topic: N000 - N099


N025: Name conflict detected.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N026: Incompatible remote device.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N027 - N032: Undocumented NetBIOS errors.

Undocumented NetBIOS error.

Parent topic: N000 - N099


N033: Interface busy.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N034: Too many commands outstanding.

Internal NetBIOS error. Too many NetBIOS request threads were specified in the XDB Server Configuration. Either reduce the number or edit your NET.CFG for Novell and increase NetBIOS and/or Named Pipe sessions (or in the case of a LAN server increase the number of sessions in the NETBEUI_NIF section of PROTOCOL.INI).

Parent topic: N000 - N099


N035: Invalid number in NCB_LANA_NUM field.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N036: Command completed while cancel occurring.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N037: Attempt to use reserved name as a group name.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N038: Attempt to issue a command out of sequence.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N040 - N049: Unusual network conditions.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N050: NetBIOS is not loaded.

The XDB Server requires a NetBIOS-compatible network with NetBIOS running. Check with your Network Administrator. Also you must have both IBM and Novell NetWare in your CONFIG.SYS in OS/2.

WINDOWS NOTE: In Windows, you must load NetBIOS prior to entering Windows. You might also be running non-IBM or Novell NetBIOS. XDB Server must see the file NETAPI.DLL which is only associated with IBM and Novell NetBIOS. Refer to file NETAPI.TXT.

Parent topic: N000 - N099


N051 - N254: Unusual network conditions.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N364: No more structures available for Named Pipe name (ERROR_OF_STRUCTURES).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N365: Invalid parameter specified for Named Pipe call (ERROR_INVALID_PARAMETER).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N366: Named Pipes system call interrupted (ERROR_INTERRUPT).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N367: Named Pipe name is broken (ERROR_BROKEN_PIPE).

The connection has been broken between the server and the client. Check to see that the server is up and that there is no problem with the network. Check that your Named Pipes configuration matches that in the XDB Server Configuration utility.

Parent topic: N300 - N399


N368: Buffer too small for Named Pipe (ERROR_BUFFER_OVERFLOW).

The communications packet was larger than the maximum. See error N006.

Parent topic: N300 - N399


N369: Semaphore not found (ERROR_SEM_TIMEOUT).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N370: Invalid name name specified for Named Pipe (ERROR_INVALID_NAME).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N371: Invalid level parameter (ERROR_INVALID_LEVEL).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N372: Invalid name name specified for Named Pipe (ERROR_SEM_NOT_FOUND).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N373: Handle does not refer to Named Pipe (ERROR_BAD_PIPE).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N374: All available instances of Named Pipe name are in use (ERROR_PIPE_BUSY).

The maximum number of users communicating via Named Pipes is logged into the XDB Server. To correct this problem, try increasing the number of Named Pipe Receive Threads (XDB Server Configuration utility, Multi-user Options). Also, if embedding SQL in COBOL, check your code to be sure you have not used the LOGON and LOGOFF directives in subprograms. See the XDB Server Administration Guide for configuration information.

Parent topic: N300 - N399


N375: Data unavailable on non-blocking read (ERROR_NO_DATA).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N376: Named Pipe name currently not connected (ERROR_PIPE_NOT_CONNECTED).

The connection has been broken between the server and the client.

Parent topic: N300 - N399


N377: Buffer too small for Named Pipe name (ERROR_MORE_DATA).

The communications packet was larger than the maximum. Check the settings in the XDB Server Configuration utility and in Options.

Parent topic: N300 - N399


N396: Undocumented Named Pipes error number.

Internal error. If number = 53, and using Novell NetWare, you must put your server name after NPDAEMON.EXE in your CONFIG.SYS file. You may be starting an OS/2 client against a local OS/2 server (make sure the OS/2 environment variable XDBSERVE is set to LOCAL). Otherwise, contact Micro Focus Technical Support.

Parent topic: N300 - N399


N406: Bad transaction program identifier: identifier.

The tp_id parameter of the APPC verb is not valid. Either the TP_STARTED verb has failed or the tp_id returned after issuing the TP_STARTED verb was not moved into the current verb control block.

Parent topic: N400 - N449


N407: Bad conversation identifier: identifier.

The conv_id parameter used in an APPC verb is invalid. The most likely cause of this error is a failure on the remote system that is severe enough to deallocate the conversation.

Parent topic: N400 - N449


N408: Bad logical unit alias: alias.

The local LU alias referenced is not defined. A local LU name in communication manager must be defined with an alias that matches the name of the XDB Server.

Parent topic: N400 - N449


N409: Allocation failure no retry. Sense code: code.

A conversation cannot be started due to a permanent error condition requiring intervention. The sense code can be used to isolate the problem.

Parent topic: N400 - N449


N410: Allocation failure retry. Sense code: code.

A conversation cannot be started. On a system that has allocated conversations successfully in the past, the error might be recoverable without intervention. The sense code could be used to isolate the problem.

Parent topic: N400 - N449


N411: Invalid data segment.

The memory block used to send and receive data is invalid.

Parent topic: N400 - N449


N412: Bad conversation type parameter.

The conversation_type APPC verb parameter is invalid. Only basic conversations and mapped conversations are supported.

Parent topic: N400 - N449


N413: Bad synchronization level parameter.

The sync_level APPC verb parameter value is invalid. XDB Server uses NONE for DRDA level 1.

Parent topic: N400 - N449


N414: Bad security parameter.

The security APPC verb parameter value is invalid. XDB Server uses PGM security.

Parent topic: N400 - N449


N415: Bad return control parameter.

The return_control APPC verb parameter value is invalid. XDB Server uses WHEN_SESSION_ALLOCATED.

Parent topic: N400 - N449


N416: Program initialization parameter length incorrect.

The pip_data_length APPC parameter value is too large.

Parent topic: N400 - N449


N001: Illegal buffer length value.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N427: Bad return status with data parameter.

The return_status_with_data APPC verb parameter value is invalid.

Parent topic: N400 - N449


N428: Bad logical length.

The Logical record length of the data buffer in invalid. Invalid values are X''0000'', X''0001'', X''8000'', and X''8001''.

Parent topic: N400 - N449


N429: Send data not in send state.

An attempt was made to send data when the conversation was in Receive state.

Parent topic: N400 - N449


N430: Send data invalid type parameter.

The type APPC verb parameter value is invalid.

Parent topic: N400 - N449


N431: Send data confirm with synchronization none.

The type APPC verb parameter value is incorrect for type of the conversation.

Parent topic: N400 - N449


N432: Send data not logical length body.

An incomplete record was sent in Send state.

Parent topic: N400 - N449


N433: Bad type.

The type APPC verb parameter value is invalid.

Parent topic: N400 - N449


N434: Undefined transaction program name: name.

The tp_name referenced was not found. The transaction program must be defined on the host system and match the value configured using XDBGPROF.EXE. When connecting to DB2 using DRDA the tp_name is X07F6C4C2 and the tp runs in the DDF address space.

Parent topic: N400 - N449


N435: Attach manager already inactive.

The APPC attach manager is not processing receive_allocate verbs.

Parent topic: N400 - N449


N436: Allocate not pending.

A receive_allocate APPC verb was issued and timed out before an incoming allocate request was received.

Parent topic: N400 - N449


N437: Invalid process.

A process issued a receive_allocate verb that was not started by the attach manager.

Parent topic: N400 - N449


N438: Security not valid.

The partner LU rejected the UserID or password used in the allocate call. Turn on security at the client using the Configuration utility. Make sure the UserID and password are valid for the host environment.

Parent topic: N400 - N449


N439: Transaction program not available retry.

The partner LU rejected the allocate call because the transaction program could not be started immediately.

Parent topic: N400 - N449


N440: Transaction program not available no retry.

The partner LU rejected the allocate call because the transaction program could not be started.

Parent topic: N400 - N449


N441: Transaction program name not recognized.

The partner LU rejected the allocate call because the tp_name was not recognized at the partner location.

Parent topic: N400 - N449


N442: Program initialization parameter not allowed.

The partner LU rejected the allocate call because it does not support PIP data or the TP has no PIP variables defined.

Parent topic: N400 - N449


N443: Program initialization parameter not specified correctly.

The partner LU rejected the allocate call because the number of PIP variables defined by the local TP does not match the number defined for the remote TP.

Parent topic: N400 - N449


N444: Conversation type mismatch.

The partner LU rejected the allocate call because the conversation type of the local TP does not match the conversation type of the remote TP.

Parent topic: N400 - N449


N445: Synchronization level not supported.

The sync_level APPC verb parameter value is not supported.

Parent topic: N400 - N449


N446: Parameter check.

A verb was issued with an invalid parameter value.

Parent topic: N400 - N449


N447: State check.

A verb was issued in a state that was not compatible with the verb.

Parent topic: N400 - N449


N448: Allocation error.

APPC failed to allocate a conversation with a remote TP.

Parent topic: N400 - N449


N449: Dealloc abend.

The conversation has ended abnormally.

Parent topic: N400 - N449


N450: Dealloc abend program.

The conversation has ended abnormally and has been cleaned up.

Parent topic: N450 - N499


N451: Dealloc abend switched virtual circuit.

The conversation has ended abnormally and has been cleaned up.

Parent topic: N450 - N499


N452: Dealloc abend timer.

The conversation has ended abnormally and has been cleaned up.

Parent topic: N450 - N499


N002: Undocumented NetBIOS error.

Undocumented NetBIOS error.

Parent topic: N000 - N099


N463: Conversation type mixed.

The TP has issued both basic and mapped conversation verbs on the same conversation.

Parent topic: N450 - N499


N464: Transaction program is busy.

An APPC verb could not execute because Communication Manager is processing another thread.

Parent topic: N450 - N499


N465: Communication subsystem abended.

Communication Manager has ended abnormally and will have to be restarted.

Parent topic: N450 - N499


N466: Communication subsystem is not loaded.

Either Communications Manager has not been started or it is not properly configured for APPC.

Parent topic: N450 - N499


N467: Invalid verb segment.

The verb crosses a segment boundary.

Parent topic: N450 - N499


N468: Unexpected DOS error.

An OS/2 system call in Communication Manager has failed unexpectedly.

Parent topic: N450 - N499


N469: Stack too small.

APPC has determined that the TP stack size is too small.

Parent topic: N450 - N499


N476: Security Location Not Configured.

First, install the Password Expiration Manager (PEM) on the mainframe (see the host installation and configuration instructions). Then, configure access to the remote host PEM software using the Gateway Profile utility. Select location type PEM (APPC) or PEM (TCP).

Parent topic: N450 - N499


N477: Invalid Host Authorization.

The AUTHID used to access the host database is not valid. Check your AUTHID and try again.

Parent topic: N450 - N499


N478: Invalid Host Password.

The AUTHID is valid, but the password is not. Check your password and try again.

Parent topic: N450 - N499


N479: Host Authorization Has Expired.

Your password has expired. See your host system administrator for assistance.

Parent topic: N450 - N499


N480: Host Authorization Has Been Revoked.

The AUTHID used to access the host database has been revoked. See your host system administrator for assistance.

Parent topic: N450 - N499


N486: Nucleus loopback error.

AS multiple database support problem. Contact Micro Focus Technical Support.

Parent topic: N450 - N499


N487: AS target not supported.

AS multiple database support problem.

Parent topic: N450 - N499


N488: An AS target module failed to load.

AS multiple database support problem.

Parent topic: N450 - N499


N489: An AS target module function address was not found.

AS multiple database support problem.

Parent topic: N450 - N499


N496: Protocol memory allocation failure.

Protocol module problem. Contact Micro Focus Technical Support.

Parent topic: N450 - N499


N497: Transaction identifier is invalid.

Protocol module problem. Contact Micro Focus Technical Support.

Parent topic: N450 - N499


N498: Connection identifier is invalid.

Protocol module problem. Contact Micro Focus Technical Support.

Parent topic: N450 - N499


N499: Unsupported protocol.

Protocol module problem.

Parent topic: N450 - N499


N500: A protocol module failed to load.

Protocol module problem.

Parent topic: N500 - N599


N501: A protocol module function address was not found.

Protocol module problem.

Parent topic: N500 - N599


N506: No available connections.

In memory module problem.

Parent topic: N500 - N599


N507: Open semaphore failure.

In memory module problem.

Parent topic: N500 - N599


N508: Create semaphore failure.

In memory module problem.

Parent topic: N500 - N599


N509: Shared memory failure.

In memory module problem.

Parent topic: N500 - N599


N003: Invalid network command.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N004: Undocumented NetBIOS error.

Undocumented NetBIOS error.

Parent topic: N000 - N099


N005: NetBIOS command timed out.

If this error was received while trying to log into the server, then the XDB Server name could not be found. Otherwise, an internal NetBIOS error occurred. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N006: Incomplete network message.

Communications packet was larger than the maximum Receive Buffer size specified by user, either at the server or at the client. If the error was received at the server, check the settings in the XDB Server Configuration utility; if received at the client, check the settings in Options.

Parent topic: N000 - N099


N008: Illegal local session number number.

Either the NetBIOS connection to the server was broken (an N024 error preceded this or was ignored) or the connection was never established. For example, this error will occur when a COBOL program attempts and fails to successfully log into the server.

Parent topic: N000 - N099


N009: Resource is not available.

Internal NetBIOS error. Contact Micro Focus Technical Support.

Parent topic: N000 - N099


N300: TCP Error errmsgfunction( ) = errorcode

The indicated TCP/IP error occurred. The list below shows possible error codes and their associated error messages.

Eight-digit error codes, including the following, indicate problems with DB2 or VTAM.

ErrorCode Description
00000008 Cannot connect to application.

On the machine where XDB Link is installed, start the Gateway Profile Utility and verify that the Remote APPLID setting matches the APPLID of the remote application. (If you are using an earlier version of the Gateway Profile Utility, this setting might appear as Remote Host instead of Remote APPLID.)

00040005 Bad user id and/or password.

Verify that the user ID is correct and valid (i.e., not revoked). Verify that the password is correct and current (i.e., not expired).

Note: If the Password Expiration Maintenance Utility (PEM) is installed on the host, you can run the PEM utility on your workstation to quickly determine why the user ID and/or password was rejected (e.g., password expired, user ID revoked, user ID invalid). If the problem stems from an expired password, you can use PEM to update that password. See the "PEM Utility" chapter in the XDB Link User's Guide for information about using PEM to diagnose and correct user ID and password problems.

Five-digit error codes starting with 110 indicate problems with XDB Link.

ErrorCode Description
11004 Cannot connect to host.

Check the following:

  1. Verify that the TCP/IP connection on the host system is up and running.
  2. On the machine where the XDB Link is installed:
    • Make sure the HOSTS file contains an entry that defines the host system's IP address, and verify that this IP address is correct. Also make sure the line containing this entry has a hard return at the end.

      OR

      If using DHCP, make sure the host system's IP address is registered with a DNS server.

    • Make sure the SERVICES file contains an entry that defines the port used by the Host Option on the host, and verify that the port number is correct. Also make sure the line containing this entry has a hard return at the end.
  3. Start the Gateway Profile Utility and verify that:
    • The Remote HOST setting matches the name assigned to the host's IP address in the HOSTS file or the DNS server.
    • The Port setting matches the name assigned to the Host Option in the SERVICES file.
11002 Cannot connect to host.

Check the following:

  1. Verify that the TCP/IP connection on the host system is up and running.
  2. On the machine where the XDB Link is installed:
    • Make sure the HOSTS file contains an entry that defines the host system's IP address, and verify that this IP address is correct. Also make sure the line containing this entry has a hard return at the end.

      OR

      If using DHCP, make sure the host system's IP address is registered with a DNS server.

    • Make sure the SERVICES file contains an entry that defines the port used by the Host Option on the host, and verify that the port number is correct. Also make sure the line containing this entry has a hard return at the end.
  3. Start the Gateway Profile Utility and verify that:
    • The Remote HOST setting matches the name assigned to the host's IP address in the HOSTS file or the DNS server.
    • The Port setting matches the name assigned to the Host Option in the SERVICES file.

The following error codes indicate problems with the client machine.

Note: Five-digit error codes (e.g., 10035) are displayed if you are running under a 32-bit operating system.

Errors marked with an asterisk (*) are ones that can occur if your XDBNET.INI file does not specify a valid TCP/IP address for the server you are attempting to access. When these errors occur, open the XDBNET.INI file and verify that the following values are correct for your server:

  • Server name
  • IPAddress
  • TCPPort
16-bit ErrorCode | 32-bit ErrorCode | Description
35 | 10035 | Operation would block.
36 | 10036 | Operation now in progress.
37 | 10037 | Operation already in progress.
38 | 10038 | Socket operation on non-socket.
39 | 10039 | Destination address required.
40 | 10040 | Message too long.
41 | 10041 | Protocol wrong type for socket.
42 | 10042 | Protocol not available.
43 | 10043 | Protocol not supported.
44 | 10044 | Socket type not supported.
45 | 10045 | Operation not supported on socket.
46 | 10046 | Protocol family not supported.
47 | 10047 | Address family not supported by protocol family.
48 | 10048 | Address already in use.
49 | 10049 | Can't assign requested address.
50 | 10050 | Network is down.
51 | 10051 | Network is unreachable.
52 | 10052 | Network dropped connection on reset.
53 | 10053 | Software caused connection abort.
54 | 10054 | Connection reset by peer. *
55 | 10055 | No buffer space available.
56 | 10056 | Socket is already connected.
57 | 10057 | Socket is not connected.
58 | 10058 | Can't send after socket shutdown.
59 | 10059 | Too many references can't splice.
60 | 10060 | Connection timed out. *
61 | 10061 | Connection refused. *
62 | 10062 | Too many levels of symbolic links.
63 | 10063 | File name too long.
64 | 10064 | Host is down. *
65 | 10065 | No route to host. *
66 | 10066 | Directory not empty.
93 | 10093 | Unknown Error. *
Parent topic: N300 - N399


N301: SPX Error: errmsgfunction() = errcode

The indicated IPX/SPX error occurred. The list below shows possible error codes and their associated error messages:

errcode | errmsg
1 | Illegal protocol address.
2 | Illegal protocol option.
3 | Access permission denied.
4 | Bad transport endpoint.
5 | Unable to allocate address.
6 | Out of state.
7 | Invalid sequence number.
8 | System error (system error code).
9 | Even requires attention (event name).
10 | Invalid data size.
11 | Buffer overflow.
12 | Unable to accept data.
13 | Data not available.
14 | No disconnect indication exists.
15 | No unit data error indication.
16 | Invalid flag specified.
17 | No orderly release indication.
18 | Not supported.
19 | State change.
20 | Invalid structure type.
21 | Invalid transport provider name.
22 | Bad value.
23 | Address in use.

For example, if an SPX connection attempted to use an incorrect address, the following error message would be displayed:

N301: SPX Error: Illegal protocol address. bind() = 1
Parent topic: N300 - N399


N302: NETBIOS Error errmsgfunction = errorcode

The specified NETBIOS error has occurred. For example, if you attempt to connect to a server using an invalid server name, or if the specified server is not up and running, the following message is displayed:

N302: NETBIOS Error: Cannot find name called or no answer.

The following describes common NETBIOS errors that can occur.

Code | Description
1 | Invalid buffer length.
2 | Buffer full.
3 | Invalid command.
5 | Command timed out.
6 | Incomplete received message.
7 | Illegal buffer address.
8 | Invalid local session number.
9 | No resource available.
10 | Session has been closed.
11 | Command was cancelled.
13 | Duplicate name in local name table.
14 | Name table full.
15 | No deletions allowed, name has active sessions.
17 | Local session table full.
18 | Remote session table full.
19 | Illegal name number.
20 | Cannot find name called or no answer. Check that you have specified the correct server in Options and that the server is up and running. See also N020: Cannot find name called or no answer. for other possible causes.
21 | Cannot put wild card(*) in NCB name.
22 | Name in use on remote adapter.
23 | Name deleted.
24 | Session ended abnormally.
25 | Name conflict detected.
33 | Interface busy, IRET before retrying.
34 | Too many commands outstanding, retry later.
35 | Invalid name number.
36 | Command completed while cancel occurring.
37 | Reserved name specified.
38 | Command not valid to cancel.
48 | Name defined by anther local process.
52 | Environment undefined. RESET required.
53 | Required OS resources exhausted.
54 | Max number of applications exceeded.
55 | No saps available for netbios.
56 | Requested resources are not available.
57 | Invalid ncb address or length > segment.
59 | Invalid NCB DDID.
61 | Lock of user area failed.
63 | NETBIOS not loaded.
64 | System error.
255 | Asynchronous command is not yet finished.
Parent topic: N300 - N399


N357: Invalid Named Pipe function call (ERROR_INVALID_FUNCTION).

Internal Named Pipes Error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N358: Invalid path path specified for Named Pipe (ERROR_FILE_NOT_FOUND).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N359: Cannot find Named Pipe name (ERROR_PATH_NOT_FOUND).

Make sure that the XDB Server configuration (XDBSRVCO.EXE or XDBSRVBT.EXE) setting for the number of Named Pipes threads is greater than zero, and that the Named Pipes protocol is turned on.

If you are trying to run locally, add the line SET XDBSERVE=LOCAL to your CONFIG.SYS file and reboot.

1. If running local and not starting the engine explicitly, then retry the programs. Under conditions of low memory it may take the XDB Server longer to initialize than the predefined wait period before a client may access the server.

2. If the Named Pipe displayed memory starts with \\, you are trying to recess a remote XDB Server via Named Pipes. Also, you may need to put your server name after NPDAEMON.EXE in your CONFIG.SYS file. The server cannot be found.

If you are operating under Banyan VINES, bring up the engine first by typing xdbserve, and then type xdb. Also see error N020.

Parent topic: N300 - N399


N360: Access denied to Named Pipe name (ERROR_ACCESS_DENIED).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N361: Invalid handle to Named Pipe specified (ERROR_INVALID_HANDLE).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N362: Not enough memory for Named Pipe operation (ERROR_NOT_ENOUGH_MEMORY).

Close or remove some programs from your machine or acquire more RAM.

Parent topic: N300 - N399


N363: Invalid format specified for Named Pipe (ERROR_BAD_FORMAT).

Internal Named Pipes error. Contact Micro Focus Technical Support.

Parent topic: N300 - N399


N417: Use of SNASVCMG or CPSVCMG for mode not allowed.

The mode names SNASVCMG and CPSVCMG are reserved and should not be used when allocating a conversation.

Parent topic: N400 - N449


N418: Unknown partner mode/alias:"<".

The partner LU alias referenced is not defined. A partner LU in communication manager must have an alias that matches the PLU alias name entered when defining a location using XDBGPROF.EXE.

Parent topic: N400 - N449


N419: Dealloc bad type parameter.

The type APPC verb parameter value is invalid.

Parent topic: N400 - N449


N420: Dealloc flush bad state.

The dealloc APPC verb type parameter value is incorrect for the state of the conversation.

Parent topic: N400 - N449


N421: Dealloc confirm bad state.

The dealloc APPC verb type parameter value is incorrect for the state of the conversation.

Parent topic: N400 - N449


N422: Dealloc not logical length body.

An incomplete logical record was sent when the dealloc was issued.

Parent topic: N400 - N449


N423: Dealloc log logical length wrong.

The log_data_length APPC verb parameter value does not match the LL field.

Parent topic: N400 - N449


N424: Receive and wait bad state.

The conversation is not in Receive or Send state.

Parent topic: N400 - N449


N425: Receive and wait not logical length body.

An incomplete logical record was sent in Send state when the Receive was issued.

Parent topic: N400 - N449


N426: Receive and wait bad fill parameter.

The fill APPC verb parameter value is invalid.

Parent topic: N400 - N449


N453: Dealloc normal.

The conversation has ended normally.

Parent topic: N450 - N499


N454: Program error no truncation.

The remote TP has issued a send_error APPC verb.

Parent topic: N450 - N499


N455: Program error truncation.

The remote TP has issued a send_error APPC verb and some of the data received locally was truncated.

Parent topic: N450 - N499


N456: Program error purging.

The remote TP has issued a send_error APPC verb and some of the data sent to the remote TP was truncated.

Parent topic: N450 - N499


N457: Conversation failure retry.

A temporary failure has ended the conversation.

Parent topic: N450 - N499


N458: Conversation failure no retry.

A permanent failure has ended the conversation.

Parent topic: N450 - N499


N459: Switch virtual circuit error no truncation.

The remote TP has issued a send_error APPC verb.

Parent topic: N450 - N499


N460: Switch virtual circuit error truncation.

The remote TP has issued a send_error APPC verb and some of the data received locally was truncated.

Parent topic: N450 - N499


N461: Switch virtual circuit error purging.

The remote TP has issued a send_error APPC verb and some of the data sent to the remote TP was truncated.

Parent topic: N450 - N499


N462: Unsuccessful.

An APPC verb could not execute.

Parent topic: N450 - N499


N510: Open process failure.

In memory module problem.

Parent topic: N500 - N599


N511: Cannot communicate with server.

The client application cannot establish communications with the specified server. An "accept connection" failure has occurred.

Check to see that the server is running.

If you receive this error when trying to start SQLWizard, it is most likely because your single-workstation server is not loaded. Start the XDB Server, then restart SQLWizard.

Note:

For non-DB2 databases, put the XDB Server icon in your StartUp Program Group or Folder to ensure that your single-workstation server is already running when you start SQLWizard.

Parent topic: N500 - N599


N512: Connection is closed.

In memory module problem.

Parent topic: N500 - N599


PIC008 Sign character found on both sides of the decimal.

The Numeric Format defined in Options contains a sign character (e.g., +) on both sides of the decimal character (e.g., +$99.99+r is invalid). This character can be placed on the left or the right of the decimal point, but not both.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC009 Error in substitution portion of picture definition.

The $=, .=, or ,= clause in the Numeric Format defined in Options is invalid. It may, for example, contain an invalid character or be missing the required delimiters.

Correct the substitution clause in the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC010 Illegal decimal found in picture.

The Numeric Format defined in Options contains an invalid decimal sign character. Only a period can be used in the picture portion of a Numeric Format. For example: 999.99 .=',' is valid; 999,99 .=',' is not.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC011 Illegal rounding character found in picture.

The Numeric Format defined in Options contains an invalid rounding character. Only an "r" can be used to indicate rounding, and this character must appear at the end of the picture string.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC012 Illegal dollar sign found in picture.

The Numeric Format defined in Options contains an invalid money character. Only a dollar sign can be used in the picture portion of the format. For example: $$9.99 .='>=' is valid; >=>=9,99 .='>=' is not.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC013 Closing single quote not found in substitution string.

The substitution character string defined in the $=, .=, or ,= clause in the Numeric Format defined in Options does not end with a single quote. For example: $999.99 .$='fl' is valid; $999,99 .='fl is not.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC014 Value too wide for picture field.

The numeric value being entered or displayed is larger than the Numeric Format picture defined in Options.

In Options, increase the Numeric Format to accommodate the value being displayed or entered. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC015 Error in time/date picture definition.

The Time Format or the Date Format in Options is incorrectly specified.

Correct the invalid format or use one of the standard time and date formats provided in Options. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC016: Error trying to identify the picture format type.

A serious internal error has occurred because the active program received an illegal data type. Contact Micro Focus Technical Support.

Parent topic: PIC - Picture Error Messages


PIC017 Invalid year value.

The date value being entered or displayed is inconsistent with the Date Format specified in Options.

Check the Date Format defined in Options. Change the value to match the picture, or change the Date Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC018 Invalid separator in value.

The numeric or money value being entered or displayed contains a separator character (e.g., the comma in 1,000) that is inconsistent with the Numeric Format currently specified in Options.

Check the Numeric Format defined in Options. Either change the value to match the picture, or change the Numeric Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC019 Invalid character in value.

A value that is being entered or displayed contains a character that is inconsistent with a picture currently specified in Options.

Check the picture formats defined in Options. Either change the values to match the pictures, or change the picture formats in Options to accommodate the values. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC020 Money value error.

The money value being entered or displayed is inconsistent with the Money Format currently specified in Options.

Check the Money Format defined in Options. Either change the value to match the picture, or change the Money Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC021 Numeric value error.

The numeric value being entered or displayed is inconsistent with the Numeric Format currently specified in Options.

Check the Numeric Format defined in Options. Either change the value to match this format, or change the Numeric Format to accommodate your values. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC022 Illegal Integer value.

The integer value that is being entered or displayed is out of range. It contains more digits than specified by the NumericFormat in Options.

Check the Numeric Format defined in Options. Either change the value to match this format, or change the Numeric Format to accommodate the size of your values. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC023 Illegal Time value.

The time value that is being entered or displayed is inconsistent with the Time Format currently specified in Options.

Check the Time Format defined in Options. Either change the value to match the picture, or change the Time Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC024 Illegal Date value.

The date value that is being entered or displayed is inconsistent with the Date Format currently specified in Options.

Check the Date Format defined in Options. Either change the value to match the picture, or change the Date Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC025 Scale is bigger than precision.

The Float Decimal Places value (i.e., scale) specified in Options is larger than the total number of digits allowed for a float value on your system (i.e., precision).

Reduce the value in Float Decimal Places to a value accepted by your system.

Parent topic: PIC - Picture Error Messages


PIC026 Invalid separator in time value.

The time value being entered or displayed contains a separator character (e.g., the colon in 4:00) that is inconsistent with the Time Format currently specified in Options.

Check the Time Format defined in Options. Either change the value to match the picture, or change the Time Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC027 Invalid separator in date value.

The date value being entered or displayed contains a separator character (e.g., the dash in 03-30-86) that is inconsistent with the Date Format currently specified in Options.

Check the Date Format defined in Options. Either change the value to match the picture, or change the Date Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC028 Invalid separator in timestamp value.

The timestamp being entered or displayed contains a separator character (e.g., the colon 04:00) that is inconsistent with the Time Format currently specified in Options.

Check the Time Format defined in Options. Either change the timestamp to match the picture, or change the Time Format to accommodate the value. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC000: Error system error: Unknown error errorID.

The program attempted to display an error that was not found in this error file.

Check to make sure that the error file, XPIC.XRR, is the proper error file for this version of Options.

Parent topic: PIC - Picture Error Messages


PIC001 Syntax error in mask definition.

The Numeric Format specified in the Options is invalid.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC002 Grouping character found twice or in illegal position.

The Numeric Format defined in Options contains two grouping characters (e.g., two commas) or the grouping character is in the wrong position (e.g., after the decimal point).

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC003 No grouping length.

A serious internal error has occurred in Option's picture parser. Contact Micro Focus Technical Support.

Parent topic: PIC - Picture Error Messages


PIC004 Decimal character found twice or in illegal position.

The Numeric Format defined in Options contains two decimal characters (e.g., two decimal points) or the decimal character is in the wrong position (e.g., 99.99,).

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC005 Rounding character in illegal position.

The Numeric Format defined in Options contains an incorrectly placed rounding character (r). This character, when used, must be the very last character in the picture string (e.g., xxx,9.99+r).

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


PIC006 Illegal character in picture specification.

A character, other than those allowed, is included in the Date, Time or NumericFormat specified in Options.

Correct the invalid format in Options. See the Options User's Guide for characters allowed by each picture type.

Parent topic: PIC - Picture Error Messages


PIC007 $ character found on both sides of decimal.

The Numeric Format defined in Options contains a money character (e.g., $) on both sides of the decimal character (e.g., $$$$.$$ is invalid). This character can appear only on the left side of the decimal.

Correct the Numeric Format. See the Options User's Guide for the proper syntax.

Parent topic: PIC - Picture Error Messages


SQL0103S error creating output file: file

Cannot create the output file file. Likely reasons are that the file already exists or there is a permissions/sharing problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0104S error writing DBRM file

Cannot write to the DBRM file. Likely reasons are that it does not exist or there is a permissions/sharing problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0105S error reading input file

Cannot read the input file. Likely reasons are that it does not exist or there is a permissions/sharing problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0106S error writing output file

Cannot write to the output file. Likely reasons are that it does not exist or there is a permissions/sharing problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0107S scope mismatch

The scope of a variable is ambiguous. Check to make sure only one variable is visible to a section with the same name.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0108S end of file before end of quoted string

A closing quote is missing.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0109S end of file before end of comment

A comment was not closed before the end of the file.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0110S token buffer overflow

The internal buffer for the lexical analyzer is full due to an object being too large.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0111S statement buffer overflow

The internal buffer for statement parsing is full due to a statement being too large to parse.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0112S parser stack overflow

The internal buffer for generic parsing is full due to an object being too large to parse.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0113S include file file not found

Cannot find the include file file in the current program path.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0114S host variable error in sqlda

Sqlda is reporting either too many or too few host variables.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0115S illegal host variable marker '?'

The '?' character cannot be used as a host variable marker.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0116S invalid directives: directive

The directives currently being used are invalid.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0117S same name specified for the input file and the output file

The same name is being used for both the input and output files. Modify the name of one of them.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0118S host variable hostvar not found

The preprocessor could not find the host variable hostvar.

Check to make sure that the host variable is declared in the program and that the picture or usage is correct.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0119S declaration stack overflow

The internal buffer for declaration parsing is full due to a declaration is too large to parse.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0120S SQL syntax error, last token read: token

The SQL Option generic syntax parser found an error in the SQL statement.

Verify that the SQL statement is valid. Make any corrections that are required and then recompile. If the error persists and the statement is valid, contact Micro Focus Technical Support.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0121S cursor cursor not declared

An OPEN, FETCH or CLOSE statement references a cursor name that was not DECLAREd.

The DECLARE CURSOR statement must be coded before an OPEN, FETCH or CLOSE SQL statement. If defined, move the DECLARE CURSOR statement before the statement in error. Otherwise, check to make sure the cursor name used in the DECLARE CURSOR statement matches the cursor name used in the SQL statement in error.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0122S cursor cursor already declared

The current cursor cursor has already been declared. Make sure the cursor name is valid and remove or rename it.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0123S invalid host variable: hostvar

Host variables must be valid PL/I identifiers

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0124S invalid null indicator variable: hostvar

A null indicator variable must be a 2-byte integer.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0125S statement statement not declared

The current statement statement has not been declared.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0126S statement statement already declared

The current statement statement has already been declared.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0127S host variable hostvar ambiguous

The same variable name is being used twice in the same scope.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0001S DECLARE syntax error, last token read: token

A syntax error has occurred in the DECLARE section. Check at or near token to find the problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0002S identifier too long

The current identifier is too long to be a valid identifier.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0003S engine check error: message

Error message message is being returned from the engine. Refer to message to determine the problem and its resolution.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0004S identifier token not defined

An identifier is being used that is not defined.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0005S host variable used without colon

The host variable is defined without a colon in the SQL statement.

No action is required, as this is a warning. For compatibility across multiple SQL syntaxes, a colon should always precede host variables. Currently, SQL Option and DB2 support the use of host variables without a colon, but this feature may be revoked at some time in the future.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0006S UNION of SELECT INTO is deprecated feature with undefined results

A UNION SQL statement that contains a SELECT INTO has been detected. This feature is no longer supported and the results are undefined.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0101S error creating DBRM file: file

Cannot create the DBRM file file. Likely reasons are that the file already exists or there is a permissions/sharing problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


SQL0102S error opening input file: file

Cannot open the input file file. Likely reasons are that the file does not exist or there is a permissions/sharing problem.

Parent topic: SQL - SQL PL/I Precompiler Error Messages


WCRT010: The location name does not exist.

A location with the name location-name was not found in the SYSXDB.SYSLOCALS catalog table.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT011: The synonym/alias name does not exist in the database.

A synonym/alias with the name name was not found in the system catalog.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT012: Incomplete location specification. No object specified.

A location was incompletely defined. Enter a valid value for the missing item.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT013: No name specified for field # fieldnum.

A field was specified without a name. Specify a valid name for the field.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT014: No data type specified for field # fieldnum.

A field was specified without a data type. Choose a data type from the drop-down list provided in the Data Type entry field.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT015: No length specified for field # fieldnum.

A field was specified without a length. Specify a valid length for the field. Some data types (e.g. Smallint, Integer, Float, Date, Time, etc.) have a fixed length and do not require a length to be entered. Others (e.g. Decimal, Char, Varchar, Graphic, & Vargraphic) require a length to be specified.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT016: No column with a matching type found.

An attempt was made to move a foreign key column to a new position within the Foreign Key Cols -> Referenced Key Cols list. However, no referenced column with a matching data type and length was found in the direction you tried to move. Remember that foreign key columns and referenced key columns must match in data type and length.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT017: No foreign key name specified.

Specify a valid foreign key name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT018: No index name specified.

Specify a valid index name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT019: No alias name specified.

Specify a valid alias name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT020: No synonym name specified.

Specify a valid synonym name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT021: Cannot undo the Drop designation for this primary key index due to the existence of another primary key specification.

An attempt was made to remove a Drop designation for a primary key index. However, another primary key index has been specified for this table. Since allowing this operation would yield more than one primary key for the table, and only one is allowed per table, this is illegal.

In order to allow this operation to succeed, you must first either delete (i.e. drop) the other (and newly specified) primary key index, or alter the type of the other primary key index from being a primary key to either a regular index or unique index.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT022: No referenced table specified for the relationship.

The relationship specification is incomplete. Specify a referenced table to complete the specification. Be sure that this referenced table contains a primary key.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT023: object name name is already defined for this table.

An object of type object-type with the name name has already been specified for this table. Choose another name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT024: Location specified in Alias Name.

There is no need to qualify the alias name with a location, as the location may be chosen from the list. Please enter a one-part (i.e. alias name alone) or a two-part name (i.e. sqlid.alias-name), and specify the locations from the list.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT025: No target location(s) specified for the Alias.

When creating an alias you must specify at least one location where it is to be created. Choose locations from the Target Locations Not Selected list to move over to the Target Locations Selected list.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT026: Index creator. index-name already exists in location location.

All indexes must have unique names within a location. The index name specified already exists in the SYSIBM.SYSINDEXES catalog table for the particular location. Choose another name.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT027: Table/View/Synonym/Alias creator. name already exists in location location.

All tables/views/synonyms/aliases must have unique names within a location. The name specified already exists in the system catalog tables for that particular location. Choose another name.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT028: Location name already exists.

XDB Server locations must be given unique names. The location name specified already exists in the SYSXDB.SYSLOCALS catalog table. Choose another name.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT029: Cannot alter/drop table with over number columns using this method.

This error should not occur under normal circumstances. If you receive this error, please contact Micro Focus Technical Support.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT030: The directory directory-name does not exist.

The directory directory-name does not exist. You have to create this directory before you proceed with the creation of the location.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT031: Log cannot be forwarded to a directory-name. It appears to be used by a different location.

Specify a directory that is not already in use by another location and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT032: Invalid format for directory directory-name.

Specify a valid directory name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT033: Illegal null permission for field Field specified.

Global temporary tables cannot contain "unique" or "with default" fields.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT034: You cannot alter a Global Temporary Table.

You have tried to alter a global temporary table. This is not allowed.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT035: You can not alter a table that contains a distinct type

An attempt was made to alter a table with a distinct data type. This is not allowed.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT000: Error system error: Unknown error error id.

SQLWizard attempted to display an error that was not found in the XCRT.XRR error file.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT001: Illegal identifier identifier specified for object Name. Last symbol read was symbol.

An invalid name was specified for the object of type object-type. SQLWizard was only able to validate the name up to the symbol symbol.

Legal identifiers must begin with a letter (A-z), and may include letters (including standard IBM code page extended characters), digits, and the special characters #%&{}$.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT004: The data type and/or length of column col1 does not match that of primary key column col2.

When specifying the foreign key columns of a relationship, you must choose those that match both in data type and length to that of its corresponding primary key column. Check the data type and length of both the foreign key and primary key column to be sure they match.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT005: No columns specified for the object.

Make sure you choose columns for the index or relationship definition. If you are specifying an index, make sure you specify column names in the Index Columns list. If you are specifying a relationship, make sure a foreign key column is specified for each primary key column in the list.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT006: Identifier identifier exceeds its maximum length of length for object-type name.

The identifier specified exceeded its maximum limit of length for an object of type object-type. Enter a shorter name and try again.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT007: Incomplete table specification. No object specified.

A table was incompletely defined. Enter a valid value for the missing item.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT008: Referenced table table does not contain a primary key.

When choosing a referenced table for a relationship, be sure to choose a table that contains a primary key.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT009: The index index does not exist for the table table.

An index with the name index-name was not found in the system catalog for the table table-name.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WCRT036: Altering a table that contains a BLOB column is not supported

An attempt was made to alter a table with a BLOB column. This is not supported.

Parent topic: WCRT - SQL Wizard Create/Alter Table Error Messages


WSQL009: Query result cannot be edited.

The current query result has been evaluated as a non-editable result, and therefore the system cannot switch to edit mode. Reasons for a query to be evaluated as non-editable are that it is/contains a: a) Join b) Union c) GROUP BY clause d) HAVING clause e) Expression or it accesses a read-only view.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL010: Error executing menu.

An error occurred when trying to process the last menu command.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL011: Printing failed.

An error occurred when attempting to print. Check the print manager for additional information.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL012: Cannot list windows.

The system was unable to list the currently open windows.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL013: Too many windows.

The system cannot open another window. Try closing down some of the currently open child windows.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL014: Window does not have METRICS data.

Unable to process window commands.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL015: Incomplete line in string.

Incomplete line in string.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL016: No default value in string.

No default value in string.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL017: Prompted number number is out of range, should be 1-100.

An SQL statement references a variable &n where n is not between 1 and 100. Modify the SQL statement to change &n so that n is within the acceptable range, or change &n to a host variable in the form :hv.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL018: Error adding item to prompted list.

An error occurred attempting to add an item to the prompted query design list. Contact Micro Focus Technical Support.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL019: Cannot find the prompted number number.

An error occurred trying to specify or rebuild a prompted query design. The table SYSXDB.SYSPROMPTQUERY may be damaged or has been incorrectly edited.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL020: Invalid characters in string.

There are illegal characters in the string shown. Correct and try again.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL021: Cannot find query.

The system was unable to find the query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. You may have entered the name incorrectly. The query may have been deleted from the query catalog, or there may be an error reading the catalog tables.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL022: Argument is NULL.

A required argument is NULL. Correct and try again.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL023: Cannot open temporary file.

The system was unable to open a temporary file. Check whether you have privileges to read and write on the temporary path, and that there is enough disk space to write the file.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL024: Cannot create temporary file.

The system was unable to write a temporary file. Check whether you have privileges to read and write on the temporary path, and that there is enough disk space to write the file.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL025: You must have a valid connection to use all of SQLWizard's options.

If you cannot connect to the database engine, you will not be able to access SQLWizard. This error sometimes occurs when you have not connected properly to a remote database server.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL026: Invalid entry in field fieldname.

An attempt was made to enter invalid data in the named field. Modify the data to match the data type.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL027: Window does not have METRICS data.

Unable to process window commands.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL028: Cannot open query.

The system was unable to open a query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. The query may have been partially deleted from the query catalog, or there may be an error reading the catalog tables.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL029: Error running batch SQL.

The system encountered an error in trying to process a batch SQL script.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL030: No such Query.

The system was unable to find the query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. You may have entered the name incorrectly. The query may have been deleted from the query catalog, or there may be an error reading the catalog tables.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL031: No column needs order by.

There are no unsorted columns in the query. Use the Query|Sort option if you want to remove some columns from the query. You cannot sort by a column that is not selected if you are in DB2 mode (this is a restriction of DB2).

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL032: Cannot create toolbar.

The system failed in an attempt to create the toolbar. Check whether resources are low.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL033: Error saving file filename.

An error occurred when trying to save the named file. Make certain the path is valid, the file name is valid, that there is enough space for the file, or that the file does not already exist and is locked by another application.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL034: Error seeking file.

A file could not be found. A seek error occurred when trying to locate it. Make certain the file specification is correct, and that the file exists.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL045: Name name is invalid.

The name shown is not a valid name based on the current SQL mode, or the system requirements. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL046: Cannot save query. Please check if disk is full.

Something is preventing SQLWizard from saving this query.

Check that nothing is preventing SQLWizard from accessing the query tables (the sysquery.tab and syspromp.tab files). For example, check that the drive on which they are stored is available and operational. Check also that the files are not "read-only."

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL047: The query has been corrupted.

SQLWizard cannot open the selected query because it contains corrupt data. This might happen if the SYSPROMPTQUERY table was edited directly.

Recreate and save the query.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL049: SELECT error. May not have privileges.

SQLWizard cannot complete this task because you do not have privileges to the specified object.

Verify that you are running with the correct SQLID for the task and that you have the permissions necessary to access the object. If you need access to an object for which you do not have privileges, see the owner of the object or your database administrator.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL050: Cannot edit tables with renamed columns.

You are attempting to edit a table that contains a renamed column. This is not allowed. This error would occur, for example, if you attempted to edit the result of the following query (which changes the name of the e_no column to xemp):

SELECT xemp = e_no FROM tutorial.employee;

When you edit the result, SQLWizard attempts to update xemp, which doesn't exist in the table.

To edit the result, reissue the query without renaming the column.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL051: Batch error in command number number.

SQLWizard has encountered an error while processing a batch SQL script.

Examine the script file and correct the error in the specified command.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL052: End of statement delimiter not found.

SQLWizard could not find an end of statement delimiter.

Check that all your SQL statements end with the proper end-of-statement character (a semi-colon). Check also that all strings in your SQL stream are delimited with matching quote characters. This error can occur if an end-of-string quote is missing or if the end-of-string delimiter doesn't match the string's start-of-string delimiter. (For example, if you typed a double quote at the beginning of the string and a single quote at the end, like this: "string value' ).

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL053: Filters yield no results. Filters are reset.

The filter value entered for the immediate sub-item (database, or AuthID) beneath the location level returns an empty result set. The Catalog Browser display will be refreshed using the latest valid set of filter values stored in XDB.INI.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL054: Cannot display result set containing a LOB field.

The result set contains a Large Object (LOB), which is not displayable.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL055: Invalid value, terminator_character, specified for TERMINATOR.

The SQL terminator character specified in a --#SET TERMINATOR statement is invalid. The following characters are not allowed to be a SQL terminator: blank, comma, double quote, left parenthesis, right parenthesis, single quote, and underscore.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL001: XDB Engine is not loaded.

The system was unable to load the SQL Engine. Make certain that you have correctly installed and configured SQL RDBMS (or the equivalent) or that you have installed the correct network redirector.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL002: Error allocating memory.

An attempt was made to allocate a block of memory, but that attempt failed. Try removing other programs from memory, and then repeat the task. Try saving your work and exiting from SQLWizard, and then reload it. If the operating system is using a temporary PAGEFILE, make sure there is at least 2MB of free disk space. If attempts to increase available resources fail, contact Micro Focus Technical Support.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL003: Error opening file filename.

An attempt was made to open the file named, but it failed. This usually occurs if the file could not be found. Check that the file exists, and that you have privileges to access it. Make sure the file is not in use by another application. Check to be sure there is enough disk space available, and that the target directory is a valid path.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL004: Error creating name window.

The system was unable to create the window, probably because resources (such as memory) are low. Close down some windows (or other applications) and try again. See WSQL002.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL005: Error creating name dialog.

The system was unable to create the dialog, probably because resources (such as memory) are low. Close down some windows (or other applications) and try again. See WSQL002.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL006: Error creating name text editor.

The system was unable to create the window, or open the specified application. Close down some windows (or other applications) and try again.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL007: Error adding line to text editor.

The system could not add additional text to the current edit control. System resources may be low. Try freeing resources by closing unnecessary programs.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL008: Prohibit Cartesian products.

The system has been set to prohibit Cartesian products. The query you are trying to run has been evaluated as a Cartesian product, and cannot be executed unless you turn off the Prohibit Cartesian Products option through the Query|Current Query Options dialog.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL035: Error seeking query.

A query could not be found. You can query the SYSXDB.SYSQUERY table to see if the query exists in the location that you are querying. You may need to make the location where the query exists the current location.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL036: Cannot find table name.

A table by the specified name could not be found.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL037: Cannot paste table name.

The system was unable to paste a table name into the current context.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL038: Cannot open init file.

The system was unable to open one or more initialization files. Run Options to check XDB.INI. Check the command line of XWIZ40N.EXE for the INI file in use.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL039: Cannot paste query.

An attempt was made to paste an SQL statement into a Query Design window, or to paste a Query Design into an SQL Edit window. Try using the Open button to open the query. Change to SQL view if necessary, and copy the query, then paste to the target SQL Edit window.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL040: The editor is read-only.

You cannot edit or paste into the current edit field.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL041: Cannot open a synonym under a different location or AuthID.

Synonyms can only be accessed from the location in which they are created. Make the synonym location your current location before attempting to open the synonym.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL042: Error in querying SYSACFUSERS.

The system encountered an error when attempting to retrieve information on users from the system catalog. This error occurs if you have not been granted privileges against the system catalog tables. You will be allowed to continue if you receive this error, but you will be connected as a regular user, not a super user.

Resolution:

We provide SQL scripts you can run to grant privileges against system catalog tables. All are located in your %ProgramData%\Micro Focus\Enterprise Developermfsql\cfg directory and must be run from there.

Note: Scripts with filenames beginning with XP enable you to grant privileges to the PUBLIC user ID. Scripts with filenames beginning with XU enable you to grant privileges to any user ID other than PUBLIC.
  • XPALLVU.SQL and XUALLVU.SQL - Create a view of the system catalog tables of a location and grant select privileges on that view.
  • XPGRTALL.SQL and XUGRTALL.SQL - Grant select privileges on the system catalog tables of a location.
  • XPGRTSYS.SQL and XUGRTSYS.SQL - Grant select privileges on the system catalog tables of the SYSTEM location.
  • XPSYSVU.SQL and XUSYSVU.SQL - Create a view of the system catalog tables of the SYSTEM location and grant select privileges on that view.
Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL043: Cannot access SYSIBM tables using AuthID authid.

This error occurs if you attempt to start SQLWizard when you have not been granted privileges for the system catalog tables.

Resolution:

We provide SQL scripts you can run to grant privileges against system catalog tables. All are located in your %ProgramData%\Micro Focus\Enterprise Developermfsql\cfg directory and must be run from there.

Note:

Scripts with filenames beginning with XP enable you to grant privileges to the PUBLIC user ID. Scripts with filenames beginning with XU enable you to grant privileges to any user ID other than PUBLIC.

  • XPALLVU.SQL and XUALLVU.SQL - Create a view of the system catalog tables of a location and grant select privileges on that view.
  • XPGRTALL.SQL and XUGRTALL.SQL - Grant select privileges on the system catalog tables of a location.
  • XPGRTSYS.SQL and XUGRTSYS.SQL - Grant select privileges on the system catalog tables of the SYSTEM location.
  • XPSYSVU.SQL and XUSYSVU.SQL - Create a view of the system catalog tables of the SYSTEM location and grant select privileges on that view.
Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


WSQL044: Cannot access SYSXDB tables using AuthID authid.

This error normally occurs if the current user does not have select privileges on the SYSXDB catalog tables, or on the equivalent views. Check the SYSXDB setting in the Options SQL page to see what AuthID the system is trying to use for SYSXDB catalog views, and contact your administrator to see if you have select privileges on the views created with this AuthID. If you do not, have the administrator grant you the privileges you need to access the catalog tables. If the SYSXDB.SYSQUERY table does not exist, you may see this error. You will still be allowed to access SQLWizard, but you may not be able to list or save queries in the catalog tables. You should still be able to save and run queries in SQL script files.

Parent topic: WSQL - SQL Wizard Interactive SQL Error Messages


X009: Illegal field name name.

A reference was made to a field that does not exist in the table specified by a command. If using a precompiler to catch an error at precompile time, then add VALIDATE directive in XDBCOB.DIR file. Make sure that all fields are defined in the declaration.

Parent topic: X000 - X049


X010: No more RAM memory available.

Insufficient memory (RAM) was available to execute a command sent to the SQL Engine. Try running the application from outside the main menu or application menu to see if that gives you enough memory to continue.

Parent topic: X000 - X049


X011: Type mismatch within expression.

A data type conflict occurred within an expression. For example, you may have attempted to perform date arithmetic with a character string.

Parent topic: X000 - X049


X012: Type mismatch while doing comparison.

An attempt was made to compare two incompatible data types. Numeric types may be compared to other numeric types (including, for example, money and numeric results of date arithmetic or string functions); dates can only be compared to dates, character strings to character strings, times to times.

This error can also be returned if a FETCH statement is returning data into a data structure, and the data structure associated with the FETCH statement is not exactly the same as the data structure associated with the DECLARE CURSOR statement. Look for transposed columns, or missing columns in one of the data structures. For example, if the engine is returning numeric data in the cursor into a character field in the fetch, this error is returned.

Parent topic: X000 - X049


X013: Order by clause invalid on singleton select statement.

An embedded SQL singleton select might not contain an older BY clause. The statement should be modified to use the OPEN CURSOR construct.

Parent topic: X000 - X049


X014: Set location can only be used for local locations.

The system was unable to locate a table or view in the relational directory (.DDT file), or the table/view is not found in the referenced query control block. In order to add a table or view to the relational directory you must create it using the CREATE command. You can copy tables from one location to another using the COPY command. To include a table or view in a query control block, you must include it in the FROM clause of a query.

Parent topic: X000 - X049


X015: Attempt to close an unopened location directory.

An attempt was made to close a location directory that was not open at the time. Check for subroutines that close the location, or logout of subprograms.

Parent topic: X000 - X049


X016: Undefined query identifier or location not open.

An attempt was made to access a query control block that does not exist, or to run a command against an unopened location. This error condition may occur if you prematurely close a query or (if using an application programming interface) if you forget to open the location. Also a subroutine may have logged out, automatically closing the location.

If you are using Direct Flight software, an internal error has occurred. Record the version of XDB Server software you are using and contact Micro Focus Technical Support.

Parent topic: X000 - X049


X017: Illegal record position.

An attempt was made to access a record at a location outside the result of the query. Typically this occurs when using the application programming interface function xdirect() to move the cursor to a record that does not exist in the current table. To find the position of a record, use the xgetpos() function. It is possible that the record has been modified since the position was saved and re-execution of the query did not include the record in the new result set.

Parent topic: X000 - X049


X018: Duplicate value in unique index name.

An attempt was made to insert a duplicate value in a field on which a unique index or primary key exists. Possible fixes: Check for a rollback file (.RB extension) and delete it; Delete all indices and rebuild them; Check if the data is wrapped; Delete all files from temporary storage before transferring new data to the storage area.

Parent topic: X000 - X049


X019: Query too long.

The system was unable to allocate enough space to process the query. XDB Server uses dynamic allocation for this task, so the length of query permitted depends on the amount of memory available. Reduce the length of the query, or remove unnecessary programs from memory and try again. See X010 and X050.

Parent topic: X000 - X049


X020: Syntax error. Last symbol read was string.

The SQL Engine was unable to parse a command it was sent. When this error occurs, the system tries to display the last token it read. Check the command syntax in the SQL Reference. Make sure that all products are using the same character set (ASCII, EBCDIC, etc.). If using the COBOL, look in the errmc element of the SQLCA structure for the error tokens. SQLCA errd[4] contains the column position of the token. In CAPI, call the function xgeterr() to get the error tokens.

This error can be caused by incorrect (or inconsistent) settings of environment variables used by the Micro Focus COBOL compiler. For example, a syntax error can occur when Micro Focus is running in EBCDIC mode and XDB Server is running in ASCII mode.

If the Micro Focus COBOL.DIR directive file (or any other Micro Focus directive file) contains a CHARSET(EBCDIC) directive, then the XDBCOB.DIR directive file should contain a matching EBCDIC directive. An EBCDIC/ASCII mismatch can be deduced while checking the value of SQLERRMC (SQLCA variable) from within your Micro Focus Animator session.

If the value which appears for SQLERRMC consists of a series of unreadable characters, then a character set mismatch has probably occurred.

If using the DAYS function, you cannot use a group level for date. You must redefine the group level to one field definition. (The group level is the level that has elementary items within a COBOL program.)

Parent topic: X000 - X049


X021: Pathname too long.

XDB Server accepts paths of up to 48 characters.

Parent topic: X000 - X049


X022: Too many queries open at same time.

There is no room to open additional query control blocks. A user may open up to 50 queries at one time. The actual number of queries open at one time depends on the complexity of the queries. Try rewriting your program so that it is not necessary to hold so many queries open at the same time. In server versions, use the XDB Server Configuration utility to increase the number of available query control blanks.

Parent topic: X000 - X049


X023: Length of value exceeds length of destination.

An attempt was made to place a value in a field too small to accommodate it.

Parent topic: X000 - X049


X024: Index Name has been damaged.

The index specified cannot be used by the system. You must drop the index and rebuild it before continuing. NOTE: If you compact a table with deleted records or use the AND INDEX clause, all indices are automatically rebuilt for you.

Parent topic: X000 - X049


X025: Incomplete comment.

Comments sent to the SQL Engine should begin with the characters /* and end with the characters */. The system found one comment marker, but not the other.

Parent topic: X000 - X049


X026: Exceeds max number of tables/views permitted in query.

You may access up to 15 tables or views per FROM clause; the limit depends on the complexity of the query, as well as the number of expressions and multi-table views involved. In addition, the number of queries already open may impact on the number of tables allowed in a query.

Parent topic: X000 - X049


X027: Maximum of number connected client nodes has been exceeded.

The XDB Server cannot process your connection request because the maximum number of licensed users is already attached to the server.

Try connecting to the server at a later time or during off-peak hours. If this problem occurs frequently, you may want to consider upgrading your XDB Server license. Contact Micro Focus Sales to do this.

Parent topic: X000 - X049


X028: Cannot find table/view/synonym name.

The table, view, or synonym specified does not have a readable entry in the database directory. You may have entered an incorrect table name, or be in the incorrect database. The database directory (.DD? file) may have been damaged or overwritten. You cannot simply copy a .TAB file to a database directory and then access it through XDB Server. You must use the CREATE or COPY commands to create a table or move a table between databases.

Parent topic: X000 - X049


X029: Invalid hex constant.

The XDB Server cannot execute the current statement because it contains an invalid hex constant. For example, a closing quote may be missing, or the hex value may contain an invalid character.

Correct the hex constant and resubmit the statement or program.

Parent topic: X000 - X049


X030: Invalid field number.

A low level CAPI function call (e.g. Xdbxgetrec or Xdbxputrec) to access a field failed; the specified field number does not exist in the query.

Parent topic: X000 - X049


X031: Cannot truncate log file.

Unable to truncate the backward log file; cannot COMMIT or ROLLBACK. Check access privileges on the drive containing the database. Run operating system program CHKDSK on the database drive. Use Options to turn the Backward Log OFF.

Parent topic: X000 - X049


X032: Lock Conflict.

Two or more users are accessing the same object.

Parent topic: X000 - X049


X033: Column name is ambiguous.

If the column specified is ambiguous, then you must reference it by a two-part column name (i.e., table/view.column).

Parent topic: X000 - X049


X034: Illegal correlation name name.

A query references a correlation name not specified in the FROM clause.

Parent topic: X000 - X049


X046: Illegal number of fields specified for compound index.

An attempt was made to create an index on more than 64 columns.

Parent topic: X000 - X049


X047: Index name too long.

An index name is currently limited to 18 characters in length, except when using mainframe syntax.

Parent topic: X000 - X049


X048: Index name already exists.

An attempt was made to create an index with the same name as an existing index in the current database. You can view index names in the current database using the query:

SELECT creator,name FROM sysibm.sysindexes
Parent topic: X000 - X049


X049: Duplicate name name in create index list.

A field name can appear only once in a CREATE INDEX statement. When creating foreign keys, a field name can appear only once in the indexed field list of a referenced table, and only once in the indexed field list of the referencing table.

Parent topic: X000 - X049


X050: No more RAM available to REDIRECTOR.

The network redirector (network communications) was unable to allocate the necessary memory required (either for packet transmission or reception).

If you are using JDBC, this error indicates a shortage of memory or swap space on the XDB Server computer.

Try resubmitting your request. If other programs/transactions have finished processing, the XDB Server may have enough memory to process your request.

If this error becomes a persistent problem...

  • Check that there is adequate disk space available on the swap device used by the server machine.
  • Reduce the number of other programs running on the server and/or limit the number of active transactions allowed by the XDB Server and other transaction-processing programs.
  • Increase the hardware capacity of your server machine (specifically, RAM and hard disk).

If this error persists, contact Micro Focus Technical Support.

Parent topic: X000 - X049


X051: Duplicate key value when creating unique index indexname.

Unable to create unique index because a value appears more than once in the column(s).

To fix this problem, drop this index and then test for duplicates using the following query:

SELECT index-field-list FROM table-name GROUP BY index-field-list HAVING count(*) > 1

where index-field-list is the list of the columns in the index you are trying to create, and table-name is the name of the table you are indexing. The rows retrieved correspond to duplicate entries that prevent you from creating a unique index on the specified fields.

If duplicates are found, perform a SELECT * from the table where values equal those of the results that come from the previous query and delete the additional entry rebuild index after dropping duplicates. If no records are retrieved, there are no duplicates.

Parent topic: X050 - X099


X052: Cannot update field to incompatible type.

An attempt was made to update a field using an incompatible value. Check the field types of the table you are updating.

Parent topic: X050 - X099


X053: String length is larger than field length.

An attempt was made to insert a character string into a field too short to hold it. Check to see if you are using DB2 compatibility.

Parent topic: X050 - X099


X054: Unequal number of fields and values.

When inserting a record, an attempt was made to insert more values than the table has fields. If you supply too few values, the system automatically places NULL values in the other fields.

Parent topic: X050 - X099


X055: Duplicate names name in insert/alter/create list.

A field name appears more than once in an INSERT, ALTER, or CREATE command.

Parent topic: X050 - X099


X056: Table/View name already exists.

All tables and views in a database must have unique names. To obtain a list of the tables or views in a database, you can perform the query:

SELECT name, ''table'' FROM sysibm.systables UNION SELECT name, ''view '' FROM sysibm.sysviews
Parent topic: X050 - X099


X057: Specified more fields or values than the table has.

The number of values listed in an INSERT command exceeds the number of fields in the table named.

Parent topic: X050 - X099


X058: Field name type incompatible with type type.

Unable to perform a command because the type of the field named is incompatible with the type displayed (e.g. a time field is incompatible with a date field for comparison operations).

Parent topic: X050 - X099


X059: Inserting character constant larger than field length specified.

A character string in an INSERT command values list is longer than the target character field. Value is truncated.

Parent topic: X050 - X099


X060: value is outside allowable field length boundary.

See the SQL Reference for description of data type ranges.

Parent topic: X050 - X099


X061: number is greater than maximum allowable number of fields.

Tables are limited to 750 fields.

Parent topic: X050 - X099


X062: Value value is too large to insert into field name.

Unable to insert the value into the field specified, because it is larger or longer than maximum value permitted.

Parent topic: X050 - X099


X063: Index name not found.

Reference was made to an index not found in the current database. For a list of the currently active indices in the current database, execute the query:

SELECT name FROM sysindex
Parent topic: X050 - X099


X064: Not a proper command or command not implemented.

An attempt was made to execute a command that is not a valid XDB Server or SQL command, or to execute a command that is not yet implemented.

Parent topic: X050 - X099


X065: Illegal field name name in order specification.

A field or column in an ORDER BY clause was not selected in the SELECT clause of the query, or does not exist in the table.

Parent topic: X050 - X099


X066: Illegal number number in order/group specification.

There is no matching column number for a column number listed in the ORDER BY or GROUP BY clause of the query.

Parent topic: X050 - X099


X067: Aggregates not allowed in WHERE clause of query.

XDB Server does not permit an aggregate function in the WHERE clause of a query. Aggregate functions should appear in a HAVING clause if used as a selection criterion.

Parent topic: X050 - X099


X068: Selecting an expression with a GROUP BY clause.

XDB Server does not permit use of expressions (other than aggregate functions) in a query having a GROUP BY clause unless you include the expression in the GROUP BY clause using its column number.

Parent topic: X050 - X099


X069: Too many set clauses in update command.

There are more SET clauses in the UPDATE command than there are fields in the table being updated.

Parent topic: X050 - X099


X070: Ordering by field name that is not selected.

In DB2 mode, the ORDER BY clause must specify one of the fields in the SELECT clause.

Parent topic: X050 - X099


X071: Selecting more than one item in a nested query.

The SELECT clause of a subquery can consist of only one column. If you want to select more than one field, try concatenating the fields using the XCONCAT function.

Parent topic: X050 - X099


X001: Cannot perform operation (errornum) on file filename.

An attempt to close/open/read/write/seek on the file specified failed. File mode may conflict. Device may be full or damaged, or file may not exist. Also, make sure that your temporary path is set to an existing path.

1005 | No such file or directory (ENOENT)
1011 | Bad file descriptor (EBADF)
1013 | Permission denied (EACCES)
1020 | File exists (EEXIST)
1023 | Too many open files (EMFILE)
1027 | No space left on device (ENOSPC)

If errornumber is less than 1000, then this is an error specific to your platform. If the errornumber you get is not in the table, contact Micro Focus Technical Support.

The following are more detailed descriptions of values for errornumber:

  • 1005 No such file or directory (ENOENT).

    The specified file or directory does not exist or cannot be found. This message can also occur when a component of the path name does not specify an existing directory.

  • 1011 Bad file descriptor (EBADF).

    The specified file handle is not a valid file handle value, it does not refer to an open file, or an attempt was made to write to a file or device opened for read-only access (or vice versa).

  • 1013 Permission denied (EACCES).

    The file's permission does not allow the specified access. This error occurs when someone attempts to access a file or directory in a way that is incompatible with the file or directory attributes. For example, this error will occur when an attempt to read is made on an unopened file, or when an attempt to write is made on a read-only file.

  • 1020 File exists (EEXIST)

    The O_CREATE and the OEXCL flags are specified when opening a file, but the named file already exists.

  • 1023 Too many open files.

    The number of files exceeds the maximum allowed.

  • 1027 No space left on device (ENOSPC).

    No more space for writing is available on the device. For example, the disk is full.

Parent topic: X000 - X049


X082: Each query in a UNION must have the same number of projected fields.

The number and type of columns selected in subselects connected with the UNION operator must match exactly.

Parent topic: X050 - X099


X083: Data types in column name do not match.

When performing a UNION, the data types of each column in one subselect must be type compatible with the corresponding column in all UNIONed subselects.

Parent topic: X050 - X099


X084: ORDER BY items must be constants for union of queries.

When the UNION operator and the ORDER BY clause appear in the same query, the ORDER BY criteria must use column numbers instead of column names.

Parent topic: X050 - X099


X085: ORDER BY must follow all queries when performing a union.

The ORDER BY clause should be the last clause in any query containing a UNION operator.

Parent topic: X050 - X099


X086: NULL not allowed in field name.

An illegal attempt was made to place a NULL in the field named. The field is specified as NOT NULL. You can obtain information on NULL permission from the SYSCOLUMNS table.

Parent topic: X050 - X099


X087: Table/View name exceeds maximum length of number.

Table, view and synonym names are limited to the number of characters shown. Some compatibility modes allow longer table names than others.

Parent topic: X050 - X099


X088: Field name length exceeds maximum length of number characters.

Table names are limited to the number of characters shown. Some compatibility modes allow longer field names than others.

Parent topic: X050 - X099


X089: Cannot open location on path. Check location path setting.

The system is unable to find or open the location-name.DDT or location-name.DDF files on the path specified. These files contain essential information on location table and field specifications. Check whether there is a location in the path specified. Check whether there is more than one set of .DDT or .DDF files in your location directory. Check to see if the location name matches the location name in the SYSXDB.SYSLOCALS table. Verify whether the path is accessible by the program accessing the location. For example, in multi-user, use the drive specifier.

Parent topic: X050 - X099


X090: Too many users registered.

The number of users registered is equal to the maximum number of users permitted to register at one time.

Parent topic: X050 - X099


X091: User has no privilege privilege on objectname.

The current user has not been granted the privilege to perform the operation attempted on the table, view or database shown. For a listing of privileges available to a user, query the SYSTABAUTH and SYSDBAUTH tables.

Parent topic: X050 - X099


X092: User account has been disabled.

The user name has been deactivated. See your database administrator, who can enable the user account.

Re-enabling is done when a superuser re-grants access authority by clicking Users on the Admin menu in SQL Wizard.

Parent topic: X050 - X099


X093: Unknown user name.

The user name entered is not found in the system, because it has not been registered on the system. See your database administrator. Query the SYSXDB.SYSACFUSERS table in the system location for a list of valid user names.

Parent topic: X050 - X099


X094: User userid cannot GRANT/REVOKE on table/view/database name.

User has no authority to grant or revoke privileges on the database, table or view named. For a list of privileges available to a user, query the SYSTABAUTH and SYSDBAUTH tables.

Parent topic: X050 - X099


X095: Invalid receipt. (Should register first.)

User did not obtain a valid process ID before entering a module. Exit to the operating system and try reentering the program. In extreme cases you may need to unload the SQL Engine, or in multi-user environments, kill a user session.

This condition may occur when a program developed with an application interface attempts to short circuit XDB Server security. Programmers should refer to the C Application Programming Interface Xdbxlogin() or Xdbxqutrcpt() functions. Others should contact their database administrator and/or software developer.

Parent topic: X050 - X099


X096: Illegal password.

Password does not match password saved for the user name entered. Repeated attempts to log on with an incorrect password will cause this program to abort. If you have forgotten your password, see your database administrator.

Parent topic: X050 - X099


X097: Illegal attempt to open more than one location.

XDB Server permits a user to access only one location at a time. This error condition occurs when a programmer attempts to call the C API Xdbxopen() function before closing the current location.

Parent topic: X050 - X099


X098: Cannot grant a privilege to yourself.

A user is not permitted to grant a privilege to him/herself. The privilege must be granted by another user possessing sufficient authority to do so.

Parent topic: X050 - X099


X099: User already exists.

A user with the same user name is already entered in the SYSXDB.SYSACFUSERS table. User names must be unique.

Parent topic: X050 - X099


X100: Memory Resident Engine not loaded!

XDB client-side software could not communicate with the XDB Server. Check to make sure that the XDB Server is up. If it is up and listening on the appropriate communications protocol, contact Micro Focus Technical Support.

Parent topic: X100 - X149


X101: Illegal function code passed to engine.

Programmer attempted to call the SQL Engine with an illegal function code. Refer to your Application Programming Interface documentation for valid function codes. Another possible cause for this error could be that you are inadvertently trying to access the wrong engine. This can occur if you have been working with a single-user engine on your own computer and then switch to using a multi-user XDB Server.

Parent topic: X100 - X149


X102: Cannot find view name.

Unable to find the view named in the SYSVIEWS table, or in the system directory files.

Parent topic: X100 - X149


X103: Must select aggregates if using HAVING clause with no GROUP BY.

A HAVING clause can only appear in a query that selects only aggregate functions, or that has a GROUP BY clause.

Parent topic: X100 - X149


X104: A password is required for connection with LU servername.

You are trying to connect to a server name that doesn't trust you. You need a password to be connected.

Parent topic: X100 - X149


X105: Operation not allowed on view name.

XDB Server cannot perform the operation attempted on the view named. For example, multi-table views are not currently updateable.

Parent topic: X100 - X149


X106: No translation row in tablename SYSUSERNAMES for LU servername.

You are trying to do inbound/outbound mapping without specifying a translation row to the AuthID in SYSUSERNAMES.

Parent topic: X100 - X149


X107: Current AuthID can't be used to reference remote object.

The XDB Server cannot execute the requested operation because the specified AuthID is not valid for the remote location.

Check that you are using a valid AuthID for the requested location (make sure you have supplied the appropriate AuthID and that you have spelled it correctly). Also check with your database administrator to determine whether this ID is valid for the requested location.

Parent topic: X100 - X149


X002: Empty query string.

An attempt was made to execute a command that was discovered to be an empty string. You may have accidentally pressed an execute option before issuing a command. You may have used an empty (NULL) string as the input for a PREPARE command, or for an xcommand() or xprepare() function.

Parent topic: X000 - X049


X119: Location name exceeds maximum length of number.

XDB Server location names are limited to the number of characters specified. Use a shorter location name.

Parent topic: X100 - X149


X120: Cannot find location name in SYSXDB.SYSLOCALS table.

An attempt was made to perform an operation on a location not found in the SYSXDB.SYSLOCALS table. Check the location path or location name specified in your command. When a location is created using the CREATE LOCATION command, an entry is inserted into the SYSXDB.SYSLOCALS table. If you are using a location that was not created with the CREATE LOCATION command, you may use the INSERT command to insert a record into the SYSXDB.SYSLOCALS table for the location.

Parent topic: X100 - X149


X121: Operation requires system level privilege.

An attempt was made to perform an operation that requires database administrator privileges. Check the authority required for the command you are trying to execute. If you do not have the proper authority, see your database administrator.

Parent topic: X100 - X149


X122: Incorrect location files on path path.

This error occurs if a specified location is not found. This might be caused by trying to access files that have been deleted, or by entering a path instead of a location. Otherwise, the problem is with SYSXDB.SYSLOCALS. You might want to check the path selections in Options.

Parent topic: X100 - X149


X123: Cannot open system location on path path.

The system was unable to open the system location on the system location path specified. To change the system location path, use the Configuration utility, described in the XDB Server Administration Guide.

Parent topic: X100 - X149


X124: Illegal operation on system object.

An illegal attempt was made to alter, insert, update or delete from a system object. XDB Server objects are for system use; they are automatically created and maintained by the system. Users may query the objects but, in general, cannot update or change them except through special commands (e.g. COMMENT ON). See XDB Server System Tables in the SQL Reference for descriptions of the system objects and how they are maintained.

SQLWizard Notes:

If you are running against XDB Server or a local copy of the SQL Engine, the SYSIBM and SYSXDB items (found in the SQL page of Options) should be set to SYSIBM and SYSXDB, respectively. This causes catalog queries to be issued directly against the catalog tables.

If you are running against DB2 via XDB Link you will usually use views of the catalog tables instead of accessing the tables directly. Your database administrator should be able to tell you the AuthID to use for catalog queries.

Contact Micro Focus Support for availability of an update that allows queries to views of the system catalog tables.

Parent topic: X100 - X149


X125: Must execute statement before fetch.

When using dynamic SQL, before issuing a FETCH command you must PREPARE and EXECUTE the command.

Parent topic: X100 - X149


X126: Cannot GROUP BY an aggregate function.

Aggregate functions cannot appear in a GROUP BY clause.

Parent topic: X100 - X149


X127: Pattern matching allowed on character fields only.

LIKE searches, which use wild card pattern matching, can only be performed on character fields. You may perform range searches on other field types, including date and time. If you want to search a date field by day, month, or year, use XDAY, XMONTH or XYEAR, respectively.

Parent topic: X100 - X149


X128: Target table cannot also be source table.

You cannot insert records selected from a table into the same table. In addition, you cannot copy a table to itself.

Parent topic: X100 - X149


X129: Attempt to insert invalid data into field name.

An attempt was made to place incompatible data in the field named. Check the command, the data, and the field type, and make any corrections needed.

Parent topic: X100 - X149


X130: Attempt to drop system location.

The system location cannot be dropped using the DROP LOCATION command, since it contains the SYSXDB.SYSLOCALS table. If you must drop the system location, use operating system commands to delete all files and remove the location directory.

Parent topic: X100 - X149


X131: Attempt to drop location in use.

You cannot drop the current location. Before dropping a location, you must change to another location.

SQLWizard Notes:

If you open a location, or query the tables in a location (by looking at the location through the Catalog Browser, for example), the SQL Engine considers the location to be in use. If you receive the error when you try to drop a location:

  1. Exit from SQLWizard (or the application that is returning the error).
  2. If your default location is the location you want to drop, you must open Options and change the default location to a different location.
  3. Restart SQLWizard.
  4. Drop the location using the Location menu's Drop option.
Parent topic: X100 - X149


X132: Cannot find location name name in SYSXDB.SYSLOCALS table.

The location named in the command does not have an active entry in the SYSXDB.SYSLOCALS table in the system location. Check the command and the SYSXDB.SYSLOCALS table for the correct location name.

Parent topic: X100 - X149


X133: Cannot use reserve word word in table/index definition.

XDB Server and SQL reserved words cannot be used as database object names (e.g. table and field names). For a list of reserved words, see the SQL Reference.

Parent topic: X100 - X149


X134: error: DOMAIN ERROR.

A mathematical function contains an argument outside the domain of the function. For example, you cannot use a column containing a negative number as the argument for XSQRT.

Parent topic: X100 - X149


X135: error: RANGE ERROR.

The result of a mathematical function is too large to be represented in the data type the system is trying to use.

Parent topic: X100 - X149


X136: Functionality not available with LITE engine.

The LITE Server cannot process this statement because it contains commands that are not supported by the LITE software.

Eliminate the invalid commands from the statement, or contact Micro Focus Sales to have the XDB Server upgraded to the full-featured version.

Parent topic: X100 - X149


X137: Cannot perform operation (errno) on location file name.

The system was unable to perform the operation specified on the location file specified.

Parent topic: X100 - X149


X138: Illegal operation on view.

An attempt was made to perform an operation not permitted on a particular view, or not yet implemented in XDB Server. For example, you cannot currently update a multi-table view.

Parent topic: X100 - X149


X139: Record size exceeds the maximum.

XDB Server records are limited to 32,767 bytes, including record overhead. For odd length character fields, overhead is one byte; for even length character fields overhead is 2 bytes. For most other data types, overhead is 2 bytes per field in DOS.

Parent topic: X100 - X149


X140: WITH CHECK OPTION clause not allowed on read only view.

You cannot specify a CHECK OPTION for a view that is not updateable. For example, you cannot currently update views involving multi-table joins.

Parent topic: X100 - X149


X141: Record does not satisfy view definition.

An illegal attempt was made to update or insert an invalid record into a view created using the CHECK OPTION clause. You can see the CHECK OPTION for the view by querying the SYSCHECK table.

Parent topic: X100 - X149


X142: Operation not allowed on read only view.

An attempt was made to perform an operation not permitted on a particular view, or not yet implemented in XDB Server. For example, you cannot currently update a multi-table view.

Parent topic: X100 - X149


X143: Table already has check condition.

You may only create one CHECK CONDITION per table. However, this CHECK CONDITION may be very complex (to the detriment of performance). If you want to add conditions to the CHECK CONDITION, you must drop and recreate the CHECK CONDITION.

Parent topic: X100 - X149


X144: Record does not satisfy table name check condition.

An illegal attempt was made to update or insert an invalid record into a view created using the CHECK OPTION clause. You can see the CHECK OPTION for the view by querying the SYSCHECK table.

Parent topic: X100 - X149


X003: INI Error errmsg

The error message returned can be any of the messages listed under Possible Error Messages below. Each possible error message is followed by a typical XDBNET.INI file error that could have caused the error message. The following notation definitions apply for each possible error message:

file - the .INI file name (XDBNET.INI in this case) where the error occurred.

section - the server section name in XDBNET.INI where an error occurred.

item - the server section parameter name (for example, IpAddress or IpxNodeAddr) where an error occurred.

string - the server section string value where an error occurred.

Possible Error Messages:

  • Item item had no associated string in file section [section].

    Sample XDBNET.INI file error where a string value is missing:

    [server XDB] IpAddress=
  • file file not found.

    The XDBNET.INI file identified by file does not exist.

  • Section [section] was not found in file.

    The server section identified by section could not be found in the XDBNET.INI file.

  • Item item was not sound in section [section] of file file.

    A required item identified by item (such as a TcpPort value) was not found in the server section identified by section of the XDBNET.INI file.

  • File file : Section [section] : Item item has data too long.

    The data in an XDBNET.INI file item has exceeded the allowable number of digits.

  • File file : Section [section] : Item item has invalid data.

    Parameter appearing in an XDBNET.INI file item contains an invalid value.

Note:

If using a version earlier than 5.0, XDB will return the following X003 error message:

X003: Money value overflow.

An attempt was made to place a value that is too large or too small into a numeric field (float, int, smallint, etc.). See XDB Server Specifications in the SQL Reference for maximum and minimum values permitted in numeric data types. Check picture specifications.

Parent topic: X000 - X049


X155: Table/record currently locked by user at node.

A lock conflict exists. A record or table lock on the object you are attempting to lock is held by the user at the node (workstation) specified.

Parent topic: X150 - X199


X156: Table/record currently locked by user at node.

A lock conflict exists. A record or table lock on the object you are attempting to lock is held by the user at the node (workstation) specified. Note: With CICS, you must commit or use the Dirty Read (DR) option.

Parent topic: X150 - X199


X157: Cannot obtain exclusive lock or drop lock in isolation level 5 or 6.

When working at isolation level 5 (dirty read) or level 6 (snapshot read), a transaction cannot acquire or drop exclusive locks on any database object. Levels 5 and 6 are intended for read only. You cannot insert, update, delete, or alter database objects at these levels. You can change the isolation level using the following command:

SET ISOLATION isolation-level
Parent topic: X150 - X199


X158: Cannot obtain or delete table locks in isolation level 5 or 6.

When working at isolation level 5 (dirty read) or level 6 (snapshot read), a transaction cannot acquire or drop table locks. Levels 5 and 6 are intended for read only. You cannot insert, update, delete, or alter database objects at these levels. Tables are accessible by other users.

Parent topic: X150 - X199


X159: Current location is locked by user at node.

A lock conflict exists. The location you are attempting to access is locked for exclusive use by the user working at the node specified.

Parent topic: X150 - X199


X160: Cannot obtain isolation level EU due to existing locks.

The database you are attempting to lock is in use by others. Isolation level EU (exclusive use) not available until all other users close the database.

Parent topic: X150 - X199


X161: Not enough memory free on XDB Server to process request.

The minimum contiguous memory block is a configurable parameter (0-64K) for the XDB Server. The XDB Server does not currently have enough memory to process the request. Increase the size of the memory block. Increase the amount of free space on the server.

Parent topic: X150 - X199


X162: Logging in to XDB Server name requires security on at user node.

Security has been turned on at the XDB Server named. Security must also be turned on at the user node via the Configuration utility.

SQLWizard Notes:

Open Options to the Connect page, and click on the Client Security option to check it. Close Options and try starting SQLWizard again.

Parent topic: X150 - X199


X163: No network node name specified. Must be set through XDBCONFIG.

In the multi-user system, each network node must have a unique name, specified via the Configuration utility. The system is shipped without a default name since names must be unique.

Parent topic: X150 - X199


X164: Operation cannot be performed in isolation level DR or SR.

The user is trying to perform an operation other than reading a record while in the Dirty Read (DR) or Snapshot Read (SR) isolation level. Change to a different isolation level using the SET ISOLATION LEVEL command, or through Options.

Parent topic: X150 - X199


X165: Redirector version does not match XDB Server version.

The LAN redirector you are using does not generate communication packets that the XDB Server understands.

Please add one of the following to the [CLIENT] section of XDB.INI:

XDBPacketVer=251

or

XDBPacketVer=255
Parent topic: X150 - X199


X166: Operation requires isolation level EU (Exclusive Use) with this server.

Compacting database can only be performed at using an exclusive use isolation level (EU).

Parent topic: X150 - X199


X167: Redirector does not support the selected protocol protocol.

The communications protocol specified in Options is not supported by the redirector currently in use. For example, a DOS client can use NetBIOS, but cannot use Named Pipes.

Parent topic: X150 - X199


X168: User has been deleted by DBA at XDB Server.

The user's account on the XDB Server has been deleted. Please contact your Database Administrator.

Parent topic: X150 - X199


X169: Attempted to examine the status of an un-executed command.

An application issued a set of calls to the Server but not all were executed. An error exists in the application being run. Make sure you are using the correct AuthID for your location, and that you are pointing to the correct server. If the application is a Micro Focus program, please contact Micro Focus Technical Support.

If in Windows, exit from Windows and then restart it. Retry the command.

SQLWizard NOTE: To recover from this problem so that you can continue running Micro Focus applications, exit from the calling application (like SQLWizard) and close the SQL Engine (if it is loaded). Then open the Process Viewer and click on the Kill All button to close down all remaining processes.

Parent topic: X150 - X199


X170: Referenced key field type(s) must match foreign key field type(s)

The fields, taken in order, of the PRIMARY or UNIQUE KEY referenced by a FOREIGN KEY must match the type of the fields in the foreign key.

Parent topic: X150 - X199


X171: Foreign key already exists on field(s) specified.

Only one FOREIGN key is permitted on any set of fields. For example, if building a foreign key on item (o_no) that references the ORDERS table, you cannot build a another foreign key in the item (o_no) field.

Parent topic: X150 - X199


X172: Cannot create directory on path path.

An attempt to create a directory in the path specified failed. The path may already exist, or an attempt may have been made to create a subdirectory for a directory that does not exist.

Parent topic: X150 - X199


X173: Cannot flush location file contents to disk.

An attempt to commit a DDL operation (e.g. CREATE) failed. Disk may be full.

Parent topic: X150 - X199


X174: Synonym/Table name already exists.

You cannot create a synonym using a name already used by another synonym, table or view.

Parent topic: X150 - X199


X175: Synonyms cannot be created on other synonyms.

Synonyms may be created on tables and views only.

Parent topic: X150 - X199


X176: Synonym name does not exist.

You cannot drop a synonym that does not exist.

Parent topic: X150 - X199


X177: Maximum identifier size exceeded.

Table names, view names, index names, column names and synonyms are limited to 18 characters.

Parent topic: X150 - X199


X178: Precision must be a value between 1 and 31.

XDB Server accepts precision between 1 and 31. Precision is the total number of digits, including scale (number of decimal places) permitted in a decimal field.

Parent topic: X150 - X199


X179: Scale must be a value between 0 and the precision.

XDB Server accepts precision between 1 and 31. Precision is the total number of digits, including scale (number of decimal places) permitted in a decimal field. Scale cannot exceed the total number of digits permitted in the decimal field.

Parent topic: X150 - X199


X180: Cannot truncate table file.

When deleting all records from a table using the DELETE FROM table-name command, the tables and indices are simply truncated. An error occurred when attempting to truncate a file. Check your disk.

Parent topic: X150 - X199


X004: Number value overflow.

An attempt was made to place a value that is too large or too small into a numeric field (float, int, smallint, etc.). See XDB Server Specifications in the SQL Reference for maximum and minimum values permitted in numeric data types. Check picture specifications.

Parent topic: X000 - X049


X191: View definition too large for memory buffer.

There is not enough memory to process a view definition. If you have multiple queries open, or if you have unnecessary programs loaded into memory, close or remove them, and try again.

Parent topic: X150 - X199


X192: Error in source view definition.

Unable to copy view because of an error in the source view definition. You may need to redefine the view in the source database before attempting to copy it.

Parent topic: X150 - X199


X193: Outer join condition not allowed on expression predicates.

Outer join conditions are allowed on fields only and not on expression predicates.

Parent topic: X150 - X199


X194: Attempt to divide by zero.

An attempt was made to divide by zero within an expression.

Parent topic: X150 - X199


X195: User does not have privileges necessary for renaming a table.

You must be the creator of the table or have DBADM privileges on the database in order to rename a table.

Parent topic: X150 - X199


X196: Expression in GROUP BY/ORDER BY clause not allowed.

Only a field name or field number is permitted in a GROUP BY clause. Only a field name or column number is permitted in a ORDER BY clause.

Parent topic: X150 - X199


X197: Expression not allowed on left side of set clause.

The left-hand side of a SET clause must be a valid keyword, such as DATABASE or BACKWARD LOG. Expressions, when permitted, may appear only on the right-hand side of the SET clause.

Parent topic: X150 - X199


X198: Expression not allowed for field of insert clause.

When specifying the target fields for an INSERT command, you must use field names; expressions are not allowed.

Parent topic: X150 - X199


X199: Illegal foreign key constraint.

A FOREIGN KEY cannot be referenced by another FOREIGN KEY. If you want A to reference B, and B to reference C, then instead have A reference C and B reference C.

Parent topic: X150 - X199


X200: Illegal attempt to log out of parent process when dependents exist.

Internal error. Contact Micro Focus Technical Support.

Parent topic: X200 - X249


X201: User does not have privilege necessary for operation.

The user does not have the privilege required for the attempted operation. Check the SQL Reference for privileges required for specific operations.

Parent topic: X200 - X249


X202: Check condition does not exist.

An attempt was made to drop a non-existent check condition.

Parent topic: X200 - X249


X204: Referenced key must be a primary/candidate key.

Foreign key must reference a Primary or Candidate (Unique) key.

This message could also be returned if a program manipulates data from the system tables, and the site is converting from Version 2.41 to 3.x or 4.0. Look for table names that are no longer in the Version 3.x or 4.0 system tables. Make sure all references to these tables are changed prior to the pre-compilation.

Parent topic: X200 - X249


X205: Invalid character representation of numeric data.

A character string that contains invalid or non-numeric data is used in a location that requires numeric data.

Parent topic: X200 - X249


X206: Compatibility index must be set to group by number.

The ability to perform a GROUP BY using column numbers in the specification is not supported in any compatibility modes other than the XDB mode. Change compatibility mode or write specification using column names.

Parent topic: X200 - X249


X207: Check condition/view name incompatible with current version.

The structure of underlying tables has changed since the view or check conditions were created. Drop the view or condition and recreate using the new database definitions.

Parent topic: X200 - X249


X208: Table/View exists in target location. Use WITH REPLACE to overwrite.

If table exists in target location, you must either drop it before overwriting, or use the COPY command with the WITH REPLACE option.

Parent topic: X200 - X249


X209: Cannot perform GROUP BY on a view containing a GROUP BY.

If a view contains a GROUP BY clause, a command using the view cannot also contain a GROUP BY clause.

Parent topic: X200 - X249


X210: Cannot perform join with a view containing a GROUP BY.

A view containing a GROUP BY clause cannot be joined to other tables.

Parent topic: X200 - X249


X211: Cannot perform aggregate function on a view containing a GROUP BY.

If a view contains a GROUP BY clause, no command using that view may contain an aggregate function.

Parent topic: X200 - X249


X212: Function not available under current compatibility setting.

The current compatibility setting set through Options does not permit the function being attempted. The setting must be modified to one that allows the functionality/syntax being attempted. See the Options User's Guide.

Parent topic: X200 - X249


X213: Internal error encountered in function function. Contact Micro Focus.

An unexpected internal error occurred. Contact Micro Focus Technical Support.

Parent topic: X200 - X249


X214: The cursor identified in an open statement is already open.

The application program attempted to execute an OPEN statement for a cursor that was already open. Correct the logic of the application program to ensure that it does not attempt this action.

Parent topic: X200 - X249


X215: The cursor identified in a fetch/close statement is not open.

The application program attempted to either (1) FETCH using a cursor, or (2) CLOSE a cursor at a time when a specified cursor was not open. In DB2 mode commit and rollback implicitly close cursor. After a cursor is closed, FETCHes or CLOSE cursor statements will generate this error code.

Parent topic: X200 - X249


X216: Exceeded maximum outer join conditions.

An outer join condition is one that contains a plus sign (+) next to a field. The number of outer join conditions allowed has been exceeded. Currently, five outer joins are allowed per query. To proceed, reduce the number of these conditions.

Parent topic: X200 - X249


X217: Specified more than one primary key clause.

The CREATE TABLE specified more than one primary key. By definition, a table may not have more than one primary key. Other candidate keys may be defined as unique keys.

Parent topic: X200 - X249


X005: Date value error.

An attempt was made to place an illegal date in a date field or attempt to perform date arithmetic on an invalid date. XDB Server performs leap year checking, and verifies that month and day are correct. Check picture specifications.

Parent topic: X000 - X049


X228: The relationship name restricts the deletion of row with ID number.

A DELETE operation attempted to delete a specified parent row in the object table and all related dependent rows in the dependent tables. However, a delete rule of RESTRICT was specified for one or more dependent tables.

A row of the table cannot be deleted because it has a dependent in a relationship with a delete rule of RESTRICT or the deletion cascades to a row which is dependent in a relationship with a delete rule of RESTRICT.

Examine the delete rule for all dependent tables to determine the cause of the problem. The specified tables involved can be determined from the relationship name name. The specific dependent row is known by record number,number. This is the number of the row from the beginning of the table.

Parent topic: X200 - X249


X229: The insert/update value of foreign key name is invalid.

An UPDATE or INSERT operation attempted to place a value in a foreign key of the object table; however, this value was not equal to some value of the primary key of the parent table.

When a row is inserted into a dependent table, the insert value of a foreign key must be equal to the value of the primary key of some row of the parent table in the associated relationship.

When the value of the foreign key is updated, the update value of the foreign key must be equal to the value of the primary key of some row of the parent table of the associated relationship.

Examine the INSERT or UPDATE value of the foreign key first, and then compare it with each of the primary key values of the parent table to determine the problem.

Parent topic: X200 - X249


X230: Index name is not compatible with current version.

The index was not created with the current version and is incompatible. Rebuild the index with the current version. All indices in the location can be rebuilt using the COMPACT LOCATION AND INDEX command. All indices for a particular table can be rebuilt using the COMPACT TABLE `table-name' and INDEX command.

Parent topic: X200 - X249


X231: Cursor must be declared as FOR UPDATE OF.

The application program attempted to execute an UPDATE WHERE CURRENT OF statement on a cursor not defined as FOR UPDATE OF. Declare the cursor FOR UPDATE OF.

Parent topic: X200 - X249


X232: Index name sort sequence different from current setting.

An attempt was made to access an index that was created using a sort sequence different from the current sort sequence setting. When an index is created, it is sorted using the sort sequence specified in Options. To access this index, your default sort sequence setting must be consistent with that of the index. Rebuild the index with the default sort sequence setting or modify the setting in Options to be consistent with the index. Alternatively, you can drop the index and then recreate it with the new sort sequence setting.

Parent topic: X200 - X249


X233: Non-quantified predicate followed by a list of values.

If using a predicate without an ANY or ALL clause, only one value is allowed.

Parent topic: X200 - X249


X234: Function not available with engine as database engine.

DB2 link CAPI function not implemented with this engine.

Parent topic: X200 - X249


X235: XDBXDIRECT function not supported on GROUP BY cursor.

The Xdbxdirect function is not supported with queries containing a GROUP BY clause.

Parent topic: X200 - X249


X236: Must use ALTER TABLE DROP PRIMARY KEY to drop index pending.

An attempt was made to drop the `pending' index, which is a temporary name for a PRIMARY KEY which has not yet had a unique index created for it. To drop this index, use the ALTER TABLE DROP PRIMARY KEY statement.

Parent topic: X200 - X249


X237: operation not allowed on table name while in use.

Another user attempted an operation on the specified table while the table was in use. Skip the operation or retry it later.

Parent topic: X200 - X249


X238: Attempt to update a deleted record.

The record you are attempting to update has been deleted.

Parent topic: X200 - X249


X239: Invalid DEGREE specified.

The SET CURRENT DEGREE command contains an invalid value.

Check that your SET CURRENT DEGREE value is one of the following:

  • "ANY"
  • "1" (a one)
  • "1 " (a one followed by 2 spaces)

These are the only values allowed by this command.

Parent topic: X200 - X249


X240: Cannot delete field name which has existing referential key.

An attempt was made to delete a field containing a referential key. To delete the field, first drop the referential key.

Parent topic: X200 - X249


X241: Cannot modify field name which has existing referential key.

An attempt was made to modify a field containing a referential key. To modify the field, first drop the referential key.

Parent topic: X200 - X249


X242: Maximum number of sort fields exceeded.

The query has exceeded the maximum number of sort fields allowed. The current maximum number of sort fields is 750.

Parent topic: X200 - X249


X243: Host variable not allowed in current command.

The command executed does not support host variables.

Parent topic: X200 - X249


X244: Object table is referenced in nested query FROM clause.

In DB2 mode, the table that is the object of an update, insert or delete cannot also be referenced in a nested query FROM clause.

Parent topic: X200 - X249


X245: Requested packet is larger than max buffer size.

The amount of data being sent from the application program to the engine is too large. Increase the receive buffer size on both the client-side and the server-side.

To increase the receive buffer size, add the following line to the XDB.INI's file's {

Parent topic: X200 - X249


X246: Primary key cannot be target of multiple-row update.

In DB2 mode, a primary key cannot be updated if an update clause retrieves more than one record.

Parent topic: X200 - X249


X247: String representation of a date/time value is invalid.

The character representation of a date or time value is not being recognized. The engine can recognize ISO, JIS, EUR, USA, and LOCAL formats. Compare your date/time representation with the picture specified in CONFIG.XDB through Options.

Parent topic: X200 - X249


X248: AuthID not allowed on synonym table reference.

In DB2 mode, a synonym cannot be referenced in a FROM clause with an AuthID. Remove the AuthID.

Parent topic: X200 - X249


X249: Invalid picture specification.

The picture used in the CHAR function is not legal.

Parent topic: X200 - X249


X250: Invalid PCTFREE value.

Valid percent free values are 0 through 99.

Parent topic: X250 - X299


X251: Only one clustered index allowed per table.

XDB Server currently supports only one clustered index per table. Make all other indices non-clustered.

Parent topic: X250 - X299


X252: Truncate not allowed on primary key table.

The TRUNCATE clause is not allowed on tables that have a PRIMARY KEY.

Parent topic: X250 - X299


X006: String constant too long.

String constants selected in a query may be up to 4056 characters long. Varchar and long varchar columns can be longer, so you could store a longer value in a table and retrieve it.

Parent topic: X000 - X049


X263: XdbWinInit() has not been called. XdbWinInit() must be called first.

Under Windows, the function XdbWinInit() must be called before all other functions. See your C documentation.

Parent topic: X250 - X299


X264: A necessary window could not be created.

A window could not be created due to the number of windows already open or the amount of system resources in use. Close other windows or shut down other applications and try again.

Parent topic: X250 - X299


X265: User program ProgramName could not be found.

The XDB Server cannot find the DLL or the function associated with the procedure specified in your SQL CALL statement.

Verify that the LOADMOD column in the SYSIBM.SYSPROCEDURES table specifies the correct DLL for your stored procedure. Also confirm that:

  • The DLL exists.
  • The DLL is in a directory that can be accessed by the XDB Server (check permissions).
  • The specified procedure (function) is contained in the DLL.
  • The procedure name as specified in the PROCEDURE column of the SYSIBM.SYSPROCEDURES table matches the function name in the DLL exactly with respect to case. For example, if your function is called "MyProc" in the DLL, it must also be specified as "MyProc" in the PROCEDURE column -- not "myproc" or "MYPROC".
Parent topic: X250 - X299


X266: Server is shutting down. Accepting no more logins.

The server has been configured to shut down on last disconnect. No new connections are allowed.

Parent topic: X250 - X299


X267: Invalid parameter in function function.

An internal error has occurred. The XDB Server has received an invalid parameter or a different number of parameters than it expected.

Do the following:

  • Record the version of the XDB Server software you are using.
  • Record the version of the client software you are using.
  • Make a note of the operation that failed.
  • Contact Micro Focus Technical Support.
Parent topic: X250 - X299


X268: Server shutdown already in progress.

Only one server shutdown command may be active at any one time.

Parent topic: X250 - X299


X269: Illegal shutdown parameter.

Internal error in shutdown processing. Contact Micro Focus Technical Support.

Parent topic: X250 - X299


X270: Update/Delete on invalid cursor position.

An application program tried to update or delete on an invalid cursor position. This is an internal error. If the application is a Micro Focus program, contact Micro Focus Technical Support.

Parent topic: X250 - X299


X271: The Server failed when trying to begin a thread.

The maximum number of threads allowed was exceeded. You must reconfigure the number of threads needed to a smaller number. The XDB Server Configuration utility options that affect this are:

Number of Named Pipe threads

Number of NetBIOS threads

Number of Engine threads

Parent topic: X250 - X299


X272: Cannot open file name. Increase the max number of open files in the XDB Server Configuration utility.

The specified file could not be opened because the maximum number of open files set in the server configuration was exceeded. Increase the maximum number of open files in XDB Server Configuration utility.

Parent topic: X250 - X299


X273: AuthID exceeds the maximum length.

The maximum length of an AuthID is 8 characters.

Parent topic: X250 - X299


X274: Location name exceeds the maximum length.

The maximum length of a location name is 16 characters.

Parent topic: X250 - X299


X275: Column name in explanation table name is not defined properly.

An error occurred during the insertion of a row into the explanation table. The table is improperly defined for one or both of the following reasons: columns are defined in the wrong order; or a column description is invalid because of its name, data type, length or NULL attributes. Correct the definition of the required explanation table.

Parent topic: X250 - X299


X276: Invalid number of fields (number) in explanation table name.

The explanation table does not have a valid number of fields. Correct the definition of the required explanation table.

Parent topic: X250 - X299


X277: userid does not have privilege to create with qualification authid.

The specified user attempted to create an object with an invalid AuthID. Only if your AuthID is SYSADM, DBADM or DBCTRL can you create an object with an AuthID other than your valid primary or secondary AuthID. Ensure that AuthID is one of your valid AuthIDs.

Parent topic: X250 - X299


X278: auth specified is not one of the valid AuthIDs.

The specified AuthID is not the user's current primary or secondary AuthID. Specify a valid AuthID.

Parent topic: X250 - X299


X279: Name name is too long. Maximum allowable size is number.

The specified name has exceeded the maximum allowable length of number characters. Columns, tables, views, indices, aliases and synonyms have a maximum length of 18 characters. Locations have a maximum length of 16 characters. Table qualifiers, view qualifiers, storage group names, database names, tablespace names, and constraint names specified in CREATE or ALTER TABLE statements have a maximum length of 8 characters. Volume serial numbers must contain 6 characters or fewer, and labels must contain 30 characters or fewer. Enter a shorter name for the object.

Parent topic: X250 - X299


X280: name is an undefined name.

The object specified by name does not exist in the XDB Server location. Be sure you have entered the correct name.

Parent topic: X250 - X299


X281: Object name name of object type type already exists.

There is already an object of the type specified with the name specified. Drop the existing object or enter another name for the new object.

Parent topic: X250 - X299


X282: Too many volume serial numbers specified.

The CREATE or ALTER STOGROUP command specified a list of volumes that exceeds the maximum of 133. Shorten the list of volumes specified.

Parent topic: X250 - X299


X283: The PART clause of an ALTER statement is omitted or invalid.

The ALTER TABLESPACE command or ALTER INDEX command has an invalid partition clause. Check to be sure that the tablespace or index to be altered is partitioned. If so, be sure you have identified the correct partition; if not, do not include a PART clause.

Parent topic: X250 - X299


X284: Duplicate keyword keyword.

The specified keyword has a duplicate specification in the SQL statement. Change the statement so that it only contains one specification for the keyword.

Parent topic: X250 - X299


X285: Attempt to drop stogroup used by a tablespace.

An attempt was made to drop a storage group that is being used by one or more tablespaces. You must first alter or drop all tablespaces that use the stogroup before the stogroup itself can be dropped. You can query the STORNAME field of the SYSIBM.SYSTABLEPART system table to find all tablespaces that are dependent on the stogroup.

Parent topic: X250 - X299


X286: Operation not allowed on system database.

The attempted operation may not be performed on a system database.

Parent topic: X250 - X299


X287: Alias name must not be defined on another alias.

The specified name identifies an alias, which is defined on another alias. Do not use aliases to define other aliases; they should only define base tables or views.

Parent topic: X250 - X299


X288: Statement reference to remote object is invalid.

This error can be caused by any of the following conditions:

  • An alias has been used incorrectly.
  • Multiple locations are referred to in the statement.
  • A three-part name is used in a statement that is not supported by Distributed Unit of Work. Only INSERT, UPDATE, DELETE, and SELECT statements can reference a remote location.
  • An attempt is made to logon to a mainframe location from SQL Wizard but the link or the location name is not configured correctly.
Parent topic: X250 - X299


X007: Incomplete string. Check for missing quotes.

A quote without a matching quote was found in a command sent to the SQL Engine. You may use either single or double quotes around character strings. If a single quote is to appear within a string, surround the string with double quotes. For example:

select * from employee where lname = 'O'Brien' and st = ''VA''

should be changed to:

select * from employee where lname = ''O'Brien'' and st = ''VA''
Parent topic: X000 - X049


X299: A segmented tablespace may not be partitioned.

The CREATE TABLESPACE statement contains both the SEGSIZE and NUMPARTS specification, but they are mutually exclusive.

Parent topic: X250 - X299


X300: Cannot open configuration file CONFIG.XDB. Check XDBCFG setting.

CONFIG.XDB was not found in the current directory, or in the directory specified by the XDBCFG environment variable.

Execute the following command:

SET XDBCFG=xdbpath

where xdbpathis the appropriate Micro Focus configuration directory. Make sure you specify the same directory using Options (described in the Options User's Guide).

Parent topic: X300 - X349


X301: Cannot open configuration file CONFIG.XDB. Check XDBCFG setting.

CONFIG.XDB was not found in the current directory, or in the directory specified by the XDBCFG environment variable.

Execute the following command:

SET XDBCFG=xdbpath

where xdbpathis the appropriate Micro Focus configuration directory. Make sure you specify the same directory using Options (described in the Options User's Guide).

Parent topic: X300 - X349


X302: Cannot read configuration file CONFIG.XDB.

The system is unable to open CONFIG.XDB. The file may be missing, damaged, or read-locked.

Parent topic: X300 - X349


X305: Cannot open help file name.

The file named was not found in the home directory. The `home' directory is set using Options.

Parent topic: X300 - X349


X306: Syntax error in mask definition.

The system was unable to parse a mask definition. Check the mask definition against the Options User's Guide.

Parent topic: X300 - X349


X307: Grouping character found twice or in illegal position.

The grouping character cannot appear to the right of the decimal point. A money symbol cannot appear between the grouping symbol and any numeric mask characters.

Parent topic: X300 - X349


X308: No grouping length.

No grouping character (,) was found in the mask; therefore, the grouping character cannot be reassigned.

Parent topic: X300 - X349


X309: Decimal character found twice or in illegal position.

A decimal point can only appear once in a numeric picture. Make sure you are not using a decimal point as a grouping character.

Parent topic: X300 - X349


X310: Rounding character in illegal position.

The rounding character (r) should appear as the rightmost character in a picture.

Parent topic: X300 - X349


X311: Illegal character in picture specification.

A character other than one of the characters in +-$,.9zr was found in a numeric picture specification.

Parent topic: X300 - X349


X312: "$" character found on both sides of decimal.

A dollar sign can only appear on one side of the decimal point in a money picture. Usually the dollar sign appears to the left. If the dollar sign appears to the right of the decimal point, only one dollar sign should appear.

Parent topic: X300 - X349


X313: Sign character found on both sides of the decimal.

A negative (-) or plus (+) sign can only appear on one side of the decimal point in a numeric picture. Usually the sign appears to the left of the decimal point. If the sign appears to the right of the decimal point, only one sign should appear in the picture.

Parent topic: X300 - X349


X314: Error in substitution portion of picture definition.

The decimal (.), grouping (,) and money ($) symbols are used when creating a numeric picture. You may substitute other characters for the decimal, grouping or money symbols by assigning a new value to these symbols after specifying the mask, for example:

x PIC $999,999.99 $='DM' .=',' ,='.' MASK salary $999,999.99 $='DM' .=',' ,='.'
Parent topic: X300 - X349


X315: Illegal decimal found in picture.

Cannot reassign the decimal character as requested, or the period character is not used as a decimal point in the mask portion of the picture.

Parent topic: X300 - X349


X316: Illegal rounding character found in picture.

Cannot interpret the rounding character r in its current location in the picture.

Parent topic: X300 - X349


X317: Illegal dollar sign found in picture.

Cannot reassign the money character as requested, or $ is not used as a money symbol in the mask portion of the picture.

Parent topic: X300 - X349


X318: Closing single quote not found in substitution string.

An expression assigning a new decimal, grouping or money symbol is missing a closing quote.

Parent topic: X300 - X349


X319: Value too wide for picture field.

An attempt was made to assign a value, or display a value using a picture that is unable to accommodate the value; for example, an attempt to display the value 1234 in a variable or column with a picture of 999.

Parent topic: X300 - X349


X320: Error in time/date picture definition.

The system is unable to parse a time or date picture. See the Options User's Guide for information on creating time and date pictures.

Parent topic: X300 - X349


X321: Invalid CONFIG.XDB. Run XDBPROFI to reconfigure system.

The configuration file, CONFIG.XDB, which is stored in the Micro Focus directory, has been damaged or is incompatible with the current version. Run Options as described in the Options User's Guide.

Parent topic: X300 - X349


X322: Invalid year value.

The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.

Parent topic: X300 - X349


X323: Invalid separator in value.

The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.

Parent topic: X300 - X349


X324: Invalid character in value.

The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.

Parent topic: X300 - X349


X325: Money value error.

The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.

Parent topic: X300 - X349


X326: Numeric value error.

The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.

Parent topic: X300 - X349


X008: Version number incompatibility in user exit file.

The structure being returned by the user exit procedure procedure is incompatible with this version. Contact your system administrator.

Parent topic: X000 - X049


X338: Table/View name does not exist.

The table or view named was not found in the current database. Check the database path and the name of your table or view.

Parent topic: X300 - X349


X339: Error opening file FileName for Page1 to Page2 translation.

The XDB Server was not able to open this file, which is needed for code page translation.

Make sure that this file exists on the XDB Server, that it is in the correct directory (as reported by the file's path in this message), and that there is nothing preventing the server from accessing this file. For example, check that the drive on which the file is stored is available and operational, that the file is readable, and the file is in a directory that can be accessed by the XDB Server (check permissions).

If you cannot locate this file on your system, contact Micro Focus Technical Support to obtain a copy of it.

Parent topic: X300 - X349


X340: Not enough memory to perform action.

There was not enough memory to execute the command. A smaller command may be possible. Remove all memory resident tools that you are not currently using and try again.

Parent topic: X300 - X349


X341: Illegal decimal precision.

The number has an illegal precision. Check your data and your data type; they are probably not the same.

Parent topic: X300 - X349


X342: Called function is not compatible with current version.

This error occurs only when running the COBOL Precompiler. You must precompile and compile your program again for compatibility.

Parent topic: X300 - X349


X343: An explicit COMMIT is illegal in an IMS/CICS program.

IMS/CICS performs an implicit COMMIT. This is mainframe-compatible.

Parent topic: X300 - X349


X344: An explicit ROLLBACK is illegal in an IMS/CICS program.

IMS/CICS performs an implicit ROLLBACK. This is mainframe-compatible.

Parent topic: X300 - X349


X345: A negative or zero ABSOLUTE FETCH is illegal.

An absolute fetch needs a value specifying the offset from the current cursor position, and the offset must be a positive number.

Parent topic: X300 - X349


X346: Cannot locate files in the directory specified.

Files needed by the system cannot be found in the path specified by the XDBPATH environment variable. Make sure that you have specified the correct directory in the XDBPATH environment variable. Also make sure that your server names match in Options and the XDB Server Configuration utility.

Parent topic: X300 - X349


X347: Illegal function code passed to the COBOL interface.

Internal error. Contact Micro Focus Technical Support.

Parent topic: X300 - X349


X348: No application path specified.

There is no application path specified in CONFIG.XDB. IMS/CICS performs an implicit ROLLBACK. This is mainframe-compatible.

Parent topic: X300 - X349


X352: Server violation.

The server experienced a protection exception while processing a user's command. The exception handling code has rolled back the user's current transaction and logged the user out.

Parent topic: X350 - X399


X354: Error loading server communications DLL(name).

Make sure you have the DLL named in the correct DLL subdirectory.

Parent topic: X350 - X399


X355: Error connecting to remote server(name).

An error has occurred while trying to connect to server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.

Parent topic: X350 - X399


X356: Error sending to remote server(name).

An error has occurred while trying to send to server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.

Parent topic: X350 - X399


X357: Error receiving from remote server(name).

An error has occurred while trying to receive from server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.

Parent topic: X350 - X399


X358: Governor limit exceeded.

One of the governor limits has been exceeded, and the server logged out the user. You could increase the governor limit for that user. The governor will be active only if the server security is ON.

Parent topic: X350 - X399


X359: Error initializing remote server gateway.

An error has occurred while trying to connect to a remote server.

Check the following:

  • Verify that the system catalog on the local server contains a server-to-server definition for the remote server and that that definition is correct.
  • Ensure that xdb\GTWY40n.DLL exists on the local server.

Also, if your local server is running as an application (rather than as a service), use the Server Configuration Utility to verify that the Remote Threads parameter is set to a value greater than 0.

See the XDB Server Administration Guide for additional information about specifying remote threads and establishing server-to-server connectivity.

Parent topic: X350 - X399


X360: Incorrect version of the server configuration file.

You have an old version of SRVCONFG.XDB. Delete your old SRVCONFG.XDB and run the new XDB Server Configuration utility to create a new one.

Parent topic: X350 - X399


X361: No remote thread available to process request.

A client has tried to connect to a remote server and the primary server does not have any thread available to handle the request. In these cases, there are no remote threads set for the primary server, or all the remote threads are already in use.

Parent topic: X350 - X399


X362: Index error during recovery.

While XDB Server was recovering a location, a fatal error occurred. You must compact and re-index the location immediately. Do not use the location until the compact and re-index has finished.

Parent topic: X350 - X399


X363: No protocol threads available to process request.

The number of protocol threads for TCP/IP, SPX, or Named Pipes must equal the number of users using the protocol.

Parent topic: X350 - X399


X364: The describe statement does not identify a prepared statement.

In order to describe a query, the query must first be prepared.

Parent topic: X350 - X399


X365: Log path cannot be set to path.

The logging system cannot set the log to the path specified. Ensure that the path exists, and that there are no other logs present in the path.

Parent topic: X350 - X399


X366: Error replacing alias name with actual table name.

XDB Server encountered an internal error when forming the alias substitution string. Contact Micro Focus Technical Support with the details of the query.

Parent topic: X350 - X399


X367: GROUP BY/HAVING not allowed in subquery/embedded select.

XDB Server and DB2 does not allow a GROUP BY or HAVING clause on a nested query.

Parent topic: X350 - X399


X035: Length of input host variable number number is invalid.

The length of the specified host variable is too long or too short.

If you are using VARCHAR fields, make sure that the length of the VARCHAR field is correct.

Parent topic: X000 - X049


X037: Invalid timeout specification.

Timeout specification should be an integer greater than 0 and less than 32,767.

Parent topic: X000 - X049


X038: Cannot acquire read/write access on specified path.

Unable to read or write any files on a path the system has tried to access as result of a command you issued. If using a network file server, check the current user's privileges. If using a multiuser system, make sure another user is not accessing the file.

Parent topic: X000 - X049


X039: Abort code.

The system aborted the current operation upon receipt of an abort code. When you press Esc in most environments, programs send an abort code to the SQL Engine, instructing it to terminate the transaction it is currently processing for you. A partial result may be displayed in some modules. Incomplete transactions involving updates, inserts or deletes are rolled back if the backward log is turned on. You can specify the abort characters through Options.

Parent topic: X000 - X049


X040: Log system couldn't operation.

An operation in the log system has failed.

If operation is a file-related operation, check that there is nothing preventing the log file from being used. For example, check that there is disk space available to write the log file. Also check that the log file is not write-protected or opened for exclusive use. If the problem with the log file is not apparent, contact Micro Focus Technical Support.

If operation is an internal operation, contact Micro Focus Technical Support.

Parent topic: X000 - X049


X041: Left side of expression incompatible with right side.

The system is unable to compare the left hand side of an expression to the right hand side of the expression. This is generally due to incompatible data types (e.g. comparing a time field to a date field).

Parent topic: X000 - X049


X042: Field type not compatible with nested query results.

The field type of a nested query result is not compatible with the field type it is being compared to.

Parent topic: X000 - X049


X043: Aggregate function on invalid type.

An attempt was made to find a numeric aggregate function result for a non-numeric field (e.g. AVG of a character field.)

Parent topic: X000 - X049


X044: Invalid data type indicator.

The SQL Engine received an invalid data type indicator from the calling program. This problem is generally due to a programming error in user programs that use one of the language interfaces. Refer to interface documentation for valid data type indicators.

Parent topic: X000 - X049


X045: Invalid element in structure structure in function function.

The values structure in CAPI function Xdbxputrec() contains invalid information. Length may be out of range, or type may be invalid.

Parent topic: X000 - X049


X072: Cannot nest aggregate functions.

Aggregate functions cannot be nested one inside the other. For example, you cannot select:

AVG(SUM(a))
Parent topic: X050 - X099


X073: Fields selected must appear in GROUP BY clause or inside an aggregate function.

If a query selects an aggregate function, any field appearing outside the aggregate function in the SELECT clause must also appear in the GROUP BY clause of the query. This is a common cause of confusion; although users may think they do not want to group a result by a particular column, they often find that adding the column name to the end of the GROUP BY clause yields the desired result.

Parent topic: X050 - X099


X074: GROUP BY clause invalid on current query.

A GROUP BY clause can only be used if the SELECT clause of the query includes one or more column names, or one or more aggregate functions (such as COUNT, and AVG.)

Parent topic: X050 - X099


X075: Cannot mix fields with aggregates without GROUP BY.

If a query selects an aggregate function, any field appearing outside the aggregate function in the SELECT clause must also appear in a GROUP BY clause.

Parent topic: X050 - X099


X076: Luname servername does not exist in tablename SYSLUNAMES table.

You are inbound/outbound mapping to or from a server name that does not exist in SYSLUNAMES. Insert a record for that server name in the SYSLUNAMES table or insert a dummy generic record with blanks.

Parent topic: X050 - X099


X077: Cannot include join in table expansion.

PREVIOUS clause cannot be used on a join.

Parent topic: X050 - X099


X078: Illegal level value for table expansion.

LEVEL clause specifies a non-positive or non-integer level, or a level beyond the maximum recursive relationship level.

Parent topic: X050 - X099


X079: Insert/Delete/Update function not allowed on sorted query.

You cannot perform a positioned update/insert/delete on a query that requires sorting. Queries that may require sorting are those involving ORDER BY, GROUP BY, DISTINCT, and UNION.

Parent topic: X050 - X099


X080: Only one DISTINCT clause allowed per query.

XDB Server only allows one DISTINCT clause per query. For example, you cannot:

SELECT count(distinct sno),count(distinct pno) FROM partsupp

Parent topic: X050 - X099


X081: Exceeds maximum number of UNIONed queries.

A maximum of 32 subselects may be connected by the UNION operator (i.e. UNION should appear no more than 31 times in a command).

Parent topic: X050 - X099


X108: Field list must be provided when expressions are selected.

The SELECT clause of commands that define views can contain expressions only if the resulting columns are explicitly named. For example:

CREATE VIEW myview(employee, currentpay, afterraise) AS SELECT lname, payrate, payrate*1.10 FROM employee

Because payrate*1.10 is an expression, column names must be provided in the CREATE VIEW clause of the command.

Parent topic: X100 - X149


X110: Cannot operation logfile filename. Check logpath setting.

An operation on the logfile named filename has failed. Check the log path in the SYSXDB.SYSLOCALS table to see if it is pointing to the correct directory. Also check to see that there is still disk space left for writing the file.

Parent topic: X100 - X149


X111: Maximum number records per table in trial version.

You are running the SQL Engine shipped with Learn, which limits the number of records in tables. The record limit includes deleted records that have not been removed using COMPACT. If you need to add more records to the table you must have a full version of XDB Server.

Parent topic: X100 - X149


X112: Cannot perform operation (errno) on index index-name.

An attempt to read/write/seek/open on the files that make up the index named failed. Check to see that the files index-name.IDX and index- name.PTR exist in the database directory. Check whether there is sufficient disk space to write to the index files. Check whether the file has been read or write protected. Increase the number of files in CONFIG.SYS to more than 100. See X001 for a description of operation errors.

Parent topic: X100 - X149


X113: Cannot perform operation (errno) on table table-name.

An attempt to read/write/seek on the files that make up the table named failed. Check to see that the file table-name.TAB exists in the database directory. Check whether there is sufficient disk space to write to the index files. Check whether the file has been read or write protected. See X001 for a description of operation errors. Compact the table (or drop it) and rebuild the indices.

Parent topic: X100 - X149


X114: Cannot close current database. Please exit.

Internal error code. Please contact Micro Focus Technical Support.

Parent topic: X100 - X149


X115: Location already exists in the path specified.

XDB Server permits one location per directory. XDB Server locations must be given unique names. This error condition occurs if you attempt to create a location in a directory that already contains a location, or if you attempt to create a location using a location name found in the SYSXDB.SYSLOCALS table.

Parent topic: X100 - X149


X116: Time value error.

An attempt was made to process a command containing an invalid time value. Check time picture specification.

Parent topic: X100 - X149


X117: Maximum number of open locations exceeded.

Maximum number of locations open exceeds the number specified through the XDB Server configuration.

SQLWizard Notes: Each time you query a location, the system holds the location open, and it is counted as a "location in use." The XDB Server Configuration program lets you specify the maximum number of concurrent "locations in use" allowed by the XDB Server.

To increase the maximum number of open locations, start your XDB Server Configuration program and set the "Maximum Locations" value to a relatively large number, such as 50. Then, restart your server to put this value into effect.

Parent topic: X100 - X149


X118: Location name table already exists.

XDB Server permits one location per directory. XDB Server locations must be given unique names. This error condition occurs if you attempt to create a location in a directory that already contains a location, or if you attempt to create a location using a location name found in the SYSXDB.SYSLOCALS table.

Parent topic: X100 - X149


X145: Key key not found when analyzing referential constraint.

One of the keys involved in a referential constraint is missing. You must create a key before you can refer to it in a FOREIGN KEY constraint.

Parent topic: X100 - X149


X146: Violation of constraint between key key1 and key key2.

An attempt to update, insert or delete a record violates a FOREIGN KEY constraint involving the keys listed. See the ALTER command description in the SQL Reference for a description of FOREIGN KEY.

Parent topic: X100 - X149


X147: Cannot find key key.

The command references a key that does not exist. You must create a key before you can refer to it in a FOREIGN KEY constraint.

Parent topic: X100 - X149


X148: Primary key key already exists on this table.

Only one PRIMARY KEY is permitted per table; other candidate keys may be defined as UNIQUE.

Parent topic: X100 - X149


X149: Primary/Unique key fields must be specified as NOT NULL.

Before creating a PRIMARY KEY, you must specify that the fields involved are NOT NULL. You can do this through the Create/Alter Table module, or by using the ALTER command.

Parent topic: X100 - X149


X150: Referenced fields must be specified as NOT NULL.

Before you can create a FOREIGN KEY, you must specify that the referenced fields involved are NOT NULL. You can do this through the Create/Alter Table module, or by using the ALTER command.

Parent topic: X150 - X199


X151: Location path exceeds maximum length of 48.

Path names are restricted to 48 characters in length.

Parent topic: X150 - X199


X152: Invalid transaction number.

Internal error code. Contact Micro Focus Technical Support.

Parent topic: X150 - X199


X153: No space for locks.

There is no space to record additional record locks. If the transaction requires many locks on the same table, it is a good idea to lock the entire table, instead of attempting to lock each record. In multi-user XDB Server versions the size of lock tables can be configured through the XDB Server Configuration program.

Parent topic: X150 - X199


X154: Cannot find table/record lock.

Internal error code. Contact Micro Focus Technical Support.

Parent topic: X150 - X199


X181: Cannot truncate index file.

When deleting all records from a table using the DELETE FROM table-name command, the tables and indices are simply truncated. An error occurred when attempting to truncate a file. Check your disk.

Parent topic: X150 - X199


X182: Cannot perform table on forward log file name.

An error occurred when attempting to read, write, search or truncate the forward log file specified. Check your disk. See X001.

Parent topic: X150 - X199


X183: Cannot perform operation on backward log file name.

An error occurred when attempting to read, write, search or truncate the backward log file specified. Check your disk. See X001.

Parent topic: X150 - X199


X184: Illegal outer join conditions.

Only five outer join conditions per query are currently permitted.

Parent topic: X150 - X199


X185: FOR UPDATE OF not allowed with GROUP BY or ORDER BY clause.

The FOR UPDATE OF clause cannot be used on a query that is not updateable. GROUP BY and ORDER BY queries are not updateable.

Parent topic: X150 - X199


X186: Maximum number of open files exceeded.

The system cannot process the current command because it is unable to open another file. You may need to close some queries, remove some indices from your table, or change the limit on the number of concurrently open files. In DOS, the number of files that can be concurrently opened by the system is specified in your computer's CONFIG.SYS file, as described in your Installation documentation.

Parent topic: X150 - X199


X187: Referenced key and foreign key must have same number of fields.

When defining a FOREIGN KEY, you must reference an existing key with the same number of fields.

Parent topic: X150 - X199


X188: Attempt to place NULL value in host variable with no indicator variable.

Embedded SQL only. If you retrieve a NULL value, you must have a special null indicator variable assigned for it. See the SQL Reference for further information.

Parent topic: X150 - X199


X189: Source and Target locations have the same name.

This error occurs when two locations with the same name exist in a system, and an attempt is made to copy a table from one to the other. You should rename one of the locations before attempting the copy.

Parent topic: X150 - X199


X190: Cannot copy table/view to itself.

XDB Server does not permit the same table to be used as the source and target for a copy operation. This error may occur when two databases with the same name exist in a system, and an attempt is made to copy a table from one to the other. Rename one of the databases before attempting the copy.

Parent topic: X150 - X199


X218: Referenced table does not contain a primary key.

The table nominated as the parent in a FOREIGN KEY clause cannot be defined as a parent because it does not have a primary key defined. Correct the statement so that the table nominated as the parent in the FOREIGN KEY clause references a table with a primary key, or define a primary key for the table nominated as parent.

Parent topic: X200 - X249


X219: Relationship name name already exists on this table.

The constraint name specified in the FOREIGN KEY must be unique among all constraint names specified for this table. Change the name to one that is unique.

Parent topic: X200 - X249


X220: Operation not allowed on table with incomplete definition.

The reference to the table is invalid because it has a primary key, but no primary index. The reference is in a FOREIGN KEY clause or an SQL manipulative statement. Define a unique primary index on the table before referencing it.

Parent topic: X200 - X249


X221: ALTER TABLE PRIMARY KEY requires existing unique index.

The ALTER TABLE statement is invalid because the table does not have a unique index with a key that is identical to the nominated PRIMARY KEY. Make sure the key list specified on the ALTER TABLE statement identifies an existing unique index of the table.

Parent topic: X200 - X249


X222: Relationship name must be less than 8 characters.

The relationship name specified in the FOREIGN KEY clause is too long. Shorten the name to 8 characters or less.

Parent topic: X200 - X249


X223: Self-Referencing tables must use the CASCADE delete rule.

The delete rule specified in the FOREIGN KEY clause of the ALTER statement is invalid. A self-referencing constraint must specify the delete rule of CASCADE. Change the delete rule in the FOREIGN KEY clause.

Parent topic: X200 - X249


X224: One or more foreign key fields must be nullable for SET NULL rule.

The SET NULL clause of the FOREIGN KEY statement is invalid because no column of the key allows NULL values. Change a column of the key to allow NULL values, or change the delete rule.

Parent topic: X200 - X249


X225: Primary key clause does not exist.

The ALTER DROP PRIMARY KEY command was attempted on a table that does not contain a primary key.

Parent topic: X200 - X249


X226: Relationship name name cannot be found in system table SYSREF.

The ALTER DROP FOREIGN KEY command specified a constraint name that could not be found on the SYSREF table. Check the name to make sure it is a valid constraint name.

Parent topic: X200 - X249


X227: Attempt to update parent having dependents in relationship name.

An UPDATE operation attempted to update a primary key in the specified row of the object table; however, the primary key in the specified row had dependent rows associated with it. The value of a primary key in a parent row cannot be updated if the parent row has dependent rows. Examine the primary key of the object table and the foreign key of the dependent table to determine if the value of the primary key should be changed. If this does not solve the problem, examine the contents of the object table and the dependent table to determine the cause of the problem.

Parent topic: X200 - X249


X253: Compact cluster by clause must specify existing clustered index.

When using the CLUSTER BY clause in a COMPACT statement, and the table has a clustered index, then you must specify the clustered index that already exists. If the table does not have a clustered index, then any index can be specified.

Parent topic: X250 - X299


X254: DUPQTY value must be 8, 16, 32, 64 or 128.

The only legal values when using the DUPQTY clause are 8, 16, 32, 64 and 128.

Parent topic: X250 - X299


X255: Communication Manager out of memory.

The XDB Server ran out of memory. You may want to reconfigure your system to increase available memory. See the XDB Server Administration Guide for specific performance tuning procedures.

Parent topic: X250 - X299


X256: Stored Procedure ProcName failed due to reason ReasonCode.

The XDB Server is not able to execute the CALL statement for the stored procedure ProcName.

If ReasonCodeis... | The problem is that...
00E79000 | A value in either SYSIBM.SYSROUTINES or SYSIBM.SYSPARMS is invalid. This is an internal error. Please contact Product Support.
00X10000 | Too many parameters. The maximum number of parameters is 750.
00X10001 | The SQL Option Server supports COBOL and C stored procedures.
00X10002 | The attempted operation was not supported. A common cause of this is that access to a remote location was attempted without the proper XDB.INI configuration.
00X10003 | The stored procedure exceeded the number of result sets. The maximum number is 50.
00X10004 | The operating system rejected a request to create a pipe used to invoke the stored procedure. Please contact Product Support.
00X10005 | The operating system rejected a request to create a pipe used to invoke the stored procedure. Please contact Product Support.
00X10006 | The operating system rejected a request to create the stored procedure process. Please contact Product Support.
00X10007 | A write to the stored procedure communications pipe by the server has failed. This typically indicates the stored procedure has abnormally exited.
00X10008 | A read from the stored procedure communications pipe by the server has failed. This typically indicates the stored procedure has abnormally exited.
00X10009 | An internal error has prevented the stored procedures communications layer from initializing. Please contact Product Support.
00X10010 | An unknown element was passed in the SQL statement that is calling the stored procedure. Please contact Product Support.
Parent topic: X250 - X299


X257: Engine configuration maximums too large. Reconfigure them smaller.

The configuration parameters for Windows must fit into 64K. The options selected require more than 64K. Use the XDB Server Configuration utility to reconfigure the options.

Parent topic: X250 - X299


X258: Out of memory for expressions.

The total amount of memory required by the query for expressions exceeded the maximum memory that can be supported by XDB Server.

Parent topic: X250 - X299


X259: Error on Operation (size) Server (server).

An error has occurred with server-to-server access.

Parent topic: X250 - X299


X260: Operation cannot be performed on current location version.

The current location format does not include support for the command. Creating a new location or upgrading the system location will bring the current location version up to date.

Parent topic: X250 - X299


X261: Redirector not loaded!

The redirector associated with the selected protocol is not currently running. If your protocol is currently set to NetBIOS, run the NetBIOS redirector.

Parent topic: X250 - X299


X262: Invalid parameter. A valid window handle was expected.

A valid window handle is not zero. Pass a valid window handle returned from the CreateWindow() function.

Parent topic: X250 - X299


X289: Invalid value specified for keyword keyword.

The value specified for the keyword is invalid. See the SQL Reference for valid keyword values.

Parent topic: X250 - X299


X290: Keyword keyword not allowed for tablespace in workfile database.

The specified keyword cannot be used for a tablespace in the workfile database. Change the SQL statement.

Parent topic: X250 - X299


X291: Illegal use of keyword keyword.

A syntax error exists in the SQL statement at the point where the specified keyword appears. Check the statement for errors.

Parent topic: X250 - X299


X292: Unable to perform operation operation on database name.

The requested operation is not legal or valid on the specified database.

Parent topic: X250 - X299


X293: Table/Index ObjectName in use.

The XDB Server cannot execute the STOP DATABASE command because the specified table or index is being used.

To restrict access to a database using the STOP DATABASE command, you must issue the command while the table or index is not is use.

Parent topic: X250 - X299


X294: Unable to operation stopped database name.

It is illegal to perform the specified operation on the specified stopped database.

Parent topic: X250 - X299


X295: Database ROSHARE can only be altered from OWNER to NONE.

XDB Server only supports the altering of Read-Only Shared Databases from a value of OWNER to a value of NONE. You must create a new ROSHARE database in order to obtain other share options.

Parent topic: X250 - X299


X296: Location name is not converted. Run location conversion program.

The location specified is not compatible with the current version of the XDB Server database engine. You must convert the location by running the XDB Server conversion program CONVERT.EXE.

Parent topic: X250 - X299


X297: FOR FETCH ONLY and FOR UPDATE OF are mutually exclusive clauses.

You cannot specify both a FOR FETCH ONLY clause and a FOR UPDATE OF clause in your query. If a cursor is to be both fetched and updated you should not specify either clause in the SELECT statement.

Parent topic: X250 - X299


X298: Synonym target must include an explicit authorization ID.

The object to which a synonym applies must specify a two-part name that includes a valid AuthID. Modify the table or view name to include an AuthID.

Parent topic: X250 - X299


X327: Integer value error.

The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.

Parent topic: X300 - X349


X328: No more RAM memory available.

Insufficient RAM available to continue processing. Remove unnecessary programs from memory. For example, bypass the Loader or the Micro Focus application menu.

Parent topic: X300 - X349


X329: COMMAND.COM not found.

Please contact Micro Focus Technical Support.

Parent topic: X300 - X349


X330: Cannot execute program.

An error occurred when attempting to use the shell facility to temporarily exit to the operating system (possibly insufficient memory). In order to reach the operating system, you will have to exit normally, instead of using the shell facility.

Parent topic: X300 - X349


X332: Index name does not exist.

The index named was not found in the current database. Check the database path and the name of your index.

Parent topic: X300 - X349


X333: Unknown field type in table name.

An unknown field type was found. A different version of XDB Server may have been used to create the table, or the system path may be set to an earlier version. Check the version.

Parent topic: X300 - X349


X334: Index name has been damaged.

Either the named index has been damaged or a different version of XDB Server is running than the one that created the index. Use the version that created the index. The system path may be set to an earlier version. Check the version.

Parent topic: X300 - X349


X335: Key name does not exist.

The key named was not found in the current database. Check the database path and the name of your key.

Parent topic: X300 - X349


X336: Key name has been damaged.

Either the named key has been damaged or a different version is running than the one that created the key. Use the version that created the key. The system path may be set to an earlier version. Check the version.

Parent topic: X300 - X349


X337: Synonym name does not exist.

The synonym named was not found in the current database. Check the database path and the name of your synonym.

Parent topic: X300 - X349


X368: Illegal string string found.

XDB Server received a different string than it expected. For example: SET CURRENT RULES <parm> must be either DB2 or STD. Using a different parameter will return an x368.

Parent topic: X350 - X399


X369: Invalid index type.

The index type must be 1 or 2.

Parent topic: X350 - X399


X370: The target location needs to be compatible with DB2 version version.

An attempt was made to perform new DB2 functionality against an XDB Server location that was created with this functionality. See the ALTER LOCATION command and CREATE LOCATION command in the SQL Reference .

Parent topic: X350 - X399


X371: The selected locksize and lockmax options do not match.

The DDL is illegal. See the SQL Reference for correct values.

Parent topic: X350 - X399


X372: Illegal attempt to convert location to a lower version.

An ALTER LOCATION can only be used to move forward in DB2 functionality, not backwards (i.e., an ALTER LOCATION cannot be used to convert a location to a lower version).

Parent topic: X350 - X399


X373: Invalid number of parameters (number expected) for stored procedure ProcName.

The number of parameters specified in your SQL CALL statement exceeds the number of parameters allowed by the ProcName stored procedure.

Verify that the PARMLIST column in the SYSIBM.SYSPROCEDURES table specifies the correct number of parameters for your stored procedure.

  • If the PARMLIST value is incorrect, correct it.
  • If the PARMLIST value is correct, edit the SQL CALL statement to pass the correct number of parameters to the stored procedure.
Parent topic: X350 - X399


X374: Stored procedure ProcName received a null value for parameter number.

The SQL CALL statement for stored procedure ProcName contains a null value in its parameter list, and this stored procedure does not accept null values.

Verify that the LINKAGE column in the SYSIBM.SYSPROCEDURES table correctly specifies whether ProcName can accept null values.

  • If ProcName can accept null values, set the LINKAGE value to N.
  • If ProcName cannot accept null values, make sure the LINKAGE value is blank. Then correct your CALL statement so that it passes a non-null value for parameter number.
Parent topic: X350 - X399


X375: Stored procedure ProcName has been placed in a must rollback state.

The stored procedure ProcName issued one of the following operations:

  • CALL
  • COMMIT
  • CONNECT
  • RELEASE
  • ROLLBACK
  • SET CURRENT SQLID

These operations are not allowed in a stored procedure.

To eliminate this error, remove the invalid operation from the stored procedure.

Parent topic: X350 - X399


X376: Missing OBID clause when creating a table in a ROSHARE READ database.

The OBID clause was not specified in the CREATE TABLE command. The OBID clause is required whenever the database containing the table is defined as ROSHARE READ.

Parent topic: X350 - X399


X377: A privilege cannot be revoked because it is not possessed by AuthID authid.

An AuthID can revoke only the privileges that it has explicitly granted to other AuthIDs, unless the AuthID has SYSADM or SYSCTRL authority and specifies the BY clause.

Check the appropriate authorization catalog tables to verify that the AuthID possesses the privilege to be revoked. Correct and reissue the REVOKE statement.

Parent topic: X350 - X399


X378: Attempt to disable login with security off.

A DISABLE LOGIN command was issued while security was off on the XDB Server.

Enable security using the XDB Server Configuration utility, then disable the login.

Parent topic: X350 - X399


X379: The login was rejected due to logins being disabled.

The database administrator has disabled logins for this XDB Server, so your login command was rejected.

Contact your database administrator for assistance.

Parent topic: X350 - X399


X380: The XDB Server has rejected this connection due to load balance requirements.

Your connection request was rejected because the XDB Server has exceeded the load balancing limits configured by the database administrator.

Contact your database administrator for assistance.

Parent topic: X350 - X399


X381: Cannot connect with requested location. Location is offline.

The location you have requested is currently offline. (Your database administrator may have taken it offline for maintenance purposes.)

Try connecting to the location at a later time. If this error persists, contact your database administrator for assistance.

Parent topic: X350 - X399


X382: Cannot take requested location offline. Location is in use.

The XDB Server cannot take the requested server offline because it is being used. You are allowed to take a location offline only when there are no users attached to it.

Wait until the active users finish processing then take the location offline (You may want to use the DISABLE LOGIN command to prevent new users from logging on to the server). If you need to take the location offline immediately, you can force the active users off the location using the Monitor utility.

Parent topic: X350 - X399


X383: Sequence error for reason code (ReasonCode) Message.

The XDB Server has received a request out of order.

If ReasonCode/Message is... The problem is that...
(1) Performed connection operation while not logged in. The XDB Server received a database request from a client program that has not yet connected or has already disconnected from the database. Often this problem is caused by faulty logic in a user program.

Check the code in your program to ensure that all connect/disconnect sequences occur in the correct order. For example...

  • Make sure that your program checks for SQLConnect failures, and that it doesn't continue to issue requests to the server when a connection failure occurs.
  • If it is a JDBC program, check that it does not call any other method in the connection class after calling the close( ) method. close( ) must be the last method called by a database transaction.
  • If it is an ODBC program, check that it does not use a connection handle before it calls SQLConnect( ) or after it calls SQLDisconnect( ).
Parent topic: X350 - X399


X384: Invalid handle.

The XDB Server has received an invalid handle. This is an internal error.

Do the following:

  • Record the version of the XDB Server software.
  • Note whether you are using JDBC or ODBC software and record which version you are using.
  • Make a note of the operation that failed.
  • Contact Micro Focus Technical Support.
Parent topic: X350 - X399


X385: Login error with Reason Code ReasonCode Message (returned Number).

An error has occurred while logging on to the XDB Server through the Direct Flight software.

If ReasonCode/Message is... | The problem is that...
1 Get Receipt Failed | The internal call to Xdbxgetrcpt( ) failed because of a Number error. See error Number for additional information and corrective action.
2 Profile Query Failed The query of SYSPROFILES failed during execution of Xdbxcommand.

Do the following:

  • Check for problems with the SYSXDB.SYSPROFILES table in the system location (confirm, for example, that it was created and hasn't been dropped).
  • Check that you have correctly specified the values for the SYSTEM location and for the SYSPROFILES authid in the URL and/or the Properties Object passed to DriverManager.getConnection.
  • Verify that you have privileges to access SYSXDB.SYSPROFILES.

See also error Number for additional information and corrective action.

If you cannot resolve the problem, contact Micro Focus Technical Support and provide them with the following information:

  • The versions of client and server software you are using.
  • The JDBC URL you have specified
  • Properties you have set in the Properties Object
3 Set Status Failed | The internal call to Xdbxstatus( ) failed because of a Number error. See error Number for additional information and corrective action.
5 System Open Failed | The internal call to Xdbxopen( ) failed because of a Number error. See error Number for additional information and corrective action.
6 Profile Fetch Failed The fetch from SYSXDB.SYSPROFILES failed during execution of Xdbxfetch.

Do the following:

  • Check for problems with the SYSXDB.SYSPROFILES table in the system location (corrupt records, for example).
  • Verify that you have privileges to access SYSXDB.SYSPROFILES.

See also error Number for additional information and corrective action.

If you cannot resolve the problem, contact Micro Focus Technical Support and provide them with the following information:

  • The versions of client and server software you are using.
  • The JDBC URL you have specified
  • The properties you have set in the Properties Object
7 Initialize Autocommit Failed | The internal call to turn on autocommit failed because of a Number error. See error Number for additional information and corrective action.
9 Close Failed | The internal call to Xdbxclose( ) failed because of a Number error. See error Number for additional information and corrective action.
10 Open Initial Location Failed The internal call to open the primary location (as specified by the location property) failed.
  • Check that a record exists in SYSXDB.SYSPROFILES for the profile name and location you are attempting to use.
  • Check that you have specified the location correctly in the URL or in the Properties Object (jet.dfjdbc.profile.location).

See error Number for additional information and corrective action.
14 Set Package Set Failed The internal call to set the Package Set Id (as specified by the packageset property) failed.
  • Check that a record exists in SYSXDB.SYSPROFILES for the profile name and package set you are attempting to use.
  • Check that you have specified the package set correctly in the URL or in the Properties Object (jet.dfjdbc.profile.packageset). See Getting Started with JetExpress for more information about the Properties Object

See error Number for additional information and corrective action.
Parent topic: X350 - X399


X386: Conflicting definitions for the same variable or parameter. Description

The SQL Server has received a parameter or host variable from the client application that does not match the data type it expected.

If this error occurs in a stored procedure, check that the parameters passed to the XDB Server match the procedure's parameter definitions in SYSIBM.SYSPROCEDURES. If this error occurs in an SQL statement, check that the variables it passes to the XDB Server match the data type the XDB Server expects.

Parent topic: X350 - X399


X392: Your SQL Option (for DB2 emulation) has expired.

The XDB component (e.g., XDB Server, XDB Link) you are attempting to use does not have a valid license from Micro Focus.

Contact Micro Focus Technical Support.

Parent topic: X350 - X399


X393: Output host variable PositionNumber is incompatible with the query result.

The XDB Server is not able to return the result of a CALL, FETCH, or SELECT statement because the data type of the variable at PositionNumber in the output SQLDA (to which the result was to be written) does not match the data type of the result.

Check your source code to ensure that it is writing its results to the correct output variable and that the data type of that variable is compatible with the expected result.

Parent topic: X350 - X399


X394: Input host variable PositionNumber is incompatible with the current query.

The XDB Server is not able to execute the requested SELECT statement because it contains a host variable whose data type is not correct. (For example, the WHERE clause may be using a numeric host variable to select from a DATE field in the database.) The host variable causing the problem is located at PositionNumber in the input SQLDA.

Check your source code to ensure that your SELECT statement specifies the correct host variable and that this variable's data type is compatible with database field with it is being used.

Parent topic: X350 - X399


X395: Value for data type Type is out of range for host variable PositionNumber.

The XDB Server cannot return the requested value because the returned value is larger than the host variable at PositionNumber in the output SQLDA (to which the value was to be written) can accept.

Check your source code to ensure that it specifies the correct host variable for this result and that the data type of this variable is large enough to hold the value produced by the database.

Parent topic: X350 - X399


X396 ColumnName is not a column of specified table or view in the query.

The specified name is not a column in the table or view referenced. A bad column name in a FOR UPDATE OF clause can generate this error.

Parent topic: X350 - X399


X397 Decimal host variable or parameter Identifier contains non-decimal data.

Data could not be used as specified in the statement because the data is not valid for this type.

Parent topic: X350 - X399


X398 ColumnName is not an updateable column; it is not identified in the update clause.

In order to update this column, you need to specify its name in the FOR UPDATE OF clause for this cursor.

Parent topic: X350 - X399


X399 Improper use of long string data, StringValue.

The operation is not supported on a long string value in DB2 mode.

Parent topic: X350 - X399


X400 Named cursor already assigned to a result set locator.

The named cursor could not be reused.

Parent topic: X400 - X449


X401 Statement can't be issued until the stored procedure has been called.

Either a DESCRIBE PROCEDURE or an ASSOCIATE LOCATOR statement has been executed prior to the CALL to the stored procedure.

Parent topic: X400 - X449


X402 Invalid result set locator.

The result set locator was never assigned a valid value. Result set locators are returned by the ASSOCIATE LOCATORS statement.

Parent topic: X400 - X449


X403 Cursor name CursorName was not defined.

The named cursor was not defined.

Parent topic: X400 - X449


X404 A Rollback is required.

The transaction is in a must rollback state.

Parent topic: X400 - X449


X405 An ON clause in a JOIN operator is invalid.

An ON clause used to specify a JOIN condition is invalid. VALUE/COALESCE functions are only allowed in FULL OUTER JOINs. Only an '=' operator is valid in FULL OUTER JOINs. Also, column may be inappropriately referenced from within the JOIN clause.

Parent topic: X400 - X449


X406 Stored procedure StoredProcName parameter ParameterName is larger than declared.

The stored procedure has used a value that is too large for the definition declared in the SYSIBM.SYSPROCEDURES PARMLIST field.

Parent topic: X400 - X449


X407 Stored procedure StoredProcName requires a host variable for parameter ParameterName.

The parameter in the stored procedure PARMLIST definition in SYSIBM.SYSPROCEDURES is defined as OUT or INOUT. A host variable must be supplied in the call for that parameter.

Parent topic: X400 - X449


X408 Stored procedure StoredProcName did not return result sets.

The stored procedure has not returned any results sets to the caller. Verify that the stored procedure has been coded correctly.

Parent topic: X400 - X449


X387: Option conflict with location rules

The statement being executed has an option that is incompatible with the current location type.

Parent topic: X350 - X399


X388: Invalid token 'token' found in PARMLIST for procedure proc-name

A Stored Procedure or Trigger definition has a syntax error.

Parent topic: X350 - X399


X389: Illegal operation on temporary table

The current operation is not allowed on a temporary table. Temporary tables are not allowed to have primary/unique keys, or to be referenced by foreign keys. Also, update/delete operations on records in temporary tables are not allowed.

Parent topic: X350 - X399


X390: Check option not allowed on temporary table

A view of a temporary table must not specify the CHECK OPTION clause.

Parent topic: X350 - X399


X391: WITH DEFAULT clause not allowed on CREATE GLOBAL TEMPORARY TABLE

WITH DEFAULT clauses are not allowed on a CREATE GLOBAL TEMPORARY TABLE statement.

Parent topic: X350 - X399


X409: Error in trigger trigger-name, section number trigger-section

A trigger trigger-name executed during an INSERT, UPDATE, or DELETE statement contained an SQL statement that returned an SQL error. The section number trigger-section identifies the statement in error.

Parent topic: X400 - X449


X410: Function function-name named without signature, function not unique

The signature of the user defined function function-name is not unique within its schema. Either the CURRENT PATH must be changed or the SPECIFIC name of the function must be used.

Parent topic: X400 - X449


X411: Signature for function function-name not unique within schema

The function function-name that is being created does not have a unique signature within the schema.

Parent topic: X400 - X449


X412: Set transition variable is used for before trigger per row only

SET transition-variable can only be used within a before trigger whose granularity is FOR EACH ROW.

Parent topic: X400 - X449


X413: Invalid insert into column %s defined as generated always

No input value is allowed for a column defined as GENERATED ALWAYS.

Parent topic: X400 - X449


X414: Internal error, identity column definition not found

An internal error has occurred. The identity column definition could not be found.

Parent topic: X400 - X449


X036: Default specification for field name is invalid.

An unexpected internal error occurred when accessing the defined default value for column name.

Contact Micro Focus Technical Support.

Parent topic: X000 - X049


X415: Only one rowid or identity column is allowed in a table

A table contains more than one row ID or identity column. This is not allowed.

Parent topic: X400 - X449


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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
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 Mainframe Access
Related concepts
Drag and Drop


Enter the required information

Specify the name of the subdirectory to be created.
Parent topic: Using Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop


Enter the required information

Specify the model for the new sequential or VSAM data set.
Parent topic: Using Mainframe Access
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 Mainframe Access
Related concepts
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


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 Mainframe Access
Related concepts
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


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 Mainframe Access
Related concepts
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


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 Mainframe Access
Related concepts
Drag and Drop
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints


Configuration

Parent topic: Using Mainframe Access
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 Mainframe Access
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints
Drag and Drop
Related reference
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 Mainframe Access
Related concepts
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Hints
Drag and Drop
Related reference
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 Mainframe Access
Related concepts
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Drag and Drop
Compare and Synchronize Monitor Hints
Related reference
Advanced filter details


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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
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)
EBCDIC SI/SO added on upload, removed on download
-SOSI-K
EBCDIC 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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
Related concepts
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


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

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 Mainframe Access
Related concepts
Drag and Drop Utility - Regular Expression Overview
Drag and Drop Utility General information
Drag and Drop Utility Overview
Drag and Drop Utility Hints
Drag and Drop


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 Mainframe Access
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 Mainframe Access
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop


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 Mainframe Access
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
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 Mainframe Access
Related concepts
Drag and Drop
Compare and Synchronize Monitor General Information
Compare and Synchronize Monitor Overview
Compare and Synchronize Monitor Hints